GBA is a CLI tool that wraps the Claude Agent SDK to help developers plan and implement features through structured, AI-assisted workflows.

• Interactive Planning: Plan features through a TUI chat interface with Claude
• Automated Execution: Execute planned features with automatic phase progression
• Resume Support: Continue from interruptions with automatic checkpoint detection
• Code Review: Integrated AI-powered code review before PR creation
• Verification: Automated verification against acceptance criteria
• Git Integration: Automatic worktree creation, commits, and PR generation

# Build from source
cargo install --path apps/gba-cli

# Or build in development mode
cargo build --release -p gba-cli

• Rust 1.85+ (2024 edition)
• Git
• Claude Code CLI installed and configured
• GitHub CLI (gh) for PR creation

cd your-project
gba init

This creates:

• .gba/ - GBA metadata directory
• .trees/ - Git worktrees (gitignored)
• .gba.md - Repository documentation for AI context

gba plan add-user-auth

Opens an interactive TUI where you can:

• Discuss feature requirements with Claude
• Review and refine the implementation plan
• Generate design specs and verification criteria

gba run add-user-auth

GBA executes a sophisticated pipeline with TUI progress display:

1. Phase Execution - Execute each phase from the design spec with real-time progress
2. Auto-Commit - Commit changes after each phase completes
3. Code Review Loop - AI-powered code review with up to 3 fix iterations
4. Verification Loop - Verify against acceptance criteria with up to 3 fix iterations
5. PR Creation - Generate detailed PR description using LLM

# List all features
gba list

# Show detailed status
gba status add-user-auth

Initialize GBA in the current repository.

gba init

Start interactive planning for a new feature.

gba plan my-feature

Execute a planned feature.

# Normal execution
gba run my-feature

# Dry run (no commits or pushes)
gba run my-feature --dry-run

# Restart from beginning
gba run my-feature --restart

# Resume from specific phase
gba run my-feature --from-phase 2

List all features and their status.

gba list

Show detailed status for a feature.

gba status my-feature

Clean up worktrees for merged or closed PRs.

# Preview what would be cleaned
gba clean --dry-run

# Clean worktrees for merged PRs only
gba clean

# Also clean closed (not merged) PRs
gba clean --force

The clean command:

• Scans .trees/ for worktrees with associated PRs
• Removes worktrees and branches for merged PRs
• Preserves .gba/<feature>/ directory for feature history
• With --force, also removes worktrees for closed (not merged) PRs

# Agent configuration
agent:
  # model: claude-sonnet-4-20250514  # Optional: Claude model to use
  permission_mode: auto               # auto | manual | none
  # budget_limit: 10.0                # Optional: cost limit in USD

# Prompt configuration
prompts:
  include:
    - ~/.config/gba/prompts  # Additional prompt directories

# Git configuration
git:
  auto_commit: true                   # Commit after each phase (default: true)
  branch_pattern: "feature/{id}-{slug}"

# Review configuration
review:
  enabled: true                       # Enable code review (default: true)
  provider: codex                     # codex | claude

Tracks execution progress including:

• Phase completion status
• Commit SHAs
• Execution statistics (turns, tokens, cost)
• PR information

your-project/
├── .gba/                           # GBA metadata
│   ├── config.yml                  # Project configuration
│   └── my-feature/                 # Feature workspace (by slug)
│       ├── specs/
│       │   ├── design.md           # Design document
│       │   └── verification.md     # Acceptance criteria
│       └── state.yml               # Execution state
├── .trees/                         # Git worktrees (gitignored)
│   └── my-feature/                 # Feature branch worktree (by slug)
└── .gba.md                         # Repository AI documentation

Note: Feature directories use the slug (e.g., my-feature), while branch names include the ID (e.g., feature/0001-my-feature).

GBA consists of three main crates:

• gba-cli: Command-line interface with TUI support
• gba-core: Execution engine using Claude Agent SDK
• gba-pm: Prompt template management with MiniJinja

The engine supports the following task types:

Each task type has corresponding templates in the tasks/ directory.

When running gba run, the engine follows this pipeline:

┌──────────────────────────────────────────────────────────────────┐
│                        Phase Execution                           │
│  ┌─────────┐   ┌─────────┐   ┌─────────┐                        │
│  │ Phase 1 │ → │ Phase 2 │ → │ Phase N │ → ...                  │
│  └────┬────┘   └────┬────┘   └────┬────┘                        │
│       ↓             ↓             ↓                              │
│   [Commit]      [Commit]      [Commit]                          │
└──────────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│                    Review & Fix Loop (max 3x)                    │
│  ┌────────┐   ┌─────────────┐   ┌─────┐                         │
│  │ Review │ → │ Issues? ────│─→ │ Fix │ ───────────┐            │
│  └────────┘   └──────┬──────┘   └──┬──┘            │            │
│                   No ↓             └───────────────┘            │
└──────────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│                 Verification & Fix Loop (max 3x)                 │
│  ┌────────────┐   ┌─────────────┐   ┌─────┐                     │
│  │ Verify vs  │ → │ Failed? ────│─→ │ Fix │ ───────────┐        │
│  │ Criteria   │   └──────┬──────┘   └──┬──┘            │        │
│  └────────────┘       No ↓             └───────────────┘        │
└──────────────────────────────────────────────────────────────────┘
                              ↓
┌──────────────────────────────────────────────────────────────────┐
│                       PR Creation                                │
│  Generate detailed PR description using LLM                      │
│  Create PR via GitHub CLI                                        │
└──────────────────────────────────────────────────────────────────┘

Key features:

• TUI Progress Display: Real-time progress visualization during execution
• Automatic Checkpointing: Resume from interruptions with --from-phase
• Check-Fix Loops: Up to 3 iterations to fix review/verification issues
• LLM-Powered PR: Generates detailed PR descriptions from commit history

# Run tests
cargo test

# Run with verbose output
cargo run -p gba-cli -- -v init

# Format code
cargo +nightly fmt

# Lint
cargo clippy -- -D warnings

This project is distributed under the terms of MIT.

See LICENSE for details.

Copyright 2025 Tyr Chen