Circuit Map

Portable navigation documents that give AI agents structured, token-efficient access to any codebase.

A .circuit-map.md file is a single markdown document that maps your entire repo — file list, symbols, co-edit pairs, and invariants — at four progressive zoom levels. An agent reading at zoom=1 gets full file coverage for ~700 tokens instead of 3,600+ tokens of raw directory exploration.

---

Quick start

# Install
cargo install --path circuitmap

# In any git repo
circuit-map init          # create .circuit-map.md
circuit-map generate      # populate it
circuit-map verify        # check freshness (run in CI)
circuit-map doctor        # diagnose issues

---

How it works

.circuit-map.md
─────────────────────────────────────────────────────────
---
schema: circuit-map/1
git_anchor: abc1234
files: 42
---

> One-sentence overview of what this repo does.   ← zoom 0

## Module Map                                       ← zoom 1
| File | Symbols | Hash |
| src/main.rs | fn main, struct Config | a1b2c3d4 |
...

## Task Routes                                      ← zoom 2
- `src/auth.rs` ↔ `src/session.rs`  (changed together 14×)

## Invariants                                       ← zoom 3
- Auth tokens must be compared in constant time.

Zoom levels let agents start with an overview and pull in more context only when they need it:

Level	Content	~tokens
0	Overview + frontmatter	80
1	+ Module Map (all files + symbols)	700
2	+ Task Routes (co-edit pairs)	900
3	Full map	varies

---

Commands

Command	What it does
circuit-map init	Create a minimal .circuit-map.md
circuit-map generate	Full index from scratch via tree-sitter
circuit-map update	Incremental update (changed files only)
circuit-map verify	Exit 1 if any tracked file hash has drifted
circuit-map watch	Re-generate on file save
circuit-map zoom <N>	Print map at zoom level 0–3
circuit-map serve	HTTP server at localhost:7070 with ?zoom=N
circuit-map doctor	Health check — tells you exactly what's wrong
circuit-map enrich	Use Claude to suggest Invariants
circuit-map push	Push map to a registry
circuit-map pull	Pull map from a registry

---

Languages supported

Rust · Python · JavaScript · TypeScript · TSX · Go · Java

---

GitHub App (zero-config)

Install the Circuit Map GitHub App on any repo and it automatically commits an up-to-date .circuit-map.md on every push to the default branch — no CLI, no CI step required.

push to main  →  circuit-map[bot] commits fresh .circuit-map.md  →  done

• Bot commits include [skip ci] — won't trigger pipelines
• Infinite-loop guard: bot's own commits are ignored
• Optional registry push on every update

See github-app/SETUP.md for full installation instructions.

---

VS Code extension

The extension shows map freshness in the status bar and lets you run all commands from the Command Palette.

contextos.circuitMap.enabled           — toggle the integration
contextos.circuitMap.autoCheckOnSave   — check freshness on every save
contextos.circuitMap.binaryPath        — path to circuit-map binary

---

CI gate

Add to .github/workflows/ci.yml to catch stale maps in PRs:

- name: Verify circuit map
  run: circuit-map verify

---

Registry (self-hosted)

Host a shared registry so AI agents on any machine can pull your maps.

# Start
docker run -p 5000:5000 \
  -e REGISTRY_ADMIN_TOKEN=my-secret \
  -v /data:/data \
  circuit-map-registry

# Create a per-org push token
curl -X POST http://localhost:5000/v1/tokens \
  -H "Authorization: Bearer my-secret" \
  -H "Content-Type: application/json" \
  -d '{"org": "myorg"}'

# Push
circuit-map push --registry http://localhost:5000 --token <tok> --slug myorg/myrepo

# Pull (no auth)
circuit-map pull --registry http://localhost:5000 --slug myorg/myrepo
circuit-map pull --registry http://localhost:5000 --slug myorg/myrepo --zoom 1

Registry endpoints

Method	Path	Auth	Description
POST	/v1/maps/:org/:repo	per-org token	Push a map
GET	/v1/maps/:org/:repo	—	Pull a map (?zoom=N)
GET	/v1/maps/:org/:repo/meta	—	JSON metadata
POST	/v1/tokens	admin	Create per-org token
GET	/v1/tokens	admin	List tokens
DELETE	/v1/tokens/:id	admin	Revoke token
GET	/health	—	Health check

---

Workspace support

For monorepos, circuit-map generate detects workspace structure (Cargo workspaces, package.json workspaces, multiple go.mod files) and generates per-package maps alongside the root map.

---

Architecture

ContextOS/
├── circuitmap/          # CLI binary (circuit-map)
│   └── src/
│       ├── main.rs      # command dispatch
│       ├── generate.rs  # map generation
│       ├── verify.rs    # hash freshness check
│       ├── zoom.rs      # progressive zoom extraction
│       ├── serve.rs     # local HTTP server
│       ├── doctor.rs    # health diagnostics
│       ├── enrich.rs    # Claude API enrichment
│       ├── registry.rs  # push/pull client
│       └── workspace.rs # monorepo detection
├── indexer/             # tree-sitter symbol + import extractor (lib)
│   └── src/
│       ├── index.rs     # RepoIndex, FileEntry, Symbol
│       ├── parse.rs     # per-language symbol extraction
│       ├── graph.rs     # import edge resolution
│       ├── lang.rs      # language detection
│       └── coedit.rs    # git co-edit pair mining
├── registry/            # hosted registry server (axum)
│   ├── src/
│   │   ├── main.rs
│   │   ├── routes.rs
│   │   └── store.rs
│   └── Dockerfile
├── extension/           # VS Code extension
│   └── src/
│       ├── extension.ts
│       └── circuitMap.ts
└── proxy/               # ContextOS LLM proxy (separate product)