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.

Workflow Blueprints

Beyond checking code, StableStack scaffolds the process around it:

stablestack add-ci           # CI + deploy pipelines, detected from your repo
stablestack add-playwright   # starter E2E suite with anti-flake rules baked in

add-ci reads the repo before it writes — package manager (with a --package-manager override when multiple lockfiles make it ambiguous), typecheck/test/lint scripts, Prisma, Python/pytest, your deploy platform (Vercel, Amplify, Netlify, Render, Fly, Docker), and any CI that already exists. It refuses to write GitHub Actions into a GitLab/Bitbucket/CircleCI repo and leaves existing deploy workflows untouched. It generates:

• ci.yml — the PR gate: lint, typecheck, unit tests, the StableStack quality gate (baseline-aware, so legacy code adopts today), and E2E if a suite exists. Red blocks the merge.
• deploy-staging.yml — every push to main lands on staging; a polling health check verifies the deployed site (never just the deploy's exit code) and the Playwright suite runs against the deployed staging URL.
• deploy-production.yml — ships when the production branch advances. Promotion is a fast-forward (git push origin main:production), or automatic after green staging E2E with --auto-promote. Uses GitHub's production environment, so adding required reviewers gives an approval gate. Verifies the live site and tags every deploy.

Platforms that auto-deploy on push (Vercel & co.) get verify-only jobs instead of duplicate deploys; anything else gets a deploy step that fails loudly until you wire in your deploy command.

add-playwright writes a config plus three starter specs: every core page renders with zero console errors, the sitemap contract, and a money-path template. Setting BASE_URL points the same suite at a deployed environment — that's what the staging E2E job does.

Both are one-shot generators: the output is plain YAML/TypeScript in your repo, yours to edit.

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.