Plan
Give FixMap one task source: plain issue text, a task file, stdin, a public GitHub issue URL, or a git diff.
Remote repository mode is issue-only. Clone the repository locally when you need --diff, --base, or --head.
Explain
Use --explain when you expected a path and it did not appear. The response distinguishes five different situations:
--limit.Explain
Use --explain when you expected a path and it did not appear. The response distinguishes five different situations:
--limit.Focus
Demo pages, marketing copy, and documentation often contain every symptom word a product documents, so they compete with the implementation. FixMap knows about conventions like examples/; it cannot know your repository’s own layout.
Patterns can also live in a .fixmapignore file at the repository root, one per line. The two combine, and --explain reports an excluded file as excluded, naming the pattern that matched.
That means staged and unstaged tracked changes against HEAD. Untracked files stay out of the change set unless you add --include-untracked, so scratch metadata is not reported as an edit. They remain ranking candidates either way — a file an agent just wrote is usually the most relevant thing in the repository.
Refine the wording, re-plan, and see whether the real file moved up:
Focus
Demo pages, marketing copy, and documentation often contain every symptom word a product documents, so they compete with the implementation. FixMap knows about conventions like examples/; it cannot know your repository’s own layout.
Patterns can also live in a .fixmapignore file at the repository root, one per line. The two combine, and --explain reports an excluded file as excluded, naming the pattern that matched.
That means staged and unstaged tracked changes against HEAD. Untracked files stay out of the change set unless you add --include-untracked, so scratch metadata is not reported as an edit. They remain ranking candidates either way — a file an agent just wrote is usually the most relevant thing in the repository.
Refine the wording, re-plan, and see whether the real file moved up:
Verify
Save a JSON plan before editing, then compare it with the real diff afterwards.
Verify does not run tests or judge correctness. Most findings are advisory because the plan can be wrong and the change can still be right.
Verify
Save a JSON plan before editing, then compare it with the real diff afterwards.
Verify does not run tests or judge correctness. Most findings are advisory because the plan can be wrong and the change can still be right.
Output
Markdown is the default handoff. Add --format json for structured output and --output <path> to save it.
Ranked paths, scores, confidence labels, and evidence.
Workspace-aware commands and reachable related tests.
Sensitive areas inferred from paths, symbols, and changes.
Vague tasks, unresolved identifiers, scan limits, and other uncertainty.
MCP
fixmap_plan maps tasks and working trees. fixmap_explain answers why a file is missing. fixmap_compare measures task refinement. fixmap_verify checks the later diff, and fixmap_doctor diagnoses install shadows. All five run locally over stdio.
Doctor
An older global install can shadow the version npm was asked for, so a feature that shipped appears not to exist. doctor reports the running version, the resolved path, any conflicting global, and the Node version.
It exits non-zero when it finds a shadow, so a CI step fails rather than reading on.
Doctor
doctor reports the running version, resolved path, conflicting global, and Node version. Version 0.8.4 and newer also checks an exact npm-requested version when that newer Doctor starts.
An older project-local binary can win before newer Doctor code runs, so always check the printed running version. Use the isolated-prefix/direct-shim procedure in the README when the exact version matters.
Safety and trust
Get started
Use one command yourself, let a compatible coding agent request the map, or publish it automatically on pull requests.
+Install the CLI once and use a short command, let a compatible coding agent request the map, or publish it automatically on pull requests.
CLI
CLI
The fastest path. Paste a public GitHub issue URL and FixMap fetches the task, infers the repository, scans a temporary checkout, and removes it when the report is done.
+Install FixMap globally, then paste a public GitHub issue URL. FixMap fetches the task, infers the repository, scans a temporary checkout, and removes it when the report is done.
+Every command above uses npx, which fetches FixMap for that run and leaves nothing behind. That is the right default for trying it. Once it is part of your routine, install it and drop the npx -y prefix:
Or pin it to one project, so everyone working on that repository gets the same version:
+Use a project dependency when everyone working on that repository should get the same version:
A project install is reached with npx fixmap inside the repository, or from an npm script.
If the current directory or one of its parents already contains FixMap, npm may deliberately choose that project-local binary. Check --version, or use the isolated-prefix test below when the exact package version matters.
Create the directory before changing into it. If cd fails, PowerShell stays in the previous directory and a project-scoped npm install will go there instead.
An older global install can shadow the version npx was asked for, which makes a feature that shipped look like it never existed. doctor reports the version in use, where it resolved from, and any conflicting global — and exits non-zero when it finds one:
Doctor 0.8.4 and newer compares an exact npm-requested version when that newer Doctor is the process npm starts. An older project-local binary can win before the newer code starts, so treat the printed running version as authoritative. For an exact clean test, use the isolated-prefix/direct-shim procedure in the repository README.
Requires Node.js 20.11 or newer. No account, API key, or model call at any point.
FixMap exposes five local stdio tools: fixmap_plan before editing, fixmap_explain when a file is missing, fixmap_compare to measure a refined plan, fixmap_verify after the diff exists, and fixmap_doctor to diagnose install shadows.
{`{
"mcpServers": {
"fixmap": {
- "command": "npx",
- "args": ["-y", "@aryam/fixmap@latest", "mcp"]
+ "command": "fixmap",
+ "args": ["mcp"]
}
}
}`}Thirty-second start
One command. No account. No API key.
+Install once. Then use one short command. No account or API key.