zirvDocs
zirv documentation
Everything here is rendered from the repository’s own markdown. Start with Just run zirv or Installation, or press / to search.
28 pages from README.md9 project files3 indexes of docs/
Start
- Just run zirvThe fastest way to start a session: run zirv with no arguments, in a zirv-managed repo (one with a local .zirv/ directory), from a real terminal.
- InstallationPick your OS below. Each has one copy-paste command.
- UpgradingIf zirv is installed via Homebrew or Chocolatey, zirv update is refused by default to prevent desynchronization: the package manager's records would report t...
- Feature overviewEvery capability below is derived from the command surface this binary actually ships (zirv commands --json), grouped by area; each bullet links to the secti...
Scripts
- Running scriptszirv help (also zirv h, zirv --help, zirv -h) lists every available script and shortcut, local and global.
- Script configurationThe .zirv/ directory contains zirv's configuration; your scripts live in its commands/ subdirectory (zirv 3.0). The structure is as follows:
- Shortcuts and reserved namesRun zirv b instead of zirv build.yaml. This will execute the build.yaml script.
Supervision (zirv ctx)
- Context managementZirv can mask credential and personal-data values before text it controls is sent to a model or another remote service. This is opt-in and off by default; th...
- Signals and verdictsVerdicts: score 40 or more is advise, 60 or more is compact, 80 or more is restart. At the token ceiling a score of 60 or more escalates to restart. Without...
- VerbsWith --worktree, extra repositories and setup commands run inside the fresh linked worktree. Without it, the explicit --workdir or current checkout is the wo...
- Chat, agents and dashboardzirv chat and zirv agent are shorter top-level aliases for zirv ctx chat and zirv ctx agent. Both are reserved command names, compared case-insensitively (se...
- Interactive and inline useThe wrapped session is byte-for-byte identical to an unwrapped one until an intervention, injection happens only at a turn boundary while you are idle, and a...
- Configuration (ctx.toml)Layered, lowest priority first: ~/.zirv/ctx.toml, then /.zirv/ctx.toml, then ZIRV_CTX_ environment variables, then flags. A .zirv/ directory that is the oper...
- Hooks and the supervisorSessionStart (issue #244) re-injects the latest stored handoff on resume/clear — a bare claude --resume or /clear sees it too, not only zirv ctx resume's own...
- Usage pacingLong autonomous runs die if a subscription window (5 hour rolling, 7 day) runs dry mid-task. zirv ctx loop and zirv ctx exec consult a pacing gate before eve...
- Fallback and handoverBeyond waiting out a subscription window, zirv can steer work onto a different harness. fallback.rs connects the agent roster, usage windows, model-tier ladd...
- Mail and sessionszirv ctx status reports how many are waiting (mail: N unread). A mail message is free-form text written by whichever agent session sent it, not an operator i...
- Memoryremember also takes --importance , --confidence , and a repeatable --tag — all optional, unset by default. They land in the stored entry and feed zirv memory...
- Safety and permissions"Headless" here is a launch mode — whether a human is present to answer a permission prompt — not a spawn topology. zirv chat, zirv ctx wrap and a pane a hum...
- MCP bridgezirv ctx mcp serve lets an MCP host such as Codex or Claude Code read zirv state through structured tools. The host launches it as a local subprocess; stdin/...
- Harness proxyThe harness proxy is an opt-in intake decision made once, before a session launches: from the request text alone it decides intent, complexity, risk, executi...
- Native runtime (coming soon)Every supervised session picks a RuntimeKind: harness (the default — an AgentAdapter spawns the real Claude Code/Codex/etc. binary through the supervise::spa...
Workflows and skills
- Development workflowsZirv owns the high-level development lifecycle outside model conversation memory. Only the current phase's selected skill instructions are injected; complete...
- Frontend, skills and brandFrontend tasks are selected automatically from task and path evidence. Zirv derives a repository-specific design profile, classifies each surface as persuade...
- Instruction filesThe portable AGENTS.md convention is a first-class source alongside it, and existing CLAUDE.md repositories work unmigrated. At the same directory, ZIRV.md o...
Reference
- Harnesses and modelszirv ships thirteen harness adapters — claude, codex, gemini, qwen, opencode, pi, copilot, droid, grok, kimi, cursor-agent, goose, and muse — each enabled or...
- zirv benchmarkzirv benchmark finds which harness and model stack suits this machine. It runs each candidate solo against a small embedded task corpus, then composes a reco...
- .settings.tomlEvery known adapter defaults to enabled. The environment is the operator, in both directions: ZIRV_AGENT_CODEX_ENABLED=true re-enables an agent a repo disabl...
- Changelog.github/workflows/cd.yaml runs that command for every release and commits the new top section here. A commit subject that does not match type(scope)!: summar...
- LicenseCopyright (c) 2025 Jonathan Solskov
Project
- ContributingFollow the Code of Conduct. Report vulnerabilities through our security policy.
- Security policyOnly the latest release is supported for security updates.
- Code of conductWe as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body siz...
- Disclaimerzirv is provided "AS IS", without warranty of any kind, express or implied, as stated in full in the MIT License. Use it at your own risk.
Research (docs/)
- Benchmark round 2026-09Target (operator): zirv with Jev off and zirv with Jev on must each be at least 20% cheaper, at least 20% faster, and at least 1% better in work quality than...
- Benchmarks58 files in docs/benchmarks/, listed with their own titles.
- Design records43 files in docs/design/, listed with their own titles.
- Specs, plans and notes35 files in docs/superpowers/, listed with their own titles.
- Provider-contract evidenceprovider-live-contract-manifest.json is the redacted record of whether each production provider route has actually been exercised against a real vendor endpo...
- Website docs pipelinecli.zirv.io renders this repository's README.md. Its own site source lives in a separate repository, Glubiz/zirv-generic-frontend (see README's own "Developm...