{"id":49540186,"url":"https://github.com/forjd/minimap","last_synced_at":"2026-05-02T15:01:22.187Z","repository":{"id":355196301,"uuid":"1227212618","full_name":"forjd/minimap","owner":"forjd","description":"Deterministic repository context compiler for coding agents","archived":false,"fork":false,"pushed_at":"2026-05-02T12:04:06.000Z","size":0,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T12:05:53.972Z","etag":null,"topics":["ai-agents","bun","cli","coding-agents","developer-tools","repository-context","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/forjd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-02T11:17:46.000Z","updated_at":"2026-05-02T12:03:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/forjd/minimap","commit_stats":null,"previous_names":["forjd/minimap"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/forjd/minimap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fminimap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fminimap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fminimap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fminimap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forjd","download_url":"https://codeload.github.com/forjd/minimap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forjd%2Fminimap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32538268,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","bun","cli","coding-agents","developer-tools","repository-context","typescript"],"created_at":"2026-05-02T15:00:59.891Z","updated_at":"2026-05-02T15:01:22.173Z","avatar_url":"https://github.com/forjd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Minimap\n\nDeterministic repository context for coding agents.\n\n[![CI](https://github.com/forjd/minimap/actions/workflows/ci.yml/badge.svg)](https://github.com/forjd/minimap/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/@forjd/minimap.svg)](https://www.npmjs.com/package/@forjd/minimap)\n[![npm provenance](https://img.shields.io/badge/npm-provenance-brightgreen.svg)](https://www.npmjs.com/package/@forjd/minimap)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Runtime: Bun](https://img.shields.io/badge/runtime-Bun-black.svg)](https://bun.sh)\n[![Status: MVP](https://img.shields.io/badge/status-MVP-orange.svg)](#project-status)\n\nMinimap 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`.\n\nIt is not a README generator. It is a deterministic context compiler for coding agents.\n\n```bash\nminimap scan\nminimap generate\nminimap write --target AGENTS.md\nminimap check --target AGENTS.md\n```\n\n## Why Minimap?\n\nCoding agents repeatedly rediscover the same repository basics:\n\n- Which language, framework, and package manager is this?\n- How should tests, linting, formatting, and type checks run?\n- Is this Laravel, Vue, Inertia, Vite, Tailwind, Pest, PHPUnit, React, Next.js, or something else?\n- Which commands are useful validation commands, and which commands should not be run without permission?\n- What project conventions should an agent preserve before making changes?\n\nMinimap turns those signals into durable, evidence-backed instructions.\n\n```mermaid\nflowchart LR\n  A[\"Repository files\"] --\u003e B[\"minimap scan\"]\n  B --\u003e C[\"agent context block\"]\n  C --\u003e D[\"AGENTS.md / CLAUDE.md\"]\n  D --\u003e E[\"minimap check\"]\n```\n\n## Example Output\n\nMinimap writes only inside its managed block:\n\n```md\n\u003c!-- minimap:start --\u003e\n\n\u003crepo_context generated_by=\"minimap\" schema_version=\"1\"\u003e\n\n  \u003csummary\u003e\n    Laravel + Vue/Inertia + TypeScript project using Composer, Bun, Pest, Vite, and Tailwind CSS.\n  \u003c/summary\u003e\n\n  \u003cstack\u003e\n    \u003clanguage name=\"PHP\" confidence=\"high\" evidence=\"composer.json present\" /\u003e\n    \u003cframework name=\"Laravel\" confidence=\"high\" evidence=\"laravel/framework dependency detected\" /\u003e\n    \u003cframework name=\"Vue\" confidence=\"high\" evidence=\"vue dependency detected\" /\u003e\n    \u003ctool name=\"Vite\" confidence=\"high\" evidence=\"vite dependency detected\" /\u003e\n  \u003c/stack\u003e\n\n  \u003ccommands\u003e\n    \u003ccommand name=\"php_tests\" value=\"composer test\" confidence=\"medium\" category=\"test\" /\u003e\n    \u003ccommand name=\"frontend_build\" value=\"bun run build\" confidence=\"medium\" category=\"build\" /\u003e\n  \u003c/commands\u003e\n\u003c/repo_context\u003e\n\u003c!-- minimap:end --\u003e\n```\n\n## Installation\n\nMinimap is Bun-native.\n\nInstall automatically:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/forjd/minimap/main/install.sh | bash\n```\n\nRun with Bun:\n\n```bash\nbunx @forjd/minimap scan\n```\n\nOr install globally:\n\n```bash\nbun install -g @forjd/minimap\nminimap --help\n```\n\nPrefer shorthand?\n\n```bash\nbun i -g @forjd/minimap\n```\n\nStandalone binaries are also attached to GitHub releases for environments where installing Bun is inconvenient:\n\n```bash\ngh release download --repo forjd/minimap --pattern 'minimap-v*-linux-x64.tar.gz' --pattern SHA256SUMS\nsha256sum -c SHA256SUMS\ntar -xzf minimap-v*-linux-x64.tar.gz\n./minimap-linux-x64 --help\n```\n\nDownloads are available for macOS, Linux, and Windows from the latest GitHub release.\n\nThe installer can be made explicit for scripts:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/forjd/minimap/main/install.sh | INSTALL_METHOD=binary BIN_DIR=\"$HOME/.local/bin\" bash\n```\n\nFor local development:\n\n```bash\ngit clone https://github.com/forjd/minimap.git\ncd minimap\nbun install\nbun run src/cli.ts --help\n```\n\n## Agent Skill\n\nMinimap 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.\n\nInstall it with the `skills` CLI:\n\n```bash\nnpx skills add forjd/minimap --skill minimap\n```\n\nOr with Bun:\n\n```bash\nbunx skills add forjd/minimap --skill minimap\n```\n\nInstall it for all detected agents:\n\n```bash\nnpx skills add forjd/minimap --skill minimap --agent '*'\n```\n\n## Commands\n\n### Scan\n\nScan the current repository and print detected signals as JSON:\n\n```bash\nminimap scan\nminimap scan --pretty\nminimap scan --cwd ./some-project\n```\n\n`scan` is read-only. To preview generated context, use `generate` or `write --dry-run`.\n\n### Generate\n\nGenerate a managed context block without writing it:\n\n```bash\nminimap generate\nminimap generate --profile agents\nminimap generate --profile claude\n```\n\nThe `agents` and `claude` profiles currently produce the same output. The profile option exists so output can diverge later.\n\n### Write\n\nCreate or update a managed block in a target file:\n\n```bash\nminimap write --target AGENTS.md\nminimap write --target CLAUDE.md\n```\n\nPreview the resulting file without writing:\n\n```bash\nminimap write --target AGENTS.md --dry-run\n```\n\n### Check\n\nDetect context drift:\n\n```bash\nminimap check --target AGENTS.md\n```\n\n`check` exits:\n\n- `0` when the managed block matches the current repository scan.\n- `1` when the file is missing, the managed block is missing, multiple blocks are present, or the generated block has drifted.\n\n## Safe Writes\n\nMinimap uses stable markers:\n\n```md\n\u003c!-- minimap:start --\u003e\n\n...\n\n\u003c!-- minimap:end --\u003e\n```\n\nWrite behavior is conservative:\n\n- If the target file does not exist, Minimap creates it.\n- If the target exists without a managed block, Minimap appends the block.\n- If the target contains one managed block, Minimap replaces only that block.\n- If multiple managed blocks are found, Minimap refuses to write.\n- Human-authored content outside the managed block is preserved.\n\n## Safety Model\n\nMinimap is local-only and deterministic.\n\nIt does not:\n\n- call an LLM\n- run project scripts during scan or generation\n- evaluate JavaScript, TypeScript, PHP, or config files\n- recursively summarize source files\n- overwrite content outside the managed block\n- send repository data to external services\n\nIt does:\n\n- read targeted manifest and config files\n- classify commands as validation, development, formatting, or risk signals\n- mark destructive database, publishing, deployment, and volume deletion commands as risks\n- include confidence and evidence for inferred facts\n\n## Supported Signals\n\nMVP detection covers:\n\n- Node, JavaScript, and TypeScript via `package.json`\n- Bun, pnpm, Yarn, and npm via lockfiles\n- PHP and Composer via `composer.json`\n- Laravel via `laravel/framework` or `artisan` plus `bootstrap/app.php`\n- Vue, React, Next.js, Nuxt, Svelte, SvelteKit, Inertia, Vite, Tailwind CSS\n- Vitest, Jest, Playwright, Cypress, Pest, PHPUnit\n- ESLint, oxlint, Biome, Pint, PHPStan, Larastan\n- shallow GitHub Actions workflow presence and names\n- pnpm, npm, Yarn, and Bun workspace package manifests\n- Turborepo, Nx, and Lerna monorepo configuration files\n\n## Good For\n\n- Maintaining `AGENTS.md` or `CLAUDE.md`\n- Giving coding agents a fast repository orientation\n- Keeping context blocks current with `minimap check`\n- CI drift checks for agent instructions\n- Avoiding repeated manual repo summaries\n\n## Project Status\n\nMinimap is an MVP.\n\nCurrent limitations:\n\n- Bun is the supported runtime.\n- Node-compatible bundling is not a goal yet.\n- Monorepo support detects root workspace configuration and package manifests, but does not deeply scan each package yet.\n- Staleness checks compare the generated managed block exactly.\n- The scanner intentionally avoids deep source parsing.\n\n## Development\n\n```bash\nbun install\nbun run format:check\nbun run lint\nbun run typecheck\nbun test\n```\n\nFormat changed files:\n\n```bash\nbun run format\n```\n\nThe test suite uses fixture repositories and snapshots for generated output.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Releasing\n\nSee [RELEASING.md](RELEASING.md).\n\n## Security\n\nSee [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT, copyright Forjd.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforjd%2Fminimap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforjd%2Fminimap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforjd%2Fminimap/lists"}