Ratchet — Code Review & Complexity

A local-first VS Code extension for code review, complexity awareness, and delivery signals, organized around an Activity Bar sidebar. Static analysis runs entirely on your machine (tree-sitter WASM, git plumbing); platform features use GitHub through VS Code's built-in GitHub sign-in; AI features run on whichever AI coding tool you already use — GitHub Copilot (via VS Code's Language Model API, the default), or a locally installed CLI agent: Claude Code, Codex CLI, Gemini CLI (Antigravity), Grok CLI, OpenCode, or any custom command. No API keys, no separate billing.

See FEATURES.md for the full checklist; every item is implemented.

Getting started

• First run: Ratchet offers a 2-minute interactive tour (also available any time via Ratchet: Getting Started (Interactive Tour)).
• Browse everything: Ratchet: All Features (Browse & Run) — a searchable menu of every tool, grouped by intent, each entry explaining what you'll get before you run it. It's also the list icon on each Ratchet view's title bar.
• Hover to learn: every sidebar section header has a plain-English tooltip explaining what it shows and how to act on it; the inline file icon on a section opens its full report.
• Status bar: the ✦ item on the right shows which AI tool is active — click it to manage and test connections.
• Reports render as Markdown previews by default (set ratchet.reports.renderMarkdown to false for raw text). AI-generated PR descriptions and standups are additionally copied to the clipboard, ready to paste.
• When something fails, the error notification has a Show Logs button that opens the Ratchet output channel.

Requirements

• VS Code ≥ 1.95, git on PATH
• For AI commands: either the GitHub Copilot Chat extension signed in with an active Copilot subscription (default), or one of the supported CLI agents installed and authenticated (Claude Code, Codex, Gemini, Grok, OpenCode, or a custom command). Pick and test the active tool via Ratchet: AI Tools — Connections & Status.
• For platform features (PR status, conflicts, CI, flaky radar, dossier advisories): a github.com origin remote; VS Code prompts for GitHub sign-in on first use.
• Optional: Sentry org/project + auth token for the production error overlay; an lcov file for the coverage ratchet.

The sidebar

Click the Ratchet icon in the Activity Bar. Sections load lazily when expanded and cache until you hit the refresh button in each view's title bar.

Branch Review — everything about the diff you're about to ship

Repo Health — longer-horizon maintenance signals

CI & Runtime Signals

Editor context menu additions: Explain Line History (blame → commit → PR → ticket refs), Blast Radius, and Safe-Delete Confidence for the symbol under the cursor.

Always-on complexity engine

• Complexity CodeLens — per-function cognitive (primary) + cyclomatic complexity. Languages: JS, JSX, TS, TSX, Python, Go, Java.
• Complexity deltas — cognitive 18 ↑ (was 12) against the HEAD version.
• Complexity ratchet — diagnostics only when a function got worse than HEAD (or is new) and is above threshold; legacy complexity is never nagged about.
• Micro-metrics — length, parameter count, nesting depth warnings.
• Branch snapshots — editors, cursors, breakpoints, and a scratch note restored per branch on checkout.

AI tools: bring the agent you already pay for

Drafting features route through a provider layer (ratchet.ai.provider):

• GitHub Copilot (default) — vscode.lm.selectChatModels({ vendor: 'copilot' }), the models your Copilot subscription already pays for; pick a family with ratchet.ai.modelFamily.
• CLI agents — one-shot headless runs of a locally installed tool: Claude Code (claude -p …), Codex CLI (codex exec …), Gemini CLI / Antigravity (gemini -p …), Grok CLI (grok -p …), OpenCode (opencode run …), or a custom command (ratchet.ai.custom.*). Binaries are found on PATH plus common install dirs (Homebrew, ~/.local/bin, …) even when VS Code was launched from the dock with a minimal PATH; override per tool with ratchet.ai.toolPaths / ratchet.ai.toolArgs.

Connecting & checking a connection: run Ratchet: AI Tools — Connections & Status (also reachable from the sidebar's AI drafting section). The panel shows a live connected/not-connected status for every tool and is a full setup UI: edit each tool's binary path and prompt arguments, define the custom command, set the Copilot model family and CLI timeout, and use Install… / Sign in… to stage the install or one-time auth command in a terminal (you press Enter to run it). Then Test connection and Use this tool. Ratchet: Check AI Tool Connection verifies the currently active tool in one click, and Ratchet: Select AI Coding Tool is a quick-pick switcher with live status.

Platform features use vscode.authentication.getSession('github', ['repo']) — the same GitHub account, no PATs to manage. Nothing leaves your machine except the AI channel you chose and GitHub, and only when you use them.

Settings

Development

npm install
npm run verify   # typecheck + bundle + 9 headless test suites

Press F5 in VS Code to launch an Extension Development Host. npm run package produces a .vsix (requires @vscode/vsce).

Architecture

src/
  extension.ts              activation, command wiring, sidebar assembly
  analyzer.ts               cached per-document metrics + HEAD baselines
  parser/                   tree-sitter WASM loading + per-language node tables
  metrics/                  complexity walker + normalizing tokenizer (pure)
  git/git.ts                git plumbing helpers
  platform/github.ts        GitHub REST/GraphQL via VS Code's GitHub auth session
  sidebar/                  Item model + lazy section-based TreeDataProvider
  features/
    codelens, diagnostics, duplication, hotspots, branchSnapshots,
    precommitGuardian, envDoctor                     (P1 core)
    history/                trends, knowledgeRisk, coupling, reviewers
    hygiene/                todoAging, flagDebt, migrations, docsDrift
    review/                 changes, riskRank, checklists, testGap, smells
    platform/               prStatus, conflicts, nudges, archaeology,
                            intentGap, dependencyDossier
    signals/                ciBridge, flakyRadar, coverageRatchet,
                            errorOverlay, stackTrace
    impact/                 blastRadius, safeDelete, testImpact
  ai/                       provider layer: service (dispatch) + copilot (vscode.lm),
                            toolRegistry + cliRunner (headless CLI agents),
                            toolsPanel (connections webview), generators
scripts/
  smoke.mjs                 parser + metrics smoke test
  hook-test.mjs             end-to-end pre-commit hook test in a throwaway repo
  test-{history,hygiene,review,platform,signals,impact}.mjs
                            headless tests for each feature area's pure logic
  test-ai-tools.mjs         headless tests for the AI provider registry + CLI runner

Known approximations

• Cognitive complexity follows the Sonar model with simplifications (boolean-operator sequences count per operator; recursion is not detected). Go multi-name params count once.
• Ratchet/delta function matching is by name + ordinal, so a rename reads as delete + new.
• Flag detection, docs drift, PR smells, and test-gap mapping are heuristic by nature — they are tuned to be useful review prompts, not proofs.
• Flaky radar works at workflow/job granularity (rerun-flips on the same commit are the strongest signal); per-test attribution happens only where job logs parse cleanly.
• Decision archaeology is an on-demand command (not a hover) to keep GitHub API usage sane.