VibeMap

VibeMap is a tool that lets a project owner see, in plain English, what AI agents (such as Claude Code) are doing in their project. VibeMap watches the project folder in the background, detects bursts of changes, translates code changes into understandable change cards, and shows the project architecture as a living map in a browser dashboard — without the user ever having to read code.

Requirements

• Node.js 20.19 or newer
• An Anthropic API key in the ANTHROPIC_API_KEY environment variable (get a key here)
• Git is optional: if the project has a git repository, VibeMap uses it to detect changes. Without git, VibeMap compares file hashes itself.

Install and run

Install and start with a single command in the root of your project folder:

npx vibemap

On first launch, VibeMap maps the current state of the project (the "baseline") and opens the dashboard in your browser. After that it watches for file changes in the background — when an agent makes changes and pauses for a moment, VibeMap analyzes the changes and adds a new change card to the dashboard.

The dashboard and the data it produces are stored in the project's .ai-status folder.

Request changes from the dashboard (experimental)

If Claude Code is installed on the same computer, a request box appears at the bottom of the architecture map. Type what you want in plain language ("Add an email notification for new orders"), read the short plan VibeMap shows you, and press Do it. When the work finishes, a new change card appears — and every card created this way has an Undo button that safely puts things back the way they were.

How it works under the hood: VibeMap runs Claude Code in the background in your project folder. Before and after each change it stores a snapshot (using git), which is what makes Undo possible. If the project is not a git repository yet, VibeMap quietly initializes one. Change requests are disabled when Claude Code is not installed; everything else works normally.

Command-line options

| Option | Description | | -------------------- | ------------------------------------------------------------------------ | | --project <path> | Project folder to track (default: current folder) | | --once | Analyze once and exit (no dashboard, no browser) | | --debounce <s> | Seconds of silence to wait after a burst of changes before analyzing (default: 15) | | --port <n> | Dashboard port (default: 4777) | | --no-open | Do not open the browser automatically | | --help | Show command-line help |

Architecture in brief

VibeMap consists of three parts:

1. File watcher (chokidar) watches the project folder and detects when a burst of changes has ended.
2. Interpreter layer collects the changes (via git diff or file comparison), sends them to Anthropic's Claude model with structured output, and stores the plain-English change cards and the updated architecture in .ai-status/data.json.
3. Local server (Node's own http module) serves the pre-built browser dashboard and an API (/api/data, /api/events with real-time updates, /api/layout). The server only listens on 127.0.0.1.

No data is sent anywhere except to the Anthropic API for analyzing code changes.

Troubleshooting

"VibeMap needs an Anthropic API key to function" The ANTHROPIC_API_KEY environment variable is missing or empty. Set it and restart VibeMap in the same window/session:

# PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."

# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-..."

For a permanent setting, add the variable to your operating system's environment variables (Windows: "Edit environment variables for your account").

Port already in use If the default port 4777 is taken by another program, start VibeMap on a different port: npx vibemap --port 5000.

Analysis fails repeatedly Check that the API key is valid and the account has usage available. VibeMap does not mark changes as processed until an analysis succeeds, so the same burst of changes is retried on the next run.

Data from an older VibeMap version If .ai-status/data.json was created by an older, incompatible version, VibeMap logs a warning, discards the old data, and maps a fresh baseline.

License

MIT