Skip to main content

Getting started

autodev is a planning board and an autonomous delivery fleet. The board keeps executable work contracts in Git. The fleet pipeline gives those contracts to agent harnesses in isolated worktrees, checks the resulting commits, asks a separate judge turn to review them, integrates them, runs the repository gate, and advances attributed stories.

Pre-release limits

The current 0.1.0 source still has known confinement, recovery, evidence-granularity, and product boundary gaps. Read Current limitations before operating a fleet.

You can adopt the board without running agents. Start there, then configure the fleet when the repository's contracts pass.

Prerequisites​

You need:

  • Git and a Git repository;
  • a current stable Rust toolchain with Cargo;
  • for fleet use, a supported coding-agent CLI installed and authenticated for the user running autodev;
  • on Linux, bwrap (Bubblewrap) for confined validation runs.

autodev is currently installed from source. It is not documented here as a published crate or packaged release.

Build or install from source​

Clone the project, then either keep a repository-local binary:

git clone https://github.com/codewandler/autodev.git
cd autodev
cargo build --release
./target/release/autodev --version

Or install the CLI into Cargo's binary directory:

cargo install --path crates/autodev-cli
autodev --version

Run the workspace tests before relying on a source checkout you have changed:

cargo test --workspace

Add a board to an existing repository​

From the root of the Git repository you want autodev to manage, create the conventional planning directories, a commented fleet configuration, and runtime-state ignore rules:

autodev init

init is convergent: it keeps existing files rather than rewriting them. Add --no-commit if you want to inspect and commit the scaffold yourself.

Then create the first story:

autodev board create \
  --prefix APP \
  --title "Reject expired sessions" \
  --kind bugfix \
  --goal "Expired sessions cannot access an authenticated endpoint." \
  --criterion "A request with an expired session receives an unauthorized response." \
  --criterion "The authentication test suite passes." \
  --area src/auth \
  --priority 80

By default, a board mutation writes and commits its file. Add --no-commit if you want to inspect and commit the change yourself. The working tree is still what board reads observe.

Check the contract and inspect the generated ID:

autodev board check
autodev board list
autodev board get APP-1
autodev board explain APP-1 --to ready

Move the story to ready only after board check reports no blocking defect:

autodev board transition APP-1 ready
autodev board list --status ready

The fleet dispatches ready work. A board-only repository can stop here. See Work with the planning board for epics, decisions, glossary terms, updates, and machine-readable output.

Choose where runtime history lives​

You do not need a daemon for a single repository. When a workspace is unregistered, fleet commands open its local .autodev/fleet.sqlite in process.

To give several repositories one central store owner, register this workspace and start the daemon:

autodev workspace register .
autodev daemon start
autodev daemon status

If this repository already has local fleet history, register and import it in one operation:

autodev workspace register . --import

An unimported legacy store is reported as unimported; it is not rendered as an empty history. The daemon owns one global runtime store at ~/.local/share/autodev/fleet.sqlite, serves the operator client on 127.0.0.1:7777, and serves the machine API on 127.0.0.1:7788. A registered workspace does not fall back to a checkout-local runtime store when the daemon is unavailable. Read Central daemon and workspaces before moving an existing fleet or replacing its binary.

Configure a fleet​

Fleet configuration lives in .autodev/fleet.toml; workflow overrides live separately in .autodev/workflows.toml. A minimal Codex example is:

.autodev/fleet.toml
[bridges.codex]
kind = "codex"
model = "your-codex-model"

[roles]
worker = "codex"
judge = "codex"

[validation]
argv = ["cargo", "test", "--workspace"]

[fleet]
worktree_root = "../my-project-fleet-worktrees"
max_wave_size = 2
max_open_waves = 2
max_concurrent_turns = 2
attempt_limit = 2
disk_floor_gb = 10

The model value is deliberately a placeholder: choose a model your installed harness supports. The worker and judge may use the same named bridge, but they run as separate turns. For independent model selection, declare another bridge and assign it to roles.judge.

Do not copy resource limits blindly. Size concurrent turns, open waves, the worktree location, and the disk floor for the repository and machine that will actually run them. See Connect coding-agent CLIs for harness installation, authentication, and bridge examples, then Configure the fleet for environment, workflow, and gate details.

Check before the first drive​

Verify the board, configuration, disk posture, and persisted fleet state:

autodev board check
autodev fleet disk
autodev fleet doctor
autodev fleet status

Then run one reconciler pass and inspect what it did:

autodev fleet tick
autodev fleet status

When that looks right, let the loop run until it becomes quiet or reaches its tick limit:

autodev daemon start --single-user

autodev applies delivered work to the branch that was current when the wave was dispatched and commits the board transition to done. It does not publish packages, push a remote branch, or deploy your software.

Check the daemon, then open the embedded operator workspace in a browser:

autodev daemon status
# Linux with Brave:
scripts/open-autodev-brave.sh

Starting the daemon starts a drive for every registered workspace, so this is the whole loop. Then visit http://127.0.0.1:7777/ for the console, /docs for this documentation, and /public for the summary page. With --single-user every client on the loopback endpoint may act; otherwise the browser is read-only unless the daemon was started with an act token and the client presents it. The Brave launcher opens a chrome-less app window with an isolated profile and exposes DevTools on loopback port 9333; it does not share renderer or extension load with your normal browser. The client and machine API use separate listeners owned by the same daemon process. See Use the operator workspace.

Continue with Run and inspect the fleet, or keep Troubleshooting open for the first live run.