forza

Autonomous GitHub issue runner. Turns issues into pull requests through configurable multi-stage workflows. Agent-agnostic — supports Claude and Codex backends.

GitHub Issue  ->  Route Match  ->  Workflow  ->  Stages  ->  Pull Request

Quick start

# Install
cargo install forza

# Process a single issue (no config needed)
forza issue 42 --workflow feature

# With a config file for automated workflows
forza init --repo owner/name
forza run --watch

Planning

forza plan analyzes a set of issues and creates a plan issue with a dependency graph, implementation order, and readiness assessment.

# Plan all open issues
forza plan

# Plan specific issues
forza plan 42 45 48

# Revise a plan based on human feedback
forza plan --revise 99

# Preview execution order
forza plan --exec 99 --dry-run

# Execute a plan in dependency order
forza plan --exec 99

The plan issue includes a mermaid dependency graph (rendered by GitHub), actionable issues in order, blocked issues with reasons, and skipped issues. Blocked issues get forza:needs-human labels and explanatory comments.

Configuration

forza works without configuration for direct commands (issue, pr). Add a forza.toml when you want automated discovery via forza run.

Minimal forza.toml:

[global]
model = "claude-sonnet-4-6"

[repos."owner/name".routes.bugfix]
type = "issue"
label = "bug"
workflow = "bug"

Documentation

Full documentation at joshrotenberg.github.io/forza, including:

• Getting Started
• Concepts — routes, workflows, stages, lifecycle
• Configuration Reference
• Examples
• Writing Issues
• Security

What forza isn't

forza will fail, and that's by design. When a run fails, forza stops, labels the issue, and tells you what happened. It doesn't retry, work around, or guess.

• Not fully autonomous — humans decide what to work on and when
• Not self-healing — failures are reported, not automatically resolved
• Not a replacement for good issue writing — vague issues produce vague results
• Not an agent — forza is infrastructure that agents run inside
• Not trying to handle every edge case — simplicity and determinism over cleverness

See design/principles.md for the full rationale.

Design

See design/principles.md for the design principles and feature evaluation guidelines.

License

MIT OR Apache-2.0