xenapse-map

Structural and semantic codebase indexing for AI consumption.

Parses TypeScript, JavaScript, and Python codebases, builds dependency and symbol graphs, optionally summarises files via an LLM, writes structured artifacts under ./xenapse-map/ (or a custom output directory), and can run as an MCP server (--mcp) so AI tools can query the index over stdio.

Documentation index

• AGENTS.md — contribution and guardrail rules
• MAP.md — repository structure map
• TEST.md — testing strategy and commands
• SKILLS.md — exported CLI/MCP tool surfaces
• CONTRACTS.md — compatibility and versioning guarantees
• docs/MCP_SPEC.md — MCP protocol/tool contract
• .agents/README.md — repo-local AI docs index
• .agents/CHECKLIST.md — repo readiness checklist
• .agents/ARCHITECTURE.md — architecture boundaries
• .agents/TEST.md — strict quality + coverage policy

Runtime requirements

• Node.js: 22+ (current package target)
• Package manager: pnpm (via Corepack)
• Python: python3 must be available on PATH for Python file parsing
• Minimum supported Python: 3.8+

If python3 is missing and .py files are detected, xenapse-map logs:

• [xenapse-map] python3 not found — .py files will be skipped

TypeScript/JavaScript indexing still runs.

Quickstart: run the MCP server

Global installation

corepack enable pnpm
pnpm install
pnpm build
pnpm link --global

xenapse-map /path/to/project --mcp

Local execution

corepack enable pnpm
pnpm install
pnpm build

node ./bin/xenapse-map.js /path/to/project --mcp

Progress and warnings go to stderr. In MCP mode, stdout is reserved for MCP protocol messages.

With semantic summaries

export OPENROUTER_API_KEY=sk-or-...
node ./bin/xenapse-map.js /path/to/project --semantic --cache --mcp

MCP startup behavior

When --mcp is enabled, the MCP server starts immediately, before indexing completes.

• get_index_status reports idle | indexing | ready | error
• some tools can return partial/stale data while indexing is running
• get_architecture_summary includes _partial: true during indexing
• artifact-backed tools can return NOT_READY until their artifacts are generated

Recommended client behavior: poll get_index_status and wait for status: "ready" before broad analysis calls.

MCP tools (25 total, v0.3.0)

1. get_architecture_summary
2. get_file_summary
3. get_dependency_graph
4. search_symbol
5. get_reverse_dependencies
6. find_parse_errors
7. search_files
8. get_index_status
9. get_diagram
10. get_repo_facts
11. get_task_inventory
12. get_api_inventory
13. get_entrypoints
14. get_reachability_summary
15. get_symbol
16. get_call_tree
17. get_callers
18. get_module
19. get_dead_code_summary
20. get_context_plan
21. search_chunks
22. get_chunk
23. search_design_deviations
24. get_design_deviation
25. get_symbol_reachability

See docs/MCP_SPEC.md for tool schemas and response notes.

CLI reference

xenapse-map <target-path> [options]

| Flag | Default | Description | | --- | --- | --- | | --semantic | false | Enable LLM file summaries | | --model <id> | anthropic/claude-3-haiku | LLM model ID | | --out <dir> | ./xenapse-map | Output directory for all artifacts | | --cache | false | Re-use semantic summaries via disk cache | | --watch | false | Watch files and incrementally update index | | --benchmark | false | Print indexing metrics to stderr | | --exclude <p> | — | Comma-separated exclude patterns | | --languages <l> | all | Comma-separated language list | | --no-report | false | Skip report generation (report.md / report.html) | | --mcp | false | Start MCP server over stdio | | --ollama | false | Use local Ollama endpoint for summaries | | --force | false | Overwrite output when it already exists | | --help | false | Show usage |

Environment variables

| Variable | Description | Default | | --- | --- | --- | | OPENROUTER_API_KEY | Required for --semantic unless using --ollama | — | | OPENROUTER_MODEL | Override default model | anthropic/claude-3-haiku | | OPENROUTER_BASE_URL | OpenAI-compatible API base URL | OpenRouter | | XENAPSE_MAP_TARGET | Default target path | current directory | | XENAPSE_MAP_OUT | Output directory | ./xenapse-map | | CI | If true, non-writable output is treated as fatal | — |

Output path semantics

--out and XENAPSE_MAP_OUT are directories, not file paths.

Precedence:

--out <dir>  >  XENAPSE_MAP_OUT  >  .xenapsemaprc.json#out  >  ./xenapse-map

If --out /tmp/map-out is used, xenapse-map writes:

• /tmp/map-out/index.json
• other artifact files under /tmp/map-out/

Artifact output layout

Default output directory: ./xenapse-map/

xenapse-map/
├── index.json
├── repo_facts.json
├── task_inventory.json
├── api_inventory.json
├── ignore_rules.json
├── docs_index.json
├── infra_inventory.json
├── reachability.json
├── symbol_index.json
├── call_graph.json
├── reverse_index.json
├── dead_code.json
├── config_inventory.json
├── repo_map.json
├── repo_map.md
├── context_plan.json
├── chunk_index.json
├── design_deviations.json
├── design_deviations.md
├── artifact_manifest.json
├── diagrams/
│   └── dependency_graph.mmd
├── reports/                  # omitted when --no-report
│   ├── report.md
│   └── report.html
└── cache/                    # populated when --cache + --semantic
    └── <sha256>.json

Docker usage

A minimal container runtime is provided via Dockerfile (Node 22 + Python 3).

docker build -t xenapse-map .

docker run --rm -it \
  -v "$PWD":/workspace \
  xenapse-map /workspace --mcp

Use --out or XENAPSE_MAP_OUT to direct artifacts to a writable mounted directory when needed.

Release flow

Tagged releases use the GitHub CD workflow in .github/workflows/cd.yaml.

• create and push a semver tag matching v*.*.*
• GitHub Actions installs dependencies, builds the package, and verifies the tag matches package.json
• release artifacts are uploaded to GitHub Releases
• the npm package is published when NPM_TOKEN is configured

Example:

git tag v0.3.0
git push origin v0.3.0

The workflow publishes the built package tarball plus a fallback source archive to GitHub Releases and pushes the package to npm.

Self-dogfooding demo

Run xenapse-map against this repository and verify generated artifacts/docs/report:

pnpm demo:self-index

This workflow now does both:

• writes raw demo artifacts to .xenapse-map-demo-output/ (scratch output)
• writes curated human-readable evidence to docs/demo/:
  • README.md
  • verification-summary.md
  • artifact-summary.md
  • docs-walkthrough.md
  • report screenshots (report-overview.png, etc.) when Playwright is available
• writes detailed operational verification output to .agents/DEMO_SELF_INDEX_VERIFICATION.md

If raw output already exists and you only want to refresh curated evidence:

pnpm demo:curate

For CI/non-graphical environments:

pnpm demo:self-index -- --skip-screenshots

Dev commands

pnpm build
pnpm lint
pnpm test
pnpm test:coverage
pnpm lint:fix
pnpm typecheck
pnpm artifacts:validate
pnpm check
pnpm demo:self-index
pnpm verify:report
pnpm demo:curate
pnpm test:watch
pnpm dev -- /path/to/project

pnpm check runs the local code-quality gate (build + lint + typecheck + 100% coverage enforcement). Artifact schema/manifest validation is intentionally separate and should run after pnpm demo:self-index has generated .xenapse-map-demo-output/.

AI-first architecture upgrades

New generated artifacts:

• repo_map.json / repo_map.md
• context_plan.json
• chunk_index.json
• design_deviations.json / design_deviations.md
• artifact_manifest.json

New commands:

• pnpm context:plan -- --goal "..." --token-budget 12000
• pnpm repair:check
• pnpm repair:fix

Precision indexing now supports backend plugins with a first SCIP integration path and parser fallback.

Design constraint workflow

design_constraints.yaml supports three policy lists:

• allowed_dependency_directions: entries like src/ui -> src/core
• forbidden_imports: substring tokens that must not appear in imported module paths
• required_docs: markdown docs that must exist

Example policy: docs/examples/design_constraints.example.yaml.

Violations are emitted into design_deviations.json with deterministic IDs, severity (low|medium|high), and evidence pointers for both source file and policy rule context.

Repair workflow (safe MVP)

• pnpm repair:check runs build/lint/typecheck/test and an index pass that computes design_deviations.json, then writes .xenapse-map-repair/repair_report.json.
• pnpm repair:fix applies only safe low-risk fixes (Biome autofix + creating missing required docs under docs/), then runs the full validation pipeline above and emits the same report.