Getting Started

Use this guide to install Batty, create a team config, launch a tmux session, send the first directive, and stop or resume the team.

Prerequisites

• Rust 1.85+
• tmux
• kanban-md
• At least one agent CLI on your PATH (claude, codex, or similar)

cargo install kanban-md --locked

Install

Install Batty from crates.io:

cargo install batty-cli

Or build from source:

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

Initialize

Run batty init from the repository you want Batty to manage.

cd my-project
batty init

Example output:

Initialized team config (5 files):
  /path/to/my-project/.batty/team_config/team.yaml
  /path/to/my-project/.batty/team_config/architect.md
  /path/to/my-project/.batty/team_config/manager.md
  /path/to/my-project/.batty/team_config/engineer.md
  /path/to/my-project/.batty/team_config/board

Edit .batty/team_config/team.yaml to configure your team.
Then run: batty start

If you want a different scaffold, use batty init --template solo|pair|simple|squad|large|research|software|batty.

Configure

Edit .batty/team_config/team.yaml. Start with name, layout, roles, and use_worktrees.

Batty also has an optional .batty/config.toml for lower-level runtime defaults, but team topology, layout, routing, standups, and channel integration all live in team.yaml.

name: my-project
layout:
  zones:
    - name: architect
      width_pct: 30
    - name: engineers
      width_pct: 70
      split: { horizontal: 3 }
roles:
  - name: architect
    role_type: architect
    agent: claude
    prompt: architect.md
  - name: manager
    role_type: manager
    agent: claude
    prompt: manager.md
  - name: engineer
    role_type: engineer
    agent: codex
    instances: 3
    prompt: engineer.md
    use_worktrees: true

Validate before you start:

batty validate

Example output:

Config: /path/to/my-project/.batty/team_config/team.yaml
Team: my-project
Roles: 3
Total members: 5
Valid.

If use_worktrees: true is enabled for engineers, Batty keeps one stable worktree per engineer at .batty/worktrees/<engineer>. New assignments reuse that path but switch the engineer onto a fresh task branch from current main. After merge, the engineer returns to eng-main/<engineer>.

Launch

Start the daemon and attach to tmux immediately:

batty start --attach

batty start --attach opens tmux instead of printing a summary. Expect something like:

┌ architect ─────────────┬ manager ───────────────┬ eng-1-1 ───────────────┐
│ role prompt loaded     │ role prompt loaded     │ codex/claude starting  │
│ waiting for directive  │ waiting for architect  │ waiting for assignment  │
├────────────────────────┼────────────────────────┼ eng-1-2 ───────────────┤
│                        │                        │ waiting for assignment  │
├────────────────────────┼────────────────────────┼ eng-1-3 ───────────────┤
│                        │                        │ waiting for assignment  │
└────────────────────────┴────────────────────────┴─────────────────────────┘

Send A Directive

From another shell, send the architect the first goal:

batty send architect "Implement a small JSON API with auth and tests."

Example output:

Message queued for architect.

Monitor

Check the team without attaching:

batty status

Example output:

Team: my-project
Session: batty-my-project (running)

MEMBER               ROLE         AGENT      REPORTS TO
--------------------------------------------------------------
architect            architect    claude     -
manager              manager      claude     architect
eng-1-1              engineer     codex      manager
eng-1-2              engineer     codex      manager
eng-1-3              engineer     codex      manager

Use these while the team runs:

batty attach
batty inbox architect
batty board

If a member has queued messages, batty inbox architect looks like:

STATUS   FROM         TYPE         ID       BODY
------------------------------------------------------------------------
pending  human        send         a1b2c3d4 Implement a small JSON API with auth...

Stop And Resume

Stop the daemon and tmux session:

batty stop

Example output:

Team session stopped.

The next batty start resumes agent sessions from the last stop:

batty start

Example output:

Team session started: batty-my-project
Run `batty attach` to connect.

Telegram

If you want a human endpoint over Telegram, use a template that includes a user role, or add one manually, then run:

batty telegram

The setup wizard will:

1. Validate your bot token with the Telegram Bot API
2. Ask for your numeric Telegram user ID
3. Optionally send a test message
4. Update .batty/team_config/team.yaml

Typical resulting config:

- 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]

If you do not want the token stored in team.yaml, set BATTY_TELEGRAM_BOT_TOKEN in the environment and remove bot_token from the file.

Restart the daemon after setup:

batty stop
batty start

Next Steps

• Runtime Config Reference
• CLI Reference