Kocoro

Ghostty terminal — requires Ghostty >= 1.3.0

shan ghostty workspace writer ops-bot # open one window per agent

MCP integrations (requires server config — see "MCP Client")

shan "list files on my Desktop" # filesystem MCP shan "show all tables in the database" # sqlite MCP ```

Inbound file format support

Requirements

• macOS (clipboard, notifications, AppleScript, screencapture, accessibility)
• Shannon Gateway at configurable endpoint
• Accessibility permission granted in System Settings > Privacy & Security > Accessibility (for accessibility and computer tools)
• Chrome (optional, for browser automation — Playwright MCP preferred)
• Ghostty >= 1.3.0 (optional, for ghostty tool)

Installation

npm (recommended) — auto-updates on every launch:

npm install -g @kocoro/kocoro

Install script — downloads the latest binary to /usr/local/bin:

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

From source — requires Go 1.25+:

git clone https://github.com/Kocoro-lab/Kocoro.git
cd Kocoro
go install .

go install places the binary in $GOPATH/bin (default ~/go/bin). Add export PATH="$HOME/go/bin:$PATH" to your shell rc if it's not already on PATH.

Verify with shan --help.

Setup

Kocoro requires a Gateway API for LLM completions and remote tools.

Shannon Cloud — get an API key from shannon.run:

```bash shan --setup

Building & Testing

go build -o shan .           # build
go test ./...                # run all tests
go vet ./...                 # lint

Quick Start

shan                                         # interactive TUI
shan "who is wayland zhang"                  # one-shot
shan --agent ops-bot "check prod health"     # named agent
shan --setup                                 # configure endpoint + API key

In 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

One-Shot Examples

```bash

CLI Usage

shan                              # interactive TUI
shan "who is wayland zhang"       # 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 tasks

Flags: -y/--yes auto-approve; --agent named agent; --dangerously-skip-permissions skip checks in interactive mode; --setup interactive wizard.

Quickstart (cloud mode)

1. Install the tlm binary somewhere on $PATH (or set memory.tlm_path).
2. Configure Cloud credentials:

   cloud:
     endpoint: https://api.shannon.run
     api_key: <your key>
   memory:
     provider: cloud
   

1. Restart the daemon. First bundle download starts ~60s after boot, then every 24h.

Vision + computer use — screenshot, computer

shan -y "open Chrome, go to x.com, and post a tweet"

Configuration

Multi-level merge — later overrides earlier:

1. ~/.shannon/config.yaml — global
2. .shannon/config.yaml — project
3. .shannon/config.local.yaml — local (gitignored)

Scalars override, lists merge + dedup, structs field-level merge.

Minimal ~/.shannon/config.yaml:

endpoint: https://api.shannon.run
api_key: <your key>
model_tier: medium

permissions:
  allowed_commands:
    - "git *"
    - "make *"

See docs/config-reference.md for the full key list including agent.*, tools.*, mcp_servers, cloud, memory, sync, daemon, hooks, UI settings, etc. Run /config in the TUI to see the merged config with sources.

Per-agent overrides live in ~/.shannon/agents/<name>/_attached.yaml — including agent.model_tier so individual agents can opt into the Large (Opus) tier without changing the global default. See docs/agents-reference.md for the precedence chain.

Configuration

See the memory: block in docs/config-reference.md for all keys (provider, endpoint, api_key, socket_path, bundle_root, tlm_path, bundle_pull_interval, sidecar_* timeouts).

Enter endpoint: https://api-dev.shannon.run

Enter API key: <your 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.

Cloud Tools (gated on `cloud.enabled` + `api_key`)

Local HTTP API (port 7533)

Localhost-only HTTP for native-app integration and scripting.

Send a message:

```bash