batty-cli 0.5.2

Batty is a tmux-native runtime for AI coding teams. Instead of one agent doing everything badly, you define roles like architect, manager, and engineers; Batty launches them, isolates engineer work in git worktrees, routes messages, tracks the board, and gives you a structured way to run parallel agent workflows without losing control or context.

Quick Start

cargo install batty-cli
cd my-project && batty init
batty start --attach
batty send architect "Build a REST API with JWT auth"

That gets you from zero to a live team session. For the full walkthrough, templates, and configuration details, see the Getting Started guide.

Quick Demo

You
  |
  | batty send architect "Build a chess engine"
  v
Architect (Claude Code)
  | plans the approach
  v
Manager (Claude Code)
  | creates tasks, assigns work
  v
Engineers (Codex / Claude / Aider)
  eng-1-1   eng-1-2   eng-1-3   eng-1-4
   |          |          |          |
   +---- isolated git worktrees ----+

Batty keeps each role in its own tmux pane, watches for idle/completed states, delivers inbox messages, auto-dispatches board tasks, runs standups, and merges engineer branches back when they pass tests.

Install

1. Install kanban-md

kanban-md is a separate Go tool. Grab the latest binary from GitHub releases:

# macOS (Apple Silicon)
curl -sL https://github.com/antopolskiy/kanban-md/releases/latest/download/kanban-md_0.33.0_darwin_arm64.tar.gz | tar xz
mv kanban-md /usr/local/bin/

# macOS (Intel)
curl -sL https://github.com/antopolskiy/kanban-md/releases/latest/download/kanban-md_0.33.0_darwin_amd64.tar.gz | tar xz
mv kanban-md /usr/local/bin/

# Linux (x86_64)
curl -sL https://github.com/antopolskiy/kanban-md/releases/latest/download/kanban-md_0.33.0_linux_amd64.tar.gz | tar xz
mv kanban-md ~/.local/bin/

Or with Go: go install github.com/antopolskiy/kanban-md@latest

2. Install Batty

From crates.io:

cargo install batty-cli

From source:

git clone https://github.com/battysh/batty.git
cd batty
cargo install --path .

How It Works

team.yaml
   |
   v
batty start
   |
   +--> tmux session per team
   +--> role prompts loaded into each pane
   +--> engineer worktrees created when enabled
   +--> daemon loop watches output, inboxes, board, retries, standups
   |
   v
batty send / assign / board / status / merge

Batty does not embed a model. It orchestrates external agent CLIs, keeps state in files, and uses tmux plus git worktrees as the runtime boundary.

Built-in Templates

batty init --template <name> scaffolds a ready-to-run team:

Highlights

• Hierarchical agent teams instead of one overloaded coding agent
• tmux-native runtime with persistent panes and session resume
• Agent-agnostic role assignment: Claude Code, Codex, Aider, or similar
• Maildir inbox routing with explicit talks_to communication rules
• Stable per-engineer worktrees with fresh task branches on each assignment
• Kanban-driven task loop with auto-dispatch, retry tracking, and test gating
• Scheduled tasks: scheduled_for delays dispatch until a future time, cron_schedule enables recurring tasks that auto-recycle from done back to todo (guide)
• Per-intervention runtime toggles via batty nudge to disable or re-enable specific daemon behaviors without restarting
• Orchestrator automation for triage, review, owned-task recovery, dispatch-gap recovery, utilization recovery, standups, nudges, and retrospectives
• Auto-merge policy engine with confidence scoring and configurable thresholds for safe unattended merges
• Review timeout escalation: stale reviews are nudged and auto-escalated after configurable thresholds, with per-priority overrides
• SQLite telemetry database: batty telemetry queries agent performance, task lifecycle, review pipeline metrics, and event history
• Run retrospectives: batty retro generates Markdown reports analyzing task throughput, review stall durations, rework rates, and failure patterns
• Team template export/import: batty export-template saves your team config, batty init --from restores it
• Daemon restart recovery: dead agent panes are automatically respawned with task context and backoff
• External senders: allow non-team sources (email routers, Slack bridges) to message any role
• Graceful non-git-repo handling: git-dependent operations degrade cleanly when the project is not a repository
• batty doctor --fix: detect and clean up orphan worktrees and branches left by previous runs
• batty board archive: move completed tasks to an archive directory to keep the active board fast
• Worktree reconciliation: auto-detect cherry-picked branches and reset stale worktrees so engineers always start clean
• Pending delivery queue: messages sent to agents that are still starting are buffered and delivered automatically when the agent becomes ready
• YAML config, Markdown boards, JSON/JSONL + SQLite logs: everything stays file-based

CLI Quick Reference

Requirements

• Rust toolchain, stable >= 1.85
• tmux >= 3.1 (recommended >= 3.2)
• kanban-md CLI: see Install for setup
• At least one coding agent CLI such as Claude Code, Codex, or Aider

Engineer Worktrees

When use_worktrees: true is enabled for engineers, Batty keeps one stable worktree directory per engineer under .batty/worktrees/<engineer>.

Each new batty assign does not create a new worktree. Instead it:

• reuses that engineer's existing worktree path
• resets the engineer slot onto current main
• creates a fresh task branch such as eng-1-2/task-123 or eng-1-2/task-say-hello-1633ae2d
• launches the engineer in that branch

After merge, Batty resets the engineer back to the base branch eng-main/<engineer> so the next assignment starts clean.

Telegram Integration

Batty can expose a human endpoint over Telegram through a user role. This is useful when you want the team to keep running in tmux while you send direction or receive updates from your phone.

The fastest path is:

batty init --template simple
batty telegram
batty stop && batty start

batty telegram guides you through:

• creating or reusing a bot token from @BotFather
• discovering your numeric Telegram user ID
• sending a verification message
• updating .batty/team_config/team.yaml with the Telegram channel config

After setup, the user role in team.yaml will look like this:

- name: human
  role_type: user
  channel: telegram
  talks_to: [architect]
  channel_config:
    provider: telegram
    target: "123456789"
    bot_token: "<telegram-bot-token>"
    allowed_user_ids: [123456789]

Notes:

• You must DM the bot first in Telegram before it can send you messages.
• bot_token can also come from BATTY_TELEGRAM_BOT_TOKEN instead of being stored in team.yaml.
• The built-in simple, large, software, and batty templates already include a Telegram-ready user role.

Built with Batty

This session shows Batty coordinating a live team in ~/mafia_solver: the architect sets direction, black-lead and red-lead turn that into lane-specific work, and the black-eng-* / red-eng-* panes are individual engineer agents running in separate worktrees inside one shared tmux layout.

• chess_test: a chess engine built by a Batty team (architect + manager + engineers)

Docs and Links

• Getting Started
• Demo
• CLI Reference
• Runtime Config Reference
• Module Reference
• Scheduled Tasks & Cron
• Intervention System
• Orchestrator Guide
• Architecture
• Troubleshooting
• Full docs site
• GitHub

License

MIT