tarocub

English  |  中文文档  |  📖 飞书图文版 (Feishu Doc)  |  Full Reference

TaroCub

A Feishu/Lark-first gateway for Codex, Claude Code, Kimi Code, DeepSeek Harness, and Antigravity running on your own machine.
TaroCub runs real CLI agents on your own machine, then gives them durable chat surfaces, files, sessions, tasks, cron, audit logs, and multi-agent workflows.
Resume local sessions anytime from your phone, whether you are at your desk, commuting, or walking the dog.

📖 Feishu Doc (飞书图文)  |   Quick Start  |   Surfaces  |   Core Highlights  |   Lark Setup  |   Commands  |   Docs

What This Is

TaroCub is a local bridge, not a hosted agent product. It runs the real Codex, Claude Code, Kimi Code, DeepSeek Harness, and Antigravity CLIs on your own computer, then gives them a durable messaging control surface in Feishu/Lark, with Telegram retained as an optional compatibility channel.

Feishu/Lark is the primary platform. The maintainer has not used Telegram as a day-to-day control surface for a long time. Telegram remains available for existing deployments, but new installations should start with Feishu/Lark.

This project was formerly named cc-telegram-bridge. The canonical repository is now cloveric/tarocub; GitHub redirects the old URL, and existing state directories plus the cctb shorthand remain supported for compatibility.

It is built for people who already use CLI agents heavily and want:

• Feishu/Lark-native operation with cards, Docs comments, Sheets, Drive, and group/thread workflows;
• optional phone-first Telegram operation for existing personal-bot deployments;
• durable state for sessions, cron jobs, file delivery, usage, timelines, audit logs, and multi-agent routing.

The intended setup flow is agent-assisted: clone the repo, open it in Codex, Claude Code, Kimi Code, DeepSeek Harness, or Antigravity, and ask the agent to configure the bridge for you. The CLI exists so your local agent can do the boring setup work instead of making you hand-edit every file.

The old long README is preserved as Full Reference. This landing page is intentionally short.

Quick Start

Recommended: ask your local agent to configure it

Open this repository in Codex, Claude Code, Kimi Code, DeepSeek Harness, or Antigravity and say:

Read the README and configure TaroCub for me.
Run the Lark wizard, check permissions, install/bind lark-cli, and tell me what I need to scan or approve.

That is the preferred path. Manual commands are still below for operators who want to see each step. If you explicitly need the legacy-compatible Telegram channel, ask the agent to configure it with a BotFather token instead.

Feishu / Lark (recommended)

git clone https://github.com/cloveric/tarocub.git
cd tarocub
npm install
npm run build

node dist/src/index.js lark setup --detached --install-cli --identity bot-only
node dist/src/index.js lark yolo unsafe

--detached keeps QR registration alive in tmux, prints one durable registration link, writes progress to ~/.cctb/<lark-instance>/lark-setup.log, and starts the Lark service when setup completes. Use --no-start-service only when you explicitly want to prepare the app without listening yet.

If lark doctor reports missing app scopes, open the permission page URL it prints and grant the JSON it prints. PersonalAgent apps activate the grant immediately after confirmation; enterprise custom apps may still require a version publish. Then run:

node dist/src/index.js lark provision
node dist/src/index.js lark doctor
node dist/src/index.js lark slash sync

DeepSeek Harness web search plugin (native bundle)

Install the standalone native plugin into the web profile used by ordinary Harness and by TaroCub's private Harness hosts:

dsh plugin --profile web add github:cloveric/deepseek-harness-web-search-plugin

The plugin adds source-traceable Brave/Tavily live search and URL extraction. TaroCub integration and /tarocub guidance are optional. Installing it does not create a Feishu/Lark app or start the bridge. The canonical TaroCub subdirectory source remains compatible. Check, update, or remove it with:

dsh --profile web --dump-config | grep -A18 -B2 mcp-cctb-search
dsh plugin --profile web update deepseek-harness-web-search-plugin
dsh plugin --profile web remove deepseek-harness-web-search-plugin

TaroCub still recognizes installations made under the former tarocub-deepseek-harness-plugin package name so they can be migrated without breaking managed bots.

Telegram (optional compatibility channel)

Create a Telegram bot with @BotFather, then run:

npm run dev -- telegram configure <telegram-bot-token>
npm run dev -- telegram yolo unsafe
npm run dev -- telegram service start

telegram yolo unsafe maps to approvalMode: "bypass": Codex uses its bypass sandbox mode, Claude Code/Antigravity use their unsafe skip-permissions modes, Kimi selects ACP auto, and DeepSeek selects Harness danger-full-access. Treat it as equivalent to bypassing normal approval prompts and local sandbox controls.

Send any message to the bot. It will reply with a pairing code:

npm run dev -- telegram access pair <pairing-code>

Surfaces

Core Highlights

Feature Map

Kimi Code engine

Select Kimi in either chat channel with /engine kimi (or use telegram engine kimi --instance <name> for a Telegram instance). The service resolves KIMI_EXECUTABLE first and otherwise falls back to ~/.kimi-code/bin/kimi; Kimi Code must already be authenticated locally. TaroCub uses the persistent kimi acp protocol, not prompt-mode text scraping.

Kimi supports streamed text/thought/tool events, /stop, tool approvals, multi-question and multi-select Lark/Telegram forms, /compact, model/effort/mode options, and /resume session scanning/selection. TaroCub loads instance and channel guidance through a workspace .kimi-code/agents/agent.md main-agent override that retains Kimi's ${base_prompt} and ${plugin_sections}. It also exposes local Codex skills to bridge-owned Kimi workspaces and injects the built-in Search MCP alongside Kimi's native MCP/plugins.

The current compatibility baseline is Kimi Code 2.0.1 with @agentclientprotocol/sdk 1.4.0. The public kimi acp entry point and packages/acp-server tree are unchanged from 2.0.0, while 2.0.1 does change internal permission, Hook-runner, Wire/history, media-tool, session-index, and workspace-watcher code. TaroCub's real adapter therefore re-verified the affected behavior rather than inferring compatibility from the entry point: new/list/load plus a resumed turn, an unanalyzable harmless Bash command under ACP yolo with zero approval requests, exactly one Hook start and terminal event for a background Bash task, Search MCP object output, a two-field multi-select form, cancellation followed by worker reuse, and image reading by both the main agent and a delegated subagent. Hook input event names and payloads consumed by TaroCub are unchanged; the upstream runner only adds telemetry and an internal errored result flag. No compatibility shim is required. Kimi 0.43's standard ACP form elicitation was verified end to end with two questions, including multi-select and distinct display labels/wire values. Older permission-style single-choice requests remain supported as a compatibility fallback. TaroCub always supplies the complete configured MCP list and fails closed if Kimi rejects session initialization; it does not retry by silently removing stdio search. Native Kimi user/project MCP files and plugins remain independent. Kimi 0.43 can defer MCP tool definitions, but the built-in Search MCP deliberately remains immediately discoverable rather than being deferred. Kimi 0.42 always enables its secondary-model pool, but without a [secondary_model] section subagents inherit the caller's model, so existing TaroCub instances do not need a new model setting. Kimi full-auto maps to ACP yolo; delegated terminal working directories are kept inside the real workspace, but this is not an OS sandbox. Explicit bypass maps to ACP auto. Starting with Kimi 0.41.0, auto is true Never Ask mode: dangerous and unanalyzable commands execute without interruption. New Kimi configurations therefore default to bridge full-auto / ACP yolo; use telegram yolo unsafe or /yolo unsafe only when fully unattended execution is intentional. Pre-0.41 Kimi bypass values without the new explicit Never Ask acknowledgement are also resolved as yolo; re-run the unsafe command to opt in under the new semantics.

Kimi 0.41.0 also allows AskUserQuestion(background=true) to outlive the foreground turn. TaroCub keeps those approval cards attached to the retained background task instead of aborting them with the completed turn, routes a late request through the hook-recorded question task even across a newer foreground turn, and aborts it on TaskStop, terminal WaitFor, worker teardown, or bounded expiry.

TaroCub implements the ACP terminal lifecycle used by Kimi for delegated Bash/process work (create, bounded UTF-8 output, wait, kill, and release), and cleans up unreleased terminals when a worker exits. KIMI_CODE_LEGACY_FLAG=1 remains a rollback escape hatch, not the recommended Bot configuration.

Kimi's plugin manager is not part of the ACP surface used by TaroCub. Optional official capabilities such as Kimi Computer Use and Kimi WebBridge must be installed or updated once in the local interactive Kimi TUI, then activated for the Bot with a fresh TaroCub session (/reset). Plugins are user-wide and may add browser/computer-control MCP servers, so TaroCub deliberately does not auto-install them.

With Kimi Code 0.32 or newer, TaroCub also installs an inert local hook plugin under KIMI_CODE_HOME and activates it only for bridge-owned ACP subprocesses. TaskStarted, background-task Notification, SubagentStop, TurnStarted, Stop, StopFailure, and Interrupt feed the existing run cards, worker retention, and restart guard. Kimi 0.33 introduced a completed-process review flow in a synthetic task-origin turn where it may inspect bad output and retry. TaroCub retains that autonomous ACP stream after the original user turn has ended, keeps intermediate process failures in the audit timeline without sending misleading failure cards, and delivers only Kimi's final reviewed conclusion. If no review turn arrives, a bounded fallback delivers the real task output; accepted relay events are drained before that fallback decides no review exists, and lost reviews expire instead of blocking that session forever.

Tool-result metadata remains the start-event fallback; terminal task tombstones reject late/duplicate start events, and detached Bash notices read the real bounded output.log tail from that Kimi session instead of showing only a generic completion title. Successful background output that explicitly ends with saved / wrote / generated plus a supported workspace artifact path is normalized into the shared file/image delivery layer; failed, missing, hidden, unsupported, or workspace-escaping paths remain plain text. Agents are also told to validate actual output rather than trust exit status, and to emit exact delivery tags instead of treating a saved path as delivery. Accepted hooks are drained before the ACP worker is destroyed, and timeline identity stays scoped by conversation, session, and task across ordinary messages, card actions, comments, and bus turns. The relay deliberately ignores SessionHeartbeat: it proves only that the Kimi process is alive, not that a turn or task is making progress. Existing Kimi credentials, sessions, skills, MCP servers, and config.toml are not replaced.

While detached work is retained, TaroCub never assumes that a quiet task is dead and never kills its ACP worker merely to apply model, effort, or instruction changes. Same-workspace non-security changes are deferred while later turns keep using the existing worker. Workspace and approval-mode changes fail closed until the task finishes (or the operator explicitly uses /reset); after terminal or six-hour safety expiry, the next turn applies the pending configuration normally.

The current Kimi ACP surface still does not expose structured per-turn token/cost usage, mid-turn steering, a direct client-supplied system-prompt field, or a /goal command; TaroCub reports those gaps instead of simulating support. See Kimi Engine Notes for protocol evidence and the Kimi Capability Matrix for Kimi's cross-engine release contract.

Telegram renders structured AskUserQuestion requests in one editable inline flow: multiple questions advance sequentially, while multi-select questions use toggle buttons plus an explicit Submit action. Kimi 0.43 now reaches that richer flow through ACP form elicitation; older Kimi permission callbacks still use the single-choice fallback.

DeepSeek Harness engine

Select DeepSeek in either channel with /engine deepseek (or use telegram engine deepseek --instance <name>). Install and authenticate dsh first; TaroCub resolves DSH_EXECUTABLE and otherwise uses dsh from PATH. The verified compatibility baseline is DeepSeek Harness 0.1.5-rc.1. This is also the npm latest version at the 2026-09-15 verification point. TaroCub has live-verified the authenticated mux, session-v2 projections, command attachment schema migration, and a streamed model turn. The npm next prerelease remains outside the supported baseline until it receives the same protocol probes.

Install the standalone native Harness bundle:

dsh plugin --profile web add github:cloveric/deepseek-harness-web-search-plugin

The shared web profile is linked into each private bot home, so the plugin is available in both ordinary Harness Web and TaroCub-backed sessions. It provides Search MCP directly, with optional /tarocub guidance. TaroCub validates the plugin marker, bundled entrypoint, and the Harness patch that registers the MCP client; if any part is absent or damaged, the private Host safely retains its built-in Search MCP fallback instead of registering two clients. Plugin activation remains separate from installing, configuring, or starting the Feishu/Lark bridge.

TaroCub owns a private loopback-only dsh web --no-open --host 127.0.0.1 --port 0 process per bot instance and uses Harness's official HTTP RPC plus the authenticated remote.mux WebSocket. Credentials and profiles are linked from the configured DSH_HOME, while mutable settings and bridge instructions remain isolated in the instance state directory. The forwarded event stream must become ready within 15 seconds, so a half-open or unauthenticated WebSocket cannot block startup forever. A crashed host is restarted and active sessions recover from ordered history/projection watermarks; incomplete or malformed recovery fails closed rather than silently skipping events.

View on GitHub