Skip to content

Getting Started

Use this guide to install Batty, create a team config, launch the daemon, and get to the unattended v0.10.0 happy path quickly.

Prerequisites

  • Rust 1.85+
  • tmux >= 3.1 (3.2+ recommended)
  • kanban-md on your PATH
  • At least one supported agent CLI such as claude, codex, or kiro

Install kanban-md if needed:

cargo install kanban-md --locked

1. Install Batty

From crates.io:

cargo install batty-cli

From source:

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

2. Initialize A Team

Run batty init inside the repository you want Batty to manage:

cd my-project
batty init

Useful variants:

batty init --template squad
batty init --template batty --agent codex
batty init --template cleanroom

The generated .batty/team_config/ directory contains team.yaml, prompt templates, and the board directory.

3. Configure team.yaml

Batty v0.10.0 is designed around a shim-backed, SDK-first runtime. Start with a team that looks like this:

name: my-project
workflow_mode: hybrid
use_shim: true
use_sdk_mode: true
auto_respawn_on_crash: true

board:
  auto_dispatch: true
  auto_replenish: true

automation:
  timeout_nudges: true
  standups: true
  triage_interventions: true
  review_interventions: true
  owned_task_interventions: true
  manager_dispatch_interventions: true
  architect_utilization_interventions: true

workflow_policy:
  review_nudge_threshold_secs: 1800
  review_timeout_secs: 7200
  context_handoff_enabled: true
  verification:
    auto_run_tests: true
    require_evidence: true
    test_command: cargo test
  auto_merge:
    enabled: true
    require_tests_pass: true

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

Recommended defaults:

  • Keep use_shim: true and use_sdk_mode: true.
  • Leave auto_respawn_on_crash: true on for unattended teams.
  • Keep board.auto_dispatch: true so idle engineers do not sit waiting.
  • Keep workflow_policy.auto_merge.enabled: true so safe diffs merge on green.

For a fuller example, see config-reference.md.

4. Validate Before Starting

batty validate
batty validate --show-checks

Use --show-checks when you want the failing validation rule, not just the top-level error.

5. Start And Attach

Start the daemon:

batty start

Attach to the tmux session:

batty attach

In a second shell, keep a non-interactive view open:

batty status

6. Send The First Directive

batty send architect "Build a small JSON API with auth, tests, and CI."

The architect plans, the manager creates and routes tasks, and engineers pick up runnable work through the daemon-managed board loop.

7. Understand The Happy Path

In v0.10.0, the intended steady state is:

  1. Architect defines the objective.
  2. Manager turns it into board tasks.
  3. Idle engineers receive work via auto-dispatch.
  4. Engineers execute inside isolated worktrees.
  5. Verification runs on completion.
  6. Small, safe diffs auto-merge; larger ones route to review.

Watch that flow with:

batty board summary
batty board health
batty queue
batty metrics

Auto-merge outcomes are intentionally heterogeneous. A green completion can lead to different operator-visible states depending on the diff, the merge result, and post-merge verification on main:

  • review: Batty routed the task to manual review because the diff was too risky to merge unattended, a per-task override disabled auto-merge, or diff analysis fell back conservatively.
  • done: the merge queue merged the branch to main; managers receive a completion message and Batty emits task_auto_merged.
  • in-progress with the engineer re-paged: Batty hit a rebase conflict and asked the engineer to fix the worktree, then retry.
  • blocked or escalated: Batty exhausted conflict retries or could not complete the merge safely and handed the next action back to the manager.
  • merged then reverted: the queue merged the branch, but post-merge verification on main failed, so Batty reset main, notified the engineer and manager, and intentionally did not emit task_auto_merged.

When several tasks finish close together, expect mixed outcomes in the same run. Check batty board summary for state changes, batty inbox manager for the queue's explanation of each task, and batty metrics if you want the review and auto-merge counters.

8. Monitor A Running Team

These are the everyday operational commands:

batty status
batty inbox architect
batty board summary
batty doctor
batty telemetry summary
batty grafana status
  • batty status shows liveness and hierarchy.
  • batty board summary shows workflow pressure.
  • batty doctor is the first stop when the team looks stuck.
  • batty telemetry and batty metrics show throughput and review health.

9. Cut A Release From Green Main

When main is clean and your verification baseline is green, Batty can record the release attempt for you:

batty release

The command uses the Cargo.toml package version as the default tag (v<version>), requires a matching CHANGELOG.md entry for that version, and re-runs the release verification command before tagging. If .batty/team_config/team.yaml exists, Batty reuses workflow_policy.verification.test_command; otherwise it falls back to cargo test.

The command fails if you are not on main, if the worktree is dirty, if the verification command is red, if the changelog entry is missing, or if the target tag already exists. Every attempt writes an operator publish handoff to .batty/reports/release/publish-handoff.json with the tag/version, git ref, verification evidence, release notes and changelog paths, blocked reasons, and manual publish commands. On success it also writes release notes into .batty/releases/, creates the annotated git tag, and records the attempt in .batty/releases/latest.{json,md} plus the normal Batty event/telemetry surfaces.

Batty does not push branches, push tags, or publish packages. After inspecting the handoff and resolving any blocked_reasons, an operator publishes manually:

git push origin main
git push origin v<version>
cargo publish --package batty-cli

To produce a release-readiness artifact without tagging, run:

batty release --readiness

The readiness report is written to .batty/releases/readiness.{json,md} and includes the current commit, proposed tag, recently merged task ids, verification evidence, GitHub verification feedback from .batty/github_verification.jsonl, and explicit blockers such as a dirty worktree, missing verification summary, failing GitHub check for the current HEAD, or stale daemon binary. A green main with no current GitHub feedback still prints a clean GitHub feedback section so the absence of feedback is visible.

Discord gives you three dedicated channels for monitoring your team from your phone.

  1. Create a Discord bot at https://discord.com/developers/applications, enable Message Content Intent under Bot -> Privileged Gateway Intents, and invite it to your server with Send Messages permission.

  2. Create three channels: #batty-commands, #batty-events, #batty-agents.

  3. Run the setup wizard:

sh batty discord

The wizard validates the bot token, lets you pick the server and channels, prompts for allowed Discord user IDs, writes the resulting channel: discord user role into team.yaml, saves BATTY_DISCORD_BOT_TOKEN into the repo .env, and sends test messages to all three channels. It also reads BATTY_DISCORD_BOT_TOKEN if you already exported the token.

  1. Verify the connection later with:

sh batty discord status

If Discord receives command-channel messages but Batty reports a MESSAGE_CONTENT fault in batty status or daemon logs, the bot can see messages but cannot read their text. Enable Message Content Intent in the Discord Developer Portal, then restart Batty.

  1. Start batty and use Discord:

  2. Type $go to launch the full team

  3. Type $status for a board overview
  4. Type $board to see todo tasks
  5. Type plain text to send directives to the architect
  6. Watch #batty-events for task progress and merges
  7. Watch #batty-agents for agent health

11. Optional: Telegram Control Plane

If you prefer Telegram over Discord, or want both:

batty telegram

The setup flow validates the bot configuration and writes the resulting channel settings into team.yaml. All $ commands from Discord also work in Telegram in single-channel mode.

11. Stop And Resume

Stop the daemon and tmux session:

batty stop

Restart later with:

batty start

Batty attempts session resume when the saved launch identity still matches. If a saved session is stale, Batty falls back to a cold respawn and rebuilds context from on-disk state instead of blocking startup.

Troubleshooting

  • If an agent stalls, check batty status, batty doctor, and .batty/daemon.log.
  • If builds contend, make sure engineers are using shared-target worktrees rather than ad hoc local target/ directories.
  • If messages do not arrive, inspect batty inbox <member> and verify the daemon is still running.
  • If auth is broken, prefer current CLI OAuth flows and then restart Batty.

For operational fixes, see troubleshooting.md.

Next Steps

  • Read cli-reference.md for the main operator commands.
  • Read config-reference.md for the full team.yaml surface.
  • Use batty metrics, batty telemetry, and batty grafana status on longer runs.