✨ Overview

Walkmap is a high-performance codebase indexer designed for LLM agents, code automation, and developer tooling.

It parses your entire repository and produces a structured, queryable representation of your code — enabling:

• Smarter AI agents
• Faster code navigation
• Reliable automation pipelines
• Incremental analysis at scale

🚀 Features

Walkmap analyzes every .ts, .tsx, .js, and .jsx file and generates:

🧠 Code Intelligence

• Symbols — functions, classes, interfaces, enums, variables, arrows (with signatures + locations)
• Call graph — function-to-function relationships
• Type hierarchy — extends / implements
• API surface — exported symbols per file

🔗 Dependency Graph

• Imports / exports graph (imports / importedBy)
• Entrypoint detection
• Dead code detection (heuristic)

📦 Structured Code Access

• Code chunks — semantic slices with full text (LLM-friendly)
• Test mapping — source ↔ test files
• Environment usage — process.env.*

⚙️ Quality & Insights

• TODO extraction — TODO, FIXME, HACK, etc.
• Complexity analysis — McCabe + hotspots
• Orphan file detection

🤖 LLM-Oriented Artifacts

Walkmap goes beyond indexing — it generates semantic artifacts to guide AI systems:

• Workspace manifest
• Pipeline description
• Glossary & FAQ
• Embeddings manifest (RAG-ready)
• Dependency rationale
• Contracts & invariants

📦 Installation

Using npm

npm install -D walkmap
npx walkmap

Using Bun

bun add -d walkmap
bunx walkmap

Global install (optional)

npm install -g walkmap
walkmap

🛠 Usage

Run in the root of your project:

npx walkmap

Or via script:

{
  "scripts": {
    "walkmap": "walkmap",
    "walkmap:force": "walkmap --force"
  }
}

⚡ CLI Flags

| Flag | Description | |------|------------| | --force | Ignore cache and re-index everything | | --quiet | Minimal logs | | --verbose | Show cache hits and indexed files | | --json | Output structured JSON (CI-friendly) | | --no-inject | Disable CLAUDE.md / AGENTS.md injection | | -j, --concurrency <n> | Parallel parsing (default: 8) |

♻️ Incremental Mode

Walkmap is optimized for large codebases via incremental indexing:

• metadata.json → file hash tracking
• .workspace/cache/per_file.json → cached extraction

Only modified files are re-parsed.

You can force a full rebuild:

npx walkmap --force

📁 Output Structure

All artifacts are generated under:

.workspace/

Core Index

• repo_map.json — file metadata
• symbols.json — extracted symbols
• import_graph.json — dependency graph
• chunks.json — LLM-friendly code slices
• dead_code.json — unused exports / orphan files
• call_graph.json — function relationships
• complexity.json — hotspots
• env_vars.json — env usage
• test_map.json — test associations

LLM / Automation Layer

• workspace_manifest.json
• entrypoints.json
• pipeline.json
• glossary.json
• faq_llm.json
• embeddings_manifest.json
• dependency_rationale.json
• external_contracts.json

🧩 Ignore Rules

Walkmap skips common directories by default:

• node_modules
• .git
• dist

You can extend this using:

.walkmapignore

🧪 Development

npm install
npm run build
npm run typecheck
npm run generate

Force re-index:

npm run generate:force

Run built version:

node dist/index.js --json

🏗 Architecture

Pipeline:

walk → filter → parse → assemble → write

Powered by:

• Parser: oxc-parser (Rust-based, high performance)
• Runtime: Node.js ≥ 18 / Bun
• CLI: lightweight, no native bindings

🎯 Use Cases

• LLM agents (Claude, GPT, custom pipelines)
• RAG over codebases
• Code search & navigation
• Static analysis tooling
• Developer productivity platforms

📜 License

MIT