Getting Started

CodeDecay analyzes pull requests for regression risk and maintainability decay. It works locally and in CI without cloud services, telemetry, API keys, LLMs, or model calls.

AI-First, User-Owned Default

Use codedecay ai when you want CodeDecay to guide your own coding agent. Without --investigate or --with-checks, it remains deterministic and report-only.

Workflow	Default	What it does
ai, analyze, redteam, agent, snapshot	Yes	Local deterministic analysis and agent-ready reporting.
execute, differential	No	Runs only repo-allowlisted local commands after explicit opt-in.
llm-review	No	Calls a user-owned provider only when invoked directly.
Optional LLM providers	No	Disabled by default and only called by commands that explicitly opt in.

Install

Use the package manager your repository already uses:

npm install -D @submuxhq/codedecay
pnpm add -D @submuxhq/codedecay
bun add -d @submuxhq/codedecay
yarn add -D @submuxhq/codedecay

For a no-install smoke test:

npx -y @submuxhq/codedecay --help

After a local install, run CodeDecay with npx codedecay, pnpm codedecay, bunx codedecay, or add codedecay to a package script.

Do not run npm install inside a Bun, pnpm, or Yarn workspace that uses workspace:* dependencies. npm may fail before CodeDecay is installed. In Bun repos with minimumReleaseAge, a fresh CodeDecay release may also be blocked by repo policy; for local evaluation you can override it explicitly:

bun add -d @submuxhq/codedecay --minimum-release-age 0

Guide The Agent Before Editing

npx codedecay ai preflight --task "Add an authorized billing export API" --format markdown

Run The AI Workflow On A PR Diff

npx codedecay ai --base main --head HEAD --format markdown

Use another handoff profile explicitly:

npx codedecay ai --profile claude-code --base main --head HEAD --format markdown

Run configured proof through repository safety gates after the code changes:

npx codedecay ai --with-checks --base main --head HEAD --format markdown

Analyze Current Working Tree

npx codedecay analyze --format markdown

Analyze Another Repository

npx codedecay analyze --cwd ../my-repo --format markdown

Generate A Redteam Report

Use redteam when you want one report for yourself or your coding agent that summarizes what the PR could break, weak-test evidence, missing edge cases, and fix tasks.

npx codedecay redteam --base main --head HEAD --format markdown

By default, redteam is report-only. Add --with-checks when you want the report to run configured commands and tool adapters through the same safety gates as codedecay execute:

npx codedecay redteam --with-checks --base main --head HEAD --format markdown

The report labels verification as not-run, verified, unverified, failed, or blocked so deterministic findings are not confused with behavior proof. It does not call an LLM unless an explicit investigation path is used.

Discover OSS Tools To Reuse

Use doctor when you want CodeDecay to recommend existing open-source tools for the repository shape instead of building custom checks from scratch.

npx codedecay doctor --format markdown
npx codedecay doctor --write-config-preview

doctor only reads local files. It does not install tools, execute commands, call models, use network access, or edit .codedecay/config.yml. The config preview is written to .codedecay/local/config-preview.yml so you can review it first.

Hand Evidence To Your Agent

Use ai for the recommended Codex-ready workflow. The lower-level agent command remains available when you want a generic bundle by default.

npx codedecay ai --base main --head HEAD --format markdown --output codedecay-ai.md

Then give codedecay-ai.md to your agent and ask it to:

• fix high-risk findings first,
• add tests that exercise real API, UI, database, or downstream behavior,
• cover the missing edge cases listed by CodeDecay,
• run the relevant project checks,
• rerun CodeDecay after changes.

The agent bundle is local evidence plus instructions. CodeDecay does not call Codex, Claude, Cursor, Ollama, cloud models, or CodeDecayCloud while creating it.

Recommended Local Loop

npx codedecay analyze --base main --head HEAD --format markdown
npx codedecay redteam --base main --head HEAD --format markdown --output codedecay-redteam.md
npx codedecay ai --base main --head HEAD --format markdown --output codedecay-ai.md

Use the redteam report to understand the PR risk. Use the agent bundle to give your own coding agent the evidence, missing checks, and fix tasks it should work through. After the agent changes code, run your project checks and run CodeDecay again.

Persist A Trend Snapshot

Use snapshot when you want a stable artifact you can keep in CI, compare with an earlier run, or review over time.

npx codedecay snapshot --format json --output .codedecay/snapshot.json
npx codedecay snapshot --compare .codedecay/previous-snapshot.json --format markdown

See Trend snapshots for a GitHub-native artifact workflow.

Import Repo Memory From Incidents Or CI

Use memory-import to turn structured learnings into repo-local memory that future analyses can reuse deterministically.

npx codedecay memory-import --input incidents.json
npx codedecay memory-import --input incidents.json --apply --format json

See Local repo memory for supported import shapes and dedupe behavior.

Write SARIF

npx codedecay analyze --format sarif --output codedecay.sarif

SARIF is the fastest local-first path for in-editor feedback because editors can show inline diagnostics without parsing Markdown.

See Editor workflows.

Inspect CodeDecay Config

Configuration is optional. Missing config uses safe defaults.

npx codedecay config --format markdown

Fail CI On High Risk

npx codedecay analyze --base main --head HEAD --fail-on high

Risk levels:

• 0-39: low
• 40-69: medium
• 70-100: high

Try An Example

Use the example projects to see a realistic high-risk report before wiring CodeDecay into your own repository:

• Next.js risk demo
• Node API risk demo

Optional Assisted Workflows

If you want optional provider-backed suggestions without changing the default workflow:

1. Configure one user-owned provider in .codedecay/config.yml.
2. Run npx codedecay llm-review --ping to validate the provider config.
3. Run npx codedecay llm-review --base main --head HEAD --format markdown.

See LLM providers for the recommended config path.