zirvDocsStart
Just Run zirv
The 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.
cd my-project
zirv| Situation | Result |
|---|---|
a local ./.zirv exists and both stdin and stdout are a real terminal | starts zirv ctx chat — an interactive orchestrator session |
No local .zirv, or stdin/stdout is piped or redirected | shows this same zirv help listing, exit 0 |
zirv --help / zirv -h | always shows help, even with nothing else on the command line |
This is a deliberate behavior change: before, a bare zirv was a clap usage
error (missing the required command argument, exit 2). A global
~/.zirv alone does not count — only a local ./.zirv says "this directory
is zirv-managed" — and both stdin and stdout have to be a real terminal:
piped stdin (echo hi | zirv, a CI job) or a redirected stdout (zirv | less) always falls back to help instead, so a bare invocation never blocks
waiting on a chat session, or opens one into a pipe, when nothing interactive
is on the other end.
AI setup and harness migration#
Run the guided setup when moving an existing Claude Code or Codex repository to Zirv:
zirv setupThe non-interactive equivalent is zirv setup apply. It initializes .zirv/,
migrates root CLAUDE.md/AGENTS.md instructions into the canonical
.zirv/context/ layer without deleting or overwriting the native files,
bootstraps a small shared memory bank, and merges Zirv's Stop,
UserPromptSubmit, PreCompact, and guarded PreToolUse hooks into Claude's
existing settings.json and Codex's existing hooks.json. Unrelated hooks
are preserved and both files are backed up before modification. Codex asks you
to review new hooks with /hooks. An existing Claude statusline is preserved;
when none is configured, setup installs zirv ctx usage tee.
zirv setup status
zirv setup status --json
zirv setup apply --dry-run
zirv setup apply --memory-source /path/to/docs-or-obsidian-vaultCanonical common context reaches both Claude and Codex; optional
.zirv/context/claude.md and .zirv/context/codex.md additions apply only to
that harness. Direct Codex launches receive the compiled prompt through the
CLI's per-run developer_instructions config override. Windows shell-shim
launches remain fail-closed: Zirv never puts repository-authored prompt text on
an argv that cmd.exe or PowerShell would reparse.
AI-specific settings can be factory-reset separately from Zirv setup. Reset is
refused without --yes, supports --dry-run, backs up every exact target with
a manifest under .zirv/backups/ai-reset/ (project) or
~/.zirv/backups/ai-reset/ (global), and preserves authentication,
sessions/history, and caches unless --include-auth is explicitly passed:
zirv setup reset claude --scope project --dry-run
zirv setup reset codex --scope global --yes
zirv setup reset all --scope all --yesGuided tour#
Start a guided tour of zirv for a new installation:
zirv tourIn a terminal, this walks you through seven topics (overview, harnesses, memory, safety, jev, config, unstuck) with paging controls: press [enter] or n to go to the next section, b to go back, q to quit. Rerun zirv tour to resume where you left off, or jump directly to a topic:
zirv tour config
zirv tour memory
zirv tour unstuckIn a pipe or with redirected output (non-TTY), zirv tour prints all sections plainly and exits 0, suitable for scripts or documentation.