tarocub

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

TaroCub

Always-on personal AI bots like Grok Bot, OpenAI dots, and Meta Muse, but running on your own machine and living in Feishu/Lark.
They give every agent its own cloud computer. TaroCub gives it yours.
Each TaroCub bot is a real Codex, Claude Code, Kimi Code, DeepSeek Harness, or Antigravity agent running locally, with a Feishu identity of its own.
Message it like a teammate: send voice notes, files, and screenshots; get back documents, images, and finished work.
Feishu is the face. Mix engines freely and run as many bots as you want, with no per-bot fee.

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

What This Is

TaroCub turns the coding agents already on your computer into personal bots you talk to in Feishu/Lark. It is not a hosted agent product: every bot runs the real Codex, Claude Code, Kimi Code, DeepSeek Harness, or Antigravity CLI on your own machine, with your files, tools, and logins. TaroCub gives each one a durable chat identity: sessions you can resume from your phone, two-way file delivery, voice transcription, scheduled tasks, multi-bot routing, and audit logs. Telegram is 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.

Grok Bot, OpenAI dots, Meta Muse vs. TaroCub

_{Grok Bot, dots, and Muse are products of SpaceXAI (xAI), OpenAI, and Meta. TaroCub is an independent open-source project and is not affiliated with or endorsed by them.}

Meet the crew

The lion cub is TaroCub's mascot. Give every bot its own face: these hand-drawn avatars are transparent 512×512 PNGs in assets/avatars/ and work well as Feishu app icons.

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

Web Console and File Center

Start the local console from the repository checkout:

npm run dev -- ui

The command prints a one-time, token-bearing loopback URL such as http://127.0.0.1:<port>/?token=.... Open the complete URL in a browser, then select File Center. Keep the terminal process running while the page is in use; press Ctrl-C to stop it. The private package does not install a global cctb executable, so cctb ui is not a supported launch command.

The console has two views:

• Bot Config lists every local instance and edits the safe configuration subset with next-restart semantics.
• File Center scans configured bot state and workspaces, groups storage units by bot, type, status, size, and age, and supports search, filters, labels, notes, importance marking, and Finder reveal on macOS.

File Center is deliberately non-destructive. It highlights protected browser profiles, recently active paths, rebuildable environments, temporary content, and items that still need human judgment, but it never deletes, moves, archives, deduplicates, or automatically cleans files.

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.1.1 with @agentclientprotocol/sdk 1.4.0. The public packages/acp-server tree and Hook event surface consumed by TaroCub remain unchanged. TaroCub's real adapter re-verified new/list/load plus a resumed turn, cancellation followed by worker reuse, exactly one Hook start and terminal event for a background Bash task, Search MCP discovery, a two-field multi-select form, and external symlinked Skills. Kimi 2.1.1 rolls back 2.1.0's post-trust realpath restrictions, so the bridge-owned .kimi-code/skills link remains supported. Its restored default filesystem watchers are left enabled so native config, Skill, MCP, and instruction changes can reload while a persistent worker is alive. 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