Docs/Start

Features

Every capability below is derived from the command surface this binary actually ships (zirv commands --json), grouped by area; each bullet links to the section that documents it in depth.

Script runner#

• Script formats and layout — YAML, JSON, or TOML scripts live in .zirv/commands/ (or the global ~/.zirv/commands/) with name/description metadata, extendable to new formats. See Directory Structure and Schema Examples.
• Parameters — required, positional ${var} parameters, plus trailing optional ones (greeting?) that resolve to an empty string when omitted. See Passing Parameters and Optional Parameters.
• Capture output — capture: var_name on any step grabs its stdout into ${var_name} for later substitution. See Capture Output.
• Failure hooks — a fallback sub-chain runs once on step failure (the original command is never retried); proceed_on_failure separately controls whether the script continues. See Failure Hooks.
• Flexible per-step options — interactive mode, operating_system filters, proceed_on_failure, delay_ms, and secrets. See Schema Examples.
• Dry run — --dry-run prints every ${...}-substituted step instead of running it. See Dry Run.
• Chaining scripts — one script calls another as an ordinary command (command: zirv build). See Chaining Scripts.
• Concurrent shells — nested command lists open one terminal window per group, with a built-in cd that updates the working directory within a window. See Concurrent Shells.
• Agent steps — an agent/prompt step runs a supervised AI-agent task in place of a shell command, under the same pacing and rot detection zirv ctx exec gives a hand-written invocation. See Agent Steps.
• Shortcuts — short aliases for local or global scripts. See Shortcuts.
• Reserved command names — built-in verbs can never be shadowed by a script or shortcut; a collision is flagged rather than silently swallowed. See Reserved Command Names.
• Helpful errors — a mistyped script or shortcut name gets up to 3 "did you mean" suggestions by edit distance instead of a bare failure. See Running Scripts.
• Cross-platform — Windows, macOS, and Linux. See Installation.

Harness supervision (zirv ctx)#

• MCP bridge — mcp (zirv ctx mcp serve) exposes repository-scoped session, memory, workflow, artifact, worker-result, and inbox reads to wrapped MCP hosts. zirv ctx mcp doctor checks a real stdio connection. See MCP bridge.
• Harness adapters — one adapter per supported harness: claude, codex, gemini, opencode, pi, copilot, droid, qwen, grok, kimi, cursor-agent, goose, and muse, each enabled or disabled per repo in .zirv/.settings.toml. See .settings.toml. For which models zirv recognises on each harness, see Supported harnesses and models.
• Dashboard — several supervised sessions in one terminal, with panes for delegated workers, worktree groups, and kill/nudge/send from the keyboard, plus an orchestrator view on ^A t. See The dashboard: multiple sessions in one terminal.
• Agent graph — graph prints a session's agents with each one's parent, job, workflow step and latest steps, and the events between them. See Hook registration (Claude Code).
• Status line — statusline puts the session's usage and spend on Claude Code's status line. See Usage pacing.
• Model discovery — models shows the discovered models and prices that routing and spend use. See Model discovery and pricing.
• Supervisor — supervisor is an operator-only strong model whose binding rulings the operator can override. See Supervisor.
• Persistent runtime (experimental) — session runs a local service that owns the PTYs, so closing or crashing the client leaves the agents running: serve starts it, list shows what it holds, attach and detach connect and disconnect a terminal, and stop is the separate verb that actually ends something. Off by default and operator-only. See Persistent runtime (zirv session).
• Nested sessions are refused — a supervisor started inside another supervised session stops instead of sharing its outer session's registry and turn signals. See Nested sessions are refused.
• Rot detection — a pure scoring engine turns transcript events into advise/compact/restart verdicts before context rot ruins a session. See Signals and verdicts.
• Usage pacing and cross-harness fallback — bounded pauses against the usage window, elastic scheduling across seats, and a handover to the other harness when one is exhausted. See Usage pacing and Cross-harness fallback and handover.
• Untrusted repository configuration — repo-owned .zirv/ surfaces may only narrow what zirv does; widening keys are operator-only. See Trust boundary.
• Supervised exit codes — headless runs map every supervision outcome to a documented exit code. See Exit codes for supervised runs.
• Banner, status bar and events — a one-line banner and status bar in interactive sessions, with events surfaced as they happen. See Banner, status bar and events.
• Session types — ctx supervises wrap (an interactive TUI through a PTY), exec (one supervised headless run), and loop (a fresh headless session per cycle); chat starts an interactive orchestrator session (also the top-level zirv chat alias, and bare zirv), and agent delegates one task to a supervised worker on another enabled harness (also zirv agent); proxy decides a request's intent, complexity, risk and workflow before a launch, so the seat, model and workflow fit the task (opt-in; proxy stats reports per-class token cost and verified-pass rate, see Harness proxy). See Verbs and Just Run zirv.
• Experimental: native — a thin, case-insensitive top-level alias (zirv native) for zirv chat --runtime native, reserved so a script or shortcut can never shadow it. Shown only in zirv help's separately labelled "Experimental / work in progress" section, never beside the stable commands; zirv commands --json reports it with "stability": "experimental" and "runtime": "native". See The native conversation pane.
• Handoffs and recovery — score rot-scores a transcript, handoff distills one, resume starts a clean session with the latest handoff injected, handover swaps the orchestrator seat's model or harness in place mid-session, and ask distills a read-only answer to an operator's question from a LIVE worker's own transcript without ever sending it input or touching its transcript or registry record. See Verbs and Cross-harness fallback and handover.
• Status and attention — status, explain-status, and wait report or block on a session's composed attention projection; watch <session-or- delegation> [--json] [--since <revision>] blocks on a session OR a zirv agent delegation id until it reaches a terminal state, printing one line per distinct revision observed along the way instead of only the final one; --since resumes without re-printing a revision an earlier watch already reported — since neither store keeps a history, only its current value, a resumed watch never replays every intermediate transition that happened while nobody was watching, only the ones it happens to catch plus the latest state. Stdout is transition data only, in both text and --json mode — "gone"/"replaced"/"timed out" are diagnostics, not transitions, and always go to stderr instead, so a --json consumer's stdout is never anything but valid {revision, phase, at} lines. An exact delegation id resolves even when it is also an ambiguous or unmatched session prefix; when it names both an unambiguous session and a delegation, the session wins. snapshot prints a redacted, capped diagnostic summary. See Verbs and Signals and verdicts.
• Mail and nudges — send/inbox leave and read short notes between live sessions on this machine, and nudge wakes one early with a message; kill terminates a registered session outright. See Sending mail between sessions and Session registry and nudging.
• Memory bank — remember/recall/forget read and write this repo's cross-session memory bank from inside a session; the standalone zirv memory (memory) surface (init, status, list, recall, remember, forget, verify, plus promote/rollback/optimize) manages it without starting one; learn promotes a recurring fail-then-fix command correction from recent transcripts into one private memory entry. See zirv memory, Memory bank, and Verbs.
• Delegation controls — group, objective, spend, savings, worktree, task, and swarm bound, account for, and reclaim delegated work; reconcile runs every dead-owner sweep in one pass (--dry-run to report only); permissions (audit/compile/propose) and safety (check/list/explain) audit and enforce zirv's harness-neutral command-safety policy; close ends a group or objective early. See Permission auditing and safe-list proposals, Command safety policy, and Verbs.
• Recall, measurement, and output — search ranks past transcripts/handoffs/artifacts/mail against a query; measure and discover report proportionality and uncompacted-tool-result metrics; run/output execute a command directly and store its full output while printing a compact, reversible summary; compile prints or measures the composed session prompt. See Verbs.
• Configuration and instruction hygiene — config shows or edits the operator's ~/.zirv/ctx.toml, and config migrate/--downgrade versions that file with a backup and a documented way back; provider (init/list/check/ credential set) configures and inspects opt-in native provider routes, accounts and credentials; context (sync/lint/status) manages the canonical instruction-file layer; optimize reports redundancy, contradictions, and dead references across every configuration surface; usage reports usage-window state or tees the statusline. See Reviewing your instruction files and Environment variables worth knowing.
• Jev advisory status — jev (zirv ctx jev status) reports whether the hosted TypeSafe Jev advisor is active: each of the [jev] gates (off by default), whether its credential is present (never its value), and the endpoint and model in use, plus a per-site usage rollup (calls, cache-hit rate, p50/p95 latency, error count, and effect size — bytes removed / rows changed) over the last 7 days, folded read-only from jev-decisions.jsonl, jev-effects.jsonl and jev-skips.jsonl (an enabled site that could not ask -- credential missing, or a state the metadata guard refused -- counts as an error with its reason, never a call; jev-session-aliases.jsonl maps a launch's pre-minted session to the persistent-runtime session it became, so a session-scoped rollup still counts its intake rows). See Harness proxy.
• Configured capabilities — capabilities reports every non-shell integration a native session can use — MCP servers, web search/fetch, browser, language diagnostics, artifact and frontend rendering — as available, unavailable or unverified, naming the missing binary, credential or config key for anything absent. --probe contacts each configured MCP server to verify it; --require gates a script on the same admission rule the workflow engine applies. See Native configured capabilities.
• Native readiness — doctor diagnoses whether this machine can run a native session: per role, which backend an unflagged session gets and which authority decided it, which route it would spend, and every problem sorted into exactly one of missing-auth-material, inaccessible-model, missing-tool, unsupported-isolation, service-failure or upstream-entitlement — so a missing native adapter is never dismissed as an entitlement problem. Writes nothing; --live additionally contacts each provider's model-list endpoint. Redacted like snapshot, so the output is safe to paste into a bug report. See Native setup, diagnosis and rollback.
• Local runtime protocol — api (schema/serve/call) publishes zirv's versioned local control surface: an owner-only unix socket or Windows named pipe carrying NDJSON requests, replies and event subscriptions, with a generated schema and frozen wire fixtures. See Runtime protocol v1.
• Hooks — hook wires zirv into Claude Code's and Codex's own lifecycle events (stop, prompt, pre-compact, pretool/posttool, permission, notify, session-start), audits recorded decisions, and checks or heals the installed hook entries against their baseline. See Hook registration (Claude Code).
• Sensitive-data masking — obfuscate (list/reveal/scan/purge) inspects, reveals, audits and clears the per-repository placeholder vault that keeps credentials and personal data out of model and remote traffic. See What leaves this device.

What wrapping costs (measured)#

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.

Development workflow commands#

• Skills — skill inspects model-agnostic engineering skills (list, show, load, export, read, each taking an <id>) layered from built-in, operator-global, and repository sources. See Development Workflows.
• Workflow lifecycle — workflow runs the durable intent → spec → plan → implement → test → review → verify → deploy lifecycle: list built-in definitions, show one, classify a task without starting, start and persist one, status an instance, resume a persisted one, reclassify its methodology overlay, and context prints the current step's resolved skill context. See The full verb set and Lifecycle and artifacts.
• Gating and progress — approve a gated step, advance records a step result and transitions the state machine, and close ends a workflow that will not reach Completed. See Deploy tiers and Workflow adoption.
• Artifacts and agent seats — artifacts inspects committed work-product artifacts and their acceptance state, and agents (list/show/dispatch) inspects provider-neutral workflow seats and trust provenance; dispatch --runtime native runs a read-only seat on zirv's own runtime with no coding harness installed. See Agent registry.
• Team composition — team (plan/show/brief) compiles the smallest capable team for a request from the agent/skill registries, persists it on a workflow, and briefs one compiled seat with only its own manifest instructions and attached skills. See Team composition.
• Review — review (package/run/add/dispose/list/ ingest-pr-comments) builds compact review packages and persists finding dispositions; run --runtime native runs the reviewer seat natively. With operator-owned jev.review enabled, bounded advisory dispositions order the package and high-confidence Nit/Minor duplicate matches can converge a round; stored severity and disposition remain authoritative.
• Maintenance and telemetry — maintain (scan) runs deterministic operator-configured maintenance detectors, stats aggregates privacy-conscious local workflow telemetry, and calibrate reads recorded workflow outcomes and proposes (never applies) one-step heavier/lighter routing per complexity bucket. See Maintain loop and Outcome calibration.
• Autoresearch campaigns — research (plan/run/status/report) runs a bounded, budgeted, resumable experiment over small policy changes against a fixed evaluator and baseline, and writes an evidence report plus a reviewable proposal it never applies; spend reconciles attributed spend exactly once, keeping execution cost and experiment overhead apart. See Autoresearch campaigns.
• Frontend quality — frontend derives a design profile and drives autonomous frontend work end to end (profile, capabilities, check, render, review, benchmark). See Frontend quality.

Verification#

• Repository-aware checks — test maps changed paths to checks (changed), runs every eligible check (all), or records an operator-owned baseline of already-failing tests (baseline) so a pre-existing failure never blocks a workflow gate. See The full verb set.
• Final verification — verify runs the full check suite plus zirv's own built-in self-check registry. When the whole-changeset fingerprint (HEAD plus the uncommitted diff) matches the prior test run exactly, it reuses that run's evidence wholesale; otherwise it can still reuse an individual check's prior result, per check, when the checkout is on the same commit as that report, the report was not narrowed to a --check subset, the check passed outright, and nothing under that check's own declared paths changed since. A check with no declared paths always re-runs, and a report built from a mix of reused and fresh checks still covers every required check. See The full verb set.
• Repository check configuration — optional, schema-versioned .zirv/verify.toml declares check id/kind/command/path patterns/phase eligibility/timeout; without it, Cargo commands and npm run scripts are discovered from the manifests present, each with its own default paths. Declaring paths narrowly lets an unrelated change elsewhere skip re-running that check at final verification. See Frontend quality.

Housekeeping#

• Guided setup — setup migrates an existing Claude Code/Codex repo to Zirv (apply, status, profile), and reset/restore factory-reset or restore AI-specific settings separately from the rest of Zirv (setup reset, setup restore). See AI setup and harness migration.
• Guided tour — tour (zirv tour [topic]) walks a new installation through nine topics (overview, scripts, workflow, harnesses, memory, safety, jev, config, unstuck); pages under a TTY, plain-prints when piped, exits 1 on an unknown topic while naming every valid one, and is offered automatically at the end of a successful first run. See Guided tour.
• Self-update — update (--version <x.y.z>) installs the latest or a specified zirv release. See Upgrading.
• Model benchmark — benchmark (plan, run, report) detects the installed harnesses and models, runs an embedded role-tagged task corpus against each candidate, and measures wall time, API-equivalent USD and quality, then recommends an orchestrator and a worker. See Benchmarking agents and models.
• Bug and feature reports — report (bug/feature) files a Zirv issue on GitHub, optionally attaching a redacted snapshot.
• Workflow artifacts — artifact registers and inspects workflow artifacts (list, present, render, show); presentation prefers an adapter's native mechanism and falls back to a static file. See Frontend quality.
• Bundled orientation — skill (--json) prints the bundled operator orientation skill for this binary (also zirv --skill).
• Command inventory — commands (--json) lists every command this binary accepts, generated straight from its own clap model.
• Project bootstrap — init creates a .zirv/ directory here, and create interactively (or flag-driven) writes a new script into .zirv/commands/. See Initialize a Project and Creating a New Script.
• Help and version — help lists every available script and shortcut, local and global, and version prints the installed version; --version and -V are accepted as shorthand equivalents. See Usage.