Docs
Understand a tracked codebase
RepoOps maps the tracked text files in a local checkout, then explains one file or HTTP route at a time. The mode badge tells you whether the answer came from static parsing or Anthropic.
For: a developer who needs a first map of an unfamiliar or AI-written repository before changing it
What it does, and why it helps
The overview is a deterministic structural map. RepoOps reads git-tracked text files and groups the result as Key files, HTTP routes, Entry points, Library modules, and Scripts. It counts those groups and suggests an orientation file. Pick a target to see its role, line count, imports, exports, route patterns, and a plain-language summary.
With no Anthropic key, the target gets a Structural badge and a summary built from path rules and regular-expression parsing. With a key, a resolved file or route can get an AI-generated badge. The whole-repo overview never makes a model call. An API error or timeout returns the structural answer with a note instead.
The pain. A large tree gives you filenames without a reading order. AI-written code adds another problem: fluent code can still be unfamiliar code.
The point of view. Map the tracked structure before judging the code. Then ask about one target and use its paths, imports, exports, and routes to decide what source to inspect next.
What gets easier. Finding a starting point. The overview puts entry points, routes, modules, scripts, and key files in one list, while each answer names how it was produced.
When it helps. You have a local, readable git checkout registered as a tracked repo and need orientation before a review, repair, or handoff.
Its limits. The parser uses path rules and regular expressions, not a full syntax tree or call graph. The scan is bounded and can be partial. The feature does not trace callers, write a whole-repo narrative, change source, or provide a hosted source-code view.
Understand it in 30 seconds
Read the narration
- 0:00 AI wrote the code.
- 0:01 You still need to understand what is really there.
- 0:06 Map the tracked tree first, then explain one file or route in its context.
- 0:13 RepoOps shows routes, modules, imports, exports, and file roles.
- 0:19 The badge says whether a model or static parsing wrote it.
- 0:23 Read the evidence, then decide where to inspect the source next yourself.
Synthetic example. Read the guide
Where to find it
Where to find it
- Desktop:
localhost:4000, then Memory in the sidebar, then Explain my codebase under All tools, in the Lessons, wiki and patterns group. - Hosted: desktop only.
- Keyboard: ⌘ K, then type “Explain my codebase”.
When to use it
Choose where to start in an unfamiliar repo
Situation. You inherited a checkout with many files and do not know which entry point, route, or library module matters first.
What you do. Open the command palette, choose > Explain this file…, and read the overview before picking a target.
What you see. The overview shows counts and the groups Key files, HTTP routes, Entry points, Library modules, and Scripts. A partial scan also shows a warning that its counts are a floor.
What it establishes. You get a bounded map and a suggested orientation file. It establishes a reading order, not that every dependency or runtime path was found.
Investigate one route or module
Situation. A route or file looks important, but its name alone does not explain what it does or where its facts came from.
What you do. Select the target. Read the summary, role, methods or file facts, and the Structural or AI-generated badge. Then open the cited source yourself.
What you see. A file can show its line, export, route, and import counts. A route can show its methods and the files where the parser found it.
What it establishes. You have an explanation tied to inspectable structure. The answer remains an orientation aid, not proof of runtime behavior.
Before you start
- Supported versions
- RepoOps desktop v0.3.1, the release this guide was read against. The selected checkout must be a git work tree.
- Where it runs
- Desktop only for the real scan. The standalone local page remains available and the command palette opens it. /team/explain-codebase is a hosted pointer because raw source is not streamed to the team database.
- Permissions
- The local process needs read access to the tracked checkout. Reading the map has no feature-specific role gate. Saving or removing the Anthropic key uses the Settings write gate and operator confirmation.
- Connections
- A tracked local git repo is required. ANTHROPIC_API_KEY is optional. Without it, the map and target summaries use deterministic parsing and make no model call.
- Plan
- No plan gate is present in the local route. The hosted route is a desktop-only stub, not a hosted edition of the explainer.
Configure it
- Open the explainer for the active repo.
Open Memory and choose Explain my codebase under All tools, or press Command K or Control K and choose > Explain this file…. It has no sidebar row of its own, and its standalone URL is preserved.
- Read the structural overview first.
The first load maps tracked text files without a model call. If the Partial scan warning appears, treat every count as a floor.
- Pick one target.
Choose a file, route, or module from the left list. The badge says Structural or AI-generated, and the detail pane shows the facts the answer can support.
- Add a key only if you want model-written prose.
In Settings, use Anthropic API key, Save key, then Test. The data-dir key takes effect without a restart. Selecting an eligible target can spend a call; the overview remains deterministic.
| Setting | Where | A sensible choice | Why it matters |
|---|---|---|---|
ANTHROPIC_API_KEY | Settings, Anthropic API key | Leave unset for Structural mode, or save your own key for AI-generated target summaries. | The overview is deterministic either way. A key allows one Anthropic Messages API call for a resolved file or route. |
llm.dailyCallCap | account-settings.json, no desktop control | 200 calls per endpoint, per account, per UTC day (the default), or a lower nonnegative integer | The route reserves a slot before a keyed call. A cap of 0 refuses the first keyed call; deterministic reads are not capped. |
target | The selected item in the explainer, sent as the target query parameter | One listed file or HTTP route | Only one target is explained at a time. Unknown targets return a structural message instead of calling Anthropic. |
fresh=1 | Re-scan repo | Use when the checkout changed and the cached map is stale. | The button bypasses the overview cache and rebuilds the structural map. The overview never makes a model call. |
What you should see
Structural orientation
Configuration. A tracked git checkout with no ANTHROPIC_API_KEY.
Expect. The overview and every resolved target use static parsing. No Anthropic request is made.
Verify. The detail badge reads Structural. The pane shows the path, role, summary, and any parsed line, export, route, import, method, or source-file facts.
Model-written target explanation
Configuration. A saved Anthropic key, an eligible file or route target, and room under the daily call cap.
Expect. RepoOps sends the target facts and, for a file, at most 12,000 characters of that file to claude-haiku-4-5-20251001. The response can contain up to 700 output tokens.
Verify. The badge reads AI-generated. If the API fails or times out after 20 seconds, the badge reads Structural and the note says the AI summary is unavailable.
Bounded or incomplete scan
Configuration. A repo that reaches 4,000 accepted files or 24 MiB of accepted text, or contains files above their per-file cap.
Expect. RepoOps reads orientation files first, then code, then remaining prose and data. Regular files above 512 KiB, orientation files above 4 MiB, binary files, lockfiles, minified assets, and source maps are skipped.
Verify. The tab shows Partial scan when the total file or byte budget stops the walk. It says the counts are a floor and some files are not listed.
Data and cost
- What is captured
- The scanner reads git-tracked text from the local checkout into memory. The response contains paths, group counts, parsed routes, roles, headers, imports, exports, line counts, summaries, and scan metadata. It does not return the raw target content.
- Who can see it
- The working-tree scan stays on the desktop. Successful response bodies can be cached in the browser and in the per-machine RepoOps store. The hosted page is a pointer and receives no source from this feature.
- How long it is kept
- No feature retention knob is provided. The route keeps up to 256 repo-and-target results in process memory. The response cache can persist last-known-good bodies in the per-machine SQLite kv store, capped with all such endpoints at 200 rows, and the overview can persist in browser IndexedDB or localStorage without a time-based expiry.
- What leaves the machine
- Structural mode sends nothing outside the machine. AI mode sends one target's structural facts, one line of repo counts, and up to 12,000 characters from the selected file to https://api.anthropic.com/v1/messages. It does not send the whole tree or the overview lists.
- What it costs
- Structural mode has no model cost. AI mode uses your Anthropic key and Anthropic bills that account. RepoOps caps the response at 700 tokens and calls at 200 per endpoint, per account, per UTC day by default, but it does not record or display this feature's dollar cost.
When the result differs
| Symptom | Likely cause | Next action |
|---|---|---|
| The tab says Couldn't scan the repo. | The selected path is missing, is not a git work tree, or the repo id could not be resolved. | Confirm the repo is tracked, its checkout exists and is readable, then reopen the explainer for that repo. |
| The tab shows Partial scan. | The accepted-file count or byte budget stopped the walk. | Treat counts as a floor. Use the listed code and orientation targets, and inspect omitted source in the checkout. |
| The badge reads Structural although a key is set. | The overview never calls a model, or the selected target was missing, or the Anthropic call failed or timed out. | Pick a listed target. Read the mode note. In Settings, press Test for the Anthropic API key, then retry if you want AI mode. |
| The pane says the daily call cap was reached. | The endpoint used its llm.dailyCallCap slots for the current UTC day. | Read a cached answer without a fresh request, wait for the next UTC day, lower spend by removing the key, or change llm.dailyCallCap in account-settings.json. |
| A route or dependency is absent or mislabeled. | The structural pass uses bounded regular-expression parsing and path rules, not a full syntax tree or runtime trace. | Use the result as a reading map and inspect the source. A missing fact is not proof that the behavior does not exist. |
- Disable
- Not provided as a master switch. Removing the Anthropic API key stops model calls immediately, while Structural mode remains available.
- Roll back
- Not provided. The feature is read-only and does not change the checkout, so there is no RepoOps change to roll back.
- Revoke access
- Settings can Remove a key stored in this machine's data-dir .env and live process environment. If the key came from an external environment or repo .env, manage it there. RepoOps does not revoke the credential at Anthropic.
- Delete
- Not provided. There is no feature control to delete saved explanations. Response bodies can sit in the process explainCache, the per-machine SQLite apilkg rows, and the browser repoops-tabcache store until replaced, evicted, or cleared outside this feature.
Related tasks
Maintenance evidence
- Feature id
explain-codebase(spine leafexplain-codebase)- Owner
- Vibe-coder mission control program. Guide: LDG-0717.
- Supported product version
- RepoOps v0.3.1
- Last verified
- 2026-09-15, read against origin/main at 52366bb6d; labels read from the served tab source; command-palette label and hosted desktop-only stub also read from source.
- Example fixtures
- No separate fixture file. lib/explain-codebase.test.mjs uses inline files and a temporary git repo; lib/explain-codebase.scan-order.test.mjs exercises the real repository scan budget. lib/llm-call-budget.test.mjs covers the per-day call ceiling.
- Source references
lib/canonical-spine.json,lib/canonical-tabs.mjs,public/dashboard.html,public/explain-codebase.html,lib/routes/explain-codebase.mjs,lib/explain-codebase.mjs,lib/llm-call-budget.mjs,lib/account-settings.mjs,lib/byok.mjs,lib/routes/settings.mjs,public/lib/repoops-tab.js,lib/api-cache.mjs,lib/api-cache-disk.mjs,website/app/team/(home)/explain-codebase/page.tsx- Documentation review
- Independent review requested on the slice pull request; not yet recorded.
- Video review
- Narrated story rendered and published 2026-09-26 (render cc333fc6f8c6, LDG-1014) with the breadcrumb Memory, which lists the feature under Moved here, checked against main at 7aab4cd82 with LDG-1014 part 1. Six frames, the captions and the transcript were reviewed by the authoring agent, not an independent reviewer; the audio was not listened to by a person. Narration is the provisional Windows voice until LDG-0721.
Last updated