How quinnaho/claudemap works
1. This repo is a monorepo for “ClaudeMap” with three main runtime surfaces:
- an interactive map UI in app/
- a skill/CLI layer in skill/ that runs inside Claude Code or Codex
- a set of build and packaging scripts in scripts/ plus a thin CLI entrypoint in bin/
2. The core product flow is: source code → semantic graph → map artifacts → visual exploration.
The skill layer scans a target repository, builds a concept-oriented graph, enriches it with AI-assisted descriptions and health/status data, then writes map/runtime JSON artifacts. The app consumes those artifacts and renders the navigable map. This is the primary data boundary in the system.
3. skill/ is the orchestration and analysis engine.
It contains commands like setup-claudemap, refresh, show, snapshot, and create-map, plus helpers for project-root discovery, file walking, import resolution, manifest/scope resolution, cache, launcher behavior, and MCP integration. This layer is what actually “understands” a repo and produces map state.
4. The skill layer is designed around assistant command execution.
skill/lib/command-harness/ wraps slash-command execution, argument parsing, logging, enrichment I/O, and MCP wiring. This is the boundary where Claude Code or Codex invokes ClaudeMap behavior. The skill/prompts/ directory holds the prompt templates used to drive enrichment and scoped enrichment.
5. skill/lib/contracts/ and app/src/contracts/ define the shared shape of map data.
Both sides have explicit contract modules for graph sources, paths, presentation, tokens/branding, and schema/version handling. This is important architecturally: the skill emits structured graph/runtime data, and the app relies on the same contract vocabulary to render it consistently.
6. app/ is a Vite/React frontend specialized for graph visualization and runtime playback.
The root App.jsx composes graph canvas, top bar, map selector, status bar, zoom controls, and presentation overlays. The main visual subsystem lives under app/src/components/graph/, where node types, custom edges, handles, runtime overlays, and affordances are rendered.
7. The UI’s state is split into graph, runtime, and UI slices.
app/src/store/graphSlice.js, runtimeSlice.js, and uiSlice.js form the application state boundary, with selectors in store/selectors.js. Hooks such as useRuntimeSync, useRuntimePolling, useGraphViewModel, and useGraphPointerHandlers connect the visual layer to runtime updates, hover/focus behavior, and layout state.
8. Graph layout is a distinct subsystem from rendering.
The app/src/lib/ directory contains graph transforms, layout engines, semantic/top-level/system-tree layout helpers, edge layout, node utilities, and view transforms. This suggests a pipeline where raw map data is normalized into positioned graph structures before React renders them. The diagram should show “layout computation” as a middle layer between data and canvas.
9. There is a runtime/state loop that keeps the map presentation synchronized.
The app includes runtime assets and polling hooks, and the repo ships claudemap-runtime*.json files in app/public/ and docs/. The runtime files appear to drive presentation state, focus/highlight changes, and assistant-guided walkthroughs. This is the mechanism behind /explain and /show style interactions.
10. Assistant-facing presentation is part of the product, not just a backend feature.
The app/src/components/graph/PresentationOverlay.jsx, GraphRuntime.jsx, and FloatingDescription.jsx indicate that explanations are rendered directly on top of the graph. The assistant doesn’t just return text; it can steer the viewport and annotate specific nodes/paths in the UI.
11. Build and distribution are multi-targeted.
scripts/build-site.js publishes the standalone site in docs/, while other scripts package the skill, generate the seed map, check contracts, and run smoke tests. The repository therefore has at least two deployables: the interactive preview site and the installable assistant skill/package.
12. docs/ is a generated/static distribution, not the source of truth.
It contains built JS/CSS assets, deployed JSON map/runtime files, and a static index.html for the hosted demo. The source lives in app/ and skill/; docs/ is the published artifact for the public preview.
13. claudemap-maps.json and the seed-map contract provide initial navigation metadata.
The repo includes a seed map in contracts/claudemap-seed-map.json plus generated map manifests at the root, in app/public/, and under docs/. These artifacts seed the visualization so the UI can load a repo’s conceptual map before or alongside assistant-driven refinement.
14. The important architectural boundaries to show in a diagram are:
- source repository being analyzed
- skill/CLI analysis and enrichment pipeline
- shared contracts/schemas
- generated map/runtime artifacts
- React/Vite graph UI and its runtime state loop
- packaging/build scripts that publish the app and skill
- external assistant runtimes: Claude Code, Codex, and MCP where applicable
Main entry points: lib Analysis engine · graph Graph canvas · skill Skill CLI · claudemap-runtime.json Map artifacts
Components 18
Runtime surfaces
Interactive app and assistant-facing CLI runtime.
- App shell · Vite/React entry that composes the map experience.
app/src/App.jsx - Graph canvas · Renders nodes, edges, affordances, overlays, and node-specific views.
app/src/components/graph - Layout engine · Transforms semantic graph data into positioned graph structures.
app/src/lib - State store · Holds graph, runtime, and UI slices plus selectors.
app/src/store - Runtime sync · Keeps presentation state and graph focus synchronized.
app/src/hooks
Skill pipeline
Repo analysis, enrichment, contracts, and command orchestration.
- Skill CLI · Command surface invoked inside Claude Code or Codex.
skill - Command harness · Runs slash commands, parses args, logs, and wires MCP.
skill/lib/command-harness - Analysis engine · Walks files, resolves imports, builds graphs, and adds health and descriptions.
skill/lib - Manifest scope · Resolves scope, fingerprints, and active-map metadata.
skill/lib/manifest - Prompt pack · Prompt templates that drive assistant-assisted enrichment.
skill/prompts - MCP bridge · Connects skill execution to MCP-enabled assistant runtimes.
skill/lib/mcp-client.js
Build and distribution
Packaging scripts and published artifacts.
- CLI entry · Thin executable entrypoint for the package.
bin/claudemap.js - Docs site · Published static preview and hosted demo output.
docs - Packaging scripts · Builds the site, packages the skill, and checks contracts.
scripts
Shared data
Schemas and generated map/runtime files used across surfaces.
- Shared contracts · Common graph, path, presentation, and version contracts used by skill and app.
skill/lib/contracts - App contracts · Frontend-side contract modules for map, presentation, paths, tokens, and zoom.
app/src/contracts - Map artifacts · Runtime and map JSON consumed by the app and published for distribution.
docs/claudemap-runtime.json
Other components
- Target repo · Repository being scanned and mapped by ClaudeMap.
Connections 20
- Target repo → Skill CLI: analyzed by · The target repository is scanned from the skill surface.
- Skill CLI → Command harness: executes · Assistant commands are routed through the harness.
- Command harness → Analysis engine: drives · Command execution triggers scanning, enrichment, and map generation.
- Analysis engine → Manifest scope: resolves · Analysis is constrained by project scope and manifest state.
- Analysis engine → Shared contracts: emits · Produces structured graph and runtime data using shared contracts.
- Analysis engine → Prompt pack: uses · Prompt templates guide enrichment passes.
- Analysis engine → MCP bridge: integrates · MCP wiring supports assistant-driven operations.
- Shared contracts → App contracts: mirrors · Frontend and skill share the same map vocabulary.
- Analysis engine → Map artifacts: writes · Map and runtime JSON artifacts are produced from the analysis pipeline.
- Map artifacts → App shell: loads into · The UI consumes generated map/runtime state.
- App shell → Graph canvas: composes · Shell assembles the graph visualization experience.
- Graph canvas → Layout engine: uses · Rendering depends on computed layout and transforms.
- Layout engine → State store: reads · Layout and view state are coordinated through the store.
- State store → Runtime sync: updates · Runtime hooks observe store slices and synchronize presentation.
- Runtime sync → Graph canvas: steers · Focus, hover, and presentation updates affect the graph view.
- Packaging scripts → Docs site: builds · Scripts publish the static demo and bundled assets.
- Packaging scripts → Skill CLI: packages · Scripts also package and install the assistant skill.
- CLI entry → Skill CLI: launches · The executable entrypoint boots the skill surface.
- Map artifacts → Docs site: published in · Runtime and map JSON are included in the public demo output.
- App contracts → Graph canvas: drives · Presentation and motion contracts shape the UI components.