How to Use Brass with Claude Code

Brass creates project intelligence files that Claude Code automatically reads, providing persistent context across all your coding sessions. Claude Code continuously draws rich insights from your Brass analysis as you work together.

Getting Started

After you've installed Brass in your project (see install page), Claude Code is ready to use your project intelligence.

Daily Usage

Standard Workflow

  1. Code normally—Brass runs automatically in the background
  2. Use Claude Code as usual—It now reads .brass/ intelligence files
  3. No additional steps required—Context persists between sessions

💡 Pro Tip:

While Claude Code naturally draws from Brass intelligence throughout your conversations, explicitly mention checking Brass when you need project-specific insights:

  • ✓Before committing code—Check for issues Brass found
  • ✓When troubleshooting bugs—See if Brass identified patterns
  • ✓With unexpected behavior—Check if Brass noted similar issues
  • ✓Before deploying—Review Brass security and quality findings
  • ✓Exploring unfamiliar code—Use Brass context for faster understanding

These moments call for your actual codebase insights rather than general programming advice.

When Claude Code Reads Brass Files

Claude Code automatically accesses these files when you mention your project:

  • .brass/CONTEXT.md—Project overview and technology stack
  • .brass/STATUS.md—Current development status
  • .brass/INSIGHTS.md—Code analysis and recommendations
  • .brass/HISTORY.md—Development patterns over time

Available Commands

Check Status

brass status

Shows analysis completion, last update time, and system health.

View Insights

brass insights

Displays current code analysis, security findings, and recommendations.

Manual Analysis

brass scout scan

Triggers immediate code analysis instead of waiting for automatic scan.

Force Refresh

brass refresh

Updates all intelligence files with latest project state.

View Help

brass --help

Shows all available commands and options.

What Brass Provides

Brass enhances Claude Code sessions by providing:

  • •Project-specific context instead of general programming knowledge
  • •Persistent memory that builds understanding over time
  • •Code analysis findings with specific file locations
  • •Architectural insights based on your actual codebase

Automatic Background Operation

Brass runs four analysis agents automatically:

Scout

Scans code patterns and structure (hourly)

Watch

Monitors file changes (every 5 minutes)

Strategist

Analyzes architecture and technical debt (every 6 hours)

Planner

Generates development recommendations (daily)

Example Usage

When you ask Claude Code "What security issues should I prioritize?", with Brass it can reference specific findings from your actual codebase instead of giving generic advice.

Before Brass:

"Generally, you should check for SQL injection, XSS vulnerabilities..."

With Brass:

"Based on your Flask application analysis in .brass/INSIGHTS.md, prioritize fixing the SQL injection vulnerability in user_auth.py:47 and the missing input validation in api/orders.py:123..."

Understanding Intelligence Files

The .brass/ folder contains markdown files that Claude Code reads:

CONTEXT.md

  • • Project type and main technologies
  • • Key directories and file structure
  • • Configuration and dependencies

STATUS.md

  • • Last analysis timestamp
  • • Code quality metrics
  • • Current development focus areas

INSIGHTS.md

  • • Security findings with line numbers
  • • Code pattern analysis
  • • Improvement recommendations

HISTORY.md

  • • Development activity patterns
  • • Code evolution tracking
  • • Change frequency analysis

Note: Brass requires a Claude API key and creates local analysis files. All processing happens locally on your machine.