Docs · Run headless

Plans from the terminal.

The corvi CLI runs the same engine as the app. Generate a plan, export the package, resume an interrupted run, and cap what a single run can fetch and spend.

Generate a plan

corvi run is the same engine the app uses, same keys. The minimum is a workspace and a prompt; add --review and --synthesize for the full three-pass plan:

corvi run --workspace . \
  --prompt "Add idempotency keys to the payments endpoint" \
  --review --synthesize

For a grounded sketch in under a minute, use --quick. For a full flag list, see the CLI reference.

Export the package

--export <dir> writes a package your tooling or agent can consume:

corvi run --workspace . --prompt "…" --review --synthesize --export ./plan
  • plan.md — the plan in Markdown, with cited paths and symbols.
  • TODO.md — the actionable checklist.
  • a machine-readable sidecar — structured todos, tests, and criteria.
  • an evidence manifest — what was read, and at what trust tier.

Or write the plan into the repo as .corvi/<slug>/ so an agent or CI step picks it up in place. Corvi gitignores its own exports automatically.

Run in CI

Export your provider keys, then call corvi run as a step. Keys come from the environment first, so a CI secret is enough:

- name: Plan the change
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  run: |
    corvi run --workspace . \
      --prompt "${{ github.event.issue.title }}" \
      --review --synthesize --export ./plan
--claude-code --preset claudeCode runs the whole pipeline on your own Claude account via the official claude CLI — but that path needs an interactive login, so it suits a developer machine more than headless CI, where an API key is simpler.

Resume and amend

A run is cached pass-by-pass. An interrupted run resumes by ID — already completed passes are restored for free:

corvi run --workspace . --prompt "…" --resume <runID>

To edit an existing plan rather than redraft it, pass the prior plan to --refine — cheaper than a full rerun:

corvi run --workspace . --prompt "Also handle the webhook retry case" \
  --refine ./plan/plan.md

Identical re-runs are free from the cache. Any code edit changes the repo signature, so passes re-run (correct); --no-cache forces a cold run.

Cap fetches and spend

Bound a run before it can fan out. --max-fetches caps outbound tool calls (it's 20 by default); --max-cost sets a per-pass dollar ceiling that pauses the run cleanly when reached:

corvi run --workspace . --prompt "…" --review --synthesize \
  --max-fetches 10 --max-cost 1.50

Preview the bill without spending anything with --estimate, which prints a p50–p90 range and exits before any provider call. Audit actual spend afterwards with corvi costs. How egress is gated and logged: Egress & trust.

PreviousRepo memoryNextRun as an MCP server