Skip to content
Bugb Docs

BravosGuides

Annotate a repository

bravos annotate hands your repository to a coding-agent CLI and asks it to write the threat model into the source as guardlink annotations: what each part exposes, what mitigates it, which assets and trust boundaries exist. It sends no traffic. It does edit your code.

Use it when a repository has no annotations yet, or when you want a second pass from a different perspective over one that does.

Before you start

Section titled “Before you start”
  • guardlink installed, and a coding-agent CLI (claude, codex, or gemini) See Install Bravos.
  • A repository with a clean working tree. The command creates a branch; a dirty tree makes it harder to see what the agent wrote.

Run it

Section titled “Run it”
Terminal window
bravos annotate .

The full surface:

usage: bravos annotate [-h]
                       [--agent {claude,codex,gemini,bridge,openai,anthropic}]
                       [--lens LENS] [--focus FOCUS] [--model MODEL]
                       [--ai-fallback AI_FALLBACK] [--run-id RUN_ID]
                       [--no-checkpoint] [--json] [-v]
                       codebase


positional arguments:
  codebase              target repository root


options:
  -h, --help            show this help message and exit
  --agent {claude,codex,gemini,bridge,openai,anthropic}
                        coding agent to annotate with (default: the configured
                        one)
  --lens LENS           perspective to annotate from (admin, chained,
                        crosstenant, mitigation-audit, stduser, unauth)
  --focus FOCUS         narrow this pass in your own words, e.g. "only
                        critical threats in the sync layer"; it narrows the
                        lens and cannot relax the rules
  --model MODEL         model for the SELECTED agent this invocation,
                        overriding its `agents.<name>.model` setting; omit to
                        use whatever that CLI is configured with. Fallback
                        agents keep their own model — ids are vendor-specific
                        and do not transfer
  --ai-fallback AI_FALLBACK
                        order to try other coding agents when one fails,
                        comma-separated (e.g. gemini,codex); `none` switches
                        failover off. Overrides cxg.ai_fallback_chain for this
                        invocation
  --run-id RUN_ID       create or resume this run id
  --no-checkpoint       do not create a git branch on the target; annotations
                        are left uncommitted in the working tree
  --json                emit JSON
  -v, --verbose         stream phase events

The two flags that shape the pass

Section titled “The two flags that shape the pass”

--lens picks the perspective the agent annotates from. The same code yields different threats depending on who is assumed to be attacking it: unauth sees what an anonymous request reaches, crosstenant sees what one customer reaches of another’s, mitigation-audit asks whether a declared control actually holds. Six lenses exist and a verify run rotates through them. Lenses explains the rotation and why the order is not arbitrary.

--focus narrows a pass in your own words:

Terminal window
bravos annotate . --lens crosstenant --focus "only the billing and export paths"

Per its own help text, focus narrows a lens and cannot relax the rules. It is a scope reduction, not an instruction the agent can be talked out of.

After the pass

Section titled “After the pass”
Terminal window
bravos model .
bravos inspect .

bravos model rebuilds the threat model from what is now in the source; bravos inspect shows what the export will and will not carry. Both are covered in Build your first threat model.

Read the diff before you keep it. The branch is bravos/run-<run-id>:

Terminal window
git diff main...HEAD
Section titled “Related”