English  |  中文文档  |  Full Reference

TaroCub

A Feishu/Lark-first gateway for Codex, Claude Code, Kimi Code, 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.

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, 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, 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, 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, bulk-import the JSON it prints, publish the app version, then run:

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

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, and Kimi selects ACP auto mode. 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, single-choice Lark and Telegram questions, /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 0.37.2. Its default agent-core-v2 ACP path has been live-probed with native tools, session creation/resume, detached-task hooks, and ACP terminal delegation. TaroCub now 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 0.37.2 also has a narrow upstream stdio-MCP identity regression: it can reject the schema-valid stdio entry after the ACP SDK removes a non-schema type discriminator. TaroCub retries only that exact error without injected stdio MCPs, keeps HTTP/SSE and native Kimi MCP/plugins intact, and probes again after every Kimi process restart so a future upstream fix restores stdio MCPs automatically. 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 the four-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's current ACP permission protocol still advertises only one single-choice question at a time; the richer flow applies when an engine such as Claude supplies it.

Lark Setup

Lark has two levels:

Recommended production flow:

# Optional but recommended for each named Lark bot:
export CCTB_LARK_INSTANCE=ccfgg1

node dist/src/index.js lark setup --detached --install-cli --identity bot-only
node dist/src/index.js lark yolo unsafe
node dist/src/index.js lark auth start --recommend --domain docs,drive --scope "sheets:spreadsheet:create sheets:spreadsheet:write_only sheets:spreadsheet:read sheets:spreadsheet.meta:read"
node dist/src/index.js lark auth finish <device-code>
node dist/src/index.js lark service restart

CCTB_LARK_INSTANCE=<name> is the Lark-specific instance selector. Without an explicit CCTB_LARK_STATE_DIR, it stores that bot under ~/.cctb/<name>/lark.env, so multiple Feishu/Lark bots do not fall back into the shared default ~/.cctb/lark directory.

lark setup wraps the QR wizard, lark-cli preflight/bind, app provisioning, OAuth status check, lark doctor, and service start for new apps. Use --detached for chat-driven setup so the QR wizard keeps running after the current agent turn ends. If you already created the app and only want to re-check the local side, use node dist/src/index.js lark setup --skip-wizard --install-cli --identity bot-only. Add --start-service to that re-check command if you also want it to start/restart the listener.

Useful Lark commands:

node dist/src/index.js lark setup --detached --install-cli
node dist/src/index.js lark status
node dist/src/index.js lark permissions --missing
node dist/src/index.js lark access pair <code>
node dist/src/index.js lark send --chat oc_xxx --message "hello"
node dist/src/index.js lark timeline 20
node dist/src/index.js lark dashboard

Inside Lark, the bot supports the same core slash surface as Telegram: /status, /usage, /engine, /model, /effort, /fast, /goal, /resume, /detach, /stop, /reset, /cron, /board, /mini, /fan, /chain, /verify, /group, /invite, /remove, /ws, /newgroup, /newtopic, and /continue — plus the Lark-only /yolo, /q, /config, /stream, /steer, /bg, /account, and /approve-session.

Lark group/session semantics:

Whether a Lark group isolates each topic into its own session follows the group's message form (the "Group message form" setting in Lark) — read from im.v1.chat.get and cached for ~30s, so switching the form takes effect within ~30s without a service restart:

• "Isolated" means a topic's context does not bleed into other topics or the group's main timeline. "Shared" means a topic reply continues the group's single session.
• A thread conversation key is lark:<chat_id>:<thread_id>; a main 1:1 timeline or shared conversation-group key is lark:<chat_id>. A private thread isolates whenever Lark supplies thread_id; a group thread isolates only when the group uses topic message form.
• chat_mode alone cannot tell a toggled topic group (chat_mode = group + group_message_type = thread) from a plain conversation group, so group_message_type is the decisive signal.
• /invite group and /group allow authorize the current group, not only the current thread. /remove group and /group deny remove the current group authorization.
• /newgroup <name>, /newgroup topic <name>, and /newtopic <name> use the instance bot by default and invite the requester; explicit user-OAuth mode creates as the OAuth user instead. Both paths ensure the instance bot joins and automatically authorize the new group. They do not enable listen-all: the safer @bot trigger remains until /group all is sent inside that group.
• Group reply mode is per-group. By default the bot replies in a group only when it is @-mentioned. /group all opts a single group into replying to ordinary (non-@) messages too — handy for a private, you-only project group — and needs the app's im:message + im:message.group_msg scopes. /group at returns that one group to mention-required, and /group status shows its current mode. These switches are per-group and never affect other groups.
• Access is still enforced per user in groups: even under /group all, only an authorized user (paired, or on the allowlist) can drive the bot — a newly added member cannot. So when a private group gains other people, /group at is the clean lock: the bot then silently ignores every non-@ message instead of replying.
• known-chats.json is diagnostic metadata for /status, /config, and dashboard labels. It never decides routing or access by itself.

Lark-native controls:

• Long-running Lark turns now send a native progress card and update it with thinking, tool calls, background notifications, and final result. The final plain reply is still delivered, so existing workflows do not depend on cards.
• Same-conversation messages still use conservative FIFO queueing by default. Optional preempt/batch behavior is off unless explicitly enabled with CCTB_LARK_QUEUE_MODE=preempt, batch, or preempt-batch; batch windows can be tuned with CCTB_LARK_BATCH_WINDOW_MS=<ms>.
• /config shows access and workspace guidance in the card. /invite group, /remove group, /invite user @person, and /remove user @person remain the safe in-chat access controls.
• /ws list, /ws save <name> [absolute-path], /ws use <name>, and /ws remove <name> manage saved Lark workspace directories. /ws use resets the current conversation binding so a workspace switch does not silently keep stale project context.

Operator Commands

Lark

lark service start
lark service restart
lark service restart --all
lark doctor
lark service status --all
lark access status
lark cli identity status
lark auth status --verify
lark send --chat oc_xxx --message "hello"

When lark service restart --all is run from inside an active Lark turn, the current Lark instance is deferred and restarted last so the reply can finish before the bot stops its own process. Avoid hand-rolled shell loops that restart Lark instances from inside a Lark bot.

Telegram (optional compatibility channel)

telegram service start --instance work
telegram service restart --all
telegram service status --all
telegram engine codex --instance work
telegram yolo unsafe --instance work
telegram usage --instance work
telegram timeline --instance work
telegram dashboard --instance work
telegram backup --instance work --out ./work.cctb.gz

In-chat slash commands

The complete command surface, grouped. Unless marked Lark, commands work on both channels. (Same list with examples: Slash Command Index.)

Sessions & tasks

Settings

Groups & access

Scheduled & durable work

Multi-agent

Context utilities & approvals

Long-audio Cloud ASR

Short audio is transcribed by the local Qwen ASR. Audio/video at or above the threshold (default 15 minutes) is routed to Aliyun Tongyi Tingwu through the operator's standalone python script; any cloud failure falls back to chunked local transcription. Recordings sent as ordinary Telegram documents or Lark files enter the same router based on their declared filename or downloaded path. This routing runs at the channel layer, before engine selection, so Claude, Codex, Kimi, and Antigravity receive the same transcript behavior. A promoted media file whose transcription fails or returns empty is still passed to the engine with an explicit bridge fallback note. /stop aborts the bridge-side local HTTP wait or terminates CLI/chunking/cloud work, and never starts a fallback after cancellation. The local HTTP server may still finish an already-running model kernel before it notices that its client disconnected.

Where to set them. On Lark, put them in ~/.cctb/<instance>/lark.env — they are read through the whitelisted config channel (loadLarkRuntimeEnv, the same one that carries LARK_APP_ID), and a service start preserves them when it regenerates the file. They can also be exported in the service process environment, which wins over the file.

Note the distinction inside lark.env: these four ride the whitelist, not the extras passthrough. The passthrough (which forwards engine credentials such as IFIND_TOKEN into the engine child) refuses every reserved bridge namespace — CCTB_, TAROCUB_, LARK_, CODEX_, CLAUDE_, KIMI_, ANTIGRAVITY_, ASR_, TELEGRAM_, TINGWU_ — precisely because those control the bridge's own behavior (TINGWU_ASR_DIR names a directory the bridge executes a script from), so an engine-written extra can never redirect it. The only KIMI_ extras admitted are the explicit credential allowlist: KIMI_API_KEY, KIMI_MODEL_API_KEY, KIMI_REGISTRY_API_KEY, KIMI_WEB_FETCH_API_KEY, and KIMI_WEB_SEARCH_API_KEY; endpoint, OAuth-host, custom-header, home, marketplace, and future unknown controls remain blocked. A refused extra is logged at startup as [lark] lark.env: ignored bridge-reserved keys ….

Secrets stay outside any engine workspace. The Tingwu script loads its own Aliyun credentials from its .env.local; the bridge never reads, copies, or logs them. Keep that directory outside every engine workspace — the convention on this machine is ~/.tarocub-secrets/tingwu_asr — so an agent working in ~/.cctb/<instance>/workspace cannot read, commit, or exfiltrate the credentials.

Safety Model

The bridge is powerful because it controls local CLIs. Treat it like local automation, not a sandboxed SaaS bot.

• Run it only on machines and workspaces you trust.
• Use access pairing/allowlists before exposing private or group chats.
• Use YOLO unsafe/bypass only for trusted instances; it intentionally bypasses normal approval prompts and sandbox restrictions.
• Keep app secrets in bridge state, not prompts, argv, or child-process env.
• Use doctor, timeline, audit, and dashboard before guessing at failures.
• Telegram/Lark can share an optional machine-wide AI worker pool when you set TAROCUB_MAX_CONCURRENT_TURNS=<n>; it is off by default, and 0/off keeps it disabled. Agent Bus independently limits each process to 8 active /api/talk delegations and returns retryable server_busy when saturated. Lark same-conversation preempt/batch is also off by default; opt in with CCTB_LARK_QUEUE_MODE=preempt|batch|preempt-batch.
• Telegram and Lark refuse credential-shaped files such as .env*, *.pem, *.key, id_rsa, and id_ed25519 even when they are inside an otherwise allowed workspace. Telegram inbound attachments are pruned after 3 days by default; set TELEGRAM_INBOUND_FILE_RETENTION_DAYS to change the retention window.
• Lark records service.health events and reconnect attempts when health probes fail; telemetry adapters receive ws_reconnect, pool_active, pool_waiting, run_e2e_ms, token, cost, and error metrics when configured.
• Lark keeps a local known-chats.json cache so /status, /config, and dashboard can show friendly chat names instead of only opaque chat IDs.
• Optional local observability can be loaded with TAROCUB_TELEMETRY_MODULE=/abs/path/adapter.mjs; telemetry failures are swallowed so they cannot break user turns.

More detail: Security Boundaries, State Model, and Full Reference.

Release Contract

In this repo, "commit and release" is not done at a GitHub tag alone. A complete TaroCub release means: commit the intended changes, create/update the GitHub Release, then restart and verify the local Telegram and Lark fleet. Keep external package-registry publishing out of the release flow.

Use docs/release-checklist.md as the source of truth for release verification. For Lark fleet restarts, use node dist/src/index.js lark service restart --all rather than manual per-instance loops.

Docs

Development

npm install
npm run build
npm test -- --run

The project is TypeScript, Node.js >= 20, and Vitest. It stores runtime state under ~/.cctb/<instance> for Telegram instances, ~/.cctb/lark for the default Lark state dir, or ~/.cctb/<CCTB_LARK_INSTANCE> for named Lark bots.

License

MIT