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.

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

Analyze A PR Diff

npx codedecay analyze --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

The current redteam MVP is report-only. It does not run commands or call an LLM.

Hand Evidence To Your Agent

Use agent when you want Codex, Claude Code, Cursor, a desktop agent, or another user-owned agent to act on CodeDecay's findings.

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

Then give codedecay-agent.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 agent --base main --head HEAD --format markdown --output codedecay-agent.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.

Write SARIF

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

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