Skip to content

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.

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.

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:

Terminal window
node "$CLAUDE_PROJECT_DIR/.bravos/hooks/session-start.mjs" --harness claude

The banner it returned for the person ends:

Bravos 1.18.0 · Free
threat counts unknown
guardlink not found on PATH — run bravos doctor

Truncated 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/main
guardlink: not found on PATH — run bravos doctor
Next: /bravos for the next step · /bravos-annotate to extend coverage · /bravos-recheck after a fix

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

Terminal window
npm install -g @bugb-technologies/bravos
bravos setup

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.0

In 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 · Free
2 open · 100% annotation coverage
2 critical
2 / 2 files
0 CONFIRMED FINDINGS · 2 claims untested
Top threats
critical #cmdi ×1
critical #sqli ×1
All findings bravos dashboard
────────────────────────────────────────────────────────────────────────────
SETUP 1/9 · Intent none · Code graph locked
Pre-PR off · Autopilot off · CI off
SAST off · Proving not set · Target none
Next: record what the app intends → /bravos-context

Truncated: 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/main
Open exposures: 2 (critical 2, high 0, medium 0, low 0) · coverage 100% (2/2 files) · worklist 0 files
Plan: 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 card

Truncated 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.