{"id":51160756,"url":"https://github.com/tao-ma/paige","last_synced_at":"2026-06-26T13:02:10.444Z","repository":{"id":360829037,"uuid":"1251215421","full_name":"Tao-Ma/paige","owner":"Tao-Ma","description":"Drive Claude Code from your chat app — bridges a claude CLI session in a tmux pane to a Feishu/Lark thread, with live streaming and tappable permission/option cards","archived":false,"fork":false,"pushed_at":"2026-05-28T02:13:26.000Z","size":563,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T04:10:46.103Z","etag":null,"topics":["ai-agents","chatops-bot","claude-code","feishu-bot","im-bridge","lark-bot","python","tmux"],"latest_commit_sha":null,"homepage":"","language":"Python","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/Tao-Ma.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-27T11:02:48.000Z","updated_at":"2026-05-28T02:13:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Tao-Ma/paige","commit_stats":null,"previous_names":["tao-ma/paige"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Tao-Ma/paige","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tao-Ma%2Fpaige","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tao-Ma%2Fpaige/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tao-Ma%2Fpaige/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tao-Ma%2Fpaige/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Tao-Ma","download_url":"https://codeload.github.com/Tao-Ma/paige/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Tao-Ma%2Fpaige/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34817641,"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-06-26T02:00:06.560Z","response_time":106,"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":["ai-agents","chatops-bot","claude-code","feishu-bot","im-bridge","lark-bot","python","tmux"],"created_at":"2026-06-26T13:02:10.192Z","updated_at":"2026-06-26T13:02:10.404Z","avatar_url":"https://github.com/Tao-Ma.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# paige\n\nDrive Claude Code from your chat app.\n\npaige bridges a running `claude` CLI session (inside a `tmux` pane on\nsome host) to an IM thread. You read Claude's stream on your phone,\ntap to answer permission prompts and option-pick questions, and\ntype replies that land in the pane as keystrokes. The pane keeps\nrunning when your laptop is asleep — paige catches up the next\ntime you open the chat.\n\nFeishu / Lark is the supported IM today. The `Channel` port keeps\nthe interface backend-agnostic, so other IMs can be added without\ntouching the rest of the codebase.\n\n## What you get\n\n- **Live streaming** of Claude's assistant text, tool calls, and\n  tool results into the thread as they happen.\n- **Coalesced fan-out cards** — a parallel agent launch renders as\n  one `🤖 Agents` card that ticks off as each subagent finishes, and\n  a burst of task-tool calls (`TaskCreate` / `TaskUpdate`) collapses\n  into one live `📋 Tasks` checklist — instead of a card per call.\n- **Inline option pickers** — when Claude asks you to pick from a\n  list (`AskUserQuestion`), the options render as tappable\n  buttons; tap one and it goes back as a keystroke.\n- **Pane-scrape interactive UI** — Bash-permission prompts,\n  edit/file permissions, `ExitPlanMode`, restore-checkpoint,\n  Settings overlays — all rendered as buttoned cards even though\n  Claude never lands them in JSONL.\n- **Slash commands** — `/start` (pick a project and bind a fresh\n  pane), `/sessions` (active / resume / archive / new chooser, with\n  archive-and-restore and per-session transcript view), `/history`\n  (paginated transcript), `/screenshot` (pane → image),\n  `/usage` (token / spend), `/server` (admin overview), plus\n  `/esc`, `/unbind`, `/help`.\n- **Voice transcription** via OpenAI (optional; only needed for IM\n  backends that don't pre-transcribe).\n- **Topic-mode group routing** (optional) — instead of one direct\n  message per pane, route each pane into its own Lark topic inside\n  a shared topic-mode group. Cleaner when driving several panes\n  at once.\n\n## Requirements\n\n- Linux or macOS host\n- Python ≥ 3.12\n- `tmux` (any recent version)\n- [Claude Code CLI](https://github.com/anthropics/claude-code)\n  installed and runnable as `claude`\n- A Feishu / Lark workspace with a custom app (App ID + Secret)\n\n## Quickstart\n\npaige is in early release (0.1.0). Install is via a release wheel\nplus a small lifecycle script.\n\n```bash\n# 1. Clone the repo\ngit clone https://github.com/Tao-Ma/paige\ncd paige\n\n# 2. Build the dev image (one-time)\n./do.sh build\n\n# 3. Build the wheel (runs inside the dev container)\n./do.sh artifact --export ~/.paige/wheels/\n\n# 4. First-time install on the host\ncp env.example ~/.paige/.env\n$EDITOR ~/.paige/.env   # fill in PAIGE_FEISHU_APP_ID + PAIGE_FEISHU_APP_SECRET\n./scripts/prod.sh upgrade ~/.paige/wheels/paige-*-py3-none-any.whl\n\n# 5. Confirm\n./scripts/prod.sh status\n./scripts/prod.sh logs -f\n```\n\nFull step-by-step (prerequisites, env reference, day-to-day ops,\nrollback) lives in [`INSTALL.md`](INSTALL.md). The lifecycle script\nauto-rolls back if a new wheel fails its health check.\n\n### Topic-mode group (optional)\n\nRun pane-per-topic in one shared Lark group instead of one DM per\npane. Two one-shot helpers seed the setup; both source\n`~/.paige/.env` for credentials.\n\n```bash\n# Create the topic-mode group (\"话题模式群\") + add yourself.\n# Prints PAIGE_FEISHU_GROUP_ID=oc_… for ~/.paige/.env.\n~/.paige/venv/bin/python scripts/create_topic_group.py --name paige\n\n# Add the printed line, then seed a permanent `general` topic.\n# Idempotent — re-running is a no-op once seeded.\n~/.paige/venv/bin/python scripts/seed_general_topic.py\n\n# Restart so paige picks up the new env.\n./scripts/prod.sh restart\n```\n\nInside that group, the `@bot` mention requirement is dropped (the\ngroup exists for bot interaction). New `/start` and `/sessions`\nflows used from within a topic create topic-scoped bindings; old\nDM bindings keep working. Full design notes —\nmode-switching, key disambiguation, routing semantics, known Lark\nquirks — live in [`doc/topic-mode.md`](doc/topic-mode.md).\n\n## Status\n\nFunctional and live-tested against real Feishu + real Claude Code.\nPre-1.0 — the public surface (slash commands, ports, env keys) may\nstill shift before v1. See [`CHANGELOG.md`](CHANGELOG.md) for the\n0.1.0 feature list.\n\n## How it works\n\n```\n   Claude Code (in tmux pane)\n        │ JSONL transcript          tmux key events\n        ▼                                 ▲\n   JsonlWatcher ─► Dispatcher ─► Outbox   │\n                       │                  │\n                       ▼                  │\n                  FeishuChannel ◄── Inbound (your reply)\n                       │                  ▲\n                       ▼                  │\n                    Lark / Feishu ────────┘\n```\n\nThe architecture is layered (`domain` / `ports` / `adapters` /\n`application` / `infrastructure` / `entrypoint`) with the layer\ngraph enforced by `import-linter`. Design decisions and rationale\nlive in [`doc/architecture.md`](doc/architecture.md) — read that\nbefore adding code.\n\n## Development\n\n```bash\n./do.sh build           # build the dev image (one-time)\n./do.sh ci              # ruff + pyright + import-linter + pytest\n./do.sh test            # pytest tests/unit (fast)\n./do.sh test-all        # unit + integration + e2e\n./do.sh shell           # interactive shell inside the dev container\n```\n\nEverything runs inside the `paige-dev` container — no host pip\ninstall needed. Contribution guidelines live in\n[`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## Layout\n\n```\nsrc/paige/\n  domain/         pure data + rules; no I/O.\n  ports/          Protocol interfaces.\n  adapters/       concrete implementations of ports.\n  application/    use cases that compose ports.\n  infrastructure/ config, logging, lifecycle.\n  entrypoint/     composition root + CLI.\ntests/\n  unit/           fast, no I/O. Default `pytest` runs only these.\n  integration/    real fs / libtmux. Slow, opt-in.\n  e2e/            full pipeline with mock_claude. Slow, opt-in.\n```\n\n## Credits\n\nThanks to [**six-ddc/ccbot**](https://github.com/six-ddc/ccbot) for\nthe core idea. The dual-channel pattern — reading Claude Code's\nJSONL transcript for structured events alongside `tmux capture-pane`\nfor state Claude doesn't write to JSONL — was ccbot's first;\npaige's `JsonlWatcher` + pane-scrape services are direct\ndescendants.\n\n## License\n\nMIT — see [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftao-ma%2Fpaige","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftao-ma%2Fpaige","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftao-ma%2Fpaige/lists"}