kanbot 0.6.1

A Kanban board where every card is a task run by your local CLI coding agents (Claude, Codex, Gemini, GLM/ZAI, or any CLI you define).

KanBot

A visual control room for your coding-agent TUIs — and a Kanban board where every card is a task run by them.

Live demo: https://getkanbot.vercel.app · Run instantly: uvx kanbot (or pipx install kanbot && kanbot up)

You run a lot of terminal coding agents (Claude Code, Codex, …). KanBot gives you one screen to see what every session is doing, pick any of them back up, and drop new tasks that agents run for you — with live logs streamed straight to the card.

Two things in one board:

1. Track your TUIs. A background runner watches each agent's local session store and surfaces every session as a card: the project, the latest message, how many turns, how long it's been brewing, and whether it's working right now. Sessions flow by recency — working → Running, just-finished → Done, older → Backlog.
2. Run new tasks. Drop a card, pick an agent, and the runner executes it and streams stdout/stderr to the card. Or drag any tracked session into Running to resume it (claude --resume, codex exec resume).

 Backlog            Running            Review      Done
 (stale sessions    (sessions          (your       (recently
  + new tasks)       working now        finished    finished
                     + running tasks)   tasks)       sessions)
        │  drag → Running, or "Run", queues for a runner
        ▼
   ╔══════════════════════════════╗
   ║  kanbot runner (background)   ║  detects claude · codex · gemini · glm · shell
   ║  watches ~/.claude, ~/.codex  ║  executes & resumes, streams logs back
   ╚══════════════════════════════╝

Quickstart

Easiest (isolated, sidesteps Homebrew's PEP 668 externally-managed error):

pipx install kanbot && kanbot up     # or zero-install:  uvx kanbot up

From source (until it's on PyPI):

python3 -m venv .venv && . .venv/bin/activate
pip install -e .
kanbot up                             # server + local runner, board at :8787

Don't use bare pip install on macOS Homebrew Python — it errors with externally-managed-environment (PEP 668). pipx/uv handle the env for you.

The board immediately fills with your recent Claude/Codex sessions. Click any one to see its recent transcript in a terminal view and resume it; or hit + add task to give an agent fresh work.

Run the pieces separately (e.g. runner on another machine):

kanbot server                                   # the board / API
kanbot runner --server http://HOST:8787 --name gpu-box

Tracking other agents (Hermes, OpenCode, your own…)

Claude Code and Codex are tracked out of the box. Any agent that logs newline-delimited JSON transcripts can be added with no code change — point KanBot at its store in ~/.kanbot/config.json:

{
  "discovery_sources": [
    {
      "name": "hermes",
      "label": "Hermes",
      "root": "~/.hermes/sessions",
      "pattern": "*.jsonl",
      "recursive": true,
      "fmt": "claude"
    }
  ]
}

• fmt: "claude" for flat records ({type, message, cwd, timestamp}) or "codex" for payload-nested records ({payload: {role, content, cwd}}).
• kanbot agents shows which trackers are active and where they read from.

Run agents

kanbot agents lists the CLIs detected on this machine. Built-in catalog:

agent	run	resume
claude	claude -p "<prompt>"	claude --resume <id> -p "<prompt>"
codex	codex exec --sandbox workspace-write "<prompt>"	codex exec resume <id> "<prompt>"
gemini	gemini -y -p "<prompt>"	—
glm	Claude Code w/ ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic	✓
opencode, aider, cursor-agent, hermes, shell	see kanbot/agents.py	—

Override or add any agent's command in ~/.kanbot/config.json → agent_overrides. A card set to auto runs on whatever the matched runner has.

Custom command per card. Need to run literally any CLI for one task? Open a card → ⚡ custom command and write it yourself, e.g. claude -p "{prompt}" --model opus --add-dir /data. It runs instead of the agent's default; {prompt} and {session_id} expand. Blank = use the agent.

Images. Paste or drop an image onto any prompt box (composer or card). KanBot uploads it and hands the agent a local path it can read; thumbnails are shown and removable, and the card gets a 📎 badge.

Safety: by default agents run with auto-approve flags so tasks run unattended (Claude --dangerously-skip-permissions, Codex workspace-write). For safe mode — agents run without those flags (Codex read-only, Claude without skip-permissions) — start with kanbot up --safe or set it persistently with kanbot config --safe (--unsafe to revert). The runner shows a 🔒 safe badge on the board when safe mode is on.

Workflows — long autonomous runs

A single prompt is a sprint; a workflow is the marathon. A workflow is an ordered chain of agent steps that runs as one card — a session per step, auto-advancing on success — built to drive 1–5 hour autonomous runs from Claude/Codex. Open ⛓ Workflows (or press w).

Each step has its own prompt, agent override, Ralph loop (loop_max / loop_until), and two switches: carry context (inject the previous step's output into this prompt) and continue on fail. Steps run with fresh context, so durable, file-based handoff (PLAN.md, NOTES.md in the repo) is the pattern — e.g. Plan → Build until tests pass → Review → Report.

The point of 0.4.0 is making workflows easy to get, not just run:

• Suggest — open ⛓ Automations → ✨ Suggest from my sessions and Deckhand reads every Claude/Codex session you've run and proposes automations (per project + cross-cutting patterns), each with a rationale and its source sessions.
• Refine (distillation) — the suggestions start as raw drafts (your actual transcript turns). Hit ✨ Refine and a connected agent (claude, codex, glm, gemini — whichever your runner advertises) rewrites them into clean, generalized, short guided step-prompts that work in fresh context — adding test/verify loops where you were iterating. This is the difference between parroting your chat and a real reusable automation. (Needs a reasoning agent on a connected runner; the same ✨ Distill button lives in the builder.)
• Templates — a built-in starter library (Ship a feature, Harden until green, Deep refactor); pick one and tweak.
• Extract — turn a single Claude/Codex session into a draft workflow: open ⟳ sessions → ⛓ workflow.
• Export / import — every workflow exports to portable JSON you can share, version, or paste into another board.
• Clone & edit — duplicate and adjust in the builder.

API: GET /api/workflow-templates, …/workflows (CRUD), …/workflows/import, …/workflows/extract, …/workflows/{id}/export, …/workflows/{id}/run. The full spec is under </> API in the app.

Goal Spree — hand it one goal, walk away for 10+ hours

Playbooks are first-class now (the ▤ playbooks button). The headline is the ⚡ Set off a goal spree: give it one big goal, a repo, a budget (hours) and an optional verify command, and it runs unattended — engineered so a skittish agent that wants to quit after five minutes can't end the run.

How it beats the early-stop problem:

• It splits the goal. A first pass writes PROGRESS.md — a checklist of small, independently-verifiable tasks plus a concrete ## DONE WHEN. The agent never faces "do the whole thing", only "do the next box".
• One task per fresh context. Each iteration does exactly one unchecked item, verifies it, checks it off, and commits — then ends. The next iteration re-reads PROGRESS.md, so a 10-hour run survives context resets.
• It can't talk its way out. The loop's stop condition is a real shell predicate — no unchecked boxes and your verify command passes. When the agent says "good stopping point", the runner re-checks and relaunches with fresh context until it's actually done. The prompt also explicitly rejects "the rest is straightforward" / "I'll let you take it from here".
• Bounded + safe to leave. A wall-clock budget and an iteration cap bound the run; between iterations the runner auto-commits any work the agent left uncommitted (so nothing is ever lost), and stops if there's no progress for several passes instead of spinning.
• Resumable. If a run hits its budget or is interrupted, ⚡ Continue spree picks up against the existing PROGRESS.md exactly where it left off.

You can seed a spree with a saved playbook (its method is folded into the plan) and apply a prompt mode (e.g. lean) to every step.

Creating playbooks (not just from sessions)

• ✎ Draft from an idea — describe what the playbook should do (optionally point it at a repo to ground in) and an agent writes the 3–6 steps for you, live.
• ✨ Build from my sessions — distill your real Claude/Codex transcripts into reusable playbooks (results are cached in the local DB, never re-generated).
• ＋ New (manual) — author steps by hand, with a ✨ Distill button to clean them up.
• ◇ Template / ⬇ Import — starter library and portable JSON.

API: POST /api/boards/{id}/spree, …/workflows/draft, …/workflows/build, GET /api/spree/progress?cwd=….

Self-improving (Training)

A workflow's job is to distill a whole conversation into a procedure that reproduces the outcome with far less prompting — cards show the estimated "↓ ~Nx less prompting." Deckhand improves at this on its own, locally, using your agents:

• Grounded distillation. Extraction runs an agent read-only inside the session's real repo, so workflows are verified against actual code, not hallucinated from chat.
• Evaluate. After Analyze, ⚖ Evaluate grades a workflow against the session's real outcome (git diff/commits) — fidelity, reusability, baked-in takeaways — and writes a grounded critique.
• Exemplar library. Anything scoring ≥75 is banked as a proven exemplar and injected as few-shot into future distillation — the system bootstraps off its own wins. See ⛓ Automations → 🧠 Training.
• Improvement pass. "🧠 Run an improvement pass" distills + judges your richest sessions and banks the winners (cost-capped; real agent runs).
• Sandbox replay (opt-in). A deeper reward: replay a workflow in a throwaway git worktree at the session's pre-state and judge the diff it produces against the real one (sandbox flag on the eval/improve API).

API: …/workflows/from-session (deep extract), …/workflows/eval, …/workflows/improve, …/exemplars.

Tags & insights

Tags are colored labels; a tag can also be an insight provider (◆) that pulls live context onto any card: git (branch/diff), files (recent changes), or a custom command (e.g. pytest -q).

CLI

kanbot up         server + local runner (best first run)
kanbot server     board / API only
kanbot runner     background runner only  (--server, --name, --concurrency)
kanbot agents     detected agents + active session trackers
kanbot config     server URL, token, runner name, enable/disable agents
kanbot open       open the board

Config: ~/.kanbot/config.json · data: ~/.kanbot/kanbot.db. Set KANBOT_TOKEN on the server to require a matching --token from runners.

License

MIT