harsh-aghara/underhood

Don't vibe-skim the code. See how it actually works under the hood and where it can break

Summary

Underhood is a JavaScript package and agent skill that gives coding assistants a structured way to explain a repository, pull request, commit, diff, module, or file. It asks them to trace execution paths and state changes, explain design contracts, predict failure modes, and compare documentation with the implementation using file-and-line citations.

What it is useful for

Use Underhood when a quick directory overview is not enough—for example, when onboarding to an inherited repository, understanding a subsystem before changing it, or reviewing a pull request for hidden regressions.

For a repository or module, it produces a report covering:

• The main execution path, with citations and state mutations
• Where volatile state lives
• Design decisions and the assumptions callers must uphold
• Nominal, interrupted, timeout, and concurrent failure modes
• Differences between documentation and source, labeled SUPPORTED, PARTIAL, or GAP

For pull requests, commits, and diffs, its “Delta mode” compares the stated intent with the actual change. It examines before-and-after behavior, touched invariants, affected callers and tests, unhandled edges, and stale documentation or tests. The report ends with the highest-risk change and the code that demonstrates the risk.

The README documents adapters for Google Antigravity, Claude Code, Cursor, Windsurf, OpenCode, Qoder, Devin, and Cline. ChatGPT, Claude, and Copilot on the web can use the included AGENTS.md as a standalone prompt.

Important limitations are explicit: Underhood performs static analysis and does not execute the code, so runtime behavior is inferred. Each report states which files were read and which were not, but engineers should still spot-check citations. It is slower than a casual explanation, works in a single turn without clarifying questions, and may be triggered by a normal “explain this codebase” request.

How engineers can use it

Underhood requires Node.js 18 or newer. For the current project, run:

npx underhood init

For global use across projects:

npx underhood init --global

Claude Code users can instead install the plugin marketplace with:

/plugin marketplace add harsh-aghara/underhood
/plugin install underhood@underhood-marketplace

After setup, invoke it inside the coding agent:

/underhood this repo
/underhood pr 14
/underhood src/engine/
/underhood commit 8e3a21b
/underhood git show HEAD~1

For a real review workflow, run Delta mode on a pull request, inspect the named highest-risk change, verify its cited lines, and check the “files not read” coverage before relying on the conclusions. The README is the source of truth for adapter-specific setup and usage.