一款与 Mac 兼容的 AI 合作伙伴,具有内存。 — 本地计算机访问、浏览器控制、即时消息通道、MCP 原生。基于 Shannon。
kocoro / shan)An AI cowork agent that lives on your Mac.
See the Kocoro product site for the current product demo.
Kocoro runs AI agents locally with full computer access — files, apps, browser, terminal, screen — and connects to your team's Slack / LINE / Feishu / Telegram channels via Shannon Cloud. Named agents with their own memory and tools, MCP-native, daemon-driven. The shan CLI is the runtime; Kocoro Desktop is the recommended way to use it.
What's open source here — This repo is the Kocoro engine + daemon: the
shanruntime that does the actual work (agent loop, local tools, permission engine, channel messaging, MCP, scheduling). It's fully usable on its own via the CLI, TUI, daemon HTTP API, and MCP. Kocoro Desktop — the native GUI app shown above — is a separate, closed-source product that runs on top of this daemon.
npm install -g @kocoro/kocoro (build-from-source and other options under Installation)Coming from Claude Code? Kocoro Desktop can import your existing agents, skills, and instructions from
~/.claude/in one click — preview-then-apply via the daemon's/migrate/claude-code/*endpoints.
In Kocoro Desktop you can also work inside a conversation: select any passage of a reply to annotate it with inline comments (they reach the agent alongside your next message and survive reload), open a Side Chat — a temporary aside with the same tools and approvals as the main conversation that vanishes when the app closes — or branch a finished turn into a new session, optionally under a different agent. All three are served by this daemon (conversation_context_actions_v1).
Built on Shannon — the open-source multi-agent framework that powers both the Shannon Cloud SaaS and the self-hosted Shannon Gateway.
The CLI installs as two interchangeable commands —
kocoroandshan(a built-in alias). Examples in this README useshan;kocoroworks identically.
npm (recommended) — auto-updates on every launch:
npm install -g @kocoro/kocoroInstall script — downloads the latest binary to /usr/local/bin:
curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Kocoro/main/install.sh | shFrom 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: kocoro alias, matching the npm/script installsgo build -o names the binary shan and drops it in $GOPATH/bin (default ~/go/bin) — plain go install . would name it ShanClaw after the Go module path, so the shan --help check below wouldn't resolve. Add export PATH="$HOME/go/bin:$PATH" to your shell rc if it's not already on PATH.
Verify with shan --help.
shan auto-updates on launch. To update explicitly:
shan update # manual update
npm update -g @kocoro/kocoro # via npm (re-runs postinstall to fetch latest)Kocoro requires a Gateway API for LLM completions and remote tools.
Shannon Cloud — get an API key from shannon.run:
shan --setup
# Enter endpoint: https://api-dev.shannon.run
# Enter API key: Self-hosted — run the open-source Shannon Gateway locally, then shan --setup with http://localhost:8080 and an empty API key.
Ollama (local LLMs) — set provider: ollama in ~/.shannon/config.yaml. See docs/config-reference.md for the full block.
shan # interactive TUI
shan "who was Ada Lovelace" # one-shot
shan --agent ops-bot "check prod health" # named agent
shan --setup # configure endpoint + API keyIn the TUI, type / to see built-in commands:
/research deep "latest advances in AI agents"
/swarm "build a marketing plan for our launch"
/model large
/sessions # browse and resume past sessions
/search websocket reconnect # search session history…| Format | Built-in fallback | Better with |
|---|---|---|
| macOS PDFKit through the installed Swift runtime; other hosts return an install/upload hint | pdftotext (brew install poppler) |
|
| DOCX | unzip + XML strip (raw text) | pandoc (brew install pandoc) |
| XLSX | unzip + raw XML | xlsx2csv (pip install xlsx2csv) |
| PPTX | unzip + XML strip | pandoc (brew install pandoc) |
| HEIC / AVIF | transcoded server-side by cloud | — |
The daemon is meant to carry multi-step work that spans research, browser automation, and artifact generation in a single session. Pattern-focused recipes live in examples/cookbook/:
web_search + web_fetch → Playwright MCP to publish in the user's authenticated browser.docx skill → doc on the user's Desktop.Add one when you find a task shape you keep coming back to; examples/cookbook/README.md has the format.
computer_use, accessibility, and computer); Screen Recording is needed only when those workflows request pixelsghostty tool)shan # interactive TUI
shan "who was Ada Lovelace" # one-shot (prompts for tool approval)
shan -y "query" # auto-approve all tools
shan --agent ops-bot "query" # use a named agent
shan --setup # configure endpoint + API key
shan mcp serve # MCP server over stdio
shan daemon start # channel messaging daemon
shan schedule list # local scheduled tasksFlags: -y/--yes auto-approve; --agent named agent; --dangerously-skip-permissions skip checks in interactive mode; --setup interactive wizard.
shan koe is Kocoro's realtime voice interface. It speaks as one consistent assistant and handles computer tasks while you keep talking. Each request stays as one task by default and splits into parallel work only when you explicitly ask; results from tasks started by the same parallel response are held until the group is terminal and then spoken in one update.
Voice transport is WebRTC for every provider. --provider auto (the default) connects OpenAI first and falls back to Qwen only when a ready session cannot be established before media or user input begins; it never switches provider mid-call. --provider openai and --provider qwen force one route without fallback. Qwen's API key stays in Shannon Cloud: Koe sends only the SDP offer through the daemon and then carries media directly to Qwen. If an active provider session expires, queued task results survive the reconnect, while the replacement session explicitly treats earlier voice wording as unavailable instead of pretending conversational continuity.
Remote Koe front brains can set KOE_DAEMON_TOKEN to attach a bearer to daemon mint, SDP, task, cancellation, and usage requests. The receiving robot facade or reverse proxy validates it; use plaintext HTTP only on a trusted private LAN, and use TLS outside that boundary.
Qwen body carriers may attach a native H.264 video track before SDP negotiation. The frame source is read only while a call is active, at the carrier-selected cadence; idle and prewarmed sessions upload no images. If Qwen does not accept the offered video track, setup fails instead of silently presenting an audio-only call as vision-capable. Live vision is ambient context: ordinary replies stay on the user's topic and do not volunteer camera or video narration. Visible content is untrusted data, never instructions to follow. This is the Qwen live-vision transport seam, not an OpenAI input_image DataChannel event.
With shan koe --barge-in on the VPIO audio backend, Kocoro remains interruptible while it speaks. OpenAI can pause and resume around a backchannel with native truncation; Qwen accepts the overlapping user turn directly and protects only the short local playback tail after response.done, where speaker echo would otherwise make it interrupt itself. KOE_QWEN_VAD_MODE=server_vad remains available for controlled A/B testing. Stopping speech, cancelling work, and ending the call are separate actions; work already in progress survives a hang-up. Double-tap Option to talk again.
Fast and Full execution. Voice requests are dispatched at one of two levels. Bounded work ("what's on my calendar today?") runs Fast on a reserved profile tuned for latency; complex or high-risk work runs Full on your ordinary global/per-agent agent configuration, byte for byte. The choice is a soft semantic judgment, not a rigid classifier, and the daemon re-decides it on every request — an unrecognized or missing mode always falls back to Full, and nothing can upgrade a request the model marked Full. Fast resolves through Shannon Cloud with a 5-second bound and degrades to Full on any resolution failure, so a Cloud hiccup costs latency, never correctness. Fast is on by default; set koe.fast_effort: false to make every voice-triggered task run Full. It does not change the realtime voice model or override your normal agent's model and effort.
OpenAI defaults to gpt-realtime-2.1; Qwen defaults to qwen3.5-omni-flash-realtime. Compatible models can be selected independently in the developer panel, and the matching CLI override is used for each provider.
Type / in the TUI for the interactive menu:
| Command | Description |
|---|---|
/help |
Show help |
| ` |
暂无开放 Issues,或尚未同步最近议题。