Kocoro: a Mac-native AI agent with memory, local computer access and MCP

The problem Kocoro targets: agents that can actually touch your machine

Most agent tooling stops at a chat box. It can read what you paste and write text back. Kocoro takes the opposite position: the agent should reach the files, apps, browser, terminal and screen directly, and it should do so from the machine you are sitting at rather than a container somewhere else. The README describes it as "An AI cowork agent that lives on your Mac" and lists exactly those surfaces as the ones it holds.

The audience is narrow and identifiable. You are on macOS. You want an agent that can run go test, kill a process on a port, drive Safari through AppleScript, or extract text from a PDF, without you copying output between windows. You may also want that same agent reachable from a team chat channel, which is where Shannon Cloud comes in. If none of that describes you, the project is not aimed at you.

The naming is worth clearing up early, because search results for this project are polluted by unrelated things. Kocoro here is not Kokoro TTS, not the Japanese word, not a food. It is the Kocoro-lab project, and the binary you will actually type is shan.

What is open source and what is not

This is the single most important thing to understand before adopting Kocoro, and the README states it plainly. The repository is the engine and daemon: the shan runtime that does the work, meaning the agent loop, the local tools, the permission engine, channel messaging, MCP, and scheduling. That part is MIT licensed and usable on its own through the CLI, the TUI, the daemon HTTP API and MCP.

Kocoro Desktop, the native GUI, is a separate closed-source product that runs on top of this daemon. The README calls it "the recommended way to use it", and the download page is a DMG. So the recommended path and the open path are not the same path. That is a real trade-off, not a detail. You can run everything from the terminal and never touch the GUI, but if you want the polished experience the project itself points you toward, you are using a closed binary sitting on an open daemon.

One consequence: the daemon's HTTP API is a documented integration surface, so the closed app is not the only client that can exist. Anything that can speak to the daemon can drive the same agents.

Architecture: a daemon, a CLI, and a permission gate between them

The Go module is named github.com/Kocoro-lab/ShanClaw, which explains a quirk in the build instructions: plain go install would produce a binary called ShanClaw, so the README tells you to use go build -o instead. The engine depends on Bubble Tea and Lipgloss for the TUI, chromedp for browser automation, mcp-go for MCP, modernc.org/sqlite for local storage, fsnotify for the file system watcher, and go-selfupdate for the auto-update path. That dependency list maps closely onto the advertised feature set, which is a good sign that the README is describing the code rather than aspirational plans.

The runtime shape is daemon-driven. A local HTTP API listens on port 7533, and the CLI, the TUI, the desktop app and MCP clients all talk to that daemon. Sessions, memory, named agents and scheduled tasks live behind it. Named agents are the unit of configuration: each has its own memory and tools, and you select one with shan --agent ops-bot "...".

Between the agent and the machine sits the permission engine. Read-only operations such as archive_inspect are described as needing no approval, while archive_extract requires approval. The -y flag auto-approves, which is why the README's macOS examples pair it with app control: shan -y "set my Mac volume to 50%". Treat -y as the switch that turns a supervised agent into an unsupervised one.

Install Kocoro and run a first real task

The npm route is the one the README recommends, and it installs two interchangeable commands: kocoro and its built-in alias shan. Examples throughout the README use shan.

npm install -g @kocoro/kocoro

There is also an install script that fetches the latest binary into /usr/local/bin, and a from-source path requiring Go 1.25 or newer. The source build names the binary explicitly, because the module path would otherwise name it ShanClaw:

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"

Verify the binary resolves before going further. The README uses this as the check:

shan --help

Kocoro needs a Gateway for LLM completions and remote tools. Shannon Cloud is the hosted option; the self-hosted option is the open-source Shannon Gateway. The setup command prompts for both an endpoint and an API key:

shan --setup
# Enter endpoint: https://api-dev.shannon.run
# Enter API key: <your key>

For a self-hosted Gateway the README specifies http://localhost:8080 with an empty API key. Ollama is also supported by setting provider: ollama in ~/.shannon/config.yaml.

Now a task that exercises local access rather than chat. This one reads files in the current project and is a reasonable first contact with the tool layer:

shan "find all TODO comments in this project"

The agent should reach for file_read, glob and grep. If it asks for approval, that is the permission engine working. Once that behaves, try something with a real side effect, and decide deliberately whether you want to type -y:

shan "run go test and fix any failures"

Where Kocoro gets awkward

Platform lock-in is the first limit. The product is described as Mac-native, the examples are macOS apps, and the local tools include applescript and system-level control. The README does not document a supported Linux or Windows path for the local tool set, so if your team is not on Macs, this is the wrong tool regardless of how well the engine itself would compile.

The permission model is the second. Auto-approval via -y is convenient and it is also the mode where an agent can kill a process, overwrite files during extraction, or drive your GUI without asking. The README shows -y used casually in examples, which understates what it means in practice. A permission engine that you routinely bypass is not a safety boundary.

The third is the split licence. The engine is MIT, but the recommended client is closed. If your organisation has rules about which binaries it runs, or you were hoping to modify the desktop experience, the open repository does not give you that. It gives you the daemon and the CLI, and the README is explicit that the GUI is separate.

Finally, the search results around this name are genuinely unhelpful. Queries like "What is Kokoro TTS" or "Kokoro in Japanese writing" have nothing to do with this project, so documentation discovery through search engines is harder than the project's quality would suggest.

Alternatives and the difference in approach

The README itself points at the closest comparison. It addresses readers "Coming from Claude Code?" and describes a migration path: Kocoro Desktop can import existing agents, skills and instructions from ~/.claude/ in one click, with a preview-then-apply flow served by the daemon's /migrate/claude-code/* endpoints. That tells you the project sees Claude Code users as its natural audience.

The approaches differ in where the agent runs and what it is allowed to touch. Claude Code is a terminal coding assistant centred on a repository. Kocoro is a daemon with named agents, persistent memory, scheduled tasks, a file system watcher and a heartbeat mode, and its tool surface extends past code into the browser, macOS apps and the screen. The migration endpoints exist because the instruction and skill formats overlap, not because the two do the same job.

The other reference point is Shannon, the multi-agent framework Kocoro is built on. The README states that Shannon powers both the Shannon Cloud SaaS and the self-hosted Shannon Gateway, and that Kocoro requires a Gateway for completions. So Shannon is not an alternative to Kocoro so much as its substrate. If you want the framework without the Mac agent, that is the repository to read.

Maintenance, licensing and what upgrades cost you

The repository is not archived, and the last push was on 2026-09-05. Releases are frequent: v0.4.7 on 2026-08-18, v0.4.8 on 2026-08-19, and v0.4.9 on 2026-08-23. The version numbers are still in the 0.4.x range, so the project is pre-1.0 and you should expect the CLI surface and configuration keys to move.

Upgrade mechanics are handled for you in the npm and script installs: the README says shan auto-updates on launch. That is convenient and also means your runtime can change under you between sessions. The explicit alternatives are shan update for a manual update, or npm update -g @kocoro/kocoro, which re-runs the postinstall step to fetch the latest binary. If you pin behaviour for a team, the auto-update default is something you have to actively work against.

The licence is MIT, which is permissive and places few obligations on how you use or redistribute the engine. That applies to this repository. It does not extend to Kocoro Desktop, which the README describes as a separate closed-source product. This is a description of what the repository states, not legal advice; if the boundary matters to your organisation, read the LICENSE file and the product terms yourself.

Editorial conclusion

Adopt Kocoro if you want an agent runtime that owns the Mac it runs on: install it with npm install -g @kocoro/kocoro, run shan --setup, and keep the permission engine in the loop for anything that touches the shell or the GUI. Do not adopt it if you need a supported non-macOS path or a fully open source desktop client, because the GUI is closed and the local tools are Mac-centric. Before committing, verify three things: that your Gateway endpoint answers under shan --setup, that your team's IM channel is one of Slack, LINE, Feishu or Telegram, and that you are comfortable with the open engine sitting under a closed desktop product.

Frequently asked questions

Official sources

1. Kocoro-lab/Kocoro on GitHub
2. License: MIT
3. Project website
4. README
5. Releases