vibe-code-map

Generate the tiny repo context file your AI coding agent wishes it had.

Built by Mustafa
Instagram: @mustafaiscoding · X/Twitter: @mustafa30

Why this exists

Your AI coding agent is usually not dumb. It just has bad context.

vibe-code-map scans your repo and generates a small AGENT_CONTEXT.md with the files, commands, risks and rules your agent needs before touching code.

No database. No server. No embeddings. Just a clean context map you can commit, paste or regenerate before a coding session.

Quick start

Run directly from GitHub:

npx github:mustafa3252/vibe-code-map

After npm publishing, this also works:

npx vibe-code-map

Scan another folder:

npx github:mustafa3252/vibe-code-map --dir ./my-app --out ./my-app

What it creates

AGENT_CONTEXT.md
CLAUDE.md
.cursor/rules/repo-map.mdc

AGENT_CONTEXT.md includes:

• detected stack
• useful commands
• important entry points
• tests and checks
• docs and config files
• risky files to avoid without approval
• a ready-to-paste agent prompt
• a repo tree sample

Example output

# AGENT_CONTEXT.md

## What this repo appears to use

- Next.js
- React
- Tailwind

## Commands found

- `npm run dev`
- `npm run test`
- `npm run lint`

## Be careful with these files

- .env.example
- prisma/schema.prisma
- app/api/auth/route.ts

## Suggested agent prompt

Read AGENT_CONTEXT.md first. Work in a small vertical slice. Before editing, say which files you plan to touch and why. After editing, run the smallest relevant check and report the exact output.

Options

vibe-code-map --help

Option	What it does
--dir <path>	repo to scan, defaults to current directory
--out <path>	where to write files, defaults to current directory
--no-cursor	skip .cursor/rules/repo-map.mdc
--no-claude	skip CLAUDE.md
--max-files <n>	max files to scan, default 500
--max-depth <n>	max folder depth, default 7

Why vibe coders need this

Vibe coding gets messy when the agent has to guess the project shape.

This gives the agent a map first:

1. what the app is,
2. where the important files are,
3. how to check its work,
4. which files are risky,
5. what “small and verified” means here.

That one file can save a surprising amount of chaos.

Works with

• Claude Code
• Cursor
• Codex
• Gemini CLI
• OpenCode
• any agent that can read Markdown

Star growth

Local development

git clone https://github.com/mustafa3252/vibe-code-map.git
cd vibe-code-map
npm test
node bin/vibe-code-map.js --dir test/fixtures/nextish --out /tmp/vibe-code-map-demo

Brand

Built with taste by Mustafa.

• Instagram: @mustafaiscoding
• X/Twitter: @mustafa30

If this helps your agent stop guessing, star it and tag me with what you build.

License

MIT. Use it, remix it and ship something useful.