Minimap

Deterministic repository context for coding agents.

Minimap scans a local repository, detects high-signal project facts, and writes a compact managed context block into files such as AGENTS.md and CLAUDE.md.

It is not a README generator. It is a deterministic context compiler for coding agents.

minimap scan
minimap generate
minimap write --target AGENTS.md
minimap check --target AGENTS.md

Why Minimap?

Coding agents repeatedly rediscover the same repository basics:

• Which language, framework, and package manager is this?
• How should tests, linting, formatting, and type checks run?
• Is this Laravel, Vue, Inertia, Vite, Tailwind, Pest, PHPUnit, React, Next.js, or something else?
• Which commands are useful validation commands, and which commands should not be run without permission?
• What project conventions should an agent preserve before making changes?

Minimap turns those signals into durable, evidence-backed instructions.

Minimap vs Hand-Written Instructions

Use Minimap for facts that should stay synchronized with repository files: stack detection, package managers, validation commands, risky scripts, workspace manifests, and evidence-backed conventions. These are easy for humans to forget to update and cheap for Minimap to refresh deterministically.

Use hand-authored instructions for judgment and team policy: architectural preferences, review expectations, product context, deployment rules, security constraints, and anything that is not directly inferable from local manifests. Keep that content outside the managed block so Minimap can refresh its section without overwriting it.

flowchart LR
  A["Repository files"] --> B["minimap scan"]
  B --> C["agent context block"]
  C --> D["AGENTS.md / CLAUDE.md"]
  D --> E["minimap check"]

Example Output

Minimap writes only inside its managed block:

<!-- minimap:start -->

<repo_context generated_by="minimap" schema_version="1">

  <summary>
    Laravel + Vue/Inertia + TypeScript project using Composer, Bun, Pest, Vite, and Tailwind CSS.
  </summary>

  <stack>
    <language name="PHP" confidence="high" evidence="composer.json present" />
    <framework name="Laravel" confidence="high" evidence="laravel/framework dependency detected" />
    <framework name="Vue" confidence="high" evidence="vue dependency detected" />
    <tool name="Vite" confidence="high" evidence="vite dependency detected" />
  </stack>

  <commands>
    <command name="php_tests" value="composer test" confidence="medium" category="test" />
    <command name="frontend_build" value="bun run build" confidence="medium" category="build" />
  </commands>
</repo_context>
<!-- minimap:end -->

Installation

Minimap is Bun-native.

Install automatically:

curl -fsSL https://raw.githubusercontent.com/forjd/minimap/main/install.sh | bash

Run with Bun:

bunx @forjd/minimap scan

Or install globally:

bun install -g @forjd/minimap
minimap --help

Prefer shorthand?

bun i -g @forjd/minimap

Standalone binaries are also attached to GitHub releases for environments where installing Bun is inconvenient:

gh release download --repo forjd/minimap --pattern 'minimap-v*-linux-x64.tar.gz' --pattern SHA256SUMS
sha256sum -c SHA256SUMS
tar -xzf minimap-v*-linux-x64.tar.gz
./minimap-linux-x64 --help

Downloads are available for macOS, Linux, and Windows from the latest GitHub release.

The installer can be made explicit for scripts:

curl -fsSL https://raw.githubusercontent.com/forjd/minimap/main/install.sh | INSTALL_METHOD=binary BIN_DIR="$HOME/.local/bin" bash

For local development:

git clone https://github.com/forjd/minimap.git
cd minimap
bun install
bun run src/cli.ts --help

Agent Skill

Minimap ships a portable agent skill for agents that support the open skills format. It teaches agents to preview, write, and check Minimap-managed context blocks instead of editing them by hand.

Install it with the skills CLI:

npx skills add forjd/minimap --skill minimap

Or with Bun:

bunx skills add forjd/minimap --skill minimap

Install it for all detected agents:

npx skills add forjd/minimap --skill minimap --agent '*'

Commands

Scan

Scan the current repository and print detected signals as JSON:

minimap scan
minimap scan --pretty
minimap scan --cwd ./some-project

scan is read-only. To preview generated context, use generate or write --dry-run.

Generate

Generate a managed context block without writing it:

minimap generate
minimap generate --profile agents
minimap generate --profile claude
minimap generate --workspace-limit 20 --evidence-limit 8

The default agents profile keeps the generic schema. The claude profile adds explicit profile metadata to the generated block so CLAUDE.md consumers can distinguish profile-specific output.

Minimap intentionally ships only these two profiles for now. Additional targets should be added only when they need concrete output differences, not as aliases for the same block.

generate --format markdown remains the only supported output format. JSON and raw XML output should wait for a real downstream consumer so Minimap does not carry parallel schemas prematurely.

Rendering limits are configurable for large repositories. Defaults are stable at 40 workspace entries and 12 evidence items.

Write

Create or update a managed block in a target file:

minimap write --target AGENTS.md
minimap write --target CLAUDE.md

Preview the resulting file without writing:

minimap write --target AGENTS.md --dry-run

Check

Detect context drift:

minimap check --target AGENTS.md
minimap check --target AGENTS.md --normalized

Use the same command in CI to keep checked-in agent instructions current:

- name: Check agent context drift
  run: bunx @forjd/minimap check --target AGENTS.md

check exits:

• 0 when the managed block matches the current repository scan.
• 1 when the file is missing, the managed block is missing, multiple blocks are present, or the generated block has drifted.

By default, check compares the generated block exactly. Use --normalized only when a repository intentionally tolerates line-ending or outer-whitespace churn.

CI Drift Check Recipe

For a Bun-based repository, add this after dependency installation:

- name: Check agent context drift
  run: bunx @forjd/minimap check --target AGENTS.md

If the check fails, refresh the managed block locally and commit the result:

bunx @forjd/minimap write --target AGENTS.md

Safe Writes

Minimap uses stable markers:

<!-- minimap:start -->

...

<!-- minimap:end -->

Write behavior is conservative:

• If the target file does not exist, Minimap creates it.
• If the target exists without a managed block, Minimap appends the block.
• If the target contains one managed block, Minimap replaces only that block.
• If multiple managed blocks are found, Minimap refuses to write.
• Human-authored content outside the managed block is preserved.

Schema Version

Generated context uses schema_version="1" on the root <repo_context> element. Version 1 is the current stable XML-shaped Markdown block format: existing element names, attributes, marker comments, and exact drift checks should be treated as part of the contract.

Future schema changes should increment schema_version when they rename or remove elements, change attribute meanings, or make older generated blocks ambiguous for consumers. Add migration notes to this section when that happens, including what changed and whether downstream repositories should refresh blocks with minimap write or make manual edits.

Safety Model

Minimap is local-only and deterministic.

It does not:

• call an LLM
• run project scripts during scan or generation
• evaluate JavaScript, TypeScript, PHP, or config files
• recursively summarize source files
• overwrite content outside the managed block
• send repository data to external services

It does:

• read targeted manifest and config files
• classify commands as validation, development, formatting, or risk signals
• mark destructive database, publishing, deployment, and volume deletion commands as risks
• include confidence and evidence for inferred facts

Supported Signals

MVP detection covers:

• Node, JavaScript, and TypeScript via package.json
• Bun, pnpm, Yarn, and npm via lockfiles
• PHP and Composer via composer.json
• Laravel via laravel/framework or artisan plus bootstrap/app.php
• Vue, React, Next.js, Nuxt, Svelte, SvelteKit, Inertia, Vite, Tailwind CSS
• Vitest, Jest, Playwright, Cypress, Pest, PHPUnit
• ESLint, oxlint, Biome, Pint, PHPStan, Larastan
• shallow GitHub Actions workflow presence and names
• pnpm, npm, Yarn, and Bun workspace package manifests
• Turborepo, Nx, and Lerna monorepo configuration files

Good For

• Maintaining AGENTS.md or CLAUDE.md
• Giving coding agents a fast repository orientation
• Keeping context blocks current with minimap check
• CI drift checks for agent instructions
• Avoiding repeated manual repo summaries

Project Status

Minimap is an MVP.

Current limitations:

• Bun is the supported runtime.
• Node-compatible bundling is not a goal yet.
• Monorepo support detects root workspace configuration and summarizes detected package stacks from workspace manifests.
• Staleness checks compare the generated managed block exactly.
• The scanner intentionally avoids deep source parsing.

Development

bun install
bun run format:check
bun run lint
bun run typecheck
bun test

Format changed files:

bun run format

The test suite uses fixture repositories and snapshots for generated output.

Contributing

See CONTRIBUTING.md.

Releasing

See RELEASING.md.

Security

See SECURITY.md.

License

MIT, copyright Forjd.