Map Codebase

Map Codebase

Generate a codebase map as a collection of atomic documents in .claude/.codebase-info/. Each document covers one aspect of the project, so the map stays easy to read, update, and navigate. The map is written for the next Claude session (and the next human): it is grounding context, not marketing.

Loading is automatic and you don't have to wire anything up: this plugin ships a SessionStart hook that injects the map at the start of each session, so Claude starts oriented and keeps consulting and updating it as work goes on. Never edit CLAUDE.md. The hook is the only loading mechanism; leave CLAUDE.md alone. Your job is just to write the docs in .claude/.codebase-info/.

Output

.claude/.codebase-info/
├── INDEX.md                # Navigation hub + how-to-use; the hook injects this at session start
├── architecture.md         # System overview, components, boundaries, data flow
├── tech-landscape.md       # Languages, frameworks, runtimes, infra, source-of-truth files
├── directory-structure.md  # Annotated folder tree
├── entry-points.md         # Where execution starts (routes, CLIs, jobs, main files)
├── modules.md              # Key modules/packages: purpose, deps, exports
├── communication.md        # APIs, events, queues, external integrations   (if applicable)
├── database.md             # Schema, relationships, migrations              (if applicable)
├── dependencies.md         # Categorized packages                           (if applicable)
├── patterns.md             # Recurring patterns, error handling, testing, config
├── coding-style.md         # Conventions derived from linters + existing code
├── docker.md               # Containers / local dev environment             (if applicable)
├── onboarding.md           # Quick start + common tasks
└── .map-state.json         # Machine state (last-mapped commit + date) for staleness checks

This list is a menu, not a checklist. Create only the documents that earn their place in this codebase, and feel free to go beyond the list when a project has a major aspect the standard docs do not cover. Two directions:

• Omit what does not apply. Skip database.md if there's no datastore, docker.md if there are no containers, dependencies.md if there's no dependency manifest, and so on. A tiny project might only need INDEX.md, architecture.md, tech-landscape.md, and onboarding.md.
• Add what the project actually warrants. If a major aspect deserves its own doc and none of the standard names fit, create one (e.g. ml-pipeline.md for a training/inference flow, cli-reference.md for a tool with many subcommands, realtime.md for a websocket/event core, iac.md for substantial infrastructure-as-code). List any such doc in INDEX.md and in the state file the same as the rest.

The test for every doc, standard or not, is the same: would a future session be meaningfully faster for having it? If yes, write it; if not, leave it out.

Process

Step 0 : Assess project state (decide the path)

Once a map exists, the plugin's session context tells the main session to assess the map after code changes and invoke update-codebase-map immediately when documentation work is warranted. It does not wait for a separate user approval. A genuine no-op ends with no map edit or state refresh. This initial mapping skill creates the starting map; use update-codebase-map for later assessments.

Get the lay of the land first, then pick a path:

• Count real source files, ignoring noise (.git/, node_modules/, vendor/, dist/, build/, target/, .venv/, __pycache__/, .next/, lockfiles, generated code, minified assets).
• Roughly size the project (file count, lines, number of top-level areas).

Then branch:

• Existing project with real code → assess and map it inline by default. For a larger remap or a small or medium initial map, use the optional Sidequest handoff below when its live contract is available; otherwise continue inline with Steps 1–8.
• Greenfield (empty repo, scaffold only, or just a spec/README) → seed mapping inline. Jump to the Greenfield projects section below, then do Step 8. Do not file a mapping ticket for this.
• Large codebase (hundreds+ of source files) → use the optional large-repo handoff below when Sidequest is available. Otherwise parallelize inline as described there, then complete Steps 7–8.

Also check today's actual date (it's provided in the session context, or run date) so the "Last Updated" stamps are real, not placeholders.

Optional Sidequest handoff for an existing project

Use this handoff only when a small or medium initial map or a larger remap benefits from a bounded shared-tree artifact writer. Inspect the session tool roster before doing mapping reads. Sidequest is optional: the standalone path above and the inline fallback below remain valid.

The handoff is available only when the normal native Agent tool and Sidequest's category_list, add, comment, dispatch, and pulse tools are present. Do not probe the Sidequest CLI or dashboard. Read the live codebase-exploration category with category_list; delegate only when it is enabled and its live contract permits one bounded documentation-artifact write. The required contract language is that project source remains read-only while a ticket may explicitly name one bounded documentation artifact directory as its only write scope.

• When the tools are absent, continue inline without an error banner.
• When Sidequest is present but the category is missing, disabled, or still says no edits, continue inline and tell the user: Sidequest is loaded, but its live taxonomy cannot accept map artifacts yet.
• When the category is ready, create one artifact ticket for a small or medium initial map. Use category codebase-exploration, files: [".claude/.codebase-info/"], and this exact carve-out: Artifact write carve-out: write only .claude/.codebase-info/**; all project source is read-only.

Record the starting HEAD (or null outside Git) and the initial working-tree status outside .claude/.codebase-info/ in the ticket. Its deliverable is warranted atomic docs, a compact linked INDEX.md, and a final .map-state.json with exact document hashes. Tell the writer to inspect the current shared tree; skip generated, vendor, and secret material; verify every cited path; never touch CLAUDE.md; and never invoke map-codebase again or create nested mapping tickets. Include this lifecycle marker verbatim:

Shared-tree artifact mode: leave the generated map as working-tree output; verify, comment, and close with done. Do not commit, submit, push, or edit source.

The invoking parent session verifies the generated paths and state after the writer closes, then commits the map if its flow permits.

Before dispatch, post this reason as a ticket comment:

Shared-tree dispatch is required because the map must describe the current working tree, including intentional uncommitted source, and the generated .claude/.codebase-info/** files must remain visible to the invoking session.

Dispatch with { sharedTree: true }. Pass every returned spawn field to the native Agent unchanged. Then end the turn and resume only on the native completion notification. Do not poll or start a proxy waiter. Do not make concurrent project edits while the writer owns the shared tree.

On completion, read the ticket evidence and verify INDEX.md, changed paths, and state/hash consistency without repeating the codebase reading. Run:

node -e "const fs=require('node:fs'),c=require('node:crypto'),p='.claude/.codebase-info/',s=JSON.parse(fs.readFileSync(p+'.map-state.json','utf8'));if(!Array.isArray(s.documents))throw Error('documents');for(const n of new Set(['INDEX.md',...s.documents])){const b=fs.readFileSync(p+n,'utf8');if(!s.hashes||s.hashes[n]!==c.createHash('sha256').update(b.replace(/\r/g,'')).digest('hex'))throw Error(n)}"

Require the writer's evidence to name cited-path checks, docs created/updated/removed, and confirmation that CLAUDE.md is untouched. If source moved during mapping, the writer reconciles once or releases rather than certifying a mixed snapshot.

For an add, dispatch, spawn, or executor failure, inspect pulse and the ticket thread first. Make at most one diagnose-first redispatch, only when that diagnosis changes the launch and no live claim remains. After a second failure, record the evidence on the ticket, make sure no writer owns the claim, and complete the map inline in this same shared tree. Validate or repair any partial map before replacing state, comment that the ticket completed through inline fallback, and give the user one short line naming the delegation failure and inline fallback.

Step 1 : Identify the stack

Read the project's manifest/config files to determine languages, frameworks, and tooling. See references/language-detection.md for a broad map of signal files across ecosystems (JS/TS, Python, Go, Rust, Java/Kotlin, .NET, Ruby, PHP, Swift, Elixir, C/C++, Dart/Flutter, monorepos, and more). Note the framework(s) : they dictate where things live.

Step 2 : Map the directory structure

List the tree (git ls-files in a git repo gives a clean, ignore-aware listing; otherwise tree or a recursive list, skipping the noise dirs above). Identify the organizing principle:

• Layer-based: controllers/, services/, models/
• Feature/domain-based: features/auth/, domains/billing/
• Hexagonal/clean: domain/, application/, infrastructure/
• Monorepo: packages/*, apps/*, workspaces

Step 3 : Find the entry points

Where does execution begin? Web routes, API routers, CLI command handlers, background workers/cron, serverless handlers, library public exports, app main/bootstrap files, build/start scripts.

Step 4 : Trace the key flows

For the 3–5 most important features, trace end to end: entry point → business logic → data layer → external effects. Example: POST /api/users → UserController.store() → UserService.create() → users table → WelcomeEmail. Note shared utilities and cross-cutting concerns (auth, logging, validation, error handling).

Step 5 : Catalog dependencies

From the manifest(s), categorize: Core (framework/runtime), Data (DB/ORM/cache), External (API clients, third-party services), Dev (test/lint/build). Capture only what aids understanding : don't transcribe the entire lockfile.

Step 6 : Capture patterns & conventions

Recurring design patterns, error-handling approach, configuration/secrets management, logging and observability, and testing structure. Derive coding style from linter/formatter configs (.eslintrc, ruff.toml, .editorconfig, rustfmt.toml, etc.) and from what the code actually does.