DevCruiser

Engineering control for AI coding agents.

DevCruiser coordinates coding agents through bounded task execution, mechanical validation, independent review, GitHub pull requests and required CI, and exact merge gates. It isolates agent work in Git worktrees and records durable state so a person supervising a task can inspect an interruption and explicitly resume.

Supervised development orchestration for AI coding agents. Version 0.1.0, 2026-10-01.

Why DevCruiser?

A coding agent can propose changes. Shipping those changes also requires scoped work, reproducible validation, independent review, authoritative CI, and a merge of the exact reviewed candidate. DevCruiser makes those controls explicit and keeps execution finite and inspectable.

DevCruiser orchestrates. Coding agents implement and review; DevCruiser owns deterministic mechanical validation and the Git/PR/merge workflow. Technical roles remain worker, reviewer, task, run, and checkpoint.

Task lifecycle

flowchart TD
    task[Task] --> worker[Isolated Worker]
    worker --> validation[Mechanical Validation]
    validation --> review[Independent Review]
    review --> candidate[Candidate]
    candidate --> pr[Pull Request]
    pr --> ci[Required CI]
    ci --> mode{Merge mode}
    mode -->|human_checkpoint| human[Human Checkpoint]
    mode -->|auto| merge[Exact Merge]
    human --> merge
    merge --> done[DONE]
    validation -.->|failure within budget| repair[Bounded Repair]
    review -.->|findings within budget| repair
    repair -.-> validation
    ci -.->|authorized within CI repair budget| cirepair[Bounded CI Repair]
    cirepair -.-> validation

Every repaired generation must pass validation and independent review again; publication is updated and required CI rechecked before merge. Exhausted budgets, unsafe changes, or unprovable identities stop progress. Required CI is mandatory in both merge modes; the human checkpoint is an additional consent gate. resume continues once, without uncontrolled polling. A checkpoint needs explicit approval; silence never grants it.

Supported agents and providers

Worker and reviewer roles use configured model profiles and review independence rules. The current runtime supports one Codex CLI profile and one Claude CLI profile per project. Paid API spending is separately controlled and disabled in the examples. DevCruiser does not log in to providers for you.

Engineering controls

• Task packets define scope, allowed and forbidden paths, tests, budgets, and merge mode.
• Isolated worktrees have verified ownership; the active human checkout is not scratch space.
• Mechanical validation and fresh independent review bind to the exact candidate.
• Authoritative required CI and branch-protection gates fail closed.
• Leases, durable checkpoints, and explicit resume protect interrupted work.
• Finite worker, review, repair, and CI repair limits keep execution bounded.

Requirements

Execution requires Linux, Python 3.11 or newer, Git, GitHub CLI (gh), and a configured supported provider. macOS and Windows execution are unsupported; some read-only commands may run elsewhere.

The target repository needs a GitHub remote and at least one authoritative required CI check on its base branch. DevCruiser fails closed if the required check policy is empty or cannot be inspected. Passing optional workflows do not satisfy this requirement.

DevCruiser v0.1.0 completed CLEAN_UNIX_USER_SAME_HOST acceptance on 2026-10-01: a separate clean Unix user, separate HOME, fresh noneditable Python installation, separate configuration and state, and a disposable target repository with real providers. The lifecycle passed validation, independent review, required GitHub CI, cold resume, separate explicit human approval, exact merge, and durable DONE. This evidence uses the same underlying host and kernel, not a fresh VM; it does not establish universal platform compatibility.

Quick start

git clone https://github.com/Ronalds007/devcruiser.git ~/src/devcruiser
cd ~/src/devcruiser
python3 -m venv .venv
.venv/bin/python -m pip install .
source .venv/bin/activate
gh auth login

Authenticate your chosen provider CLI through its own supported login flow, or set the named API key environment variable for an OpenAI-compatible provider. DevCruiser does not log in to providers for you. Copy the neutral files in examples/onboarding to a target repository and ~/.config/devcruiser, then replace placeholder repository, paths, model names, and task content with real, authorized values. The catalog and runtime YAML live on the machine. Project, queue, and task YAML live in the target repository. See installation and project onboarding for the required directory layout and field meanings. Keep state and worktrees outside the active source checkout.

Once configured, inspect before starting a task:

devcruiser projects
devcruiser use my-project
devcruiser doctor
devcruiser next
devcruiser start next

doctor checks configuration, executable presence, local Git identity, GitHub authentication, repository identity, and required-check policy. It makes bounded read-only GitHub requests. For Codex and Claude, it does not prove provider login, account health, or future quota. next selects the first eligible queue entry; start next starts one queued task and runs its foreground lifecycle until a checkpoint, another stop condition, or DONE. The example task is a schema example, not an instruction to run it unchanged. Its merge_mode: human_checkpoint is a supervised starting choice. Omitting merge_mode currently defaults to auto; set human_checkpoint explicitly when a task should require a human gate.

Inspect the result and continue only when appropriate:

devcruiser logs
devcruiser resume
devcruiser logs
devcruiser approve

resume is an explicit one-shot continuation, including after an interruption or while waiting for CI. It does not start polling. The final approve command applies only when the task uses merge_mode: human_checkpoint and DevCruiser reports a GREEN AWAITING_HUMAN checkpoint. Inspect the PR and checkpoint before approving. Approval rechecks the reviewed head, required CI, merge gates, and durable ownership before an exact merge. With merge_mode: auto, DevCruiser may merge after those gates pass without a separate approve command. In both modes, an authoritative required check must be GREEN and the reviewed head and publication identity must match. The human checkpoint adds a human consent gate; it is not what makes required CI mandatory. Keep allow_unattended_full: false as the baseline.

For machine output, place --json after the command, for example devcruiser doctor my-project --json. To select a machine-local configuration root, place --config-dir PATH before the command. devcruiser logs my-project --limit 50 is read-only and shows bounded diagnostic metadata.

Architecture and documentation

• Installation and provider configuration
• Onboard an existing repository
• Troubleshooting and recovery
• Detailed V1 architecture and schemas
• Operating skill and setup skill

The portable queue sets task order. The exact task packet defines scope, tests, limits, and merge mode. Machine-local configuration defaults to ~/.config/devcruiser; portable files live under .devcruiser/ in the target repository. The docs use ~/.local/state/devcruiser for state and worktrees; these locations are explicitly configured in the machine catalog. Runtime SQLite and artifacts belong to DevCruiser and must not be hand edited.

Current boundaries

Execution is foreground and Linux only, with GitHub as the repository and CI integration. There is no GUI, daemon, background queue, multi-node scheduler, SaaS control plane, automatic approval, automatic stale-run recovery, or unlimited provider retry. It does not bypass a task's merge policy or safety gates. CLI authentication is managed outside DevCruiser. The CI repair classifier is conservative and may return UNKNOWN.

Version 0.1.0 does not migrate existing state, installed tools, or worktree ownership metadata. A worktree without the current devcruiser-owner-v1 marker is not DevCruiser-owned; do not relabel existing worktrees to bypass ownership checks.

Contributing, security, and license

See contributing, security reporting, release notes, and the MIT license.