Understand the map.
Use it deliberately.

Slash command

Open the complete FixMap menu.

fixmap setup installs project-level discovery for Claude Code, Cursor, GitHub Copilot, and Agent Skills. Invoking /fixmap with no task lists Plan, Context, Graph, Explain, Compare, Verify, Watch, Benchmark, Validate, Doctor, MCP, focus controls, working-tree mapping, and fresh scans.

The installer is idempotent and will not overwrite a customized command unless you explicitly pass --force.

Plan and Impact Graph

Find the right place to start—and what to inspect next.

Give FixMap one task source: plain issue text, a task file, stdin, a public GitHub issue URL, or a git diff. The primary context remains task-ranked. A separate Impact Graph maps imports, reverse dependents, routed tests, and files that repeatedly changed together in bounded Git history. Impact files are inspection candidates, not instructions to edit every path.

Public issue URL

Working-tree or branch diff

Remote repository mode is issue-only. Clone the repository locally when you need --diff, --base, --head, or complete local Git-history evidence. Shallow and unavailable history are reported explicitly while import and test relationships continue to work.

Context Pack

Package the relevant source ranges.

fixmap context uses the Plan and Impact Graph to select deterministic source ranges. The default 10,000-token budget is an estimate of one token per four UTF-8 bytes of source; metadata is not charged to that budget. It is reproducible, but it is not a model-specific tokenizer count.

Every snippet records its primary or impact role, reason, confidence, line range, estimated source tokens, and whether the scanner sampled only part of a large file. Files omitted for budget or availability remain listed instead of disappearing silently.

Graph export

Carry the evidence into a review.

fixmap graph exports imports, reverse dependents, routed tests, and co-change relationships as Mermaid or versioned JSON. Direction is preserved, and only relationships already supported by the Impact Graph are emitted.

Explain

Ask the missing-file question.

Use --explain when you expected a path and it did not appear. The response distinguishes five different situations:

• The file ranked, just lower than expected.
• It scored below the report cutoff.
• It tied for a reported place but fell outside --limit.
• It was excluded intentionally, such as a generated file whose source ranked instead.
• The scanner never saw it, including a scan limit, a sparse checkout, or an unsupported extension.

Focus

Narrow the map to what matters.

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.

Map what you are editing now

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.

Measure a better task

Refine the wording, re-plan, and see whether the real file moved up:

Verify

Compare the plan with the change.

Save a JSON plan before editing, then compare it with the real diff afterwards. Verify recalculates impact around the files that actually changed and reports strong relationships outside the original plan as advisory inspection notes.

Watch

Keep the map beside the edit.

fixmap watch fingerprints a local Git working tree and emits a fresh verification only when its state changes. Each update recalculates impact around the real edits, so an agent can see unmapped files, missing tests, new risks, and related inspection candidates while it works.

JSON output is newline-delimited for streaming consumers. Use --once for a bounded automation check. Watch reads Git and source text, but never runs repository code or tests.

Repository benchmark

Measure FixMap where you work.

fixmap benchmark selects recent bounded non-merge commits, checks out each parent in an isolated temporary worktree, derives task text only from the commit metadata, and scores changed maintained source paths rather than generated twins. BM25-over-code, FixMap, and Impact Graph see the identical pre-change scanned corpus.

Results split all, path-mentioned, and unmentioned cohorts and include raw cases and Wilson intervals. Commits that are too large, have no usable task text, or contain no pre-existing target source are skipped with counts. FixMap never runs repository code during this process.

Output

Readable by people, agents, and tools.

Markdown is the default handoff. Add --format agent for a compact EDIT CANDIDATE / INSPECT / TEST / RISK / AVOID / UNCERTAINTY handoff, or --format json for structured output. Use --output <path> to save it. The current issue, comparison, verification, and output files are kept out of ranking, change detection, and cache state, so a saved FixMap report cannot recommend itself.

New JSON plans include reportVersion: 1. Within a report version, fields may be added but existing fields will not be removed or change type; consumers should ignore unknown fields. A breaking output change requires a new report version. Compare and Verify still accept legacy plans without a marker, while rejecting marker values they do not understand.

Validate

Check a saved report directly.

The CLI exposes the same additive structural validator used by Compare, Verify, the GitHub Action, and MCP. It accepts legacy unmarked reports, accepts version 1 with additive fields, and rejects unsupported report versions or malformed context entries.

MCP

Seven tools for the agent workflow.

fixmap_plan maps tasks and working trees. fixmap_context packages source ranges. fixmap_graph exports relationships. 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 seven run locally over stdio.

Doctor

Check what actually started.

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

What FixMap will not do.

• It does not install dependencies.
• It does not run package scripts, builds, tests, or git hooks.
• It does not upload local repository source.
• It does not call a hosted model.
• It does not claim the ranking proves a change is correct.