Skip to main content
Glama

Why

Solo developers working with coding agents keep hitting the same walls:

The problem

What the research and reports say

What MAP-IT-ALL does

Agents add code instead of changing it, break parts they cannot see, lose the plot in a large repo

Columbia DAPLab's 9 failure patterns of coding agents (repeated code, codebase awareness, refactoring)

connections shows the blast radius before the edit; find and symbol find the helper that already exists

Every new session re-explains the project and burns input tokens

A constant complaint in developer threads; context files drift out of date

brief at session start, handoff at session end

Memory goes stale as the code changes

STALE: can LLM agents know when their memories are outdated?, Dosu on pruning stale agent memory

Notes carry file hashes; recall flags stale and orphaned notes

Too many MCP tools cost tokens on every request and make tool choice worse

MCP tool overload reports ~42,000 tokens of definitions for GitHub's official server

4 to 12 tools in three profiles: ~670 / ~1,270 / ~1,400 tokens (measured, map-it-all tokens)

Dead code piles up, docs describe deleted files

Developers report that agents add and rarely delete

leads, diff, and a docs-drift check

Shell output floods the context

RTK

doctor detects it and prints the setup (docs/rtk.md)

Related MCP server: Symbra

What you get

  • A session brief (~450 tokens): git state, stack, layout, most-imported files, public surface, cleanup leads, your last handoff and memory notes. No more re-explaining the project.

  • Connections and blast radius. Who imports this file, what it imports, and who calls the route or function it registers, including callers an import graph cannot see: 'module:fn' strings, wrapper helpers, URL literals, Kotlin/JS native bridges.

  • Memory that knows when it is stale. Notes are anchored to files by content hash. Change the file and the note is flagged before an agent trusts it.

  • Cleanup leads with the right amount of fear. No references, test-only references, unmounted routes, unregistered native modules, tests no runner executes, docs pointing at deleted files. Anything an installed client or external caller could still reach is marked public: VERIFY, never REMOVE.

  • A session diff. "What did this session just orphan?" in one call.

  • A zoomable map you can open (the picture above).

  • Local and cheap. No network, no API keys, no telemetry. One runtime dependency, ast-grep. Works with any MCP client: Claude Code, Cursor, VS Code, Codex.

It does not replace a language server or a call-graph tool. For exact, type-aware call graphs, run one next to it (graft, codebase-memory-mcp, Serena, CodeGraph). MAP-IT-ALL covers what those do not: registration and liveness facts, session memory and the brief. See the comparison.

Quickstart

Works the same on macOS, Windows and Linux (including WSL). You need Node 20 or newer and git; the three commands below are identical on every OS and in every shell. Where the OSes differ (installing Node, registering the server by hand, troubleshooting) there is a per-OS guide right after.

0. Check the prerequisites:

node -v      # v20 or higher
git --version

Missing one? Jump to your OS for the install line.

1. See it first (10 seconds, touches nothing of yours):

npx -y github:peterish8/map-it-all demo --open

That maps a bundled sample project into your temp folder and opens the zoomable map.

2. Set it up in your project, with one command (run it from your project folder):

npx -y github:peterish8/map-it-all init --npx

That works in bash, zsh, fish, PowerShell and cmd alike (on Windows it writes the cmd /c npx form the MCP config needs), and it does everything:

[1/4] Map             built in 0.6 s: 46 files, packs: convex, express, expo
                      connections: 16 import edges across 14 imported files; most imported: web/src/lib/api.ts (x3)
                      19 public records (verify, never remove), 15 cleanup leads
[2/4] MCP config      claude: added in .mcp.json
[3/4] Instructions    CLAUDE.md: appended; AGENTS.md: created
[4/4] .gitignore      .map-it-all/ added
  1. Builds the map and the connections (import graph, who calls what, public surface).

  2. Writes the MCP config for your agent (--agent claude|cursor|vscode|codex|all, default Claude Code), merging with servers you already have.

  3. Appends three lines to the very end of CLAUDE.md and AGENTS.md, between <!-- map-it-all:start --> and <!-- map-it-all:end --> markers. Your own text is never touched, a second run changes nothing, and uninstall removes exactly that block.

  4. Adds .map-it-all/ to .gitignore.

Preview it first with --dry-run. Add --hook to also install the Claude Code hooks (a session-start brief and realtime). Use --no-docs to leave CLAUDE.md/AGENTS.md alone.

3. Restart your agent and ask it to "call the map-it-all brief tool". Claude Code asks you to approve a project-level server once. Check with claude mcp list, or run npx -y github:peterish8/map-it-all doctor.

Prefer to register the server yourself, or not on Claude Code? The per-OS commands are in the next section, and Connect your agent covers Cursor, VS Code and Codex.

Setup by operating system

Pick your OS. Each one has the same four parts: install the prerequisites, run init, register by hand if you prefer, and fix the usual problems.

Install Node and git with Homebrew:

brew install node git
node -v && git --version

No Homebrew? Download the LTS installer from nodejs.org, and run xcode-select --install for git.

Set up, from your project folder:

cd ~/code/my-project
npx -y github:peterish8/map-it-all init --npx

Register by hand (Claude Code):

claude mcp add map-it-all -- npx -y github:peterish8/map-it-all mcp
claude mcp list                                   # map-it-all should be listed
npx -y github:peterish8/map-it-all doctor         # checks Node, git, ast-grep, the map

Open the map: npx -y github:peterish8/map-it-all view --open

Good to know: if node or npx is "command not found" right after installing, open a new terminal tab. On Apple Silicon, Homebrew lives in /opt/homebrew; if brew itself is not found, run eval "$(/opt/homebrew/bin/brew shellenv)" and add that line to ~/.zprofile.

Install Node and git with winget (built into Windows 10 and 11), then open a new terminal so PATH refreshes:

winget install OpenJS.NodeJS.LTS
winget install Git.Git
node -v; git --version

No winget? Use the installers from nodejs.org and git-scm.com.

Set up, from your project folder (same line in PowerShell, cmd and Git Bash):

cd C:\code\my-project
npx -y github:peterish8/map-it-all init --npx

init writes the Windows form of the MCP entry for you (cmd /c npx ...), because Windows cannot launch npx directly from an MCP config.

Register by hand (Claude Code). The shell matters here:

# PowerShell: quote the double dash (PowerShell swallows a bare --) and go through cmd
claude mcp add map-it-all '--' cmd /c npx -y github:peterish8/map-it-all mcp
:: cmd.exe
claude mcp add map-it-all -- cmd /c npx -y github:peterish8/map-it-all mcp
# Git Bash or WSL: the macOS/Linux form
claude mcp add map-it-all -- npx -y github:peterish8/map-it-all mcp

Then claude mcp list and npx -y github:peterish8/map-it-all doctor.

Open the map: npx -y github:peterish8/map-it-all view --open

Good to know:

  • error: unknown option '-y' means PowerShell ate the --. Use the quoted '--' above, or sidestep the problem with npx -y github:peterish8/map-it-all init --agent claude --npx.

  • npx.ps1 cannot be loaded because running scripts is disabled: run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned once, or call npx.cmd instead of npx.

  • Cursor and VS Code configs on Windows use "command": "cmd", "args": ["/c", "npx", ...]; init --agent cursor or --agent vscode writes that for you.

  • Project-scope servers need a one-time approval inside Claude Code (see step 3).

  • Prefer Linux tooling? Everything in the Linux section works inside WSL. Install Node inside WSL too: which node must not point at /mnt/c/....

Install Node 20+ and git. Distro packages are sometimes older than Node 20, so check node -v after installing. If it is too old, use nvm (follow the install line in its README), which needs no root:

# Debian / Ubuntu
sudo apt update && sudo apt install -y git curl
# Fedora / RHEL
sudo dnf install -y git nodejs npm
# Arch
sudo pacman -S git nodejs npm

# any distro, if node is older than v20: install nvm (see its README), then
nvm install --lts
node -v && git --version

Set up, from your project folder:

cd ~/code/my-project
npx -y github:peterish8/map-it-all init --npx

Register by hand (Claude Code):

claude mcp add map-it-all -- npx -y github:peterish8/map-it-all mcp
claude mcp list
npx -y github:peterish8/map-it-all doctor

Open the map: npx -y github:peterish8/map-it-all view --open uses xdg-open. On a server, over SSH or in a container there is no browser, so run view without --open: it prints the path of graph.html to copy to a machine that has one. On WSL, open the file from Windows Explorer (explorer.exe . in the folder).

Good to know:

  • With nvm, make sure the shell that launches your agent loads it (it must see the same node as your terminal). If an editor starts the MCP server and fails with npx: not found, put the absolute path from which npx in the config's command field.

  • npx needs git to fetch github: packages; install it if you see spawn git ENOENT.

  • Behind a proxy or offline? Use the local clone below, which needs the network only for npm install.

Same thing, side by side

macOS / Linux / WSL / Git Bash

Windows PowerShell

Windows cmd

Set up

npx -y github:peterish8/map-it-all init --npx

same

same

Register (Claude Code)

claude mcp add map-it-all -- npx -y github:peterish8/map-it-all mcp

claude mcp add map-it-all '--' cmd /c npx -y github:peterish8/map-it-all mcp

claude mcp add map-it-all -- cmd /c npx -y github:peterish8/map-it-all mcp

Verify

claude mcp list and ... doctor

same

same

Realtime on / off

npx -y github:peterish8/map-it-all realtime on

same

same

Open the map

... view --open (open on macOS, xdg-open on Linux)

... view --open

... view --open

Remove

... uninstall (add --purge to delete .map-it-all/)

same

same

(... stands for npx -y github:peterish8/map-it-all.)

Update, pin, undo

Same on every OS:

npx -y github:peterish8/map-it-all#v0.1.0 init --npx   # pin a release instead of tracking main
npx -y github:peterish8/map-it-all uninstall           # remove the block, MCP entry and hooks; keeps your memory notes
npx -y github:peterish8/map-it-all uninstall --purge   # also delete .map-it-all/ (only ever inside your project)

npx caches what it fetches, so a newer main may not be picked up right away. Pin a tag (above) for a predictable version, or delete the _npx folder inside the directory printed by npm config get cache to force a fresh download.

Working with teammates on other operating systems? init --npx writes the MCP entry for the OS it runs on (cmd /c npx on Windows, plain npx elsewhere), so a committed .mcp.json from one OS will not start on the other. Either have each person run init locally and leave .mcp.json uncommitted, or commit one OS's file and let the others re-run init.

Prefer a local clone?

git clone https://github.com/peterish8/map-it-all.git
cd map-it-all && npm install            # installs ast-grep, the only dependency

Then, from your project folder, call the script by its path:

# macOS / Linux / WSL
node ~/code/map-it-all/bin/map-it-all.mjs doctor
node ~/code/map-it-all/bin/map-it-all.mjs init      # the MCP entry points at your clone
node ~/code/map-it-all/bin/map-it-all.mjs view --open
# Windows PowerShell
node C:\code\map-it-all\bin\map-it-all.mjs doctor
node C:\code\map-it-all\bin\map-it-all.mjs init
node C:\code\map-it-all\bin\map-it-all.mjs view --open

Realtime mode

Optional, off by default, and switchable at any time, by you or by the agent.

map-it-all realtime on        # or: off | status

An agent can also call the realtime tool (action: on|off|status) when it wants the map kept current during a long edit session and switch it off again afterwards. It needs the edit hook, which init --hook installs.

How it stays cheap:

  • No watcher, no daemon. A PostToolUse hook fires only when the agent edits a file. While realtime is off the hook exits after one file check.

  • One rebuild per burst. Edits are coalesced: a detached, below-normal-priority worker waits for a quiet moment (about 1.5 s, at most 8 s), then rebuilds once. Many edits cost one build.

  • Never blocks an edit. The hook returns in about 0.2 s (mostly Node start-up), always exits 0, and has a 10 s timeout.

  • Quiet by design. After an edit the agent hears something only if it matters: the file holds public records, many files import it, or a recent edit left something with no references. Each warning is delivered once, in under 560 characters.

  • Safe reads. Map files are written atomically and readers wait for a rebuild in progress, so a tool call never sees a half-written map.

On a 2,500-file monorepo a background rebuild takes about 5 seconds of one low-priority core, roughly 7 seconds after the last edit of a burst.

Connect your agent

map-it-all init --agent <claude|cursor|vscode|codex|all> [--npx] writes the right config for your OS and keeps any servers you already have (--dry-run previews). By hand:

# macOS / Linux / WSL / Git Bash, from your project folder
claude mcp add map-it-all -- npx -y github:peterish8/map-it-all mcp

# Windows PowerShell: npx runs through cmd, and the double dash must be quoted
claude mcp add map-it-all '--' cmd /c npx -y github:peterish8/map-it-all mcp

# any shell, no `--` to get wrong: the tool writes .mcp.json for you
npx -y github:peterish8/map-it-all init --agent claude --npx

init --hook adds a SessionStart hook to .claude/settings.json (and the realtime edit hook). The session hook rebuilds only if HEAD or the working tree changed, saves the baseline that diff compares against, and prints the brief, which Claude Code adds to the session. By hand it is:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "npx -y github:peterish8/map-it-all session-start", "timeout": 120000 }] }
    ]
  }
}

.cursor/mcp.json:

{
  "mcpServers": {
    "map-it-all": { "command": "npx", "args": ["-y", "github:peterish8/map-it-all", "mcp"] }
  }
}

.vscode/mcp.json (note servers, not mcpServers):

{
  "servers": {
    "map-it-all": { "command": "npx", "args": ["-y", "github:peterish8/map-it-all", "mcp", "--root", "${workspaceFolder}"] }
  }
}

~/.codex/config.toml:

[mcp_servers.map-it-all]
command = "npx"
args = ["-y", "github:peterish8/map-it-all", "mcp", "--root", "/absolute/path/to/your/project"]

By default the server maps the directory the client starts it in. Use --root <dir> or MAP_IT_ALL_ROOT to point elsewhere. Add --profile minimal to expose four tools (about 670 tokens of definitions) instead of ten. More in docs/agents.md.

init writes these three lines to the end of your CLAUDE.md / AGENTS.md for you (snippet if you prefer to paste them):

- Start each session with the map-it-all `brief` tool. Before editing or deleting, use `connections` and `find`.
- Zero refs is a lead, never proof. `public` records may be used by installed clients: VERIFY, do not remove.
- Save durable learnings with the `memory` tool, anchored to files; call `handoff` before ending.

See it work

Real output from the bundled demo project (map-it-all demo).

brief: what an agent needs to start, in ~450 tokens.

# Session brief: demo-app

Stack: convex: 9 functions (7 public), 4 tables · express: 11 routes (2 conditional) · expo/android: 2 screens, 2 native modules, 3 kotlin classes
Layout:
  web  11 files (tsx/ts)
  convex  10 files (ts)
  mobile  8 files (kt/tsx)
  server  7 files (ts)
Most-imported files (change with care):
  web/src/lib/api.ts  ×2
Public surface (installed clients may still call it: VERIFY before removing): 7 convex-function, 1 convex-http, 11 express-route
Cleanup leads: 5 express-route, 3 convex-function, 2 kotlin-class, 2 npm-script, 2 test-file, 2 env-var
Docs pointing at missing paths: 1 doc(s); worst README.md (2). Do not trust those docs' file references.

leads: what looks unused, and what needs care.

convex-function (3)
  convex:streaks.forHabit   convex/streaks.ts:4         [no-refs] public
  convex:habits.archive     convex/habits.ts:8          [no-refs] public
  convex:legacyImport.run   convex/legacyImport.ts:4    [test-only] public
native-module (1)
  native-module:HabitWidget mobile/android/.../HabitWidgetModule.kt:2  [not-in-ExpoModulesPackageList]
express-route (5)
  express:GET /api/admin/users   server/routes/admin.ts:4   [conditional-mount,no-refs,undocumented] public
  express:GET /api/stats/export  server/routes/stats.ts:4   [no-refs,undocumented] public

connections: the blast radius, with the warning an agent needs.

$ map-it-all connections convex:habits.archive
No by-name callers recorded for convex:habits.archive [no-refs] public: installed or external clients may still call it

$ map-it-all connections web/src/lib/api.ts --direction in
IN: depends on this file (blast radius) (3)
  d1  web/src/hooks/useHabits.ts:2
  d1  web/src/lib/api.test.ts:1 [test]
  d1  web/src/pages/Settings.tsx:1

memory recall: a note that notices the code moved.

health-route-stays-above-the-routers-3fdf2  [decision] STALE
  Health route stays above the routers
  Load balancers hit /health before auth is mounted.
  anchors: server/app.ts
  ! server/app.ts changed since this note was written: verify before relying on it

The loop

  1. Start: the SessionStart hook (or the agent) calls brief.

  2. Before editing or deleting: connections and find. public means installed clients or external callers: VERIFY.

  3. While working: memory → remember for a decision or a gotcha, anchored to the files it is about.

  4. After a change: diff lists records that just lost their last production reference.

  5. End: handoff → save with a summary and next steps. The next brief shows it, and flags files that changed since.

Tools

Tool

What it answers

brief

What do I need to know to start?

find

Which routes, functions, native modules, scripts or docs match this? Filter by flag or public surface.

file

Everything about one file: records, importers, imports, debt, anchored notes

connections

Who depends on this, what does it depend on, who calls what it registers? (format: "mermaid" draws it)

leads

What looks unused or broken, and what needs VERIFY?

symbol

Where is this name declared and mentioned? (name-based, not type-aware)

diff

What did this session newly orphan?

memory

remember, recall, confirm, forget, list: notes anchored to files

handoff

save at the end, read at the start

realtime

Turn the realtime refresh on, off, or read its status

refresh, view

Rebuild now (optionally with Knip); path of the zoomable map

Profiles (--profile): minimal is brief, find, connections, memory; standard (default) adds file, leads, symbol, diff, handoff, realtime; full adds refresh and view. Every tool is also a CLI command, so the terminal and the agent always agree.

CLI

map-it-all demo [--open]                try it on a bundled sample, touching nothing of yours
map-it-all init [--npx] [--hook] [--dry-run]   map + MCP config + CLAUDE.md/AGENTS.md block + .gitignore
map-it-all uninstall [--purge]          remove what init added (keeps memory unless --purge)
map-it-all realtime [on|off|status]     keep the map fresh as the agent edits (needs init --hook)
map-it-all doctor                       check Node, git, ast-grep, Knip, RTK, the map
map-it-all build [--with-knip]          build the map (about 5 s on 2,500 files, under 1 s on small repos)
map-it-all view [--open]                the zoomable map page
map-it-all brief | session-start        the session brief | rebuild, snapshot, brief (a hook)
map-it-all query <text> [--kind k] [--flag f]
map-it-all file <path> | connections <target> [--direction in|out|both] [--depth n] [--mermaid]
map-it-all leads [--kind k] [--flag f] [--public] | symbol <name> | diff
map-it-all memory list|recall <q>|forget <id> | handoff | tokens
map-it-all check                        exit 1 if a pack's rules drifted (for CI)
map-it-all mcp [--profile minimal|standard|full]

map-it-all <command> --help for one command. Run map-it-all tokens to see what the MCP tool definitions cost on your install.

What gets mapped

Generic, any JS/TS repo: an import graph with real alias resolution (tsconfig paths and extends, workspace packages), docs and their inbound links, docs drift (docs naming files that no longer exist; fenced examples skipped), debt markers, npm scripts and script files nothing references, tests outside every runner glob, env vars read but set nowhere in the checkout, web workers.

Framework packs, auto-detected:

Pack

Detected from

Maps

convex

a convex/ folder with schema.ts

functions and every caller form (api.x.y, internal.x.y, anyApi, 'module:fn' strings, `module:${name}` wrappers, crons, runbook mentions), tables with reads and writes, HTTP routes

express

files that call express()

routes with full mount paths (nested, default-export, factory and same-file routers, conditional mounts), URL callers across the repo, whether a doc mentions the route

expo

a package.json with expo or react-native next to a Kotlin android/ folder

screens, native modules (Kotlin Name("X") against JS callers against the package list), Kotlin classes

Details, limits and how to write a pack: docs/packs.md.

Memory that knows when it is stale

memory remember  title:   "Health route stays above the routers"
                 body:    "Load balancers hit /health before auth is mounted."
                 kind:    decision
                 anchors: ["server/app.ts"]

recall re-hashes every anchor against the working tree: fresh, stale (an anchored file changed) or orphaned (it is gone). confirm re-verifies after the agent checked. Notes are small JSON files under .map-it-all/memory/; set memoryDir to commit them and share with a team. docs/memory.md

How it works

flowchart LR
  A[Your working tree<br/>git + files] --> B[ast-grep rules<br/>+ regex + import graph]
  B --> C[.map-it-all/<br/>JSON records]
  C --> D[MCP server<br/>stdio, local]
  C --> E[CLI]
  C --> F[Zoomable map<br/>graph.html]
  G[Memory notes<br/>+ handoff] --> D
  D --> H[Claude Code · Cursor<br/>VS Code · Codex]

Code structure comes from ast-grep rules (tree-sitter, so comments and strings never cause false hits). A pack only reports what a plain regex count also sees: map-it-all check compares them and exits 1 on drift, so a rule that stops matching is loud. Everything is plain JSON and Markdown you can read.

Pair with RTK

MAP-IT-ALL shrinks what an agent has to read about your code. RTK shrinks what comes back from the commands it runs. They do not overlap and neither needs the other. map-it-all doctor detects it and prints the install line for your OS (docs/rtk.md).

Configuration

Zero config works. To override detection, add map-it-all.config.json at the repo root:

{
  "historyDirs": [".planning", "archive"],
  "ignore": ["**/vendor/**"],
  "driftIgnore": ["^\\.mcp\\.json$"],
  "convex": { "dir": "convex" },
  "express": { "appFiles": ["server/app.ts"] },
  "expo": { "dir": "apps/mobile" }
}

Every option · example file

How it compares

MAP-IT-ALL

Call-graph servers (graft, codebase-memory-mcp, CodeGraph, Serena)

General agent-memory services (Mem0, Zep, Letta, Cognee)

RTK

Answers

What registers, references and imports what; what is safe to touch; where we left off

Exact symbol-level callers and definitions

What was said or decided across conversations

Shorter command output

Memory is tied to code

Yes, by file hash; flags stale

Not their focus

Not by file hash, typically

No

Marks what shipped clients may still call (VERIFY, not REMOVE)

Yes (public)

Not their focus

Not their focus

No

Needs a model, vector store or API key

No

No

Typically yes

No

Tool-definition cost

~670 to ~1,400 tokens

Varies by server

Varies

n/a (CLI hook)

They are complements: run a call-graph server for exact call graphs, MAP-IT-ALL for the brief, registration facts and memory, RTK for shell output.

FAQ

Roadmap

Ideas, not promises. Open an issue to vote or to propose.

  • More packs: Next.js route handlers, Hono/Fastify, NestJS, tRPC

  • Convex nested module folders

  • Optional import of SCIP indexes for exact call edges

  • A per-file incremental build for very large repos (today realtime rebuilds the whole map once per burst)

  • Publish to npm and the MCP registry

Contributing

Issues and pull requests are welcome, especially a wrong or missing result with a small project that shows it. See CONTRIBUTING.md; please read the Code of Conduct. Report security problems privately (SECURITY.md).

git clone https://github.com/peterish8/map-it-all.git && cd map-it-all
npm install && npm test       # 33 tests: packs, import resolution, memory, MCP protocol, CLI, init, realtime

Acknowledgements

Built on ast-grep (code structure) and informed by Knip (unused files and exports, an optional bridge), RTK (command-output compression), and the research and reports linked above.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to query a local, continuously updated symbol graph of a codebase, providing ranked search, caller/callee exploration, dependency paths, and git-diff impact analysis through MCP tools.
      14 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables coding agents to query a local, multi-repo code graph for symbol exploration, blast radius analysis, co-change mining, and durable code-anchored memory via MCP tools.
      271 npm
      16
      Business Source 1.1
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to query a locally indexed structural code graph — source entities, callers/callees, Git relationships and recorded mistakes — so they retrieve focused, token-bounded context instead of reading entire files. It runs over local SQLite and can be served through a CLI, agent hooks, an MCP executable and an authenticated local dashboard.
      24 npm
      MIT