zirv
v4.58.0

Agents write the code.zirv runs the rest.

One Rust binary around your coding agents. zirv runs your project’s scripts, supervises Claude Code, Codex and eleven more harnesses from one terminal, moves work through gated workflows, holds every command to a safety policy, and paces long runs against your usage windows.

curl -sSfL https://raw.githubusercontent.com/Glubiz/zirv-cli/main/install.sh | sh

Install script for Linux and macOS. Homebrew, Chocolatey or from source

Read the docs What it covers
zirv chatorchestrator view · 120×36

A real render of zirv’s dashboard, drawn by its own ratatui code. The session is example data: the repository, tasks, models and times are examples.

The force-push waits for you: press y or click y Allow once in the card. Only the allowed state was rendered. Scroll sideways for the full width.

Example session in my-project. Seat: claude opus, orchestrator. Workflow feature at implement, step 3 of 5. Worker 1, codex gpt-5.6-sol, works on adding the limiter middleware and its tests. Worker 2, claude sonnet, rebases the branch onto main and asks to run git push --force origin rate-limit.

README.md: what wrapping costs (measured)

Same model. Lower cost per task, and work rated higher.

runs
78, on Claude Sonnet 5
against
Claude Code with the superpowers plugin (v6.4.1)
judge
blind Claude Opus, not told which setup produced the work
statistics
paired bootstrap, 95% CI
  • cut cost per task by about20%

    on ten large coding tasks

  • and by up to42%

    on a 9-step working session

  • rated zirv’s work9–11%

    higher. A blind reviewer (Claude Opus, not told which setup produced the work)

In a headless benchmark against Claude Code with the superpowers plugin (78 runs on Claude Sonnet 5), zirv cut cost per task by about 20% on ten large coding tasks, and by up to 42% on a 9-step working session. A blind reviewer (Claude Opus, not told which setup produced the work) rated zirv’s work 9–11% higher. Hidden-test pass rates matched, and wall-clock speed was on par. The large-task cost and quality gains are statistically significant (paired bootstrap, 95% CI). Results and caveats: the 2026-09 benchmark round; protocol and harness: docs/benchmarks/wrapped-vs-vanilla.md.

Quoted in full from README.md. Below: every task group of the round it summarises, with cost, time and judge side by side.

Round 7, every task group

Change against vanilla Claude Code with the superpowers plugin (v6.4.1), same model. Jev is off by default, so Jev off is zirv as it ships.

Round 7 results per task group: change in cost per task, time and judge score against vanilla Claude Code with superpowers
Task groupCost per tasklower is betterTimelower is betterJudge scorehigher is better
XL tasks t13–t222 reps, 60 runs
−20%sig
+19%†sigworse; 15 s intake timeout
+9%sig
t23, 9-step chain3 reps
−42%
−32%*
+0%
t24b, 22-step chain3 reps
−16%
−11%*
+9%+2 test pts

better than vanillaworse than vanillafilled: sigoutline: within noisebars start at 0 (vanilla); one scale for every bar, −45% to +25%

  • “sig” means the paired-bootstrap 95% CI over tasks excludes zero; everything else is within noise.
  • * Chain time is the agent’s own time (sum of Claude’s per-step duration_ms). The measured chain wall included the harness’s stagger wait, so it is ~equal for every condition and not usable.
  • † Jev off’s XL time is one intake timeout: without a Jev credential the intake falls through to the helper model’s ~15 s timeout. The write-up’s rounds table marks it “+19% (worse, sig)”.
  • The write-up’s own target also asked for 20% faster; its status for round 7 reads “not met” on time.

Results and caveats: the 2026-09 benchmark round Protocol and harness

zirv init, zirv create

It starts with your scripts.

YAML, JSON or TOML scripts live in .zirv/commands/, or globally in ~/.zirv/commands/. Call one by name. A mistyped name gets up to 3 suggestions by edit distance instead of a bare failure.

.zirv/commands/commit.yamlyaml
name: Commit Changes
params:
  - commit_message
commands:
  - command: git add .
  - command: git commit -m "${commit_message}"
  - command: git push origin
$ zirv commit "Your commit message here"

$ zirv buld
error: No script or shortcut found for 'buld'. Did you mean: build? Run `zirv help` to see available scripts and shortcuts.
${var} and greeting?
Required positional parameters, plus trailing optional ones that resolve to an empty string when omitted.
capture: var_name
Grabs a step’s stdout into ${var_name} for later steps.
fallback
A sub-chain runs once on step failure. The original command is never retried.
--dry-run
Prints every ${...}-substituted step instead of running it.
command: zirv build
One script calls another as an ordinary command.
Nested command lists
One terminal window per group, with a built-in cd inside each window.
agent: + prompt:
A step that runs a supervised agent task, under the same pacing and rot detection zirv ctx exec gives a hand-written invocation.
.shortcuts.yaml
Short aliases for local or global scripts. Built-in command names can never be shadowed.
Running scripts

zirv chat, zirv agent, zirv ctx

Thirteen harnesses. One terminal.

On a large enough terminal, zirv chat opens a dashboard that owns several supervised sessions at once. The first pane is always the orchestrator you are talking to; workers open as panes beside it.

Dashboard keys, behind one prefix: CtrlA

  • 1–9switch panes
  • sspawn
  • nnudge
  • mmail
  • ohandover
  • zzoom
  • torchestrator view
  • qquit

zirv agent <name> <prompt>

Delegates one task to a supervised worker on another enabled harness, with the same pacing, rot detection and restart-with-handoff behaviour zirv ctx exec gives a hand-written invocation. It lands in a dashboard pane whenever a dashboard is live.

Chat, agents and dashboard

zirv ctx send  /  zirv ctx inbox

Sessions on the same machine leave each other short notes, scoped to the repository. A mail message is free-form text from another session, never an operator instruction.

Mail and sessions

zirv ctx remember  /  recall

A small bank of durable facts about the repository itself, independent of any one task or session. zirv memory manages it without starting a session.

Memory

What zirv can see in each harness

Each adapter is enabled or disabled per repo in .zirv/.settings.toml. Claude Code gets the full feature set; for the others, zirv’s own help names what it cannot see.

Transcribed from the degraded-surface list in zirv ctx --help (zirv 4.58.0): a hollow mark means the help lists that surface as missing for the harness. Full event support is tracked in issue #11.
HarnessRot scoreUsageTurn signalInjected promptDepth
claudeClaude Codeyesyesyesyes4/4
piyesyesnoyes3/4
qwenyesyesnoyes3/4
codexCodexyesnonoyes2/4
droidyesnonoyes2/4
opencodeyesnonoyes2/4
geminiyesyesnono2/4
copilotyesyesnono2/4
goosenononoyes1/4
groknononoyes1/4
kiminononoyes1/4
cursor-agentnononono0/4
musenononono0/4

zirv workflow --help

One lifecycle, from intent to deploy.

zirv owns the development lifecycle outside model conversation memory. Only the current phase’s selected skill instructions are injected; completed phases stay durable and are not repeated after a restart or compaction.

  1. intentintent.md, approved and hash-pinned
  2. specspec.md
  3. planplan.md
  4. implementthis phase’s skills only
  5. testzirv test changed
  6. reviewindependent reviewer seat
  7. verifyzirv verify
  8. deployby deploy tier

a gate the step must passno gate

Ceremony in proportion

A trivial bugfix skips straight to the debug/test/verify spine, while substantial or high-risk work gains intent, plan and spec artifact gates plus an approval-gated design step. Sensitive auth/security and database/schema changes cannot be downgraded below High risk.

Built-in workflows: feature, bugfix, refactor, spike and review.

Deploy tiers

  • developmentAuto-advances once test/review/verify evidence passes.
  • stagingRequires an explicit zirv workflow approve on the deploy step.
  • productionRequires approval, plus at least one fresh independent reviewer-seat run and fresh final zirv verify evidence.

Skills and teams

zirv skill inspects model-agnostic engineering skills layered from built-in, operator-global and repository sources.

zirv workflow team plan compiles the smallest capable team for a request and briefs each seat with only its own instructions and skills.

Development workflows 
$ zirv workflow classify --task "fix authentication race"
$ zirv workflow start bugfix --task "fix authentication race" --agent codex
$ zirv workflow status

zirv ctx safety --help

Quiet for everyday commands. Firm on the dangerous ones.

One harness-neutral command policy. Everyday and unknown commands run silently in an interactive session; a short list of genuinely dangerous commands prompts; a shorter list is refused outright. Headless launches stay fail-closed, because nobody is present to answer.

Runs silently

Plain curl/wget, dependency installation, builds, commits, in-repo writes, read utilities, and commands zirv has never seen. Generated-directory cleanup, downloads, loopback requests and dry runs.

Asks

Force-push, hard reset, local ref/stash/reflog/worktree loss, recursive deletion, process termination, registry mutation, remote HTTP mutations, infrastructure destruction and device/partition tools. Local reads or copies of .env, *.pem and *.key files.

Refused

Irreversible package or release publication/deletion, credential-store access, secret-file uploads, privilege escalation, download-to-shell pipelines, and attacks on zirv itself.

Repository config may only narrow.

A checked-out repository’s own zirv configuration, system prompt, context files, memory, skills and agents are untrusted input: they can narrow what a session does but never widen a security setting. Widening keys are operator-only.

Secrets can stay on the device.

Opt-in masking turns credential and personal-data values into stable typed placeholders, such as ZIRV_SECRET_GITHUB_PAT_1, before text zirv controls reaches a model. Off by default.

$ zirv ctx safety check --mode interactive -- rm -rf /  # exits 0/1/2 for allow/ask/deny
Safety and permissions

zirv ctx exec, loop, handover

Long runs, supervised.

An unattended run can stall three ways: a usage window runs dry, a harness hits its limit, or the session itself degrades as its context fills. zirv handles each one.

Usage pacing

zirv ctx loop and zirv ctx exec consult a pacing gate before every spawn and every restart, and wait instead of exiting when a 5-hour or 7-day window is at or above pace.max_percent (default 99).

Usage pacing

Fallback and handover

A new delegation can be rerouted away from an exhausted harness before it starts; a running session moves only once its harness stops on a recognised usage-limit message. Either way the alternate must provide a verified equivalent model tier (cheap, standard or deep); zirv never guesses a tier translation for a pinned model it cannot verify.

Fallback and handover

Rot detection

A deterministic score over the transcript (tool failures, repeated calls, same-error loops) advises, compacts early, or restarts the session with a distilled handoff before context rot ruins it. Every decision is logged.

Try the rule in the docs

README.md: installation and setup

Install, migrate, measure.

Pick your OS. Each has one copy-paste command.

Recommended: install script (works on both Linux x86_64 and macOS Intel/Apple Silicon):

curl -sSfL https://raw.githubusercontent.com/Glubiz/zirv-cli/main/install.sh | sh

To install a specific version:

curl -sSfL https://raw.githubusercontent.com/Glubiz/zirv-cli/main/install.sh | sh -s -- <version>

Precompiled binaries for every version are on GitHub Releases. Full installation notes

  1. zirv setup

    Migrates an existing Claude Code or Codex repository: root CLAUDE.md/AGENTS.md instructions move into .zirv/context/ without deleting or overwriting the native files, and zirv’s hooks merge into each harness’s own settings, which are backed up first. zirv setup apply --dry-run previews it.

  2. zirv benchmark plan

    Shows which harness and model stack would be measured on this machine, without any model call. run spends real quota, needs --yes and stops at --max-usd (default 10).

  3. zirv

    In a repo with a local .zirv, from a real terminal, bare zirv starts an interactive orchestrator session. zirv tour walks a new installation through the rest.

Start readingThe docs render the repository’s own markdown.