A Kanban board with mandatory peer review gates and mechanical integrity enforcement, designed for concurrent AI agents.

btrain coordinates Claude Code, Codex, Gemini, and other AI agents working in the same repo. Lanes are WIP-limited work items moving through status columns (idle -> in-progress -> needs-review -> ready-for-pr -> pr-review -> ready-to-merge -> resolved), with feedback loops (changes-requested, repair-needed) that route work back to the writer or escalate to a human. Work is pulled, not pushed — agents claim lanes when capacity opens. File locks provide branch-level isolation without actual git branches, because AI agents share a single worktree. A watchdog auto-detects invalid state transitions, every active lane carries a structured delegation packet, and every handoff requires structured reviewer context (files changed, verification run, review asks) — essentially a PR description plus a worker contract built into the workflow.

The closest human equivalent: a team using a Kanban board where every card requires a PR approval before moving to "done", with automated integrity enforcement that a human board can't provide.

Human types "bth" in agent chat
       |
       v
btrain handoff   <-- prints state + guidance
       |
       v
Agent follows instructions:
  idle/resolved   --> claim a task
  in-progress     --> continue working
  needs-review    --> review (if you're the reviewer)
  ready-for-pr     --> create/link a GitHub PR
  pr-review        --> wait for bot feedback, poll PR status
  ready-to-merge   --> merge the PR, then resolve
  changes-requested --> fix findings, re-handoff
  repair-needed   --> fix workflow state

The source of truth is .claude/collab/HANDOFF_*.md (one per lane). Never edit these directly — always use the CLI.

PR flow is opt-in per repo:

[pr_flow]
enabled = true
base = "main"
required_bots = ["codex", "unblocked"]

# Install
git clone https://github.com/codeslp/btrain.git && cd btrain && npm link

# Bootstrap a repo
btrain init /path/to/repo --agent "claude" --agent "codex" --agent "gemini"

# Launch the chat UI with all agents
btrain-chat all /path/to/repo

# Or launch a single agent
btrain-chat codex /path/to/repo
btrain-chat claude /path/to/repo

# Claim work
btrain handoff claim --lane a --task "Add auth middleware" \
  --owner "claude" --reviewer "codex" --files "src/auth/"

# Check guidance
btrain handoff

# Hand off for review (poller auto-notifies the reviewer in #agents)
btrain handoff update --lane a --status needs-review --actor "claude" \
  --preflight --changed "src/auth/index.ts" --verification "npm test" \
  --why "Auth logic drifted" --review-ask "Check unauth flows"

# Keep this agent session attached to lane A and wake when its handoff changes.
# `bth wait` snapshots the current lane hash when --since is omitted.
bth wait --lane a --timeout 3600

# After a session restart, resume from a previously printed state hash.
bth wait --lane a --since <state-hash> --timeout 3600

# Reviewer approves
btrain handoff resolve --lane a --summary "Approved." --actor "codex"

# In repos with [pr_flow].enabled = true, local approval moves to ready-for-pr:
btrain pr create --lane a --bots all
btrain pr poll --lane a --apply

# If bots request changes, fix/push and request them again
btrain pr request-review --lane a --bots all

# When the PR is merged, poll once more to release locks and resolve the lane
btrain pr poll --lane a --apply

# Or requests changes
btrain handoff request-changes --lane a \
  --summary "Need verification pass" --reason-code missing-verification \
  --actor "codex"

Use the probe-first harness commands before changing workflow prompts or context wiring:

btrain harness list --repo .
btrain harness inspect --repo . --profile default

btrain harness list shows the configured active profile and every bundled or repo-local profile the loader can see. btrain harness inspect shows the selected profile's description, purpose, dispatch prompt, source path, and the registry/schema metadata behind it.

Repo-local overrides live under .btrain/harness/:

.btrain/harness/
├── registry.json
└── profiles/
    └── <profile>.json

Use btrain startup --repo . for a compact first-turn packet: current branch and dirty summary, active agents/lanes, active harness profile, the most relevant lane focus, and the next commands to run.

Use btrain go --repo . when you need the broader bootstrap inventory of files and directories to read. startup is the quick orientation surface; go is the deeper file-reading checklist.

The dashboard is one global HUD for every repo in the BTrain registry. btrain init registers a repo; it does not create another dashboard process.

A local HUD at http://localhost:3333 with live lane status, hot seat indicators, and file locks:

btrain dashboard start             # start and open the HUD
btrain dashboard status            # print the process and URL
btrain dashboard open              # reopen an existing HUD
btrain dashboard stop              # stop the shared HUD

The first interactive btrain handoff claim in any registered repo starts and opens the HUD automatically. Claims from every other repo reuse that process and browser tab. The HUD reads btrain status --json, displays repo-qualified lanes, and lists stale registry entries separately instead of silently dropping them. The always-visible Manage repositories panel has a switch for every repo, so lanes can be hidden or restored directly from the dashboard. Disabled repos stay registered but are excluded from global status, sync operations, and dashboard lanes until re-enabled.

Use btrain repos prune to safely remove every registry entry whose directory no longer exists. btrain repos remove /path/to/repo only removes the registry record; it never deletes the repository or its files.

Set BTRAIN_DASHBOARD_AUTO_OPEN=false to disable claim-time startup, BTRAIN_DASHBOARD_DISABLED=true to disable all dashboard starts, or BTRAIN_DASHBOARD_PORT=<port> to choose the preferred port. If that port is occupied, btrain selects the next available port. Process state and logs are global at ~/.btrain/dashboard.json and ~/.btrain/dashboard.log (or under BRAIN_TRAIN_HOME). Existing repo-owned dashboards are stopped and migrated when that repo first starts the global HUD.

Features: all canonical handoff and PR states, compact status-colored lane indicators, per-repo on/off controls, hot-seat agent badges, expandable delegation details, repair-needed hazard styling, and a health endpoint for lifecycle monitoring.

A chat UI where Claude, Codex, and Gemini collaborate in real-time with live btrain integration.

Launch agents on any repo:

cd agentchattr && ./macos-linux/start_claude.sh   # from the bootstrapped repo root

Then open http://127.0.0.1:8300 — the repo name shows in the header.

Features:

• Split-pane layout — lanes panel (left) + chat window (right)
• Mini lane pills — status-colored summary bar with dashboard animations
• Lane cards — status badge, LANE ID, W// R// agent meta, hot seat designation
• Live btrain state — 5s polling via btrain status --json, WebSocket broadcasts
• Auto-notify — poller auto-posts @mentions to #agents on handoff transitions
• Self-healing — content-hash dedup ensures notifications re-send if lost
• Auto-archive — lane messages archived when task changes
• Resizable/collapsible lanes panel with grip drag
• Click-to-switch — master-detail: click a lane card to switch the chat channel

Supported agents:

Also needed: tmux (brew install tmux) and ripgrep (brew install ripgrep) for Gemini.

Pre-flight readiness checks (btrain-chat status or GET /api/btrain/readiness) validate binary, auth, and working directory before launch.

Lane count = len(active agents) x per_agent:

1 agent,  per_agent=3  -->  lanes a, b, c
2 agents, per_agent=3  -->  lanes a, b, c, d, e, f
3 agents, per_agent=3  -->  lanes a, b, c, d, e, f, g, h, i

Config lives in .btrain/project.toml:

[project]
name = "your-repo"

[agents]
active = ["Claude", "GPT", "Gemini"]
writer_default = "Claude"
reviewer_default = "GPT"

[lanes]
enabled = true
per_agent = 3

[handoff]
# require_diff = false   # Allow needs-review without a diff (docs-only repos)

[feedback]
# enabled = false         # Opt out of feedback log scaffold and doctor warnings

Manage agents:

btrain agents set --repo . --agent "Claude" --agent "GPT" --lanes-per-agent 3
btrain agents add --repo . --agent "Gemini"

Reviewer selection: --reviewer any-other picks any configured peer except the owner.

Every active lane may carry a structured Delegation Packet describing the contract for the work:

btrain handoff claim seeds these fields with useful defaults, and btrain handoff update can refine them as the lane is clarified or re-scoped.

Every needs-review handoff must include:

btrain rejects needs-review transitions with placeholder context or empty diffs. Pass --no-diff to skip the diff gate for non-code changes (docs, config), or set require_diff = false under [handoff] in project.toml to disable it repo-wide.

changes-requested: spec-mismatch, regression-risk, missing-verification, security-risk, integration-breakage

repair-needed: invalid-handoff, unreviewed-push, lock-mismatch, ownership-conflict, state-conflict, invalid-transition, actor-mismatch, contradictory-state

btrain scaffolds a .claude/collab/FEEDBACK_LOG.md during init and monitors it via btrain doctor.

feedback-triage skill — Triages user-reported feedback: assess category (MINOR/BUG/SPEC) and complexity, log to the feedback log, wait for user confirmation, then drive test-first resolution or route to speckit.

bug-fix skill — Test-first workflow for developer-found bugs: define the bug, write a failing reproduction test, fix against it, prove it passes.

btrain doctor warns on:

• Missing feedback log (on initialized repos)
• Stale entries (new or triaged for >7 days)
• Entries missing required fields (Category, Status)

btrain init scaffolds these skills into .claude/skills/ and .agents/skills/ (skip with --core-only). Re-running init restores missing files but preserves existing skill content. Use btrain sync-skills --force --skill <name> to refresh an existing mirror from the bundled source; omit --skill to sync the whole bundle, and omit --force to preserve local edits while restoring missing files. Skill sync also refreshes the shared Unblocked helper required by the context-aware workflows.

btrain hooks or btrain init --hooks installs:

• pre-commit — blocks commits while a lane is waiting on review
• pre-push — blocks pushes while unresolved handoff state exists

Override: btrain override grant --action push --requested-by <agent> --confirmed-by <human> --reason "..."

btrain verifies which agent is speaking:

1. Checks BTRAIN_AGENT or BRAIN_TRAIN_AGENT env var
2. Falls back to runtime hints + [agents.runners] in config
3. Prints agent check: line so agents can confirm identity

[agents.runners]
"Claude" = "claude -p"
"GPT" = "codex"
"Gemini" = "gemini"

New and updated collaborator configurations infer these runner commands from common Claude, Codex/GPT, and Gemini names. Unknown agents receive an explicit notify runner so fallback behavior is visible in config. btrain doctor warns if an active agent has no runner mapping.

Use --lane when asking btrain to launch the agent whose turn it is:

btrain loop --lane b --max-rounds 1 --timeout 300

The child process receives a pinned agent identity plus BTRAIN_LANE and BTRAIN_LANE_LOCKED=1. Its btrain and bth commands default to that lane and reject attempts to select a different lane. Dispatch traces are written under .btrain/harness/runs; inspect them with btrain harness trace list and btrain harness trace show <run-id>.

The original lane-less form remains available for single-lane repositories.

btrain/
  src/brain_train/
    cli.mjs          # CLI entry point
    core.mjs         # State machine, locks, events, watchdog
  scripts/
    serve-dashboard.js    # Console HUD (port 3333)
  agentchattr/
    app.py           # FastAPI server (port 8300)
    wrapper.py       # Agent CLI launcher + queue watcher
    readiness.py     # Pre-flight binary/auth/cwd checks
    static/          # Chat UI (HTML/CSS/JS)
    macos-linux/     # Launcher scripts per agent
  specs/             # Design specs (004-007)
  test/              # Node.js test suite
  .btrain/           # Config, events, history, locks
  .claude/collab/    # Handoff files (HANDOFF_A.md, etc.) + FEEDBACK_LOG.md
  .claude/skills/    # Bundled + custom skills
  .agents/skills/    # Bundled + custom skills for agents that read .agents

The agentchattr/ chat UI is built on agentchattr by @bcurts. btrain extends it with btrain lane integration, auto-notify handoff routing, split-pane lane cards, and multi-agent orchestration.

MIT