Crucible

Your team's standards, applied by Claude, every time.

Claude without context applies generic best practices. Crucible loads your patterns—so Claude reviews code the way your team would, not the way the internet would.

├── Enforcement:   Pattern + LLM assertions that block bad code
├── Personas:      Domain-specific thinking (how to approach problems)
├── Knowledge:     Coding patterns and principles (what to apply)
├── Cascade:       Project → User → Bundled (customizable at every level)
└── Context-aware: Loads relevant skills based on what you're working on

Why Crucible?

• Enforcement — Not suggestions, constraints. Assertions block code that violates your patterns
• Consistency — Same checklist every time, for every engineer, every session
• Automation — Runs in CI, pre-commit hooks, and Claude Code hooks
• Institutional knowledge — Your senior engineer's mental checklist, in the repo
• Your context — Security fundamentals plus your auth patterns, your conventions
• Cost efficiency — Filter with free tools first, LLM only on what needs judgment

Not affiliated with Atlassian's Crucible.

Quick Start

pip install crucible-mcp

# Initialize your project
crucible init --with-claudemd

# Install enforcement hooks
crucible hooks install              # Git pre-commit
crucible hooks claudecode init      # Claude Code hooks

That's it. Crucible will now:

1. Run on every commit (pre-commit hook)
2. Review files Claude edits (Claude Code hook)
3. Block code that violates bundled assertions (security, error handling, smart contracts)

CLAUDE.md Setup

Add to your CLAUDE.md to inject rules at session start:

# Project

At session start, call get_assertions() to load enforcement rules.

For code review: crucible review

This tells Claude to load the active assertions before writing code, not just catch violations after.

How Enforcement Works

Claude writes code
    ↓
PostToolUse hook triggers
    ↓
Crucible runs pattern assertions
    ↓
Finding detected → Exit 2 (block) + feedback to Claude
    ↓
Claude fixes the issue

30 bundled assertions covering:

• Security: eval, exec, shell injection, pickle, hardcoded secrets, SQL injection
• Error handling: bare except, silent catch, empty catch blocks
• Smart contracts: reentrancy, CEI violations, access control, tx.origin auth

Customize with your own assertions in .crucible/assertions/:

# .crucible/assertions/my-rules.yaml
version: "1.0"
name: my-rules
assertions:
  - id: no-console-log
    type: pattern
    pattern: "console\\.log\\("
    message: "Remove console.log before committing"
    severity: warning
    priority: medium
    languages: [javascript, typescript]

MCP Tools

Add to Claude Code (.mcp.json):

{
  "mcpServers": {
    "crucible": {
      "command": "crucible-mcp"
    }
  }
}

Tool	Purpose
get_assertions()	Session start: Load enforced patterns into context
get_principles(topic)	Session start: Load engineering knowledge by topic
load_knowledge(files)	Session start: Load specific knowledge files
review(path)	Full review: analysis + skills + knowledge + assertions
review(mode='staged')	Review git changes with enforcement
delegate_*	Direct tool access (semgrep, ruff, slither, bandit)
check_tools()	Show installed analysis tools

Tip: Call get_assertions() at the start of a session so Claude knows what patterns to avoid before writing code.

CLI

# Review
crucible review                     # Review staged changes
crucible review --mode branch       # Review current branch vs main
crucible review src/file.py --no-git # Review without git

# Assertions
crucible assertions list            # List all assertion files
crucible assertions test file.py    # Test assertions against a file

# Hooks
crucible hooks install              # Install pre-commit hook
crucible hooks claudecode init      # Initialize Claude Code hooks

# Customize
crucible skills init <skill>        # Copy skill for customization
crucible knowledge init <file>      # Copy knowledge for customization

# Ignore patterns
crucible ignore show                # Show active patterns
crucible ignore init                # Create .crucibleignore
crucible ignore test <path>         # Test if path is ignored

# CI
crucible ci generate                # Generate GitHub Actions workflow

Customization

Everything follows cascade resolution (first found wins):

1. .crucible/ — Project overrides (checked into repo)
2. ~/.claude/crucible/ — User preferences
3. Bundled — Package defaults

Ignore patterns:

Crucible auto-excludes node_modules/, .next/, dist/, etc. Add project-specific patterns:

crucible ignore init
# Edit .crucible/.crucibleignore

Override a skill:

crucible skills init security-engineer
# Edit .crucible/skills/security-engineer/SKILL.md

Add project knowledge:

crucible knowledge init SECURITY
# Edit .crucible/knowledge/SECURITY.md

Add custom assertions:

mkdir -p .crucible/assertions
# Create .crucible/assertions/my-rules.yaml

See CUSTOMIZATION.md for the full guide.

What's Included

30 Bundled Assertions — Pattern rules for security, error handling, and smart contracts.

18 Personas — Domain-specific thinking: security, performance, accessibility, web3, backend, and more.

14 Knowledge Files — Coding patterns and principles for security, testing, APIs, databases, smart contracts, etc.

See SKILLS.md and KNOWLEDGE.md for details.

Documentation

Doc	What's In It
QUICKSTART.md	5-minute setup guide
FEATURES.md	Complete feature reference
ARCHITECTURE.md	How MCP, tools, skills, and knowledge fit together
CUSTOMIZATION.md	Override skills and knowledge for your project
SKILLS.md	All 18 personas with triggers and focus areas
KNOWLEDGE.md	All 14 knowledge files with topics covered
CONTRIBUTING.md	Adding tools, skills, and knowledge

Development

pip install -e ".[dev]"
pytest                    # Run tests (580+ tests)
ruff check src/ --fix     # Lint