Codebase Mapping

The ai map command analyzes source code and creates searchable knowledge nodes for every file and function. It bridges the gap between business documentation and implementation — making actual code searchable alongside organizational knowledge.

How It Works

Mapping works at two levels:

Module nodes— one per source file, with a markdown summary of exports, imports, and dependencies. Connected via "imports" edges that mirror the real dependency graph.
Chunk nodes — one per function, method, or class, containing the actual source code. An AST-based parser extracts these so you can search for implementations by describing what they do.

For example, searching "exponential backoff with jitter" finds the retryWithBackoff function by its implementation, not just its name.

Quick Start

# Preview what will be analyzed
ai map . --dry-run

# Map and approve immediately
ai map . -y --status approved

# Map with a root node connection
ai map . -y --status approved --root-node <service-root-id>

The Full Mapping Cycle

For the best results, combine code mapping with business documentation. The recommended cycle creates five layers:

1. Create a Root Node

Every service/product gets one architecture node as its anchor in the graph.

ai add --type architecture --title "Service: my-service" \
  --domain architecture --status approved \
  "my-service is a workflow management platform that..."

# Link to your platform overview if you have one
ai link <platform-overview-id> <root-id> --rel contains

2. Write Business Feature Notes

One note per major feature. Describe what it does and whyit matters — not how it's implemented.

ai add --type note --title "Assignment Resolution" \
  --domain design --status approved \
  "## What It Does
Assignment Resolution automatically determines who should handle a task...

## How Organizations Use It
- Large property management companies use role-based assignment..."

3. Write Architecture Nodes

One architecture node per major subsystem. Describe howit's built.

ai add --type architecture --title "Workflow Engine Architecture" \
  --domain architecture --status approved \
  "## Overview
Template-instance pattern with hierarchical instantiation...

## Key Services
| Service | File | Responsibility |
|---------|------|---------------|
| WorkflowService | workflow.service.ts | Core CRUD |"

4. Link Documentation to Root

ai link <root-id> <note-id> --rel documents
ai link <root-id> <arch-id> --rel documents

5. Create Workspaces

ai workspace create myservice-engineering \
  --description "Architecture and code for My Service" \
  --domains "architecture,development" \
  --types "architecture,policy,module,function,method,class"

ai workspace create myservice-product \
  --description "Business features for My Service" \
  --domains "products,design" \
  --types "note,decision"

6. Map the Code

ai map . -y --status approved --root-node <root-id>

What Gets Created

Node Type	Content	Edges
`module`	Export/import summary per file	`imports` → other modules, `contains` → chunks
`function`	Full source code of the function	`contains` ← parent module
`method`	Full source code with parent class context	`contains` ← parent module
`class`	Full source (small classes) or split into methods (large classes)	`contains` ← parent module

Supported Languages

Language	Parser	Detection
TypeScript / JavaScript	TypeScript Compiler API (full AST)	`tsconfig.json`
Python	Indentation-based parsing	`setup.py`, `pyproject.toml`, `requirements.txt`

Large Codebases

Projects with many files are automatically split into batches of ~200 chunks each. No manual splitting needed. Cross-batch operations (import edges, stale cleanup) run in a finalize pass after all batches complete.

Note

For TypeScript projects, files outside the project root directory are automatically excluded, and duplicate files (appearing via different tsconfig paths) are deduplicated.

Re-running

Re-running ai map on the same project is safe and idempotent:

Existing nodes are updated (upserted by title)
New files/functions create new nodes
Removed functions are cleaned up (stale chunk detection)
Import and contains edges are rebuilt

Incremental Updates

Between full mappings, use the /sync Claude Code skill for incremental updates:

# Install skills into your project
ai codebase init

# Then in Claude Code, run:
/sync

The sync skill detects changed files via git, creates/updates module nodes for modifications, and archives nodes for deleted files.