# π©οΈ agent-takkub
### Your AI dev team β in one desktop cockpit.
**Prompt one _Lead_ agent. It plans the work, splits it across specialist teammates, runs them in parallel as real `claude` processes, and verifies the result β while you watch and steer.**
[](https://www.npmjs.com/package/agent-takkub)
[](https://www.npmjs.com/package/agent-takkub)
[](https://github.com/takkub/agent-takkub/blob/main/LICENSE)
[](https://github.com/takkub/agent-takkub)
```bash
npm install -g agent-takkub
```
100% local Β· runs on **your** logged-in Claude Code CLI Β· no SaaS middleware
---
## π₯οΈ The Desktop Cockpit
One window: you talk to the Lead, and it spawns and drives specialist teammates (frontend Β· backend Β· qa Β· reviewer Β· devops Β· β¦) as live Claude Code panes.
---
## β¨ Why agent-takkub?
A single AI agent hits a wall on big work: context fills up, sub-tasks collide, and everything runs one-at-a-time. `agent-takkub` runs it like a **real engineering team** β a **Lead** you talk to, and specialist teammates it delegates to, each in its own isolated `claude` process, working **concurrently**.
### Orchestration
| | |
| :-- | :-- |
| π§ **Orchestrated teammates** | Converse with the Lead; it spawns, tasks, and manages specialist panes (`frontend`, `backend`, `qa`, `reviewer`, `devops`, `mobile`, β¦) on demand β only the roles a job actually needs. |
| π **True parallelism** | `frontend` and `backend` build a feature at the same time; QA always verifies **last**, against the real running stack. |
| πΏ **Branch & worktree isolation** | Parallel teammates each work on their own git branch in an isolated worktree β no commit races, no dirty-state collisions. You merge when ready. |
| π₯ **Fleet mode** | One toggle scales a role into a fleet (`frontend#1β¦#K`) sized to your machine β for many independent features or sharded test suites at once. |
| π§ **Plan-first shards** | `takkub assign --role qa --plan --shards N` β a planner splits a big browser-QA sweep into N buckets before fanning out, instead of guessing an even split. |
| π₯οΈ **Steerable, always** | Every pane is a live `claude` shell. Watch output in real time, interrupt, or type straight into any teammate. |
| ποΈ **Multi-project tabs** | One isolated Lead per project β no cross-talk. |
| π **100% local** | No SaaS middleware. Everything runs on your machine, on your logged-in Claude Code CLI. |
### Token efficiency & memory
| | |
| :-- | :-- |
| π₯ **Pull-on-demand context** | Reference docs, patterns, and CLI cheatsheets live outside the Lead's default prompt β it reads them only when a task needs them, instead of paying for them on every turn. |
| π§Ύ **Per-role memory + L2 archive** | Each teammate keeps a short, token-budgeted "learned notes" file; entries that get trimmed for space are archived (not deleted) to a searchable sibling file instead of being lost. |
| π **BM25 search (`takkub search`)** | Full-text search over session logs and role-memory archives, ranked with Okapi BM25 β tokenizes both English words and Thai character trigrams, no external segmenter. |
| β
**Evidence-gated QA/review** | A verify role's "done" report is checked for actual evidence (a file, a test run, an exit code) β reports with no evidence cited get flagged for the Lead instead of trusted at face value. |
| 𧬠**Structural code-intelligence (`graft`)** | Symbol search, call-graph tracing, and signatures-only file views wired into code-reading roles (frontend/backend/mobile/devops/qa/reviewer/critic) β no LLM call, ~92% smaller than reading a large file whole. Fully optional: install with `takkub doctor --fix` (needs Node β₯ 20); a pane never gets the extra tools unless a project's graph has actually finished building. The graph lives outside the repo (`~/.agent-takkub/graft-graphs`, never committed); disable entirely with `TAKKUB_SKIP_GRAFT_BUILD=1`. |
### Reliability & diagnostics
| | |
| :-- | :-- |
| π©Ί **`takkub doctor --live`** | Checks the running cockpit's spawn queue, CPU/RAM governor, resource waits, PTY queue depth, stale-write drops, and remote mirror β catches live wedges that config-only checks cannot see. |
| π‘οΈ **Reliability v2** | Delivery IDs, pane-session generations, TTL, single-flight submission, bounded priority PTY queues, fair heavy-work admission, adaptive hidden-pane rendering, durable completion dedupe, and Windows Job Object cleanup. |
| β¨οΈ **Multiline input that just works** | Shift+Enter / Alt+Enter add a newline instead of submitting, provider-aware (works on claude/gemini panes; skipped where the underlying TUI would misinterpret it) β includes a macOS IME fix for Thai/CJK input dropped after switching input languages. (community contribution by [@than-aa](https://github.com/than-aa)) |
---
## π§ One team, many model "brains"
Model diversity beats a single point of view. Takkub lets the Lead pull in a **second, third β or sixth** brain for planning, review, and cross-checks, and it never breaks if you don't have them installed.
| Brain | Backed by | Great at |
| :-- | :-- | :-- |
| π£ **Claude** | Claude Code CLI | The Lead + every specialist β build, test, review |
| π’ **Codex** | OpenAI Codex CLI | Second opinion Β· refactor patterns Β· cross-checking a plan |
| π΅ **Gemini** | Google Antigravity (`agy`) | Long-context planning (reads the whole repo) Β· a third perspective |
| π **OpenCode** | sst OpenCode | One CLI, 75+ model backends (GLM Β· DeepSeek Β· local Ollama β¦) |
| β« **Cursor** | Cursor CLI (`cursor-agent`) | Pick per-task from Cursor's own model roster |
**Pick the model, not just the CLI.** Every provider β and every *role* β can be pinned to a specific model from **Settings β Providers & Roles**, or from the terminal:
```bash
takkub provider model gemini "Gemini 3.1 Pro (High)" # this CLI spawns with that model
takkub provider list # who's installed, and on which model
```
A role's own model wins over the provider default, so `backend` can run Codex on `gpt-5.6` while `reviewer` runs it on something cheaper.
> **Never a hard dependency.** If a provider isn't installed (or you've toggled it off), the Lead keeps the role β **Claude transparently stands in**, and tells you you've traded away model diversity. No refusals, no dead ends.
> β οΈ **Cursor is new in 1.0.27** β they spawn and take tasks, but its idle/busy screen markers are not calibrated yet, so prefer Claude/Codex/Gemini/OpenCode for roles you leave unattended.
---
## β‘ Quick Start
```bash
# 1. Install the cockpit globally (isolated Python runtime + a Desktop icon)
npm install -g agent-takkub
# 2. Authenticate with your Claude account (if you haven't already)
claude login
# 3. Provision recommended plugins + browser-automation tools (idempotent)
takkub provision
```
> β οΈ **Install it globally β the `-g` flag matters.** It provisions the isolated runtime and the Desktop launcher. A plain `npm install agent-takkub` (no `-g`) will **not** set the app up.
Then **double-click βTakkub Cockpitβ** on your Desktop β or launch from a terminal:
```bash
agent-takkub
```
|
**Requirements** β Node.js β₯ 18 and Python β₯ 3.11 already on your system. They're **detected, never reinstalled**. Everything else lives in an isolated `~/.agent-takkub`; your existing `claude` CLI, plugins, and config are left completely untouched.
**Optional: `graft` code-intelligence** needs Node β₯ 20 β stricter than the cockpit's own Node β₯ 18 floor. It's off until you run `takkub doctor --fix`; without it (or on Node 18β19), the cockpit runs exactly the same, just without the extra structural-search tools for code-reading roles.
|
---
## π¦ Two ways to run: 1:1 or a whole team
A chip in the status bar flips how the Lead works:
- **π€ 1:1 (default)** β one agent per role, one feature at a time. Focused and predictable.
- **π₯ Multi** β hand the Lead several independent features and it **fans out** into multiple instances per role (`frontend#1β¦#K`, `backend#1β¦#K`) running at once, like a team of several devs per position. Finishes fast.
Dependent work stays sequential automatically; **QA is always the final gate**, run against the real stack.
---
## π Orchestration Flow
```mermaid
sequenceDiagram
actor User
participant Lead as Lead Agent
participant Cockpit as Cockpit Engine
participant Spec as Specialist Pane(s)
participant Git as Git Repository
User->>Lead: "Build the login feature"
Lead->>Cockpit: takkub assign --role frontend / backend (parallel)
Cockpit->>Git: create isolated branch + worktree (optional)
Cockpit->>Spec: spawn claude pane + inject task
Note over Spec: teammates code & test independently
Spec->>Cockpit: takkub done "report"
Cockpit->>Lead: done notice β verify sequence (devops β QA last)
Lead->>Git: review + merge branches, propose ship
```
---
## π± Mobile Remote Control (PWA)
Step away from the desk β pair your phone once (link / QR) and watch and steer the Lead from anywhere, through an install-free PWA.
- **π² Install-free PWA** β open the paired link, *Add to Home Screen*, done. Offline-capable app shell, no store.
- **π¬ Live Lead console** β the Lead's replies stream to your phone in real time (with a "still workingβ¦" indicator); type back to steer it.
- **π Pulse** β a glanceable, project-grouped view of which teammates are running and for how long.
- **ποΈ View vs. control** β read-only by default; flip to control mode to send prompts or open projects remotely.
- **π Three-factor, off by default** β secret path + bearer token (never in the QR) + a password gate, on a loopback-only server behind a Cloudflare/ngrok tunnel, with per-client sessions & brute-force lockout. Data-minimized: never ships raw tool output, commands, or filesystem paths. Turn it on from the cockpit's **π Remote** chip.
---
## π οΈ Everyday Commands
| Command | Purpose |
| :--- | :--- |
| `takkub assign --role backend "β¦"` | Spawn a specialist and assign a task |
| `takkub assign --role frontend --isolation worktree "β¦"` | Task on an isolated git branch + worktree |
| `takkub assign --role qa --plan --shards 4 "β¦"` | Plan-first parallel browser QA (auto fan-out) |
| `takkub worktree list / merge / clean` | Review + merge isolated branches |
| `takkub send --to qa "β¦"` | Message a teammate (Lead CCβd) |
| `takkub search "β¦"` | BM25-ranked search over session logs + role-memory archives (Thai + English) |
| `takkub goal "β¦"` | Set a session goal injected into every task |
| `takkub restart` | Restart the whole cockpit from the terminal |
| `takkub doctor --fix` | Diagnose the environment + auto-repair (add `--install-providers` to also install missing provider CLIs) |
| `takkub doctor --live` | Same checks, plus a live look at the running cockpit's spawn queue |
| `takkub provider list` | Show every provider CLI, whether it's installed, and its model |
| `takkub provider install ` | Install one provider CLI (Codex / OpenCode) |
| `takkub provider model []` | Show or set the model a provider spawns with (`--clear` to reset) |
| `takkub provision` | Install / repair plugins + browser tools |
---
## π Deep Dives & Resources
- ποΈ **Architecture & design** β [Architecture Guide](https://github.com/takkub/agent-takkub/blob/main/docs/ARCHITECTURE.md)
- βοΈ **System overview & flow diagrams** β [docs/system-overview](https://github.com/takkub/agent-takkub/tree/main/docs/system-overview)
- π‘οΈ **Performance & Reliability v2** β [configuration, invariants, diagnostics, and rollback](docs/performance-reliability.md)
- π§ **From source / one-shot installer** (Chrome, gh, Codex, Antigravity, rtk, β¦) β [INSTALL.md](https://github.com/takkub/agent-takkub/blob/main/docs/INSTALL.md)
- π **GitHub** β [takkub/agent-takkub](https://github.com/takkub/agent-takkub)
---
Windows & macOS β’ built on PyQt6 β’ powered by the Claude Code CLI β’ MIT-licensed