Kocoro: a Mac-native agent daemon with local tools, IM channels and MCP

What Kocoro solves, and who is expected to run it

Most agent frameworks give you a library and leave the execution environment to you. Kocoro takes the opposite position: it assumes the execution environment is your Mac, and it ships the pieces needed to act on that machine. The README lists the surfaces it can reach: files, apps, browser, terminal and screen. Those are exposed as named tools such as file_read, file_write, file_edit, glob, grep, directory_list, bash, system_info, process, applescript, and document converters for PDF, DOCX, XLSX and PPTX. The audience is therefore not someone prototyping a prompt chain. It is an engineer or operator who wants a local agent that can run go test, kill a process on port 3000, open Calendar, or extract pages 3 to 8 of a PDF without building the tool layer first.

The second audience is teams that already work in chat. The README states that agents connect to Slack, LINE, Feishu and Telegram via Shannon Cloud, so the same named agent can be reached from a channel rather than a terminal. That is a different deployment shape from a personal CLI: an agent with a name, its own memory and its own tools, reachable by other people. The repository is explicit that only the engine and daemon are open source here. Kocoro Desktop, described as the recommended way to use it, is closed source and runs on top of the daemon.

Architecture: daemon, named agents, and where Shannon sits

The runtime is a single Go binary that installs under two interchangeable command names, kocoro and shan, with shan as a built-in alias. The README describes the repo as the engine plus daemon: agent loop, local tools, permission engine, channel messaging, MCP, and scheduling. The daemon is the hub. It exposes a local HTTP API on port 7533, serves SSE events, and backs the desktop app's features, including the conversation context actions grouped under conversation_context_actions_v1 (inline annotations, Side Chat, and branching a finished turn into a new session).

LLM completions and remote tools do not come from the binary itself. Kocoro requires a Gateway API. You either point it at Shannon Cloud with an API key, or self-host the open-source Shannon Gateway and point at http://localhost:8080 with an empty key. There is also an Ollama path via provider: ollama in ~/.shannon/config.yaml. Shannon is described as the multi-agent framework that powers both the Shannon Cloud SaaS and the self-hosted gateway, so the dependency is architectural rather than incidental. If you want a fully offline agent, the Ollama route is the only one the README names, and it still routes through the same configuration file.

On the tool side, the project is MCP-native in both directions. It acts as an MCP server and as an MCP client. Browser automation is a concrete example: the README says Playwright MCP is preferred, with pinchtab/chromedp as a fallback. That ordering matters because it means browser control quality depends on which MCP path is actually available at runtime, not only on Kocoro.

Installing the shan runtime and pointing it at a gateway

The npm route is the one the README recommends, and it auto-updates on every launch:

npm install -g @kocoro/kocoro

There is also an install script that downloads the latest binary to /usr/local/bin:

curl -fsSL https://raw.githubusercontent.com/Kocoro-lab/Kocoro/main/install.sh | sh

Building from source requires Go 1.25 or newer. The README gives an explicit build command rather than go install, and explains why: go install would name the binary ShanClaw after the Go module path, so the shan --help check would not resolve.

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"

After install, configuration goes through shan --setup, which prompts for an endpoint and an API key. For Shannon Cloud the README shows https://api-dev.shannon.run as the endpoint. For a self-hosted gateway it is http://localhost:8080 with an empty API key. Updates run through shan update, or npm update -g @kocoro/kocoro, which re-runs the postinstall step to fetch the latest binary. Verify the install with shan --help.

Daily use is short. shan opens the interactive TUI, shan "who was Ada Lovelace" is a one-shot, and shan --agent ops-bot "check prod health" targets a named agent. Inside the TUI, slash commands include /research deep, /swarm, /model large, /sessions and /search. The -y flag auto-approves actions, which is what makes examples like shan -y "open Safari and navigate to github.com" and shan -y "kill the process on port 3000" run without a prompt.

Permissions, audit logging and hooks as the real control surface

The interesting design decision in Kocoro is that approvals are a first-class subsystem rather than a flag. The README separates tools by approval behaviour: archive_inspect needs no approval, while archive_extract does. The -y flag exists precisely because some tools would otherwise stop and ask. A permission engine and an audit log are listed as top-level sections of the documentation, alongside hooks.

That structure tells you where the risk sits. An agent that can run bash and AppleScript on your machine, and that can be triggered from a Slack or Telegram channel, is a different threat model from a chat window that only produces text. The mitigations the project offers are the permission engine, the audit log, and hooks. The README does not, in the material available here, spell out default policies per tool, so the honest position is that you should read those sections before granting broad approvals, not after. Auto-approving shell and app control with -y is a convenience that shifts the burden onto whatever guardrails you configured first.

Hooks are worth noting for a second reason: they are the extension point that does not require forking the daemon. If your organisation needs a policy check before a bash call, hooks and the permission engine are where that belongs, rather than in a wrapper script around the CLI.

Memory, scheduling and the features that assume a long-running process

Several capabilities only make sense if the daemon stays up. Scheduled tasks, a file system watcher, and heartbeat mode are all listed in the contents. Heartbeat mode implies periodic agent activity rather than request-response, and the file system watcher implies the agent reacts to disk changes. Neither is a feature you get from a one-shot CLI invocation.

Memory is split. Named agents have their own memory and tools, and there is a separate Kocoro Cloud memory feature plus session sync to Cloud. Context compaction is documented as its own topic, which is the expected pressure point for an agent that holds long sessions with large tool outputs. Sessions can be browsed and resumed (/sessions) and searched (/search websocket reconnect), and a finished turn can be branched into a new session, optionally under a different agent. Prompt suggestion appears as ghost text in the input.

The Cloud-coupled parts are the ones to read carefully. Memory and session sync route through Kocoro Cloud rather than staying local, and the channel integrations route through Shannon Cloud. If your constraint is that prompts, session history and agent memory never leave the machine, the self-hosted gateway plus Ollama is the configuration to investigate, and the README's coverage of that combination is thinner than its coverage of the Cloud path.

Where Kocoro is the wrong tool

The platform boundary is stated plainly: this is a Mac-native agent. The examples lean on macOS specifics such as applescript, setting system volume, and opening Calendar or TextEdit. If your fleet is Linux or Windows, the local tool layer as described here does not apply, and you would be adopting a daemon whose most distinctive capabilities are inert.

The second boundary is the open-source boundary. The README is unusually direct about it: this repository is the engine and daemon, and Kocoro Desktop is a separate closed-source product. If your adoption criteria require an open-source GUI, the CLI, TUI, daemon HTTP API and MCP surfaces are what you actually get. The migration path from Claude Code, which imports agents, skills and instructions from ~/.claude/ via the daemon's /migrate/claude-code/* endpoints, is described as a Kocoro Desktop feature, so that convenience is on the closed side too.

The third boundary is the gateway dependency. Kocoro requires a Gateway API for completions and remote tools. Running it without Shannon Cloud means running the Shannon Gateway yourself, which adds a second service to operate. A team that wants a single self-contained binary with no external service will find that requirement inconvenient, and the README does not present a mode that removes it.

Finally, the README carries a Known Limitations section. Whatever is in it should be treated as authoritative over any impression created by the feature list, because the feature list is long and the limitations section is where the edges are documented.

How it differs from Claude Code and from a plain MCP client

The most natural comparison is Claude Code, and the project invites it: Kocoro Desktop can import agents, skills and instructions from ~/.claude/ with a preview-then-apply flow. The difference in approach is where the agent lives. Claude Code is a coding agent driven from a terminal session in a repository. Kocoro is a daemon with named agents, its own memory, a permission engine, an audit log, scheduling, a file watcher and heartbeat mode, plus chat channel delivery. Coding is one thing it can do through bash and file tools; it is not the organising concept.

The second comparison is a bare MCP client. Kocoro is MCP-native on both sides, acting as server and client, and it prefers Playwright MCP for browser work. A plain MCP client gives you tool invocation and nothing else. Kocoro adds the layer around it: approvals per tool, an audit trail, session persistence, context compaction, and a local HTTP API on port 7533 that other processes can drive. If you already have a host application and only need tool plumbing, that surrounding layer is weight you would be carrying for nothing.

The third comparison is a self-hosted Shannon Gateway deployment without Kocoro. Shannon is the multi-agent framework underneath, and the gateway is the piece that talks to models. Choosing Shannon alone means you build the local tool surface, the permission model and the channel integrations yourself. Choosing Kocoro means you accept its opinions about all three.

Maintenance, licence and what to check before adopting

The repository is MIT-licensed and not archived. Releases are frequent and small: v0.4.7, v0.4.8 and v0.4.9 all landed within roughly a week in August 2026, and the last push recorded is 2026-09-05. That cadence is a maintenance cost signal in both directions. You get fixes quickly, and you also get a moving target. The npm package auto-updates on every launch, which means the binary on a developer's machine can change between two invocations of shan. If you need reproducible agent behaviour across a team, that default is worth overriding deliberately, and the README documents shan update and npm update -g @kocoro/kocoro as the explicit paths.

The MIT licence covers this repository. It does not cover Kocoro Desktop, which is a separate closed-source product, and it does not automatically cover the Shannon Gateway or Shannon Cloud, which are described as separate projects with their own terms. If you are deploying the daemon inside a company, the licence question is not only about this repo: it is about the gateway you point shan --setup at and the Cloud services that memory and session sync use. That is a question for your own review, not something the README answers.

Concretely, before adopting: read the Known Limitations section, read the permission engine and audit logging sections, and decide whether the Cloud memory and session sync features are acceptable for the data you plan to run through the agent. If they are not, confirm the self-hosted gateway and provider: ollama path in ~/.shannon/config.yaml works for your models before you standardise on Kocoro. The daemon's local HTTP API on port 7533 is also worth treating as a service to secure, not just a convenience for the desktop app.

Editorial conclusion

Adopt Kocoro if you want an agent that touches real Mac state (files, shell, AppleScript, browser) and you are willing to read the permission engine and audit log before granting approvals. Skip it if you need Linux or Windows hosts, or if you want a fully open-source desktop GUI: the GUI is a separate closed product. Before installing, verify three things in the repository: the known limitations section, whether your LLM provider works through a Shannon Gateway or Ollama, and what the default approval policy is for bash and applescript. Then run shan --setup and confirm the endpoint you entered is the one you intend to send prompts to.

Official sources

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