StableStack

Catch the subtle bugs AI assistants introduce.

A lightweight linter that catches issues traditional linters miss — non-determinism that breaks LLM caching, silent exception swallowing, async mistakes, SSR pitfalls, and more. 146 rules across 23 categories, with first-class support for Python, JavaScript/TypeScript, and C# (including Unity).

Marketing site: stablestack.ai

Install

# Python (recommended)
pip install stablestack

# Node.js — thin wrapper around the pip package
npx stablestack

After upgrading, pin the version — pip caches aggressively:

pip install stablestack==0.3.26

Quick Start

# Check your source directory
stablestack src/

# Check specific files
stablestack app.py utils.py

# CI mode (exit 1 on errors)
stablestack src/ --ci

# JSON output
stablestack src/ --format json > results.json

# Only run critical rules
stablestack src/ --tier critical

# List every available rule
stablestack --list-rules

# Explain a specific rule
stablestack explain DET001

Claude Code Integration

StableStack ships opt-in Claude Code slash commands. Run once per repo:

stablestack init                 # pyproject.toml + .stablestackignore + /check, /fix-production slash commands
stablestack init --minimal       # just pyproject.toml
stablestack init --no-commands   # skip the slash commands

After init, inside Claude Code you can use:

• /check — run StableStack and fix findings
• /fix-production — detect your CI/CD platform, monitor builds, and keep fixing until production is green

StableStack never writes files to your repo unless you run init explicitly.

Language Support

What It Catches

Full reference: stablestack --list-rules

Free vs. Paid Tiers

• Free (24 rules) — always available, no license required. Covers critical security, schema, project setup, quality, structure, async, API, and C# checkers.
• Paid (122 rules) — unlocked with stablestack activate <license-key>. Buy a license at stablestack.ai.

Pricing and features: stablestack.ai/pricing.

Example Output

src/cache.py

  ⚠ Line 42: Looping through 'config.items()' without sorting. This may produce different results on different runs.

    Problem:
      for key, value in config.items():

    Fix:
      for key, value in sorted(config.items()):

    Why? Dictionary order isn't guaranteed to be the same every time your program runs.
    This can cause tests to pass sometimes and fail other times, and can break caching
    systems that depend on consistent output.

────────────────────────────────────────────────────────────
Found 1 warning in 1 file

Configuration

Configure StableStack in your pyproject.toml:

[tool.stablestack]
# Enable only specific rules (empty = all enabled)
enable = []

# Disable specific rules
disable = ["QUAL005", "QUAL006"]

# Path patterns
include = ["src/**/*.py"]
exclude = ["**/migrations/**", "**/test_*.py", "node_modules/**"]

# Override severity per rule
[tool.stablestack.rules.DET001]
severity = "info"

You can also add a .stablestackignore file (glob patterns, one per line) for paths the checker should skip.

CLI Options (essentials)

Usage: stablestack [OPTIONS] [PATHS]...

Options:
  -f, --format [text|json|claude]  Output format (default: text)
  -c, --config PATH                Path to pyproject.toml config
  --enable TEXT                    Comma-separated rule IDs to enable
  --disable TEXT                   Comma-separated rule IDs to disable
  --ci                             Exit 1 if any errors found
  -t, --tier [critical|recommended|optional|preference]
                                   Run ONLY rules from this tier
  -u, --up-to [critical|recommended|optional|preference]
                                   Run rules up to and including this tier
  --list-rules                     List all available rules and exit
  --stats                          Show codebase statistics
  --baseline PATH                  Only report issues not in baseline
  --generate-baseline              Generate a baseline file
  --fix                            Automatically fix issues where possible
  --dry-run                        Show what --fix would do
  -w, --watch                      Watch for changes and re-run
  --top INTEGER                    Show only the top N findings
  --help                           Show full help

Subcommands:
  stablestack init       Install Claude Code commands and config files
  stablestack explain    Explain a specific rule (e.g. `stablestack explain DET001`)
  stablestack activate   Activate a paid license key

Why StableStack?

AI coding assistants are fast, but they ship patterns traditional linters don't catch:

• Non-determinism that breaks LLM caching and causes flaky tests
• Hardcoded secrets that slip into git history before review
• Silent exception swallowing that hides production bugs
• Missing await on async calls that return without doing any work
• SSR-unsafe code that crashes in Next.js production builds
• Unity anti-patterns like GameObject.Find in Update() loops that kill frame rates
• Weak types (any, Dict[str, Any]) that bypass IDE checking

StableStack focuses specifically on the shape of bugs AI assistants generate.

Repository Structure

Development Setup

Running tests

cd stablestack
PYTHONPATH=src python -m pytest tests/ -v

Running the site locally

cd site
npm install
npm run dev

Secrets management

This project uses Doppler for secrets. Never commit .env files.

brew install dopplerhq/cli/doppler
doppler login --scope /path/to/vibecheck
doppler setup

# Run commands with secrets injected
doppler run -- stablestack src/

Ask a team member to add you to the CTS workspace in Doppler.

Contributing

See CONTRIBUTING.md.

License

MIT — see LICENSE.