wtfismyrepo — onboarding for agents & humans

You just got dropped into a 200k-line codebase. You have no idea what's going on. This fixes that.

Most "explain my code" tools read the code and stop — but code only tells you what exists. The why, and the landmines, live in the structure and the history. wtfismyrepo treats onboarding as a graph problem, not a reading problem — it builds an import graph, runs PageRank to find the files that hold the system together, scores fragility from git churn, and reads the GitHub history (open PRs = hot zones, issues = pain) to tell you exactly where to start.

Then comes the part most tools get wrong: the explanation itself. A single linear walkthrough anchors on whatever angle it happens to start with. So under the hood wtfismyrepo runs the ADHD divergent-ideation engine — it generates many onboarding angles in parallel (new-grad, archeologist, security-researcher, on-call-at-3am…), with zero cross-talk, then a critic pass scores them, prunes the traps, and deepens the single best angle for you and your goal. No premature convergence on "just start at main()."

It ships as both a CLI/library (the deterministic data engine + ADHD explanation engine) and a Claude Code skill (the guided, part-by-part walkthrough).

Reach for it whenever you're new to a repo, lost, inheriting legacy code, or thinking "where do I even start with this?"

Side-by-side: day one, lost vs. wtfismyrepo

npx github:nandnijaiswal/wtfismyrepo .

What you get

Unedited output, run on this very repo:

━━ THE SPINE — most central files (PageRank) ━━━━━━━━━━━━━━━
  read these first; everything depends on them
  ██████████ src/install.mjs
  █████████░ src/graph.mjs
  █████████░ src/pagerank.mjs
  ████████░░ src/detect.mjs
  █████░░░░░ src/git.mjs

━━ THE HISTORY — what's happening on GitHub ━━━━━━━━━━━━━━━━
  🔥 0 open PRs (hot zones — avoid surprising people)
  🩹 3 open issues (where it hurts)
     #3 Per-directory responsibility summaries
     #2 gh-free history via GitHub REST API
     #1 Add Rust import parsing
  🌱 good first issues — START HERE:
     #1 Add Rust import parsing

━━ YOUR FIRST MOVE ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  1. Open bin/wtfismyrepo.mjs and read top-to-bottom.
  2. Then trace into src/install.mjs — it's the spine.
  3. Pick up issue #1: "Add Rust import parsing".

The Handle-with-care / fragility pass (centrality × git-churn) needs commit history to light up — it's empty on a one-commit repo like this one, and ranks the genuinely risky files on any mature codebase.

Install

One command — installs the skill into your Claude Code agent (no npm account needed):

npx github:nandnijaiswal/wtfismyrepo install

Restart Claude Code, then just ask: "wtf is this repo" · "I'm new here, where do I start?"

Using Cursor / Codex / another agent? Add @~/.claude/skills/wtfismyrepo/SKILL.md to your CLAUDE.md / AGENTS.md / .cursorrules. Full matrix in documentation/install.md.

Quickstart

CLI:

npx github:nandnijaiswal/wtfismyrepo .          # analyze the repo you're in
wtfismyrepo . --json                            # machine-readable (what the skill consumes)
wtfismyrepo ../service --no-history --top 5      # offline, just the top 5

# ADHD-powered explanation (npm install -g adhd-agent to enable the live engine)
wtfismyrepo explain . --level new-grad --goal "fix a bug"

Library:

import { analyze, renderText, buildADHDContext } from "wtfismyrepo";

const report = analyze(".", { history: true, top: 10 });
console.log(renderText(report));
// report.importance · report.fragility · report.hotZones · report.entryPoints · report.history

// Hand the analysis to the ADHD engine for a divergent explanation:
const { problem, context } = buildADHDContext(report, { experience: "new-grad" });
// → feed to adhd-agent's run(), or paste into a /adhd session

Full reference: documentation/api.md.

How it works

Two engines, chained. The data engine (deterministic) extracts ground-truth structure; the ADHD engine (divergent) turns that into the right explanation.

 ┌─ DATA ENGINE (deterministic) ────────────────────────────────────────┐
 │ files ─► import parser ─► directed import graph ─► PageRank ──┐       │
 │                                                               ├─ spine│
 │   git log ──────────────► per-file churn ────────────────────┤       │
 │                                                               └─ fragility = centrality × churn
 │   gh CLI ──► open PRs (hot zones) + issues (pain) ────────────► where to start
 └──────────────────────────────────┬───────────────────────────────────┘
                                     │  (analysis as ADHD problem + context)
                                     ▼
 ┌─ ADHD ENGINE (divergent) — github.com/UditAkhourii/adhd ──────────────┐
 │  DIVERGE  N onboarding frames in parallel, zero cross-talk            │
 │  SCORE    novelty / viability / fit + trap detection                  │
 │  CLUSTER  group angles by underlying approach                         │
 │  DEEPEN   the non-obvious best angle → full walkthrough for *you*     │
 └───────────────────────────────────────────────────────────────────────┘

Data engine:

1. Scan — list git-tracked files (respects .gitignore), read parseable sources (JS/TS/JSX/Python/Go).
2. Graph — parse real import / require / from statements, resolve to internal files, build a who-depends-on-whom graph.
3. PageRank — power iteration with damping + dangling-node handling. High rank = the spine.
4. Churn — git log change-frequency per file.
5. Fragility — normalize(centrality) × normalize(churn). Central and churned = handle with care.
6. History — gh pulls open PRs (→ hot zones), merged PRs (→ conventions), issues (→ pain & good-first-issues).

ADHD engine (UditAkhourii/adhd, MIT) — wtfismyrepo explain packages the analysis as an ADHD problem + context, then runs the diverge → score → cluster → deepen loop so the explanation is chosen from many parallel angles instead of anchoring on the first one. Without adhd-agent installed, the CLI prints the formatted ADHD prompt; the skill runs the same loop with Claude as the generator.

The engine is tested (PageRank correctness, import parsing, scoring, install, ADHD context-building) and runs in CI on Node 18 / 20 / 22. Deep dive: documentation/how-it-works.md.

Documentation

Also: SKILL.md — the runnable Claude Code skill.

Project layout

bin/wtfismyrepo.mjs   CLI entry (analyze · install · uninstall)
src/
  index.mjs           public library surface
  analyze.mjs         orchestrator
  scan.mjs            file discovery + source reading
  graph.mjs           import parsing + resolution
  pagerank.mjs        the PageRank algorithm
  git.mjs             churn + tracked files
  fragility.mjs       importance + fragility scoring
  entrypoints.mjs     entry-point detection
  history.mjs         gh PR/issue signals
  report.mjs          terminal + JSON rendering
  install.mjs         skill installer
SKILL.md              the Claude Code skill
documentation/        docs · test/ unit tests · .github/ CI

Roadmap & contributing

This is a young project — early issues and PRs are especially welcome:

• Rust / Java / Ruby import parsing
• gh-free history via the GitHub REST API
• Per-directory "responsibility" summaries
• Published to npm (npx wtfismyrepo, no github: prefix)
• HTML/JSON export of the onboarding report

Found a repo where the spine ranking looks wrong, or a language it should parse? Open an issue — those are the most useful contributions right now.

Star History

Credits

The explanation layer is powered by ADHD — Parallel Divergent Ideation for Coding Agents by Udit Akhouri (MIT). wtfismyrepo adapts ADHD's diverge→score→cluster→deepen engine and frame-based generation for the codebase-onboarding problem — see src/onboarding-frames.mjs and src/explain.mjs. The cognitive-frame design and the generator/critic split are ADHD's; the codebase-specific frames and the analysis→problem mapping are this project's.

License

MIT © Nandni Jaiswal

The deterministic data engine lives in src/; the ADHD explanation layer in src/explain.mjs + src/onboarding-frames.mjs; the runnable skill is SKILL.md. Go forth and stop being lost.