Skip to main content
███████  ███████  █████   █████   ██   ██  ███████
██       ██       ██  ██  ██  ██  ██   ██  ██     
█████    █████    █████   █████   ██   ██  ███████
██       ██       ██  ██  ██  ██  ██   ██       ██
██       ███████  ██  ██  ██  ██   █████   ███████

Deterministic orchestration of AI agents for real software work.

// A Supervisor → Executor → Reviewer state machine for coding agents.

Get startedGitHub →
alpha · v0.4.0Apache-2.0Rust 1.95+

$ Install

ferrus ships as a single Rust crate. Install it with a single command, from crates.io or build from source.

Quick install

|
irm https://ferrus.dev/cli/install.ps1 | iex

From crates.io

# stable — published on crates.io
cargo install ferrus
# or pin an exact version:
cargo install --locked ferrus@0.4.0-alpha.1

From source

# latest main — tracks the repo
git clone https://github.com/ferrus-dev/ferrus
cd ferrus
cargo install --path .

$ Quick start

From any project directory, scaffold ferrus, register your agents, and drop into HQ.

ferrus init                                                  # scaffold ferrus.toml + .ferrus/
ferrus register --supervisor claude-code --executor codex    # write agent configs
ferrus                                                       # enter HQ

Inside HQ, type /spec to draft a written spec first, or /task to go straight in. A supervisor spawns, you describe what you want, and the Executor → Reviewer loop runs automatically until the task is Complete.

$ Repository graph

New in 0.4: an optional, machine-local structural index of your repository. Agents query it by symbol, path, and relationship instead of re-grepping the codebase on every spawn — and every fact comes back with its evidence location, extractor, and confidence.

ferrus graph index                        # build the snapshot (incremental)
ferrus graph status                       # availability, freshness, fact counts
ferrus graph search RuntimeTaskContext    # ranked, evidence-backed lookup
ferrus graph context --symbol <key>       # bounded context packet

Snapshots are immutable and atomically published. Executors query their own worktree view — a pinned baseline plus a changed-file overlay — so parallel tasks never see each other's work in progress. The index is opt-in, entirely local, rebuildable, and safe to delete: an absent graph never blocks the task loop.

Read the repository graph docs →

$ Why ferrus

> Deterministic
Not a chat. A real state machine with explicit transitions, retries, and review cycles.
> Agent-agnostic
Claude Code, Codex, Qwen Code, goose, and opencode are interchangeable workers — including local models.
> Crash-safe
Runtime state lives in SQLite. Agents are stateless between runs — restarts resume exactly where you left off.
> No hidden context
Everything the agents see lives in plain files you can read, scoped per task under .ferrus/tasks/ and .ferrus/runs/.
> Repository-aware
An optional local graph indexes structure, symbols, and relationships so agents navigate instead of rediscovering — every fact evidence-backed and snapshot-pinned.
> Remembers decisions
Project memory keeps approved outcomes, milestones, and deviations queryable, so settled questions stay settled across specs.