How to use Brass

Three commands cover 95% of usage. Then you hand the YAML to your AI assistant and ship.

1

brassai scan

Analyze your project. Writes .brass/*.yaml with the prioritized findings.

# From your project root:
$ brassai --offline scan
# Or scan a specific path:
$ brassai --offline scan /path/to/project

Useful flags:

  • --fast — skip privacy + content moderation passes
  • --dev — source code only (skip tests, build artifacts)
  • --code / --privacy / --content — narrow scope
  • --offline — guarantee zero outbound network calls (default behavior; flag is for explicitness)
2

brassai filter

Pipe an AI reviewer's JSON output through Brass's noise-reduction. Returns the high-confidence findings.

# Pipe Claude / Cursor's review JSON in:
$ cat review.json | brassai filter
# Or as files:
$ brassai filter --input review.json --output filtered.json

CRITICAL findings always pass the filter. Style-only Pylint codes (C0301 line-too-long, etc.) are dropped. Per-file caps prevent any single file from dominating output.

3

brassai watch

Re-scan incrementally on file change. Useful while you're actively editing and want the YAML to stay current.

$ brassai --offline watch
# Polls every 2 seconds, debounced by 5 seconds.
# Tune with --poll-interval and --debounce-delay.

Watch mode runs while the command is in your terminal — Brass is on-demand by design, no background daemon, no auto-start. Ctrl+C to stop.

Reading the output

After a scan, .brass/ contains:

FilePurpose
ai_instructions.yamlTop-level summary; this is what you hand to Claude Code / Cursor
detailed_analysis.yamlEvery finding, grouped by type
file_intelligence.yamlPer-file priorities
security_report.yamlSecurity-only view
statistics.yamlAggregate metrics
privacy_analysis.yamlPrivacy-only view (only if PII findings exist)

Directory perms are 0700; YAML files are 0600 (POSIX). Brass scans private source code, so the output is locked down.

Hand off to Claude Code (or Cursor / Continue / etc.)

Open .brass/ai_instructions.yaml. Copy its contents into your AI assistant session. Ask the assistant to address the findings in order — the YAML is short on purpose so it fits comfortably in any context window.

A typical Brass-aware Claude Code prompt:

"Here's a Brass scan of this codebase: [paste YAML]. Address the critical_issues in order. For each one, propose a diff and explain the fix."