Kocoro-lab/Kocoro

Kocoro – an AI coworker that lives on your Mac

What it is – Kocoro is a locally‑run AI‑agent framework for macOS. The open‑source part of the project (the shan runtime) is a daemon that drives “agents” capable of reading and writing files, controlling apps, running shell commands, automating browsers, and chatting over Slack/LINE/Feishu/Telegram. A separate closed‑source GUI app (Kocoro Desktop) talks to this daemon, but the daemon itself can be used directly from the command line, a TUI, or an HTTP API.

Why it matters – It lets you give a language model full computer access while keeping the heavy lifting on your own machine. The agent loop, permission checks, tool inventory, and memory handling are all bundled in the daemon, so you can run the same AI‑driven workflows without sending your files or screen data to a third‑party service.

---

Core capabilities

Area	What Kocoro can do
Agent runtime	Named agents with persistent memory, configurable tools, and per‑task approvals.
Local tools	File read/write/edit, glob/grep, archive inspect/extract, PDF/DOCX/XLSX/PPTX text extraction, shell (bash), macOS AppleScript, accessibility/Computer‑Use UI automation, clipboard, notifications, browser automation via Playwright (fallback to ChromeDP).
Permission engine	Fine‑grained approvals (yes to auto‑approve, per‑tool prompts, or --dangerously-skip-permissions for testing).
Interaction modes	• Interactive TUI (shan), • CLI one‑shot commands, • Daemon HTTP API (port 7533), • MCP (Message‑Control‑Protocol) server/client, • Real‑time voice front‑brain (shan koe) on macOS.
Team integration	Sends/receives messages to Slack, LINE, Feishu, Telegram via the Shannon Cloud gateway.
Memory & sync	Session history stored locally, optional cloud sync (Kocoro Cloud) for cross‑device continuity.
Scheduling & watchers	Local scheduled tasks, file‑system watcher, heartbeat mode for periodic checks.
Extensibility	Hooks, custom commands, and a plug‑in style Info() schema for each tool.

---

Getting started (as described in the README)

1. Install the daemon

   # npm (recommended – auto‑updates on launch)
   npm install -g @kocoro/kocoro
   
   # or script
   curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Kocoro/main/install.sh | sh
   
   # or build from source (requires Go 1.25+)
   git clone https://github.com/Kocoro-lab/Kocoro.git
   cd Kocoro
   go build -o $(go env GOPATH)/bin/shan .
   ln -sf shan $(go env GOPATH)/bin/kocoro   # optional alias
   

2. Configure an LLM gateway – either a Shannon Cloud API key or a self‑hosted Shannon Gateway, or Ollama for local models.

   shan --setup   # prompts for endpoint and API key
   

3. Run the agent
   • Interactive TUI: shan
   • One‑shot query: shan "who was Ada Lovelace"
   • Use a named agent: shan --agent ops-bot "check prod health"
   • Auto‑approve all tool uses: shan -y "open Safari and navigate to github.com"
4. Optional GUI – download Kocoro Desktop (macOS DMG) which talks to the same daemon.

---

Architecture snapshot

• shan binary – the daemon/runtime. It exposes:
  • A TUI/CLI front‑end.
  • An HTTP API (default port 7533) for programmatic control.
  • An MCP server/client for streaming messages to/from external services.
• Tools – Go packages under internal/tools/ each implementing a Info() schema (name, approval mode, input/output). The daemon loads them at start‑up.
• Permission engine – decides whether a tool call needs user confirmation; can be bypassed with -y or the dangerous flag.
• Memory layer – local session logs plus optional cloud sync (Kocoro Cloud) for persistent agent memory.
• Voice front‑brain (shan koe) – real‑time speech interface that routes audio via WebRTC to OpenAI or Qwen, then feeds the transcribed request into the same agent loop.

---

Who might use it?

• Power users who want an LLM to automate repetitive macOS tasks (file cleanup, code linting, data extraction, UI navigation) without giving the model full remote access.
• Developers building custom AI‑driven workflows; they can add new tools or hook into the HTTP API.
• Teams that need a shared “AI coworker” integrated with Slack/Telegram for on‑demand assistance.

---

License

The repository is released under the MIT License (see the LICENSE file). Only the daemon/runtime is open source; the accompanying Kocoro Desktop GUI is proprietary.

---

Quick reference cheat‑sheet

# start interactive UI
shan

# one‑shot query (prompts for tool approvals)
shan "list all TODO comments in this project"

# auto‑approve every tool (use with care)
shan -y "open Calendar and show me today's events"

# run a named agent
shan --agent research-bot "summarize the latest AI papers"

# start the MCP server (for external clients)
shan mcp serve

# schedule a recurring task
shan schedule create "daily backup" "shan "run backup.sh"" --cron "0 2 * * *"

---

Bottom line – Kocoro’s open‑source shan daemon gives macOS users a fully‑featured, locally‑executed AI agent platform that can read/write files, control the GUI, run shell commands, and talk to team chat services, all while keeping the heavy LLM inference either in the cloud (Shannon) or on a local Ollama server.