百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
K

Kocoro

> 编程语言
开源

一款与 Mac 兼容的 AI 合作伙伴,具有内存。 — 本地计算机访问、浏览器控制、即时消息通道、MCP 原生。基于 Shannon。

398 stars0 点赞1 次浏览
访问官网GitHub

工具介绍

一款与 Mac 兼容的 AI 合作伙伴,具有内存。 — 本地计算机访问、浏览器控制、即时消息通道、MCP 原生。基于 Shannon。

Kocoro (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 shan runtime 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.

Get Kocoro

  • Download Kocoro Desktop (macOS) — DMG, the recommended way to use Kocoro
  • CLI only — 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.

Contents

  • Installation · Updating · Setup · Requirements
  • Quick Start · One-Shot Examples · Multi-step Cowork Recipes
  • CLI Usage · Voice Front Brain · Commands
  • Local Tools · Permission Engine · Audit Logging · Hooks
  • MCP Server · MCP Client
  • Configuration · Instructions & Memory · Sessions · Context compaction
  • Named Agents
  • Daemon Mode · Local HTTP API · Prompt Suggestion
  • Memory (Kocoro Cloud) · Session sync to Cloud
  • Scheduled Tasks · File System Watcher · Heartbeat Mode
  • SSE Event Handling · UI Behavior · Keyboard
  • Building & Testing · Known Limitations · License

Installation

The CLI installs as two interchangeable commands — kocoro and shan (a built-in alias). Examples in this README use shan; kocoro works identically.

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

bash
npm install -g @kocoro/kocoro

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

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

From source — requires Go 1.25+:

bash
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 installs

go 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.

Updating

shan auto-updates on launch. To update explicitly:

bash
shan update                       # manual update
npm update -g @kocoro/kocoro      # via npm (re-runs postinstall to fetch latest)

Setup

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

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

bash
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.

Quick Start

bash
shan                                         # interactive TUI
shan "who was Ada Lovelace"                # 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

…

Inbound file format support

Format Built-in fallback Better with
PDF 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 —

Multi-step Cowork Recipes

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/:

  • Publish a Truth Social digest to note.com from Slack — web_search + web_fetch → Playwright MCP to publish in the user's authenticated browser.
  • Scrape a Substack and generate a Word doc — attempted browser scraping, pivot to the site's JSON API, then 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.

Requirements

  • macOS (clipboard, notifications, AppleScript, screencapture, accessibility)
  • Shannon Gateway at configurable endpoint
  • Accessibility permission granted in System Settings > Privacy & Security > Accessibility (for computer_use, accessibility, and computer); Screen Recording is needed only when those workflows request pixels
  • Chrome (optional, for browser automation — Playwright MCP preferred)
  • Ghostty >= 1.3.0 (optional, for ghostty tool)

CLI Usage

bash
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 tasks

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

Voice Front Brain (macOS)

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.

Commands

Type / in the TUI for the interactive menu:

Command Description
/help Show help
`

Issues· 19 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Go

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言