Understand the map.
Use it deliberately.

Plan

Find the right place to start.

Give FixMap one task source: plain issue text, a task file, stdin, a public GitHub issue URL, or a git diff.

Public issue URL

Working-tree or branch diff

Remote repository mode is issue-only. Clone the repository locally when you need --diff, --base, or --head.

Explain

Ask the missing-file question.

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

• The file ranked, just lower than expected.
• It scored below the report cutoff.
• It was excluded intentionally, such as a generated file whose source ranked instead.
• The scanner never saw it, including when a scan limit was reached.

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 unless you add --include-untracked, so agent metadata does not rank beside real edits.

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.

Output

Readable by people and tools.

Markdown is the default handoff. Add --format json for structured output and --output <path> to save it.

MCP

Three tools for the agent workflow.

fixmap_plan creates the starting map and accepts a limit when context budget matters. fixmap_explain answers why a file is missing, for agents with no shell to run --explain in. fixmap_verify compares the report with the later diff, and takes it either inline or as a file path so a large plan need not be re-embedded in the call. All three run locally over stdio.

Doctor

Check you are running what you asked for.

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.

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.