BrassCoders Setup Guide: From Install to CI in 30 Minutes

This guide walks the full BrassCoders setup end to end. BrassCoders, the scanner that catches what AI assistants structurally miss, runs 12 static-analysis tools locally and produces a ranked YAML file your AI assistant can read directly — this guide gets you from a fresh machine to a working CI integration in under 30 minutes. Each section is a procedural step; follow them in order.

Install BrassCoders

BrassCoders installs in one command via pipx: pipx install brasscoders. The full install — including Bandit, Pylint, Pyre, Pysa, Semgrep, ast-grep, detect-secrets, and BrassCoders's custom scanners — takes 30-60 seconds and requires Python 3.10 or newer.

Why pipx and not pip: pipx installs CLI tools into isolated virtual environments so the BrassCoders dependencies don't conflict with your project's dependencies. Same effect as python -m venv .venv-brass && .venv-brass/bin/pip install brasscoders, with one command and automatic PATH management.

If you don't have pipx yet, install it once: brew install pipx on macOS, python3 -m pip install --user pipx on Linux/Windows, then pipx ensurepath to put the pipx binaries on your PATH. After that, the BrassCoders install is one line.

Verify the install: brasscoders --help should print the usage banner. If you see "command not found," your PATH doesn't include pipx's bin directory — restart your shell or check pipx ensurepath output.

Run Your First Scan

BrassCoders scans run with a single command from your project root: brasscoders scan .. The OSS core makes zero outbound network calls; the scan typically takes 5-30 seconds depending on codebase size and produces YAML output in .brass/ inside the scanned directory.

The first run will look something like this:

$ cd ~/code/your-project
$ brasscoders scan .
Scanning project (12 scanners)...
✓ bandit            142 raw findings
✓ pylint            383 raw findings
✓ pyre              0 raw findings
✓ pysa              4 raw findings
✓ semgrep           67 raw findings
✓ ast-grep          21 raw findings
✓ detect-secrets    2 raw findings
✓ brass-ai-pattern  18 raw findings
✓ brass-privacy     5 raw findings
✓ brass-secrets     2 raw findings
✓ brass-performance 11 raw findings
✓ brass-jsts        N/A (no JS/TS files)
Total: 655 raw findings → 47 critical_issues after filtering
Output: .brass/ai_instructions.yaml
Time: 18.7s

Open .brass/ai_instructions.yaml to see the ranked critical issues. The file is designed to fit comfortably in any AI assistant's context window — typically 100-500 lines versus the 3000-10000 lines of raw scanner output.

Understand the .brass/ Output

BrassCoders writes seven YAML files to .brass/ inside your project root. The most important one is ai_instructions.yaml — the short summary file your AI assistant reads. The other six are reference views (per-file, per-category, statistics) you'll only look at when you need detail.

The full set:

• ai_instructions.yaml — Top-level summary, ranked critical issues, AI-readable instructions. This is the one you hand to your AI assistant.
• detailed_analysis.yaml — Every finding from every scanner, grouped by type.
• file_intelligence.yaml — Findings collated per file.
• security_report.yaml — Security-only view (Bandit, Pysa, secret detection).
• privacy_analysis.yaml — Present only when PII findings exist.
• statistics.yaml — Aggregate metrics (counts by severity, scanner, finding type).
• brass.log — Diagnostic log of the scan run.

File permissions: the directory is created at 0700 and YAML files at 0600 (POSIX). BrassCoders scans private source code, so the output is locked down to your user account.

BrassCoders also writes a .brass/.gitignore that excludes everything in the directory. If you want to commit the output, override that explicitly. Most teams treat .brass/ as ephemeral scan artifacts and let CI regenerate them per PR.

Integrate With Your AI Assistant

BrassCoders output is filesystem-resident plain text designed for AI consumption. Any AI assistant with file-read capability — Claude Code, Cursor, Continue, Aider — can read .brass/ai_instructions.yaml directly with a single instruction in the prompt.

The canonical hand-off prompt:

Read .brass/ai_instructions.yaml in this project. Work through each entry in critical_issues in order. For each one, read the noted file at the noted line, decide whether the finding is real or a false positive given the surrounding code, and if real propose a diff. If you're unsure, mark it for human review and move on.

The AI then walks the findings sequentially. For a typical 47-critical-issue scan, expect 2-3 minutes of AI walk-through plus 5-10 minutes of human approval on the proposed diffs. The constraint that makes this work: the AI is reviewing 47 deterministic findings, not 655 raw ones or an unbounded diff.

Tool-specific variations: Cursor uses @ file references in the composer; Continue uses @file slash commands; Aider uses /add. The prompt template is the same; only the file-reference syntax changes.

Add BrassCoders to CI

BrassCoders runs in any CI environment with Python 3.10+. The minimal CI integration is a three-line addition: install brasscoders via pipx, run brasscoders scan ., and grep the output for CRITICAL findings to fail the build. The full scan adds 30-60 seconds per PR.

GitHub Actions:

name: BrassCoders scan
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: { python-version: '3.12' }
      - run: pipx install brasscoders
      - run: brasscoders scan .
      - run: |
          if grep -q "severity: CRITICAL" .brass/security_report.yaml; then
            echo "Critical findings present. Failing build."
            cat .brass/ai_instructions.yaml
            exit 1
          fi

GitLab CI:

brass_scan:
  image: python:3.12
  script:
    - pip install pipx && pipx install brasscoders
    - brasscoders scan .
    - |
      if grep -q "severity: CRITICAL" .brass/security_report.yaml; then
        echo "Critical findings present"
        exit 1
      fi
  artifacts:
    paths:
      - .brass/
    when: always

For pre-commit (local), use the same pattern in .git/hooks/pre-commit. Pass --offline so the scan makes no network calls during the commit.

Activate the Paid Plan (Optional)

BrassCoders Paid is optional but recommended — the OSS core stays free forever. Paid activation takes one command after subscribing: brasscoders activate <license-key>. From that point, scans automatically use the AI-powered enrichment that turns roughly 1500 raw findings into 300 actionable ones.

Subscribe at coppersun.dev/pricing.

What activation adds: semantic deduplication (similar findings get collapsed into one ranked entry), ranking against your project signature (a SQL injection in a CLI tool ranks differently than the same finding in a web service), and cluster sizing (findings carry a count of how many similar issues were collapsed into them). The OSS core does a heuristic filter that gets you partway there; the Paid plan does the full enrichment pass.

What activation does NOT change: the scanners. The same 12 scanners run regardless of license state. Only the post-detection enrichment changes.

Each license covers 3 machine activations. Run brasscoders license to see your status and remaining token budget. Run brasscoders portal to manage your subscription via LemonSqueezy's hosted billing portal. Cancel any time; service continues until the end of the current billing period.

Configuration: .brassignore and Other Tweaks

BrassCoders reads a .brassignore file from your project root the same way git reads .gitignore — line-by-line glob patterns of files to skip. The most common tweaks: skip generated files, skip test fixtures, skip vendored third-party code, and exclude language-specific build directories.

A reasonable starting .brassignore:

# Generated code
*_pb2.py
*_pb2_grpc.py
generated/

# Test fixtures (intentionally bad code)
tests/fixtures/
**/test_fixtures/

# Vendored third-party
vendor/
third_party/

# Language-specific build artifacts
__pycache__/
*.pyc
dist/
build/
node_modules/
.venv/

# Large generated assets
*.min.js
*.min.css

Other useful flags. --offline forces zero network calls regardless of license state. --check-package-hallucination enables the optional package-existence check (the only OSS-core path that makes outbound calls). --no-enrich skips the Paid plan's gateway call even with an active license. Use brasscoders scan --help to see the full set.

Closing

The BrassCoders setup is intentionally minimal: install, scan, hand off, optionally activate. The OSS core does most of the work for free; the Paid plan adds the AI-powered enrichment when team size justifies it.

For the broader context on AI code review workflows and where BrassCoders fits, see AI Code Review: The Practical Guide for 2026. For the tooling landscape comparison, see the Static Analysis Buyer's Guide.