Complete reference for the guardian CLI and the protocol it maintains in your git. Every command here reflects the real --help of the installed version. If something changes in a newer version, the --help of your CLI is the source of truth.
GuardianContext is a Git-native control plane: the entire coordination protocol lives in versioned markdown files in your repository tree, with no separate database. So there is no setup, diffs show up in PRs and everything works offline.
The protocol has six pieces, all in files:
Every path is configurable in guardian.json (for example, repositories that already keep their knowledge base in docs/router.md use guardian init --router docs/router.md).
The working mode is declared on the Modo: shared or Modo: branches line of router.md, so it is versioned and visible to every session:
wiki/como-trabalhar.md is created with the shared-tree rules.Switching modes after installation means editing wiki/como-trabalhar.md by hand: an existing file is never overwritten by a new init.
The one-line installer installs uv if it is missing, the guardiancontext[semantic,desktop] package (Python 3.11) and opens the Desktop Manager.
irm https://api.ironstack.dev.br/install.ps1 | iexcurl -fsSL https://api.ironstack.dev.br/install.sh | shIn the Desktop Manager: create an account (optional name, email, password, acceptance of the Terms of Use) or sign in to an existing account; choose the git repository folder and the working mode; the app runs init, hook install, index rebuild, report and license with the log on screen.
The free plan has no time limit and covers 1 repository per account. The server URL is stored in <repo>/.guardian/config.json and the API key in ~/.guardian/config.json (outside the repo). Password and session are never written to disk.
Terminal-only alternative, no GUI:
uv tool install --python 3.11 "guardiancontext[semantic]"
cd my-repo
guardian signup
guardian init
guardian hook install
guardian index rebuild --semantic
guardian reportOn another machine or in a fresh clone of the same project, use guardian login: it lists the account's installations and reissues the key. Forgot your password: guardian reset-password. Key issued by an admin or another login: guardian configure --api-url … --api-key ….
Once the account is connected, the routine for a new repository:
guardian init --mode shared # or --mode branches
guardian hook install
guardian index rebuild --semantic
guardian report
guardian licenseCustom layout (a repository that already keeps its knowledge base elsewhere):
guardian init --router docs/router.md --wiki docs/wiki --decisoes docs/decisoes \
--trabalho docs/trabalho --quadro docs/quadro.md --quadro-max-linhas 20guardian doctor validates the whole structure (and runs the audit); a non-zero exit indicates an error. Run it before trusting a freshly configured repository and after any layout change.
The index is a hybrid SQLite database (FTS5 + vectors), derived from the protocol's markdown files. The rebuild is incremental by sha256: it only re-embeds new or changed pages.
guardian index rebuild # automatic: semantic if available, otherwise lexical
guardian index rebuild --semantic # forces the multilingual model
guardian index rebuild --lexical # FTS5 only, no embeddingsSearch combines FTS5 + cosine similarity with Reciprocal Rank Fusion (RRF):
guardian index search "how we do migrations"
guardian index search "push rules" --tool claude --limit 5
guardian index search "deploy" --kind wiki --lexical --json--tool filters kind=instrucao documents (claude|agents|gemini|cursor); the other document types apply to any tool. guardian brief packages the same top-k, plus the instruction rules of the chosen tool and related decisions/work, ready to paste into a plan:
guardian brief "add cancellation route" --tool claude --limit 5 --max-tokens 2000 --saida .guardian/brief.mdguardian audit is deterministic (no LLM) and covers: missing files, a bloated work board (and bloated work artifacts, such as PLAN.md/PLAN-REVIEW-LOG.md), decisions without a status, expired or conflicting claims, abandoned handoffs and broken links between documents.
The work board budget is configurable (--quadro-max-linhas on init, default 20 lines): above the budget is a warning, above 3× is an error, always with the token estimate in the message itself. guardian doctor runs the audit and fails (exit ≠ 0) if there is an error. It is the recommended command for a CI hook or a periodic check.
guardian audit
guardian audit --json
guardian doctorClaims reserve a file scope with a TTL and refuse overlap with another actor; handoffs pass the baton between sessions with single acceptance (the second accept is refused).
guardian claim --actor claude-session-1 --task "cancellation route" --minutes 90 backend/**
guardian release <claim_id> --actor claude-session-1guardian handoff create --actor claude-session-1 --to codex --work-item "cancellation route" \
--summary "endpoint ready, idempotency test missing" --files backend/cancellation.py
guardian handoff accept <handoff_id> --actor codexThe pre-commit hook (guardian hook install) prints [guardian] branch=<x> head=<sha7> arquivos=<n> on every commit, refuses staging of a file under another actor's active claim (identity via GUARDIAN_ACTOR or --actor) and, in shared mode, refuses broad staging (more than --max-files files, default 25, without a claim by the actor itself covering all of them). In branchesmode this check does not apply. The escape hatch is git's own, git commit --no-verify.
Merge: the protocol itself has no merge command. The merge rules (fast-forward, PR, never --force on the main branch) live in the wiki/como-trabalhar.md generated by init --mode branches; claims and handoffs remain the notice channel between sessions before the merge.
Each tool family reads its own instruction file: Claude Code reads CLAUDE.md; other families read AGENTS.md, GEMINI.md or .cursorrules. Without reconciliation, a rule written in only one of these files is invisible to the other families.
guardian instrucoes status # per-folder table: files, lines, who sees whom
guardian instrucoes sync # creates/updates pointer blocks in the gaps (idempotent)syncnever copies content between files: it writes a pointer block between markers, pointing to where the other family's rule lives. It changes no tool and duplicates no text that could diverge.
guardian benchmark compares, in tokens, four search scenarios on your own repository: no knowledge base (grep), a code graph only, a well-maintained router and the GuardianContext index. Without --casos, the answer key is derived from the router.md table itself.
guardian index rebuild --semantic
guardian benchmark --markdown relatorio.md --json relatorio.json
guardian benchmark --gerar-casos casos.json # generates the answer key for you to rewrite in your own words
guardian benchmark --casos casos.json --markdown relatorio.mdMost-used flags: --cenarios nada,router,guardian (chooses the scenarios; the code graph scenario is included by default when a generated graph already exists in the repository), --caracteres-por-token (default 3.7), --tokenizer cl100k (uses tiktoken instead of the characters/token ratio, if installed), --max-linhas-leitura (cap per file read in every scenario, default 2000 lines). The methodology details and the numbers for the reference repository are on the metrics page.
The curated pattern library is IronStack content, fed by real decisions from installed repositories, without ever centralizing the customer's raw content.
guardian sync-patternsSends only the slug, title, sha256 and embedding from the local index, never the body of the documents.
guardian contribute decisoes/0007-my-rule.md --tags git,migrationsThis is the only output that sends a document body: the content is anonymized locally, shown in full on screen and only leaves with your confirmation (without an interactive terminal, it requires --yes). guardian report warns when there are new decisions or wiki pages since the last report; it only names the command and sends nothing on its own.
The curator side (an internal IronStack role, requires GUARDIAN_ADMIN_TOKEN):
guardian proposals list --status pending
guardian proposals show <id>
guardian proposals approve <id> --slug my-slug --tags git,migrations
guardian proposals reject <id> --reason "already covered by pattern X"Claudex Loop: a cross-review skill between Claude Code and Codex. Before each round, reconcile the instructions and generate the brief for the reviewer:
guardian instrucoes sync
guardian brief "task description" --tool agents --saida .guardian/brief.mdDetails on why this solves the friction of different instruction files and sessions without memory: Claudex Loop section of the product page.
Obsidian: for those who keep an Obsidian vault alongside the repository:
guardian obsidian-setup # auto-detects the vault
guardian obsidian-setup /caminho/do/vault --yes
guardian obsidian-monitor /caminho/do/vault --daemon --debounce 2.0All subcommands from guardian --help, one per line. Run guardian <command> --help for the full list of flags of each one.
| Command | What it does |
|---|---|
| guardian init [--mode shared|branches] [--router …] [--quadro …] [--wiki …] [--decisoes …] [--trabalho …] [--claims …] [--handoffs …] [--quadro-max-linhas N] | Idempotent bootstrap of the structure and the working mode; writes the layout to guardian.json. |
| guardian doctor | Validates the structure and runs the audit; fails with exit ≠ 0 if there is an error. |
| guardian hook install [--max-files N] | Installs the pre-commit hook (idempotent; respects core.hooksPath). |
| guardian hook uninstall | Removes only the guardian block from the pre-commit hook. |
| guardian hook run {pre-commit} [--actor A] [--max-files N] | Runs the hook; this is what the script in .git/hooks calls. |
| guardian audit [--json] | Deterministic discipline audit (no LLM). |
| guardian index rebuild [--semantic|--lexical] | Rebuilds the SQLite index from the markdown files; incremental by sha256. |
| guardian index search <query> [--limit N] [--kind K] [--tool T] [--semantic|--lexical] [--json] | Full-text/hybrid top-k search; --tool filters kind=instrucao documents. |
| guardian instrucoes status | Per-folder table: files, lines, which tool family sees which. |
| guardian instrucoes sync | Creates/updates pointer blocks in the gaps found (idempotent). |
| guardian claim --actor A [--task T] [--minutes N] scope [scope ...] | Reserves a file scope (lease); refuses overlap with another actor. |
| guardian release [--actor A] claim_id | Releases an active claim. |
| guardian handoff create --actor A --to D --work-item W --summary S [--files ...] | Creates a continuity handoff between sessions. |
| guardian handoff accept --actor A handoff_id | Accepts a pending handoff (single acceptance). |
| guardian signup [--api-url U] [--email E] [--name N] [--repo R] [--invite C] [--aceito-termos] | Creates the account, the first installation and saves the connection (the normal way in). |
| guardian login [--api-url U] [--email E] [--repo R] [--new] [--yes] | Signs in to an existing account and connects this repository; reissues the key. |
| guardian reset-password [--api-url U] [--email E] | Sends the password reset link to the account email. |
| guardian configure --api-url U --api-key K | Configures the server connection manually (key issued by another login/admin). |
| guardian report [--actor A] | Audits and sends the report (metrics only) to the server; queues it if offline. |
| guardian sync-patterns | Syncs local patterns with the server: only slug/title/sha256/embedding, never the body. |
| guardian contribute <arquivo.md> [--tags a,b] [--yes] [--no-embedding] | Proposes a decision/rule to the curated library; anonymizes, shows the text and asks for confirmation. |
| guardian proposals list|show|approve|reject | Curation of the proposal queue (admin; token in GUARDIAN_ADMIN_TOKEN). |
| guardian embed <texto> [--semantic|--hashing] [--json] | Generates a local 384-dimension embedding (for inspection/debugging). |
| guardian license [--force] | Checks the license state (validated once a day, with cache and offline grace). |
| guardian benchmark [--casos F] [--gerar-casos F] [--cenarios ...] [--json F] [--markdown F] | Compares token usage: nothing (grep) × code graph × router × guardian index. |
| guardian brief "<tarefa>" [--tool claude|agents|gemini|cursor] [--limit N] [--max-tokens N] [--saida F] [--json] | Markdown context package to paste into a plan or a review briefing. |
| guardian obsidian-setup [vault_path] [--yes] [--json] | Configures the integration with an Obsidian vault (auto-detects it or uses the given path). |
| guardian obsidian-monitor vault_path [--daemon] [--debounce S] | Monitors the Obsidian vault in the background. |
Yes, for the local core: init, doctor, audit, index, claim, release, handoff and the pre-commit hook do not need the server. report queues and resends when the network returns; license uses a local cache with offline grace.
By default, never the content of your files. report sends metrics (audit score, counts, protocol file paths, branch/head); sync-patterns sends the slug/title/sha256/embedding of the index. The only exception is contribute, which sends text only after it has been anonymized locally and shown to you for confirmation.
No. init, doctor, audit, index, claim, release, handoff and hook work without a server. The account comes into play for report, license, sync-patterns, contribute and the curated library.
The free plan covers 1 repository per account; the second installation answers with the plan limit (402). See docs/termos-de-uso.md and docs/guia-do-testador.md in the product repository.
Remove the protocol files from the repository and run guardian hook uninstall. Nothing is tied to an external service, because the protocol is git.
Published release · 0.1.9 · 2026-10-02
Sessions from different clients can discover peers and exchange messages within one repository. The desktop brings together MCP configuration, sessions, human messaging and update state.
Use the official installer with MCP and update extras on Python 3.11. Initialize the repository protocol and install the hook. Keep credentials on your machine. The full protocol guide is at ironstack.dev.br/en/guardiancontext/manual/.
uv tool install --python 3.11 --refresh "guardiancontext[semantic,desktop,mcp,update]"guardian --versionguardian initguardian hook installguardian-desktopChoose a repository in Operations and copy the MCP configuration. It includes the required paths without an access token. The server accepts authenticated local connections; keep its port off the network. Worktrees sharing a git common dir can discover each other. Separate clones have different identities. You choose where to paste the client configuration. The MCP server does not start models.
guardian --root /caminho/do/repo mcp --configcodex mcp add guardian -- guardian mcpclaude mcp add --scope user guardian -- guardian mcpguardian sessions listStart the native session in a foreground terminal. Provide the task through stdin; the client keeps its configured model and effort. In the desktop, choose a recipient, write the message and confirm sending. The inbox belongs to this worktree's CLI identity. Acknowledge only after reading. Revocation cancels the identity; the native process may take one cycle to exit. A queued message may still be unread. If delivery to the provider is uncertain, the supervisor does not resend automatically. Pipes must use UTF-8: tasks accept up to 64 KiB and messages up to 16 KiB. One leading BOM is removed; remaining line endings are preserved. In PowerShell, use $OutputEncoding = [Text.UTF8Encoding]::new($false). --model, --effort and --read-only apply only to the session being started. In Codex, --approve-guardian-tools preapproves only the six Guardian tools; use after human authorization. Discarded messages do not prove reading. messages retry ID --confirm requires an active CLI actor in the same repo and an uncertain submitted delivery; it keeps the ID and key and acknowledges the risk of duplicate delivery. Ambiguous legacy purges are excluded from acknowledgements during database migration.
guardian sessions start --provider codexguardian sessions start --provider claudeguardian sessions stop IDguardian messages send --to IDguardian messages inboxguardian messages ack IDOperations shows the installed version, update policy and last result. Check release queries compatible stable versions. Before enabling a legacy install, migrate hooks in every repository and confirm migration. Close and request update shuts down the desktop before preparation or scheduling. Other active clients may defer it. Reopen afterwards and check the result. Editable/pip or unknown-origin installations need manual updates. Keep locks and journals: deleting them to force an update can leave the installation incomplete.
guardian update statusguardian update check --forceguardian hook installguardian update enable --confirm-legacy-migratedguardian update disableguardian update applydeferred means the update was postponed: check active clients and hook migration. journal_failed means a failure before installation; the current version was preserved. rolled_back confirms recovery after a failed health check. For rollback_required or rollback_failed, reinstall the previous version and inspect the journal. Keep wheels referenced by recovery receipts. An offline check preserves the current version. After updating, check the installed version and the clients used in your environment. The October 2, 2026 canary validated communication with real models and recovery in the recorded scenarios; it does not measure a production SLA or prove every upgrade path.
Run the simulation from Operations or guardian simulate. It creates disposable HOME, GUARDIAN_HOME and repository state in another process. Tests use real SQLite, RPC protocol and locks; model, installation and health check are simulated. Results show scenario pass counts and local latency. AI answer quality, network performance and an SLA need their own measurements. Website targets describe expected behaviour; simulation numbers apply to the reported scenarios and sample only. There is no overall quality score.
guardian simulate --samples 20guardian simulate --samples 20 --json reviewed-result.jsonguardian benchmarkguardian manual --lang enThe latest result is .guardian/quality-result.json. An atomic write under a lock retains one record with version, UTC date, platform, counts and p50/p95. Message bodies, session IDs, paths and hostnames stay out of the result. CLI and desktop read the same file. You can export the JSON, review it and pass --evidence to the site generator. The app does not upload results automatically. A small sample leaves production scenarios uncovered.