# Kocoro: Local AI Agent Runtime and Development Framework for macOS

> Kocoro is a local AI Agent runtime designed specifically for macOS, offering an interactive TUI, daemon mode, a rich set of local tools (file operations, GUI control, browser automation), MCP integration capabilities, and support for Shannon Cloud connection and cloud workflow delegation.

- 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm)
- 发布时间: 2026-05-13T06:15:53.000Z
- 最近活动: 2026-05-13T06:25:40.298Z
- 热度: 150.8
- 关键词: AI Agent, macOS, 本地运行时, MCP协议, Shannon, 命令行工具, 自动化, GUI控制
- 页面链接: https://www.zingnex.cn/en/forum/thread/kocoro-macos-ai-agent
- Canonical: https://www.zingnex.cn/forum/thread/kocoro-macos-ai-agent
- Markdown 来源: floors_fallback

---

## Kocoro Core Guide: Local AI Agent Runtime and Development Framework for macOS

Kocoro is a local AI Agent runtime environment and complete development framework developed and maintained by the Shannon team, specifically built for macOS systems. Its core positioning is 'local-first'—unlike AI assistants that fully rely on cloud services, Kocoro emphasizes local code execution, file access, and system resource control, while maintaining flexible connectivity with cloud services, thus protecting user data privacy and providing powerful local computing capabilities. Key features include an interactive TUI, daemon mode, a rich set of local tools (file operations, GUI control, browser automation), MCP integration capabilities, Shannon Cloud connection, and cloud workflow delegation.

## Background and Core Architecture Components

### Command Line Interface (shan CLI)
shan is Kocoro's main command-line tool, supporting multiple operation modes:
- **Interactive TUI Mode**: Launch a terminal user interface to support continuous dialogue with the Agent
- **One-time Mode**: Execute a single query directly and return the result
- **Auto-confirmation Mode**: Skip tool call confirmation via the `-y` flag, suitable for automation scripts
The CLI follows the Unix philosophy and can be integrated with other tools via pipes and scripts.

### Daemon
The daemon is the core service component, providing:
- WebSocket connection: Establish a persistent connection with Shannon Cloud to receive messages from channels like Slack and LINE
- Local HTTP API: Provide RESTful API at localhost:7533
- Multi-Agent management: Support running multiple named Agents simultaneously, each with independent configurations and session history
- Task scheduling: Local scheduled task management based on launchd
It uses the 'claim-ack' protocol and can run up to 5 Agents concurrently.

### Local Toolset
Covers file operations, system control, GUI interaction, etc.:
#### File and Document Operations
file_read/file_write/file_edit, glob/grep, directory_list, archive_inspect/extract, pdf/docx/xlsx/pptx_to_text, etc.
#### Shell and System Control
bash (120-second timeout, auto-approval for safe commands), system_info, process management, HTTP client (supports network whitelist).
#### macOS GUI Control
accessibility (accessibility API), computer (mouse and keyboard control), screenshot, applescript, clipboard/notify, browser automation, ghostty terminal control, etc.

## MCP Integration and Personalized Agent Configuration

### MCP Integration Architecture
Kocoro implements the Model Context Protocol (MCP) open protocol, supporting:
- As MCP client: Connect to external MCP servers (file system, SQLite, GitHub, etc.) to expand tool capabilities
- As MCP server: Expose local tools to clients like Claude Desktop and Cursor via `shan mcp serve`
MCP configuration supports multi-level merging: global (~/.shannon/config.yaml), project (.shannon/config.yaml), and local override (.shannon/config.local.yaml).

### Named Agents and Personalized Configuration
Support creating multiple named Agents, each with independent:
- Instruction file (AGENT.md): Define role, capabilities, and behavioral guidelines
- Memory file (MEMORY.md): Persist memory across sessions
- Configuration file (config.yaml): Tool whitelist, MCP server, model parameters, etc.
- Custom commands (commands/): Exclusive slash commands
- Attached skills (_attached.yaml): Bound skill list
Example scenario Agents: ops-bot (operation monitoring), reviewer (code review), writer (writing assistant).

## Security Mechanisms and Session Memory Management

### Security and Permission Model
Multi-layer protection mechanisms:
- **Tool call permissions**: Hard block dangerous commands (e.g., rm -rf /), auto-approve read-only/safe commands, require interactive confirmation for destructive operations, check compound command splits
- **File system protection**: Symbolic link resolution protection, sensitive file pattern matching (.env, .pem, etc.), allowed directory whitelist
- **Audit logs**: All tool calls are recorded to ~/.shannon/logs/audit.log (JSON Lines format), with automatic desensitization of sensitive information.

### Session Management
- Session persistence: Dialogue history is saved as JSON files, supporting resume from breakpoints
- Session search: Full-text search based on SQLite FTS5
- Session recovery: Browse and restore historical sessions via the `/sessions` command
- Context compression: Automatically compress historical messages when window pressure is too high
Each named Agent has an independent session directory.

### Memory System
- **Structured memory**: Achieve cross-session knowledge accumulation via MEMORY.md
- **Episodic memory**: Optional cloud memory service, extract relevant memory from historical sessions and inject into new sessions (opt-in, disabled by default)
- **Skill system**: Reusable capability modules following the Anthropic SKILL.md specification, supporting global installation, Agent binding, and dynamic activation; built-in kocoro (platform configuration) and kocoro-generative-ui (visualization) skills.

## Cloud Integration and Developer Ecosystem

### Cloud Integration
- **Shannon Cloud connection**: Receive multi-channel messages via WebSocket, delegate cloud deep research via `/research`, launch cloud multi-Agent collaboration via `/swarm`, generate images via cloud API
- **Model provider options**: Shannon Cloud, self-hosted Gateway, Ollama (local open-source models like Llama 3.1, Qwen3, etc.)

### Developer Ecosystem and Extensibility
- **Lifecycle hooks**: Execute custom scripts before/after tool calls and at session start/end (e.g., PreToolUse, PostToolUse)
- **Custom commands**: Create Markdown files in the commands/ directory to add slash commands
- **HTTP API**: The daemon provides interfaces for sending messages, session management, Agent configuration reloading, SSE event streams, etc., supporting custom clients and automation scripts.

## Installation Methods and Application Scenarios

### Installation and Usage
Provide multiple installation methods:
- npm: `npm install -g @kocoro/kocoro`
- Installation script: `curl -fsSL ... | sh`
- Go source code: `go install .`
After installation, configure endpoints and API keys via `shan --setup` to use.

### Application Scenarios
Suitable for:
- Personal automation: File organization, system monitoring, scheduled tasks
- Development assistance: Code review, project analysis, document generation
- Knowledge management: Note organization, data archiving, information retrieval
- Intelligent customer service: Access multi-message channels to provide automated replies
- Research assistant: Web search, data aggregation, report generation
Provide a fully functional, secure, and controllable local AI Agent solution for macOS users who value data privacy.

## Future Outlook of the Project

As an actively developed open-source project, Kocoro's possible future evolution directions include:
- Expand more local tools (e.g., browser automation capabilities)
- Optimize compatibility with open-source models
- Enhance multi-modal capabilities (image understanding, voice interaction)
- Provide a richer skill market
- Improve cross-platform support (currently macOS only)
For AI Agent technology explorers, Kocoro is both a practical tool and an excellent platform for learning and experimentation.