Minimap is a local workbench for one developer working with AI agents on markdown files. It provides two views:
- Roadmap — browse and edit a file-based roadmap, including features being worked on in separate Git worktrees.
- Spec sessions — review a markdown file with anchored comments, replies, and proposed edits that you preview before applying.
Your files remain the source of truth. One local server serves both modes across repositories. There is no hosted service or shared team account; review discussions are stored locally outside the target repository.
Part of the Rore collection: local tools for developers working with coding agents.
Get started · Roadmap · Spec sessions · Agent guide · Development
You need Node.js available on your path; this repository's CI uses Node.js 22. Git is needed for worktree discovery. Each mode ships as a self-contained skill folder with instructions, runtime, and scripts. Using an installed skill requires no npm install or system service.
Clone this repository and copy either or both folders into your agent client's skill directory. For example, for a personal Claude Code installation, run these commands from the cloned repository:
mkdir -p ~/.claude/skills
cp -R package/minimap/skills/minimap-roadmap ~/.claude/skills/
cp -R package/minimap/skills/minimap-spec-review ~/.claude/skills/PowerShell equivalent:
New-Item -ItemType Directory -Force "$HOME/.claude/skills" | Out-Null
Copy-Item -Recurse package/minimap/skills/minimap-roadmap "$HOME/.claude/skills/"
Copy-Item -Recurse package/minimap/skills/minimap-spec-review "$HOME/.claude/skills/"For a project-scoped Claude Code installation, use <your-repo>/.claude/skills/ instead. For another agent client, use its supported skill location or point its instructions at the relevant SKILL.md. Follow your client's procedure for discovering newly installed skills.
Spec sessions works with any markdown file. Roadmap uses the file convention below. Add a pointer to the installed skills in your repository's agent instructions; AGENTS_SNIPPET.md provides an example whose paths you can adapt.
On Windows and Linux, you can optionally install one background service for your user account. It serves both modes across repositories and starts after login, independently of your agent application. Windows uses Task Scheduler; Linux requires a working user systemd manager. No administrator privileges or Linux lingering are needed.
To migrate an existing standalone server, use a current skill copy and obtain explicit approval for the service installation:
- Explicitly set
MINIMAP_HOMEto the existing data directory for every command. Defaults are%LOCALAPPDATA%\minimapon Windows (%USERPROFILE%\AppData\Local\minimapifLOCALAPPDATAis absent) and~/.minimapon Linux. Keep the same user account and back up that home, including review records and settings, while clients are idle. - Run
node <path-to-skill>/scripts/status.mjs, inspect the live PID/source, and coordinate with other views before runningnode <path-to-skill>/scripts/stop-server.mjs. If ownership cannot be verified, stop and investigate. - Set
PORTto the intended existing port (default 4312), then runnode <path-to-skill>/scripts/service.mjs install. - Run
node <path-to-skill>/scripts/status.mjsand verify its live source is under the chosen home, its port is unchanged, and participant settings are preserved. Open the printed URL. If the port is occupied, installation fails; investigate the conflict without killing another process or deleting the registry by hand.
This is an explicit installation step, not something an agent should run merely to open a board. It copies the runtime to a stable location under the Minimap home; later changes to a repository checkout do not change that copy. Your project Roadmap skill and personal Spec Review skill keep their existing scopes and connect to the same service. The ordinary start, stop, restart and status scripts then manage that installation.
To update, run node <new-skill>/scripts/service.mjs update from the new skill copy. Copying a skill refreshes that folder; restarting a managed service uses its existing installed runtime. Older skill copies may reuse a compatible healthy service, but must be refreshed before managing it. service.mjs rollback restores the previous runtime. Both update and rollback preserve whether the service was running or stopped. service.mjs uninstall removes service registration and its runtime, retaining review records and settings. These operations affect all views using that server; see the service lifecycle guide before changing an installation.
Without this optional installation, the existing standalone launch still works.
Ask your agent:
“Show me the roadmap for this repo.”
“Open a spec session on
docs/architecture.md.”“Show the roadmap across this repo's worktrees.”
The agent starts or reuses the local server and gives you a browser URL. You can also start it yourself using either installed skill:
node <path-to-skill>/scripts/start-server.cjsUse the port printed by the launcher; the default is 4312. Roadmap URLs identify the repository explicitly:
http://localhost:4312/#repo=/absolute/path/to/repo&view=board
Use forward slashes for Windows paths and URL-encode the path when necessary. Spec sessions require an attach step; the spec-review skill provides the command and URL format. Switching repositories does not require restarting the server.
The board reads markdown files in your repository. List and Columns show the same items; grouping can follow the board or metadata such as milestone or lane. Editing an item or dragging it in an editable checkout writes back to those files. Agents edit the same files directly.
Unfinished narrows the board to unfinished statuses. In play includes items with status active, in-progress, or blocked, or confirmed attached, nonclosed agent sessions—including dormant sessions. It combines with the other filters, so those can still hide matching items. When participant information is unavailable, known active, in-progress, and blocked items remain visible with an incomplete-results notice.
Columns can be collapsed to give other groups more room:
Each item opens in Read mode. Edit provides a form; Raw edits the markdown. Unknown metadata and extra sections are preserved. Review opens the item as a spec session, and a comment badge indicates open discussion.
The collapsed Linked tasks section in Read mode finds local Agent Workflow Work Records that explicitly cite that exact feature. Open a record to read it, or follow its recorded PR links. The record's state and PR URLs are historical references, not live execution or PR status. Results refresh independently of the board and editor, including on manual Refresh. Same-scope refresh keeps surviving disclosures, focus and reading position, including when a lookup fails. Across worktrees combines task records from every loaded proven feature checkout. Each task has one heading; expand its compact worktree rows to inspect branch, saved state, differing titles and PR links or open the exact source record. A changed record still requires Refresh rather than silently opening different content. A count with + is a lower bound while pages or source checks remain incomplete. Missing, unverified, invalid, or unreadable relationships yield partial or unavailable coverage rather than a confirmed zero. Discovery is bounded to 1,000 records per checkout and the list shows 20 at a time; the roadmap contract gives the exact limits.
Agents working in separate worktrees may update different copies of the roadmap. Use the picker beside the repository name to switch between This checkout and Across worktrees.
Across combines local checkout versions into one read-only board. It uses Git ancestry to identify shared features and flags differences between versions; these differences do not necessarily mean Git has a merge conflict. Open an item and choose a checkout version to inspect or edit it. Save changes only that checkout and rejects stale files or changed checkout identities. Minimap does not merge or synchronize roadmap files, and board reordering is disabled in the combined view.
The opened checkout appears first while other worktrees load. Feature totals and In play results remain provisional until full feature identity is resolved. In both board modes, session badges refresh independently of roadmap loading. Automatic reads reuse a validated snapshot for up to 30 seconds; while the board is visible, an expired snapshot is validated again. Refresh always requests fresh validation and keeps the board and drafts usable. Hidden or superseded refreshes are cancelled. Returning to the board reuses a current snapshot; returning after an interrupted read or tracked Spec change validates it again. Failed refreshes retain the last usable view and badges with a stale or unavailable notice and a Refresh retry.
Only local linked Git worktrees are included, not separate clones or remote branches.
The combined view selects up to 25 checkouts: the opened checkout, then the 24 most recent eligible siblings. Recency uses the latest recorded local HEAD Git event (such as checkout, commit, reset, or rebase); plain uncommitted edits do not affect it. Missing activity timestamps sort last, with path order breaking ties. Stale or missing checkouts do not consume slots. Selection updates on fresh validation; cached reads retain their existing selection.
Partial coverage means some sources were excluded—for example, because of that limit or an unreadable roadmap. Expand the board summary for the reasons. Counts describe loaded sources; each proven feature appears once, and differing placements remain in its checkout-version details.
The default layout is:
roadmap/
board.md # groups and shared item order
scope.md # current focus
features/ # one markdown file per feature
ideas/ # one markdown file per idea
Item metadata holds status, priority, lane, milestone, and similar classifications. board.md holds the shared manual order; use a neutral # Items group when you want metadata-based grouping with unrestricted shared ordering. Git records file history.
Within metadata groups, List and Columns show displayed Done cards last in both This and Across views. Relative order stays unchanged within the non-Done and Done buckets; group headings and manual Board order do not move. Mixed/unknown current statuses are not Done. This is view-only, with no sorting setting or file rewrite; other finished labels retain their existing semantics. Explicit ordering still updates canonical order, but does not move a card across the derived display's Done boundary.
Across ignores an older status only when Git proves its clean feature-file revision was superseded by a newer clean revision. A genuine reopening wins over older Done; conflicting, dirty or uncertain evidence stays visible. Status filters, status grouping, In play's status criterion and Done ordering use that resolved status. Historical text/metadata search, title/content selection and other groupings stay unchanged, and every checkout version remains selectable with its own saved status. The version picker labels historical status; This worktree always shows its own file. There is no main-branch preference or automatic synchronization.
An optional roadmap.config.json at the repository root changes the location and available views:
{
"roadmapPath": "docs/roadmap",
"defaultLens": "lane",
"filters": {
"fields": ["owner", "team"]
},
"appearance": {
"cardFields": ["status", "priority", "repo"],
"colorTags": true,
"tagColors": {
"repo": {"sample-core": "blue", "sample-app": "purple"}
},
"cardColorBy": "repo"
},
"lenses": {
"fields": {
"lane": { "order": ["Product", "Platform", "Operations"], "draggable": true },
"milestone": { "order": ["M1", "M2", "Later"] }
}
}
}Here, a lens means a grouping. defaultLens sets the initial grouping independently of List/Columns layout; an explicit URL grouping takes precedence. filters.fields adds project-specific metadata filters.
Optional appearance configures card badges, Read-view tags and colors for the opened board in both This and Across views and both layouts. Cards omit an enabled field when the current metadata grouping already expresses it: grouping by Repo hides Repo, and grouping by Milestone hides Milestone. The remaining badges keep their configured order; Board grouping hides none. Read keeps all enabled tags regardless of grouping, with primary status separate; Edit and Raw retain every field. In the example, commitment and milestone are omitted from cardFields, so neither is injected into cards or the Read tag row. Add milestone to enable it with an explicit list. Grouping never changes cardColorBy, even when its badge is hidden.
| Setting | Effect |
|---|---|
cardFields |
Ordered card badges and Read tags; [] hides those rows' metadata, not Read's primary status. Omission restores defaults. |
tagColors |
Map exact field/value pairs to named colors: gray, blue, green, amber, red, purple, teal. |
colorTags |
Defaults to true; false disables custom badge/detail colors, not semantic status/commitment tones. |
cardColorBy |
Colors only the left border using tagColors; missing mappings use neutral. Independent of colorTags. |
Omit cardColorBy for tag colors only; set colorTags: false with cardColorBy for border only; keep the default colorTags: true with cardColorBy for both. Remove appearance and Refresh to restore defaults. This is file configuration only—there is no settings UI or separate persistence. See the roadmap contract for field rules, validation, and fallbacks, and the roadmap skill for setup and updates.
With Pallium configured, roadmap items show Recent and Dormant attached sessions. “Recent” refers to the session's last-seen time within Pallium's 24-hour window, not proof that an agent is working on this feature now. The item panel separates lifecycle groups and shows last-seen information. Missing or partial results are not shown as zero participants.
Lookup is read-only and bounded to 200 features per request. Completed items normally omit board badges; In play can include them when the other filters allow it. Their sessions remain accessible in the item panel. Board and detail observations may differ because they refresh at different times.
To enable lookup, supply MINIMAP_PALLIUM_ENDPOINT as an explicit local HTTP origin when starting or restarting the server. Exact-session links require a separate compatible MINIMAP_PALLIUM_DASHBOARD_ENDPOINT. Successful lifecycle commands remember these settings. Without configuration, Minimap makes no Pallium requests.
Minimap does not detach sessions or manage assignments. Supported links lead to Pallium's controls; associations do not guarantee a complete historical participation record. See participant integration for compatibility, configuration, and agent work references.
A spec session attaches to one markdown file in any repository. You and your agents can leave whole-document, section, or quote comments, reply in threads, and propose edits. Suggestions display a diff before application; discussion alone does not modify the file.
Anchors track text across edits. If a target becomes ambiguous or cannot be found, Minimap surfaces that state instead of silently attaching feedback elsewhere. Each entry records an actor label such as human, claude, or codex; this is attribution, not authentication.
A typical review:
- Ask one agent to review the file and leave anchored comments or suggestions.
- Ask another agent to review those findings and reply in the same threads.
- Read the discussion, resolve settled threads, and apply the suggestions you approve.
Comments and suggestions live outside the repository in the local Minimap home: ~/.minimap on macOS/Linux or %LOCALAPPDATA%/minimap on Windows, unless MINIMAP_HOME overrides it. They are not distributed by committing the target file. The spec-review skill documents attach, comment, preview, and apply commands.
Start with the skill matching the task; its references contain the detailed CLI and API contracts.
| Task | Entry point |
|---|---|
| Show, create, or update a roadmap; pick up, resume, investigate, test, or complete assigned roadmap work | minimap-roadmap/SKILL.md |
| Review or comment on a markdown file | minimap-spec-review/SKILL.md |
| Add repository instructions | AGENTS_SNIPPET.md |
| Understand roadmap file ownership | CONTRACT.md |
For roadmap work, resolve roadmap.config.json first, edit the assigned checkout's canonical files, preserve unknown metadata, and reconcile the owning feature when work completes. The combined board does not authorize copying changes between worktrees or create a second roadmap tracker.
For spec review, read the target file and existing discussion before adding feedback. Use the documented CLI or API; preview suggestions and obtain explicit user approval before applying them. This is workflow policy, not an enforced permission check. CLI mutations require an explicit --by actor label.
Both skills expose these scripts under scripts/. Use them for lifecycle operations instead of launching server.js directly, sending process signals, or editing the registry.
| Script | Purpose |
|---|---|
start-server.cjs |
Start or reuse a compatible running server. |
status.mjs |
Report live identity, participant settings, and lifecycle diagnostics; exits 0 running, 1 stale, 3 not running. |
stop-server.mjs |
Gracefully stop the server or clean a stale registry. |
restart-server.mjs [--replace-runtime] |
Restart; replacing a different or unknown runtime requires explicit opt-in. |
Packaged start and restart default the new server's filesystem worker pool to 8 (UV_THREADPOOL_SIZE) only when unset. Explicit overrides remain authoritative. The legacy start-server.mjs and direct development entrypoints retain Node's caller-configured/default pool; a reused server is unchanged. See the lifecycle reference for preloads and startup details.
The server is shared across repositories and both modes. Coordinate before replacing it: replacement interrupts all clients and can downgrade the running version. Updating an installed skill's files does not restart the server. For an installed service, use service.mjs update or rollback; --replace-runtime cannot bypass service ownership. See server lifecycle for compatibility, configuration, and diagnostics.
The server binds to 127.0.0.1. Requests must use loopback addresses and a loopback Host; browser Origin must match the request origin. Minimap has no user authentication or remote team access. Actor labels and participant associations do not grant permissions.
From a cloned repository:
npm ci
npx playwright install chromium
npm test
npm run test:uiRead AGENTS.md before changing the implementation. package/minimap/ is the source of truth; each skill's runtime/ is generated. After changing server, CLI, UI, or runtime code, run:
node scripts/sync-mirrors.mjsDo not edit the runtime mirrors by hand. Update affected skill documentation alongside behavior changes; mirror synchronization does not update prose. Contributors can link installed skill folders to this checkout instead of copying them. See the package README for the package layout.



