{"id":50293124,"url":"https://github.com/cloveric/tarocub","last_synced_at":"2026-05-31T02:02:40.933Z","repository":{"id":350136081,"uuid":"1204857340","full_name":"cloveric/tarocub","owner":"cloveric","description":"TaroCub runs Codex, Claude Code, and Antigravity locally, then lets you control them from Telegram and Feishu/Lark.","archived":false,"fork":false,"pushed_at":"2026-05-28T07:21:24.000Z","size":11680,"stargazers_count":121,"open_issues_count":0,"forks_count":23,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-05-28T07:22:24.809Z","etag":null,"topics":["agent-bus","ai","anthropic","automation","claude-code","cli","codex","developer-tools","feishu","lark","lark-cli","multi-agent","openai-codex","session-management","tarocub","telegram-bot","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloveric.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-boundaries.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-08T11:59:19.000Z","updated_at":"2026-05-28T07:21:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cloveric/tarocub","commit_stats":null,"previous_names":["cloveric/cc-telegram-bridge","cloveric/tarocub"],"tags_count":143,"template":false,"template_full_name":null,"purl":"pkg:github/cloveric/tarocub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloveric%2Ftarocub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloveric%2Ftarocub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloveric%2Ftarocub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloveric%2Ftarocub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloveric","download_url":"https://codeload.github.com/cloveric/tarocub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloveric%2Ftarocub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33716339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-bus","ai","anthropic","automation","claude-code","cli","codex","developer-tools","feishu","lark","lark-cli","multi-agent","openai-codex","session-management","tarocub","telegram-bot","typescript"],"created_at":"2026-05-28T07:02:10.555Z","updated_at":"2026-05-31T02:02:40.927Z","avatar_url":"https://github.com/cloveric.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eEnglish\u003c/strong\u003e\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;\u003ca href=\"./README.zh-CN.md\"\u003e\u003cstrong\u003e中文文档\u003c/strong\u003e\u003c/a\u003e\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;\u003ca href=\"./docs/full-reference.md\"\u003e\u003cstrong\u003eFull Reference\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/github-banner.png\" alt=\"TaroCub: local AI agents controlled from Telegram and Feishu/Lark\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/cloveric/tarocub/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/cloveric/tarocub?style=flat-square\u0026color=818cf8\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=flat-square\u0026logo=node.js\u0026logoColor=white\" alt=\"Node.js \u003e= 20\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-5.9-3178c6?style=flat-square\u0026logo=typescript\u0026logoColor=white\" alt=\"TypeScript\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/engines-Codex%20%7C%20Claude%20Code%20%7C%20Antigravity-F97316?style=flat-square\" alt=\"Codex | Claude Code | Antigravity\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/channels-Telegram%20%7C%20Feishu%2FLark-2563eb?style=flat-square\" alt=\"Telegram | Feishu/Lark\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eTaroCub\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eRun Codex, Claude Code, and Antigravity locally. Control them from Telegram and Feishu/Lark.\u003c/strong\u003e\u003cbr\u003e\n  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.\u003cbr\u003e\n  Resume local sessions anytime from your phone, whether you are at your desk, commuting, or walking the dog.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"#surfaces\"\u003eSurfaces\u003c/a\u003e\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"#core-highlights\"\u003eCore Highlights\u003c/a\u003e\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"#lark-setup\"\u003eLark Setup\u003c/a\u003e\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"#operator-commands\"\u003eCommands\u003c/a\u003e\u0026nbsp;\u0026nbsp;|\u0026nbsp;\u0026nbsp;\n  \u003ca href=\"#docs\"\u003eDocs\u003c/a\u003e\n\u003c/p\u003e\n\n## What This Is\n\n`TaroCub` is a local bridge, not a hosted agent product. It runs the real Codex, Claude Code, and Antigravity CLIs on your own computer, then gives them a durable messaging control surface across Telegram and Feishu/Lark.\n\nThis 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.\n\nIt is built for people who already use CLI agents heavily and want:\n\n- phone-first operation through Telegram and Feishu/Lark;\n- Feishu/Lark-native operation with cards, Docs comments, Sheets, and group workflows;\n- durable state for sessions, cron jobs, file delivery, usage, timelines, audit logs, and multi-agent routing.\n\nThe intended setup flow is agent-assisted: clone the repo, open it in Codex, Claude 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.\n\nThe old long README is preserved as [Full Reference](./docs/full-reference.md). This landing page is intentionally short.\n\n## Quick Start\n\n### Recommended: ask your local agent to configure it\n\nOpen this repository in Codex, Claude Code, or Antigravity and say:\n\n```text\nRead the README and configure TaroCub for me.\nUse this Telegram bot token: \u003cpaste token\u003e\nEnable YOLO mode for my personal bot instance.\n```\n\nFor Lark, say:\n\n```text\nRead the README and configure the Feishu/Lark bot for me.\nRun the Lark wizard, check permissions, install/bind lark-cli, and tell me what I need to scan or approve.\n```\n\nThat is the preferred path. Manual commands are still below for operators who want to see each step.\n\n### Telegram\n\nCreate a Telegram bot with [@BotFather](https://t.me/BotFather), then run:\n\n```bash\ngit clone https://github.com/cloveric/tarocub.git\ncd tarocub\nnpm install\nnpm run build\n\nnpm run dev -- telegram configure \u003ctelegram-bot-token\u003e\nnpm run dev -- telegram yolo on\nnpm run dev -- telegram service start\n```\n\n`telegram yolo on` is the recommended default for a personal, trusted bot instance. It lets Codex, Claude Code, and Antigravity keep moving without asking for approval on every turn. Use `telegram yolo unsafe` only for fully trusted local workspaces, and use `telegram yolo off` when you explicitly want approval prompts.\n\nSend any message to the bot. It will reply with a pairing code:\n\n```bash\nnpm run dev -- telegram access pair \u003cpairing-code\u003e\n```\n\nYou can now talk to your local CLI agent from Telegram.\n\n### Feishu / Lark\n\nFor the full Lark-native setup, let the aggregate setup command install/bind `lark-cli \u003e= 1.0.41`, run the QR wizard, provision permissions, and check the app:\n\n```bash\nnpm install\nnpm run build\n\nnode dist/src/index.js lark setup --install-cli --identity bot-only\nnode dist/src/index.js lark service start\n```\n\nIf `lark doctor` reports missing app scopes, copy the JSON it prints into the Feishu/Lark app permission page, publish the app version, then run:\n\n```bash\nnode dist/src/index.js lark provision\nnode dist/src/index.js lark doctor\n```\n\n## Surfaces\n\n| Surface | Best for | Status |\n|---|---|---|\n| **Telegram** | Mobile control, voice input, file delivery, multi-bot operations, cron, Agent Bus | Primary and deepest-tested |\n| **Feishu/Lark** | Team chat, interactive cards, Docs comments, Sheets/Docs/Drive workflows, group/thread workflows | Production-capable with `lark-cli` |\n| **Local CLI** | Operations, setup, debugging, status, backups, direct sends | First-class operator interface |\n\n## Core Highlights\n\n| Highlight | Why it matters |\n|---|---|\n| **Real CLI engines, not a fake chat backend** | Codex, Claude Code, and Antigravity run as their native local CLIs, so your real auth, local files, project instructions, MCP/plugins, and engine behavior stay intact. |\n| **Session Resume** | Continue existing work instead of starting over: Claude local sessions, Codex threads, and Antigravity conversations can be attached from chat and detached later. |\n| **Telegram as a mobile control plane** | Talk to agents from your phone, send files and screenshots, record voice messages, approve work, stop stuck turns, inspect status, and restart instances. |\n| **Feishu/Lark as a native work surface** | Lark adds what Telegram cannot: Card 2.0 choices, approval cards, Docs comment @mentions, Sheets/Docs/Drive workflows through `lark-cli`, `/newgroup`, and thread-aware group work. |\n| **ASR for voice/audio/video** | Telegram and Lark voice/audio/video resources can be downloaded, locally transcribed, and passed into the engine as normal task context. |\n| **File and artifact delivery** | Agents can return generated images, PDFs, reports, decks, source bundles, and other files through structured `send.file`, `send.image`, `send.batch`, audio, and video tags. |\n| **Scheduled work and reminders** | `/cron` and `cron.add` persist one-shot reminders, recurring jobs, and agent-run scheduled tasks outside model memory, with chat/thread routing preserved. |\n| **Agent Bus** | Multiple bot instances can call each other as local workers for delegation, fan-out, chain, verifier, and coordinator-led crew workflows. |\n| **Mini Bus** | Telegram topics or Lark threads can become lightweight named peers, so one group can run planner/writer/reviewer-style workflows without separate bots. |\n| **Board** | Durable Kanban state for tasks, dependencies, WIP, review gates, and execution history, instead of relying on a model to remember project state. |\n| **Search MCP** | Optional Brave/Tavily MCP gives source-traceable `web_search`, `web_extract`, provider status, fallback notices, and source logs. |\n| **Operational visibility** | `status`, `doctor`, `timeline`, `audit`, `dashboard`, usage tracking, service locks, and backups make failures inspectable instead of mysterious. |\n\n## Feature Map\n\n| Feature | Telegram | Feishu/Lark | Local CLI |\n|---|---:|---:|---:|\n| Codex / Claude Code / Antigravity engines | Yes | Yes | Yes |\n| Session resume / detach | Yes | Yes | Yes |\n| Voice, audio, and video ASR | Yes | Yes | Inspect/debug |\n| File and image delivery | Yes | Yes | `telegram send` / `lark send` |\n| Stop and approvals | Inline buttons | Interactive cards | Service controls |\n| Plan Mode-style choices | Limited buttons | Rich choice cards | Tool/debug path |\n| Cron reminders and agent jobs | Yes | Yes | Manage/list/run |\n| Board durable tasks | Yes | Yes | Inspect/export |\n| Agent Bus fan/chain/verify | Yes | Yes | Configure peers |\n| Mini Bus topic/thread workflows | Telegram topics | Lark threads | Inspect state |\n| Docs comments and Sheets workflows | Not applicable | Yes, with `lark-cli` | Provision/auth/doctor |\n| Timeline, audit, dashboard, usage | Yes | Yes | Primary ops surface |\n\n## Lark Setup\n\nLark has two levels:\n\n| Level | What works |\n|---|---|\n| **SDK transport only** | Long-connection receive/send, access checks, ordinary replies, stop/approval cards, media intake. |\n| **Full Lark-native mode** | Docs/Drive/Calendar/Sheets actions, `/newgroup`, document creation/auto-grant, user OAuth, richer agent workflows. Requires `lark-cli \u003e= 1.0.41`. |\n\nRecommended production flow:\n\n```bash\n# Optional but recommended for each named Lark bot:\nexport CCTB_LARK_INSTANCE=ccfgg1\n\nnode dist/src/index.js lark setup --install-cli --identity bot-only\nnode 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\"\nnode dist/src/index.js lark auth finish \u003cdevice-code\u003e\nnode dist/src/index.js lark service restart\n```\n\n`CCTB_LARK_INSTANCE=\u003cname\u003e` is the Lark-specific instance selector. Without an explicit `CCTB_LARK_STATE_DIR`, it stores that bot under `~/.cctb/\u003cname\u003e/lark.env`, so multiple Feishu/Lark bots do not fall back into the shared default `~/.cctb/lark` directory.\n\n`lark setup` wraps the QR wizard, lark-cli preflight/bind, app provisioning, OAuth status check, and `lark doctor`. 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`.\n\nUseful Lark commands:\n\n```bash\nnode dist/src/index.js lark setup --install-cli\nnode dist/src/index.js lark status\nnode dist/src/index.js lark permissions --missing\nnode dist/src/index.js lark access pair \u003ccode\u003e\nnode dist/src/index.js lark send --chat oc_xxx --message \"hello\"\nnode dist/src/index.js lark timeline 20\nnode dist/src/index.js lark dashboard\n```\n\nInside Lark, the bot supports the same core slash surface as Telegram: `/status`, `/usage`, `/engine`, `/model`, `/effort`, `/fast`, `/yolo`, `/goal`, `/resume`, `/detach`, `/stop`, `/reset`, `/cron`, `/board`, `/mini`, `/fan`, `/chain`, `/verify`, `/group`, `/newgroup`, `/newtopic`, and `/continue`.\n\n## Operator Commands\n\n### Telegram\n\n```bash\ntelegram service start --instance work\ntelegram service restart --all\ntelegram service status --all\ntelegram engine codex --instance work\ntelegram yolo on --instance work\ntelegram usage --instance work\ntelegram timeline --instance work\ntelegram dashboard --instance work\ntelegram backup --instance work --out ./work.cctb.gz\n```\n\n### Lark\n\n```bash\nlark service start\nlark service restart\nlark doctor\nlark access status\nlark cli identity status\nlark auth status --verify\nlark send --chat oc_xxx --message \"hello\"\n```\n\n### In-chat slash commands\n\nSee the full [Slash Command Index](./docs/slash-commands.md) for command groups, Telegram/Lark support, and examples.\n\n## Current Release\n\n- **v0.1.0** — resets the public product to **TaroCub**, renames the GitHub/package surface, adds the product thesis to the banner, and keeps `cctb` plus old state paths as compatibility surfaces.\n- **v4.6.70** — transitional release that introduced the TaroCub family name before the full product reset.\n- **v4.6.69** — makes Lark setup more self-healing: when user OAuth is missing, setup now prints the recommended Docs/Drive/Sheets auth command, and the docs clarify that `user-default` no longer force-rebinds existing lark-cli sessions.\n- **v4.6.68** — deepens Lark-native reliability: safe running reactions, native @name resolution, card-to-text fallback, one-shot `lark setup`, clearer permission repair, and safer lark-cli binding that will not wipe user OAuth.\n- **v4.6.67** — closes a Lark runtime secret-boundary gap: runtime `lark-cli` child processes now get `LARK_CHANNEL=1` without inheriting `LARK_APP_SECRET`.\n\nSee [GitHub Releases](https://github.com/cloveric/tarocub/releases) for the full changelog.\n\n## Safety Model\n\nThe bridge is powerful because it controls local CLIs. Treat it like local automation, not a sandboxed SaaS bot.\n\n- Run it only on machines and workspaces you trust.\n- Use access pairing/allowlists before exposing private or group chats.\n- Use YOLO/full-auto only for trusted instances.\n- Keep app secrets in bridge state, not prompts, argv, or child-process env.\n- Use `doctor`, `timeline`, `audit`, and `dashboard` before guessing at failures.\n\nMore detail: [Security Boundaries](./docs/security-boundaries.md), [State Model](./docs/state-model.md), and [Full Reference](./docs/full-reference.md).\n\n## Docs\n\n| Need | Link |\n|---|---|\n| Complete old README / full operations reference | [docs/full-reference.md](./docs/full-reference.md) |\n| Release process | [docs/release-checklist.md](./docs/release-checklist.md) |\n| Runtime architecture notes | [docs/architecture-notes.md](./docs/architecture-notes.md) |\n| State files and persistence | [docs/state-model.md](./docs/state-model.md) |\n| Security model | [docs/security-boundaries.md](./docs/security-boundaries.md) |\n| Agent Bus protocol | [docs/bus-protocol.md](./docs/bus-protocol.md) |\n| Search MCP setup | [docs/search-mcp.md](./docs/search-mcp.md) |\n| Runtime env troubleshooting | [docs/runtime-env-troubleshooting.md](./docs/runtime-env-troubleshooting.md) |\n\n## Development\n\n```bash\nnpm install\nnpm run build\nnpm test -- --run\n```\n\nThe project is TypeScript, Node.js \u003e= 20, and Vitest. It stores runtime state under `~/.cctb/\u003cinstance\u003e` for Telegram instances, `~/.cctb/lark` for the default Lark state dir, or `~/.cctb/\u003cCCTB_LARK_INSTANCE\u003e` for named Lark bots.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloveric%2Ftarocub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloveric%2Ftarocub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloveric%2Ftarocub/lists"}