briefed

Consequence-aware context for Claude Code. briefed gives Claude a live dependency map and consequence hooks — so before every file edit, Claude sees exactly what else will break.

What it does

1. Scans your repo — static analysis: dep graph, routes, schemas, test mappings, env vars, conventions
2. Installs hooks — before each edit, Claude gets: blast radius, affected routes, affected tests, affected schemas
3. Verifies at stop — after Claude finishes, a verification plan shows which tests to run and what changed

Everything fires automatically inside Claude Code. You run briefed init once.

Bench results

Consequence tasks (multi-file edits that require understanding blast radius)

Tested on epic-stack @ 19eeb4b, 6 tasks: add Prisma model fields, rename widely-used functions, add env vars, update routes.

| Arm | Correctness (mean 6 tasks) | Config | |---|---|---| | B — briefed context only | 2.50 / 5 | skeleton + dep graph, no hooks | | H — briefed + hooks | 4.00 / 5 | skeleton + consequence map hooks |

+60% correctness on consequence-heavy edits. Hooks closed the gap on tasks like extend-note-model (1→5) and healthcheck-include-version (1→5) by surfacing what downstream files, routes, and tests each edit affects — before Claude writes a line.

Knowledge tasks (explain-architecture, list-routes, env-var-audit, trace-auth-flow) are unaffected: A/B/H all score ~4.75/5.

SWE-PolyBench (v1.6, TypeScript)

| Task | baseline | briefed | |---|---|---| | mui/material-ui-13828 | Pass | Pass | | microsoft/vscode-106767 | Fail | Fail | | microsoft/vscode-135805 | Fail | Pass |

2/3 vs 1/3. The vscode-135805 win: adaptive skeleton (200 files) let the model locate multicursor.ts in 23 turns while baseline hit the 41-turn cap.

Install

npm install -g briefed
briefed init        # static analysis, hooks, dep graph
briefed init --deep # + LLM behavioral descriptions (uses claude -p, cached by SHA256)

briefed installs a post-commit git hook that re-indexes after every commit. No CI required.

How the hooks work

Once installed, you don't run briefed commands — everything fires inside Claude Code:

| Event | What fires | What Claude sees | |---|---|---| | Session start | session-start.cjs | skeleton: file tree, routes, schemas, dep graph | | Before each file edit | pre-edit.cjs | consequence map: blast radius, affected routes/tests/schemas for the file being edited | | After each file edit | post-edit.cjs | tracks which files changed | | Claude stops | stop.cjs | verification plan: tests to run, routes to check |

The consequence map for prisma/schema.prisma tells Claude which routes query the model, which tests cover it, and which seed files need updating — before it types a single character.

--deep flag

--deep is opt-in (not default) because it makes LLM calls using your claude -p subscription.

Without --deep: hooks fire, dep graph works, consequence map is fully functional. Fast.

With --deep: additionally generates one-line behavioral descriptions for each exported function and danger-zone annotations for high-centrality files. Results are cached by SHA256 — first run adds ~40-60s, re-runs are free. If claude isn't in PATH, silently skips.

The bench H arm (4.00/5) used --deep. Worth running.

What gets extracted

Static analysis only (unless --deep). Extractors run only when relevant files are present.

Code structure

• Function/class/type signatures via TypeScript AST (regex fallback for other languages)
• Dependency graph with PageRank-ranked file importance
• Import cycle detection (runtime imports only — type-only imports correctly ignored)
• Symbol-level cross-references and call-site lookup

APIs & data

• HTTP routes — Express, Fastify, Hono, Next.js, FastAPI, Flask, Django
  • Per-route auth detection
  • Per-route request body schema detection (Zod, validateBody, Schema.parse)
• Database schemas — Prisma, Drizzle, TypeORM, Django models, fields, relations
• Cross-layer graph linking frontend fetch calls to backend route handlers

Project context

• External deps with installed versions and import counts (Context7-aware)
• Environment variables (required vs optional, grouped by category)
• Build/test/dev scripts
• Monorepo workspace detection

Quality signals

• Complexity scoring per file
• TODO/HACK/FIXME/WARNING comment extraction
• Project conventions (naming, error style, export style)
• Test mappings (source → test file, with test names and assertion lines)
• Secret redaction

MCP tools

briefed mcp starts an MCP server for on-demand queries:

| Tool | What it does | |------|--------------| | briefed_context | Search modules by topic — returns contracts for best-matching directories | | briefed_issue_candidates | Given a bug report, returns top candidate files via keyword matching | | briefed_symbol | Look up a function/class/type — signature, description, importers, test coverage | | briefed_find_usages | Every call site of a symbol, including the defining file | | briefed_blast_radius | BFS over the dep graph — every file affected by changing a file | | briefed_routes | Filter API routes by method or path pattern | | briefed_schema | Look up database models with fields, types, and relations | | briefed_test_map | Look up which test covers a source file, with test names | | briefed_env_audit | Every env var the app reads — required/optional, category, consumers |

{
  "mcpServers": {
    "briefed": { "command": "briefed", "args": ["mcp"] }
  }
}

What gets written

your-repo/
├── CLAUDE.md                        # skeleton — Claude Code
├── AGENTS.md                        # cross-tool (Codex, Copilot, generic)
├── .cursorrules                     # Cursor IDE
├── codex.md                         # OpenAI Codex CLI
├── .github/copilot-instructions.md  # GitHub Copilot
├── .claude/
│   ├── settings.json                # hooks (PreToolUse, PostToolUse, Stop, SessionStart)
│   └── rules/
│       └── briefed-*.md             # path-scoped gotchas (--deep only)
└── .briefed/
    ├── contracts/                   # module behavioral contracts
    ├── index.json                   # module map for hook matching
    └── test-map.json                # source → test file mappings

CLI reference

briefed init              # scan + generate context + install hooks
briefed init --deep       # + LLM behavioral descriptions (cached)
briefed plan              # preview without writing
briefed stats             # token usage breakdown
briefed doctor            # validate setup, check staleness
briefed impact <file>     # map consequences of changing a file
briefed surface <target>  # locate implementation of a symbol/route/env var
briefed verify <files>    # build verification plan for changed files
briefed mcp               # start MCP server
briefed unhook            # remove git post-commit hook

Requirements

• Node.js >= 20
• Git (for the auto-update hook)
• Claude Code (for hooks and --deep)

License

MIT