Kocoro: 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.

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 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 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

• 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 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.

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.