Annotate a repository

bugb 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

• guardlink installed, and a coding-agent CLI (claude, codex, or gemini) — see What bugb needs.
• A repository with a clean working tree. The command creates a branch; a dirty tree makes it harder to see what the agent wrote.

The agent runs with its permission prompts off

As shipped, bugb launches each agent with approvals bypassed — --dangerously-skip-permissions for claude, --dangerously-bypass-approvals-and-sandbox for codex, --approval-mode yolo for gemini. That is what makes an unattended loop possible, and it means a repository whose contents can steer an agent can steer this one.

The argv is per-phase configuration, not code, so it can be narrowed in $BUGB_HOME/config.toml. See Authorization and blast radius.

Run it

bugb annotate .

The full surface:

usage: bugb annotate [-h]
                     [--agent {claude,codex,gemini,bridge,openai,anthropic}]
                     [--lens LENS] [--focus FOCUS] [--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
  --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

--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:

bugb 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

bugb model .
bugb inspect .

bugb model rebuilds the threat model from what is now in the source; bugb 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 bugb/run-<run-id>:

git diff main...HEAD

Related

• Annotate an existing codebase — guardlink’s own annotation workflow, and what each annotation means.
• Why annotations live in code — the argument for the format bugb is writing.
• Run the loop unattended — annotation as one phase of the full loop, rather than a command you run yourself.