{"id":45645951,"url":"https://github.com/battysh/batty","last_synced_at":"2026-04-17T01:04:06.044Z","repository":{"id":339856533,"uuid":"1163606463","full_name":"battysh/batty","owner":"battysh","description":"Supervised agent execution for software teams. Kanban-driven, tmux-native, test-gated.","archived":false,"fork":false,"pushed_at":"2026-04-05T05:49:55.000Z","size":25195,"stargazers_count":15,"open_issues_count":6,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-05T07:02:19.385Z","etag":null,"topics":["agent-automation","agent-supervisor","ai-agent","ai-agents","aider","claude-code","cli","codex","coding-agents","developer-tools","kanban","llm","rust","software-development","tmux"],"latest_commit_sha":null,"homepage":"https://batty.sh","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/battysh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["Zedmor"]}},"created_at":"2026-02-21T21:57:12.000Z","updated_at":"2026-04-05T05:49:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"d27f0899-93ed-4cfe-b195-8b732d3597c9","html_url":"https://github.com/battysh/batty","commit_stats":null,"previous_names":["battysh/batty"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/battysh/batty","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/battysh%2Fbatty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/battysh%2Fbatty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/battysh%2Fbatty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/battysh%2Fbatty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/battysh","download_url":"https://codeload.github.com/battysh/batty/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/battysh%2Fbatty/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31671741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-automation","agent-supervisor","ai-agent","ai-agents","aider","claude-code","cli","codex","coding-agents","developer-tools","kanban","llm","rust","software-development","tmux"],"created_at":"2026-02-24T04:05:53.090Z","updated_at":"2026-04-11T07:08:20.455Z","avatar_url":"https://github.com/battysh.png","language":"Rust","funding_links":["https://github.com/sponsors/Zedmor"],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD041 --\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/batty-icon.png\" alt=\"Batty\" width=\"200\"\u003e\n  \u003ch1 align=\"center\"\u003eBatty\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\u003cstrong\u003eSelf-improving hierarchical agent teams for software development.\u003c/strong\u003e\u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    Define a team in YAML, launch it in tmux, and let Batty handle the happy path:\n    dispatch work, isolate engineers in worktrees, verify completions, and auto-merge\n    safe changes back to `main`.\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/battysh/batty/actions\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/battysh/batty/ci.yml?style=for-the-badge\u0026label=CI\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/batty-cli\"\u003e\u003cimg src=\"https://img.shields.io/crates/v/batty-cli?style=for-the-badge\" alt=\"crates.io\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://crates.io/crates/batty-cli\"\u003e\u003cimg src=\"https://img.shields.io/crates/d/batty-cli?style=for-the-badge\u0026label=downloads\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/battysh/batty/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue?style=for-the-badge\" alt=\"MIT License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.rust-lang.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/built_with-Rust-dea584?style=for-the-badge\u0026logo=rust\" alt=\"Built with Rust\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://battysh.github.io/batty/\"\u003eDocs\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://github.com/battysh/batty\"\u003eGitHub\u003c/a\u003e\n\u003c/p\u003e\n\n______________________________________________________________________\n\nBatty is a control plane for agent software teams. Instead of one overloaded coding\nagent, you define roles such as architect, manager, and engineers; Batty launches\nthem through typed SDK protocols or shim-backed PTYs, routes work between roles,\ntracks the board, keeps engineer work isolated in git worktrees, and closes the\nloop with verification and auto-merge.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/batty-supervision-flow.png\" alt=\"How Batty works: Define → Supervise → Execute → Verify → Deliver\" width=\"900\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003eHow Batty works: Define → Supervise → Execute → Verify → Deliver\u003c/em\u003e\n\u003c/p\u003e\n\n## Quick Start\n\n```sh\ncargo install batty-cli\nbatty init\nbatty start\nbatty attach\nbatty status\n```\n\n`cargo install batty-cli` installs the `batty` binary. After `batty init`, edit\n`.batty/team_config/team.yaml`, start the daemon, attach to the live tmux session,\nand use a second shell to send the architect the first directive:\n\n```sh\nbatty send architect \"Build a small API with auth, tests, and CI.\"\n```\n\nFor the step-by-step setup flow, see [docs/getting-started.md](docs/getting-started.md).\n\n## What v0.10.0 Adds\n\nBatty v0.10.0 closes the autonomous development loop. Type `$go` in Discord,\ngo to sleep, wake up to merged features.\n\n- **Discord control surface** — three-channel bot (`#commands`, `#events`,\n  `#agents`) with `$go`/`$stop`/`$status`/`$board` commands and rich embeds\n- **Closed verification loop** — daemon auto-tests completions, retries on\n  failure, merges on green. No agent in the merge path.\n- **Notification isolation** — daemon chatter stays in the orchestrator log,\n  not in agent PTY context. Agents stay focused on code.\n- **Supervisory stall detection** — architect and manager roles get the same\n  health monitoring as engineers. No more silent 30-minute stalls.\n- **Manager inbox signal shaping** — 200 raw messages/session batched into\n  prioritized digests. Manager sees what matters.\n- **Hashline-style edit validation** — content-hash checks prevent stale-file\n  corruption when multiple agents edit concurrently.\n- **3,080+ tests**, up from 2,854 in v0.9.0.\n\n## Architecture\n\n```text\nUser (Discord / Telegram / CLI)\n        |\n        v\nArchitect (Claude) ──\u003e Roadmap ──\u003e Board Tasks\n        |\n        v\nManager (Claude) ──\u003e Review + Merge\n        |\n        v\nEngineers (Codex x3) ──\u003e Worktrees ──\u003e Code + Tests\n        |\n        v\nDaemon ──\u003e Verify ──\u003e Auto-merge ──\u003e main\n        |\n        v\nDiscord (#events, #agents, #commands)\n```\n\nThe daemon is the control plane. **Discord is the recommended monitoring and\ncontrol surface** — three channels with rich embeds, commands, and mobile access.\ntmux is the agent runtime display (what agents see), not the primary human\ninterface. Each agent uses a typed SDK protocol (Claude: stream-json NDJSON,\nCodex: JSONL event stream, Kiro: ACP JSON-RPC 2.0) or falls back to the\nshim-owned PTY runtime.\n\n## Features\n\n- **Hierarchical supervision**: architect-level planning, manager-level dispatch,\n  and bounded engineer execution.\n- **Daemon-owned workflow loop**: auto-dispatch, review routing, claim TTLs,\n  merge queueing, verification retries, and board reconciliation.\n- **Discord + Telegram**: three-channel Discord with rich embeds and commands,\n  single-channel Telegram with the same command surface. Monitor from your phone.\n- **Multi-provider support**: mix Claude, Codex, Kiro, and other supported agent\n  CLIs per role.\n- **Per-worktree isolation**: each engineer gets a stable git worktree and fresh\n  task branches without stomping on other engineers.\n- **Self-healing runtime**: crash respawn, stall detection (all roles), delivery\n  retries, context exhaustion handoffs, and auto-restart.\n- **Closed verification loop**: engineer completions are auto-tested, retried on\n  failure, and merged on green without human review in the path.\n- **Observability**: `batty status`, `batty metrics`, SQLite telemetry,\n  Grafana dashboards, daemon logs, and board health views.\n- **OpenClaw integration**: supervisor contract, DTOs, and multi-project event\n  streams for external orchestration.\n- **Clean-room workflow**: optional barrier groups, verification commands, and\n  parity artifacts for re-implementation work.\n\n## Configuration\n\nBatty topology and runtime workflow live in `.batty/team_config/team.yaml`.\nThis is a complete example with the fields most teams touch in v0.10.0:\n\n```yaml\nname: my-project\nagent: claude\nworkflow_mode: hybrid\nuse_shim: true\nuse_sdk_mode: true\nauto_respawn_on_crash: true\norchestrator_pane: true\norchestrator_position: left\nexternal_senders: [slack-bridge]\nshim_health_check_interval_secs: 30\nshim_health_timeout_secs: 90\nshim_shutdown_timeout_secs: 10\nshim_working_state_timeout_secs: 1800\npending_queue_max_age_secs: 600\nevent_log_max_bytes: 5242880\nretro_min_duration_secs: 900\n\nboard:\n  rotation_threshold: 20\n  auto_dispatch: true\n  auto_replenish: true\n  worktree_stale_rebase_threshold: 5\n  state_reconciliation_interval_secs: 30\n  dispatch_stabilization_delay_secs: 30\n  dispatch_dedup_window_secs: 60\n  dispatch_manual_cooldown_secs: 30\n\nstandup:\n  interval_secs: 300\n  output_lines: 40\n\nautomation:\n  timeout_nudges: true\n  standups: true\n  failure_pattern_detection: true\n  triage_interventions: true\n  review_interventions: true\n  owned_task_interventions: true\n  manager_dispatch_interventions: true\n  architect_utilization_interventions: true\n  intervention_idle_grace_secs: 60\n  intervention_cooldown_secs: 300\n  utilization_recovery_interval_secs: 900\n  commit_before_reset: true\n\nworkflow_policy:\n  wip_limit_per_engineer: 1\n  review_nudge_threshold_secs: 1800\n  review_timeout_secs: 7200\n  stall_threshold_secs: 120\n  max_stall_restarts: 5\n  context_pressure_threshold: 100\n  context_pressure_threshold_bytes: 512000\n  context_pressure_restart_delay_secs: 120\n  auto_commit_on_restart: true\n  context_handoff_enabled: true\n  handoff_screen_history: 20\n  verification:\n    max_iterations: 5\n    auto_run_tests: true\n    require_evidence: true\n    test_command: cargo test\n  claim_ttl:\n    default_secs: 1800\n    critical_secs: 900\n    max_extensions: 2\n    progress_check_interval_secs: 120\n    warning_secs: 300\n  auto_merge:\n    enabled: true\n    max_diff_lines: 200\n    max_files_changed: 5\n    max_modules_touched: 2\n    confidence_threshold: 0.8\n    require_tests_pass: true\n    post_merge_verify: true\n\ngrafana:\n  enabled: true\n  port: 3000\n\nroles:\n  - name: human\n    role_type: user\n    channel: telegram\n    channel_config:\n      provider: openclaw\n      target: \"123456789\"\n    talks_to: [architect]\n\n  - name: architect\n    role_type: architect\n    agent: claude\n    prompt: batty_architect.md\n    posture: orchestrator\n    model_class: frontier\n    talks_to: [human, manager]\n\n  - name: manager\n    role_type: manager\n    agent: claude\n    prompt: batty_manager.md\n    posture: orchestrator\n    model_class: frontier\n    talks_to: [architect, engineer]\n\n  - name: engineer\n    role_type: engineer\n    agent: codex\n    instances: 3\n    prompt: batty_engineer.md\n    posture: deep_worker\n    model_class: standard\n    use_worktrees: true\n    talks_to: [manager]\n```\n\nSee [docs/config-reference.md](docs/config-reference.md) for the hand-written\n`team.yaml` guide and [docs/reference/config.md](docs/reference/config.md) for\nthe lower-level `.batty/config.toml` runtime defaults.\n\n## Monitoring\n\nThese are the day-to-day commands that matter once the team is running:\n\n```sh\nbatty status\nbatty board health\nbatty metrics\nbatty telemetry summary\nbatty grafana status\n```\n\n- `batty status` gives the quickest liveness view.\n- `batty board health` shows stale tasks, dependency problems, and queue health.\n- `batty metrics` and `batty telemetry` summarize throughput, review latency,\n  and agent utilization.\n- `batty grafana setup|status|open` manages the built-in dashboard.\n\n## Troubleshooting\n\n- **Claude or Codex stalls**: keep `auto_respawn_on_crash: true`; inspect\n  `.batty/daemon.log`, `batty status`, and `batty doctor` for restart evidence.\n- **Cargo lock contention**: use engineer worktrees with shared targets; avoid\n  ad hoc `target/` directories inside each worktree.\n- **OAuth/auth confusion**: prefer current CLI auth flows and avoid relying on\n  stale API-key-only setups.\n- **Disk pressure**: use `batty doctor --fix`, archive done tasks, and clean\n  unused worktrees if long-lived teams accumulate state.\n\nMore operational guidance lives in [docs/troubleshooting.md](docs/troubleshooting.md).\n\n## Documentation\n\n- [Getting Started](docs/getting-started.md)\n- [CLI Reference](docs/cli-reference.md)\n- [Team Config Reference](docs/config-reference.md)\n- [Architecture](docs/architecture.md)\n- [Troubleshooting](docs/troubleshooting.md)\n\n## Highlights\n\n- Hierarchical agent teams instead of one overloaded coding agent\n- SDK mode by default for Claude Code, Codex CLI, and Kiro CLI\n- PTY shim fallback when typed protocol support is unavailable\n- tmux-backed visibility with persistent panes and resume support\n- Stable per-engineer worktrees with fresh task branches\n- Auto-dispatch, verification, review routing, and auto-merge\n- SQLite telemetry, Grafana monitoring, and board health reporting\n\n## Telegram Integration\n\nBatty can expose a human endpoint over Telegram through a `user` role. This is\nuseful when you want the team to keep running in tmux while you send direction\nor receive updates from your phone.\n\nThe fastest path is:\n\n```sh\nbatty init --template simple\nbatty telegram\nbatty stop \u0026\u0026 batty start\n```\n\n`batty telegram` guides you through:\n\n- creating or reusing a bot token from `@BotFather`\n- discovering your numeric Telegram user ID\n- sending a verification message\n- updating `.batty/team_config/team.yaml` with the Telegram channel config\n\nAfter setup, the `user` role in `team.yaml` will look like this:\n\n```yaml\n- name: human\n  role_type: user\n  channel: telegram\n  talks_to: [architect]\n  channel_config:\n    provider: telegram\n    target: \"123456789\"\n    bot_token: \"\u003ctelegram-bot-token\u003e\"\n    allowed_user_ids: [123456789]\n```\n\nNotes:\n\n- You must DM the bot first in Telegram before it can send you messages.\n- `bot_token` can also come from `BATTY_TELEGRAM_BOT_TOKEN` instead of being\n  stored in `team.yaml`.\n- The built-in `simple`, `large`, `software`, and `batty` templates already\n  include a Telegram-ready `user` role.\n\n## Grafana Monitoring\n\nBatty includes a bundled Grafana dashboard template for long-running team\nsessions. Use it alongside `batty metrics` and `batty telemetry` when you want\nmore than a point-in-time CLI snapshot.\n\nThe dashboard JSON lives at `src/team/grafana/dashboard.json`. Import it into\nGrafana and point the datasource at `.batty/telemetry.db`.\n\nPre-configured alerts:\n\n| Alert                  | Detects                            |\n| ---------------------- | ---------------------------------- |\n| Agent Stall            | Agent silent past threshold        |\n| Delivery Failure Spike | Message delivery failures climbing |\n| Pipeline Starvation    | Not enough work in the pipeline    |\n| High Failure Rate      | Tasks failing above threshold      |\n| Context Exhaustion     | Agent context window nearly full   |\n| Session Idle           | Entire team idle too long          |\n\n## Docs and Links\n\n- [Getting Started](docs/getting-started.md)\n- [CLI Reference](docs/cli-reference.md)\n- [Team Config Reference](docs/config-reference.md)\n- [Generated CLI Reference](docs/reference/cli.md)\n- [Runtime Config Reference](docs/reference/config.md)\n- [Module Reference](docs/reference/modules.md)\n- [Scheduled Tasks \u0026 Cron](docs/scheduled-tasks.md)\n- [Intervention System](docs/interventions.md)\n- [Orchestrator Guide](docs/orchestrator.md)\n- [Architecture](docs/architecture.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [Full docs site](https://battysh.github.io/batty/)\n- [Examples](examples/) — Ready-to-run team configs\n- [Use Cases](USECASES.md)\n- [Contributing](CONTRIBUTING.md)\n- [Good First Issues](https://github.com/battysh/batty/labels/good%20first%20issue)\n- [GitHub](https://github.com/battysh/batty)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbattysh%2Fbatty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbattysh%2Fbatty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbattysh%2Fbatty/lists"}