Share Bravos with your team
Bravos keeps its setup in the repository, so git is how a team shares it. Commit
the files bravos setup writes. A teammate who clones the repository and has
Bravos installed then gets the same briefing, threat model and design context
in their first session, with nothing to configure.
Before you start
Section titled “Before you start”- A repository set up with Bravos.
What to commit
Section titled “What to commit”After bravos setup --agent claude,codex and the first annotations, the
audit-notes fixture had these new files. None of them is gitignored:
| Path | What it is |
|---|---|
.bravos/hooks/, .bravos/hooks/lib/ |
the hook scripts every agent’s registration runs: session start, coach, threat cards, pre-PR gate and autopilot |
.bravos/hooks/lib/proof-tool-pins.json |
the GuardLink and cxg versions this Bravos pins, which the CI workflows install |
.bravos/setup.json |
the repository’s setup answers, for bravos setup --change |
.bravos/skills.lock |
the sha256 of every file Bravos wrote, so an update keeps files you edited |
.bravos/context/ |
your design documents and their index, when you add any. See context |
.claude/skills/, .agents/skills/ |
the 16 Bravos skills and GuardLink’s playbook skills |
.claude/settings.json, .codex/hooks.json, .cursor/hooks.json, .agents/hooks.json |
each agent’s hook registration |
.mcp.json, .codex/config.toml |
MCP servers: guardlink, cxg, and the code graph on Team |
.cursor/rules/bravos.mdc |
Cursor’s pointer to the skills |
CLAUDE.md, AGENTS.md |
GuardLink’s block telling agents how to keep the threat model |
.guardlink/ |
the threat model: definitions, sidecars, config, and intent.md once context is recorded |
.github/workflows/bravos-*.yml |
the PR gate and nightly, with --ci on Team |
Which agent files appear depends on the agents you chose. GuardLink also adds
.gitignore entries for its generated exports, and docs/GUARDLINK_REFERENCE.md.
What stays out of git is what a run produces on one machine. Each of these
folders gets its own .gitignore of * when it is first written:
| Path | Written by |
|---|---|
.bravos/sast/ |
bravos sast run: run folders and the analyzer’s caches |
.bravos/dashboard/ |
bravos dashboard |
.bravos/reports/ |
bravos report data |
.bravos/workspace/ |
bravos workspace |
.bravos/watch/ |
the hooks, for the event log bravos watch shows |
.bravos/resync/ |
bravos resync |
Your answer to “should the agent commit Bravos’s files”, set with
bravos prefs set commits, is kept under the clone’s .git/ directory and is
never committed.
What a teammate sees without Bravos
Section titled “What a teammate sees without Bravos”A teammate who clones the repository but has not installed Bravos still has
the committed hook registrations, and their agent still runs them. To check
what that teammate sees, the fixture was cloned under a fresh home folder with
no bravos, guardlink or cxg on PATH, and the session-start hook run the
way Claude Code’s registration in .claude/settings.json runs it:
node "$CLAUDE_PROJECT_DIR/.bravos/hooks/session-start.mjs" --harness claudeThe banner it returned for the person ends:
Bravos 1.18.0 · Freethreat counts unknownguardlink not found on PATH — run bravos doctorTruncated to the banner’s last three lines, after the logo, repository name, commit and branch. The briefing it returned for the model:
GuardLink security picture (bravos) — audit-notes @ 33e0056, base origin/mainguardlink: not found on PATH — run bravos doctorNext: /bravos for the next step · /bravos-annotate to extend coverage · /bravos-recheck after a fixThe Codex registration gives the same lines. The banner shows that the
repository uses Bravos, but it does not say how to install it, and the
bravos doctor it names is not on that teammate’s machine. Tell new
teammates to install Bravos yourself, for example in your README or
contributing guide:
npm install -g @bugb-technologies/bravosbravos setupWhat a teammate sees with Bravos
Section titled “What a teammate sees with Bravos”With Bravos installed, the teammate’s bravos setup in the clone asks nothing
about the repository’s setup and changes no file. Without a terminal, which is
how their agent runs it, it reports:
bravos setup: no terminal here, so this is upkeep only: nothing is asked and nothing new is installed. In a terminal, bravos setup is the guided setup.repository: up to date with bravos 1.18.0In a terminal, setup lists what the repository is set up with and asks whether to keep it or change it. Keep is the default.
The same session-start hook then returns the whole picture. The banner:
Bravos 1.18.0 · Free2 open · 100% annotation coverage2 critical2 / 2 files0 CONFIRMED FINDINGS · 2 claims untestedTop threatscritical #cmdi ×1critical #sqli ×1All findings bravos dashboard────────────────────────────────────────────────────────────────────────────SETUP 1/9 · Intent none · Code graph lockedPre-PR off · Autopilot off · CI offSAST off · Proving not set · Target noneNext: record what the app intends → /bravos-contextTruncated: the two blocks are taken from the banner, without the logo beside the first one or the lines between and after them. The briefing for the model begins:
GuardLink security picture (bravos) — audit-notes @ 33e0056, base origin/mainOpen exposures: 2 (critical 2, high 0, medium 0, low 0) · coverage 100% (2/2 files) · worklist 0 filesPlan: Free (researcher) — the pre-PR gate, CI and nightly workflows, scheduled upkeep, multi-repository workspaces, campaigns, SAST, the code graph are on Team · bravos account activate starts a 30-day Team trial, no cardTruncated after the plan line. It goes on with the annotation mode, what to test next, teammates’ open pull requests, the recorded intent, the proving choice, the code graph, SAST, the setup score, and how to coach this person. The plan is the teammate’s own: each machine’s licence decides it, and the committed files carry no licence.
This capture was taken before context was recorded, so it shows Intent none.
Once .guardlink/intent.md and .bravos/context/ are committed, the
teammate’s agent reads the same intent and design rules as yours.
- Context from your design documents
- Run Bravos in CI/CD: gate every pull request, including those from teammates who do not run Bravos.

