Backpressure

Assess your repository's readiness for AI coding agents

Backpressure is a CLI tool that evaluates whether your codebase has sufficient guardrails—tests, linters, CI/CD, documentation—to safely work with AI coding agents like Claude, GitHub Copilot, or Cursor. It assigns a maturity level (1-5) based on how well your repository can verify and validate AI-generated changes.

Why Backpressure?

AI coding agents can accelerate development, but they need "backpressure"—automated checks that catch and prevent errors. Without proper guardrails, AI-generated code can introduce bugs, security vulnerabilities, and technical debt.

Backpressure analyzes 41 criteria across 7 categories to determine if your repository has the infrastructure to:

• ✅ Catch errors through automated testing
• ✅ Enforce code standards with linters and formatters
• ✅ Validate changes in CI/CD pipelines
• ✅ Provide clear documentation for AI context
• ✅ Maintain code quality and security

Features

• Multi-Language Support: Node.js, Python, Go, Rust, Java, Kotlin, Swift/iOS, C#, Ruby, PHP
• Monorepo Detection: npm/yarn/pnpm workspaces, Lerna, Nx, Turborepo, Kotlin multi-module
• Profile-Based Filtering: Auto-detects your stack and marks irrelevant criteria as N/A (e.g., iOS lock files are N/A on a Python project)
• 7 Category Assessment: Developer Environment, Security, Style & Linting, Documentation, Testing, CI/CD, Code Health
• 5 Maturity Levels: From basic (Level 1) to expert (Level 5)
• AI-Powered Checks: Optional subjective quality assessment using Claude
• Multiple Output Formats: Rich terminal UI, JSON, or interactive web dashboard
• CI/CD Integration: Quality gates with --min-level and --ci flags
• Actionable Recommendations: Prioritized by impact and effort

Installation

npm install -g backpressure

Quick Start

# Analyze current directory
backpressure

# Analyze specific repository
backpressure /path/to/repo

# With AI-powered quality checks (requires Claude CLI)
backpressure --agent claude

# CI mode with minimum level requirement
backpressure --ci --min-level 3

Usage

Basic Command

backpressure [path] [options]

Options

| Option | Description | Default | |--------|-------------|---------| | [path] | Path to repository to analyze | Current directory | | --agent <model> | Enable AI-powered checks (currently supports claude) | Disabled | | --ci | Run in CI mode (non-interactive, plain output) | false | | --format <type> | Output format: text or json | text | | --min-level <level> | Minimum maturity level required (1-5). Exit code 1 if not met | None | | --no-color | Disable colored output | Colors enabled | | --no-web | Disable web dashboard server | Web enabled | | -v, --version | Display version number | N/A |

Configuration File

Generate a starter configuration file:

backpressure init

This creates backpressure.config.json with all available options. See Configuration for details.

Output Formats

Terminal Output (Default)

Rich, color-coded terminal display with:

• Maturity level badge with progress bar
• Active profiles line (e.g., Active Profiles: node, web-frontend, general)
• Category summary table with pass/fail counts and N/A column
• Detailed criteria breakdown per category (✓ pass, ✗ fail, ⊘ N/A, ⊝ skipped)
• Top 10 prioritized recommendations

backpressure

CI Mode: Plain text output without colors for continuous integration:

backpressure --ci
# or set CI=true environment variable

JSON Output

Machine-readable format for automation and integration:

backpressure --format json > report.json

Perfect for:

• CI/CD pipeline integration
• Custom report generation
• Historical tracking
• Data analysis

Web Dashboard

Interactive React-based visualization with:

• Radar chart showing category scores
• Expandable category cards with criteria details
• Prioritized recommendations list
• Dark theme UI

backpressure --web
# Automatically opens in browser

Disable with --no-web flag.

Maturity Levels

Backpressure assigns maturity levels from 1 (basic) to 5 (expert) based on passing criteria:

| Level | Name | Description | Key Requirements | |-------|------|-------------|------------------| | 1 | Basic | Fundamental tooling in place | Lock files, license, linter, test framework, README | | 2 | Intermediate | Development workflow documented | Environment setup, security policy, formatter, CI config | | 3 | Advanced | Quality automation established | Type checking, pre-commit hooks, test coverage, architecture docs | | 4 | Professional | Comprehensive CI/CD and testing | E2E tests, CI enforcement, branch protection, dead code detection | | 5 | Expert | AI-enhanced quality practices | High-quality tests and docs verified by AI analysis |

Progression: Each level requires ≥80% of its criteria to pass (configurable). Lower levels must be achieved before reaching higher levels.

Categories

🛠️ Developer Environment (Level 1-3)

• Lock files for reproducible builds
• Environment variable documentation
• Setup scripts and version pinning
• Containerization (Docker)

🔒 Security (Level 1-4)

• LICENSE file
• SECURITY.md policy
• Dependency update automation (Dependabot, Renovate)
• Security scanning (CodeQL, Snyk)
• Secrets detection (gitleaks)

🎨 Style & Linting (Level 1-3)

• .editorconfig
• Linters (ESLint, Ruff, ktlint, SwiftLint, etc.)
• Formatters (Prettier, Black, ktfmt, etc.)
• Type checking (TypeScript strict, mypy)
• Pre-commit hooks (Husky, Lefthook)

📚 Documentation (Level 1-5)

• Substantive README.md
• CONTRIBUTING.md
• API documentation (OpenAPI, JSDoc, Dokka)
• CODEOWNERS
• AI context files (CLAUDE.md, .cursorrules)
• Architecture documentation
• AI-assessed quality checks

🧪 Testing (Level 2-5)

• Test framework configuration
• Test file presence
• Runnable test scripts
• Code coverage setup
• E2E/integration tests
• AI-assessed test quality

🚀 CI/CD (Level 2-4)

• CI configuration (GitHub Actions, GitLab CI, etc.)
• Automated test execution
• Lint enforcement
• Build automation
• Deploy/release pipelines
• Branch protection rules

💚 Code Health (Level 3-5)

• Lock file freshness (< 6 months)
• Dead code detection tools
• Bundle/binary size analysis

AI-Powered Checks

Enable optional AI-powered quality assessment using Claude:

backpressure --agent claude

Requirements:

• Claude CLI installed (npm install -g @anthropic-ai/claude-cli)
• Anthropic API key set (ANTHROPIC_API_KEY environment variable)

What AI evaluates:

• Test quality and meaningfulness
• README completeness and effectiveness
• Documentation agent-friendliness
• Naming convention consistency
• Overall code health indicators

AI checks run in read-only mode with timeouts and structured output parsing.

Profiles

Backpressure auto-detects your project's technology stack and activates the appropriate profiles (e.g., node, python, ios). Criteria that don't apply to your stack are marked N/A and excluded from scoring — so an iOS project's lock-file check doesn't drag down a Python project's score.

Built-in profiles: node, python, go, rust, java, kotlin, android, ios, csharp, ruby, php, web-frontend, monorepo, general

Auto-detection is based on detected project types (lock files, config files, source directories). You can override auto-detection or add custom profiles via config.

Configuration

Create backpressure.config.json in your repository root:

{
  "categories": {
    "dev-environment": true,
    "security": true,
    "style-linting": true,
    "documentation": true,
    "testing": true,
    "ci-cd": true,
    "code-health": true
  },
  "criteria": {
    "dev-env-containerization": false,
    "security-secrets-detection": false
  },
  "threshold": 80,
  "ai": {
    "aiEnabled": false,
    "apiKey": "your-api-key-here"
  },
  "profiles": {
    "activeProfiles": ["node", "web-frontend"],
    "customProfiles": {
      "my-custom": {
        "id": "my-custom",
        "name": "My Custom Profile",
        "description": "Custom profile extending node",
        "extends": "node",
        "criteria": {
          "dev-env-ios-lock-files": false
        }
      }
    }
  }
}

Configuration Options

categories: Enable/disable entire categories

• dev-environment, security, style-linting, documentation, testing, ci-cd, code-health

criteria: Enable/disable specific checks

• See full criteria list for all 41 criterion IDs

threshold: Custom pass percentage (0-100, default: 80)

ai: AI configuration

• aiEnabled: Enable AI checks globally
• apiKey: Anthropic API key (or use ANTHROPIC_API_KEY env var)
• apiBaseUrl: Custom API endpoint (default: https://api.anthropic.com)

profiles: Profile configuration (optional — auto-detected by default)

• activeProfiles: Override auto-detected profiles (e.g., ["node", "web-frontend"])
• customProfiles: Define custom profiles with optional inheritance via extends

Priority: CLI flags > config file > environment variables > defaults

CI/CD Integration

Use Backpressure as a quality gate in your CI pipeline:

# .github/workflows/backpressure.yml
name: Repository Quality Gate
on: [pull_request]

jobs:
  backpressure:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install -g backpressure
      - run: backpressure --ci --min-level 3

Exit Codes:

• 0: Analysis passed (or minimum level met)
• 1: Analysis failed or below minimum level

Examples

Basic Analysis

$ backpressure
✓ Analyzing /Users/dev/my-project...

╔═══════════════════════════════════════╗
║  Repository: my-project               ║
║  Path: /Users/dev/my-project          ║
║  Project Types: node, typescript      ║
║  Monorepo: No                         ║
║  Active Profiles: node, web-frontend, general ║
╚═══════════════════════════════════════╝

Current Level: 2 ████████░░░░░░░░░░░░ (40% toward Level 3)

Category Summary:
┌─────────────────────┬────────┬───────┬─────┬────────┐
│ Category            │ Passed │ Total │ N/A │ Score  │
├─────────────────────┼────────┼───────┼─────┼────────┤
│ 🛠️  Dev Environment │   5    │   5   │  2  │  100%  │
│ 🔒 Security         │   4    │   5   │  0  │   80%  │
│ 🎨 Style & Linting  │   3    │   6   │  0  │   50%  │
└─────────────────────┴────────┴───────┴─────┴────────┘

Top Recommendations:
1. [LOW] Add pre-commit hooks (Husky, Lefthook)
   → Catches errors before they enter version control
2. [MED] Set up code coverage (Jest, pytest, etc.)
   → Ensures tests are comprehensive

The N/A column shows criteria that don't apply to your detected profiles (e.g., iOS lock files on a Node.js project). N/A criteria are excluded from scoring denominators.

JSON Output

$ backpressure --format json
{
  "repoPath": "/Users/dev/my-project",
  "projectInfo": {
    "detectedTypes": ["node", "typescript"],
    "isMonorepo": false,
    "activeProfiles": ["node", "web-frontend", "general"]
  },
  "activeProfiles": ["node", "web-frontend", "general"],
  "levelResult": {
    "currentLevel": 2,
    "nextLevelProgress": {
      "level": 3,
      "passed": 8,
      "required": 10,
      "total": 12
    }
  },
  "categoryScores": {
    "dev-environment": {
      "criterionResults": [
        {
          "criterionId": "dev-env-ios-lock-files",
          "status": "not_applicable",
          "message": "Not applicable to active profiles"
        },
        {
          "criterionId": "dev-env-lock-files",
          "status": "pass",
          "message": "Lock file found: package-lock.json"
        }
      ]
    }
  },
  "recommendations": [ ... ]
}

Each criterion result has a status field with one of: "pass", "fail", "not_applicable", "skipped".

CI Mode with Quality Gate

$ backpressure --ci --min-level 3
Repository Quality Check: FAIL
Current Level: 2
Required Level: 3
Missing 2 criteria to reach Level 3
$ echo $?
1

Migrating from v1 to v2

Breaking Change: CriterionResult shape

The pass and skipped boolean fields have been removed from CriterionResult. Use the status enum instead:

v1 (removed):

{ "criterionId": "dev-env-lock-files", "pass": true, "skipped": false, "message": "..." }

v2:

{ "criterionId": "dev-env-lock-files", "status": "pass", "message": "..." }

Status values: "pass" | "fail" | "not_applicable" | "skipped"

If you consume the JSON output programmatically, update your code:

// v1
if (result.pass) { ... }
if (result.skipped) { ... }

// v2
if (result.status === 'pass') { ... }
if (result.status === 'skipped') { ... }
if (result.status === 'not_applicable') { ... }

New fields in JSON output

• activeProfiles (top-level and inside projectInfo): array of active profile IDs
• Per-criterion status field (replaces pass/skipped booleans)

New terminal output markers

| Symbol | Meaning | |--------|---------| | ✓ / [PASS] | Criterion passed | | ✗ / [FAIL] | Criterion failed | | ⊘ / [N/A] | Criterion not applicable to active profiles | | ⊝ / [SKIP] | Criterion skipped (requires --agent flag) |

New profiles config field

Add optional profile overrides to backpressure.config.json:

{
  "profiles": {
    "activeProfiles": ["node", "web-frontend"]
  }
}

Leave this unset to let Backpressure auto-detect profiles from your project files.

Development

Prerequisites

• Node.js >= 22
• npm

Build

# Install dependencies
npm install

# Build CLI only
npm run build

# Build web dashboard
npm run build:web

# Build both
npm run build:all

# Run in development
npm run dev

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

Type Checking

npm run typecheck

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Credits

Built by gertig

Made with ❤️ to help teams safely adopt AI coding agents