Fixmap

FixMap

Tell AI coding tools which files to check first.

Describe what is broken. FixMap checks the project and gives tools like Codex, Claude Code, and Cursor a short list of files to open, tests to run, and other code to review. It includes reasons and says when it is unsure—without an account, API key, or model call.

Website · Use cases · Live demo · Documentation · Evidence · Changelog

Watch the 31-second FixMap workflow video with sound

Try a task in the homepage sample. It runs the real FixMap Plan engine in the tab against the bundled sample-api project. It does not inspect your repository or upload the task text. Use Get started for your own repository, or open the full browser demo for advanced workflows.

Install

Requires Node.js 20.11 or newer.

npm install --global @aryam/fixmap@latest

fixmap plan --issue https://github.com/chalk/chalk/issues/624

For a one-off trial:

npx -y @aryam/fixmap@latest plan --issue https://github.com/chalk/chalk/issues/624

Install a discoverable /fixmap command for Claude Code, Cursor, GitHub Copilot, and Agent Skills:

fixmap setup

Type /fixmap with no task to see the full feature menu, or run fixmap features in a terminal. Use fixmap setup --agent to install one integration, and --force only after reviewing an existing customized command.

FixMap fetches a public task, infers its repository, scans a temporary isolated checkout, and removes it when the report is complete. Local repository analysis never uploads source.

Everyday workflow

Save a plan before editing:

fixmap plan --issue "password reset emails fail" --format json --output plan.json

The plan separates primary context from likely impact: imports, reverse dependents, routed tests, and repeated Git co-change relationships. Impact files are places to inspect, not assumed edits.

Measure BM25, FixMap, and Impact Graph on your own repository's history:

fixmap benchmark --repo . --last 50

Keep the saved plan beside an agent while it edits. Watch emits a new verification only when the working tree changes and recalculates impact around the actual diff:

fixmap watch --report plan.json --repo . --include-untracked

Give an agent the relevant source ranges instead of only file names. Context draws from primary and impact files and stays within an estimated source-token budget:

fixmap context --issue "password reset emails fail" --budget 10000

Export the evidence graph for a pull request, issue, or design note:

fixmap graph --issue "password reset emails fail" --format mermaid

Use compact headings in an agent context window:

fixmap plan --issue "password reset emails fail" --format agent

Ask why an expected path is missing:

fixmap plan --issue "password reset emails fail" --explain src/auth/token.ts

Refine the task and compare the ranking:

fixmap plan --issue "sendMail throws during password reset" --compare plan.json

Verify the completed diff against the saved plan:

fixmap verify --report plan.json --diff main...HEAD

Validate a saved report before another tool consumes it:

fixmap validate plan.json

Use --working-tree for staged and unstaged tracked edits, --include-untracked when new files should count as changes, --exclude or .fixmapignore to focus the map, and --no-cache to force a fresh scan. Add --fail-on warning to Verify when advisory findings must fail CI. Run fixmap --help for the complete command reference.

Complete feature catalog

Inputs and repository mapping

• Accepts a public GitHub issue or pull-request URL, plain task text, a UTF-8 or UTF-16 --issue-file (including common BOM-less Windows UTF-16 files), or task text from stdin.
• Normalizes supported browser and GitHub API issue URLs, including www, query strings, and fragments, while rejecting credentials, lookalike hosts, ports, and unsafe encoded paths.
• Scans the current checkout, another local path, a file:// URL, or an isolated checkout of a public GitHub repository.
• Maps --diff , --base/--head, or the current --working-tree; untracked changes remain opt-in with --include-untracked.
• Reuses raw repository scans only when the repository root, commit, status, and binary diff are identical. Task text, --limit, and exclusion rules are applied after that scan, so changing them can safely reuse the same cached files while still producing a newly ranked and filtered report; Compare scans the current plan, while Verify validates its supplied report against a fresh or exact-state repository map. cache-hit reports reuse and scan age, entries expire after seven days, and FIXMAP_CACHE_DIR moves the OS cache. Force a fresh scan with CLI --no-cache, MCP noCache: true, or Action no-cache: true.
• Keeps the current --issue-file, --compare, --report, and --output artifacts out of repository ranking, change detection, and cache invalidation, so FixMap never recommends its own report as the fix site.
• Detects npm, pnpm, Yarn, and Bun projects and reads the scripts declared by each workspace package. When the root is silent it can infer an agreed nested lockfile, while conflicting root declarations produce a diagnostic instead of silently choosing.

Plan and ranking

• Ranks source, test, configuration, documentation, and other files from path terms, source content, identifiers, quoted fragments (including smart quotes and guillemets), file mentions, and real diff content.
• Recognizes JavaScript/TypeScript declaration tests, Go _test.go, Python test_*.py and *_test.py, common test directories, and framework single-file components.
• Deprioritizes lockfiles, sync-client backups, bundled output, examples, and generated counterparts when maintained source exists, while keeping ordinary modules such as deep-copy.ts and tracked first-party vendor/ source rankable.
• Routes reachable test commands from real package scripts and pairs them with the nearest related test files. It warns when routed JavaScript, Python, Go, or Rust tests are skipped, ignored, conditional, or gated.
• Reports six bounded risk areas: authentication, billing, automation, data, public API, and dependencies.
• Explains task grounding, ranking shape, unresolved or partially matched identifiers, exclusions, scan limits, unread content, skipped submodules, empty diffs, and Git failures.
• Supports a strict decimal --limit, repeatable --exclude, and ordered .fixmapignore patterns with negation. Root-leading patterns are repository-relative, pasted absolute paths inside the repository are normalized, and patterns that match nothing produce a warning. Limits change only how many rows are shown, never confidence or ranking-shape analysis.

Impact Graph and repository benchmark

• Builds a separate likely-impact view from direct imports, reverse dependents, routed tests, and Git files that repeatedly changed with a primary ranked file.
• Reads at most 1,000 non-merge commits, excludes commits touching more than 30 files, requires at least two co-occurrences, and marks shallow or unavailable history instead of inventing evidence.
• Recalculates impact around files actually changed during Verify and identifies high-evidence dependents outside the original plan as inspection notes, never mandatory edits.
• fixmap benchmark --repo . --last 50 evaluates BM25-over-code, ordinary FixMap context, and Impact Graph against historical parent snapshots. Every case's history stops before its target change, all arms see one scanned corpus, generated twins are not scored as primary answers, and mentioned/unmentioned tasks are reported separately.
• fixmap watch --report plan.json --repo . monitors a local working tree, re-runs Verify, and recalculates impact only when edits change. It never executes repository code; --format json produces one JSON object per update.
• Benchmark Markdown and versioned JSON include Wilson intervals, excluded-case counts, secondary-file recall, safeguards, and raw per-case outcomes. Historical commit messages are a repository-specific backtest, never proof of agent savings.

Context packs and graph export

• fixmap context selects deterministic line ranges from primary and impact files, labels each snippet as primary or impact, and records its reason, confidence, line range, estimated token cost, source truncation, and omitted-file reason.
• The budget counts source using the stable estimate ceil(UTF-8 bytes / 4); metadata is excluded. This is a reproducible planning estimate, not a tokenizer-specific exact count.
• Context may use FixMap's bounded scanner sample rather than an entire large file. sourceTruncated makes that boundary explicit in JSON and Markdown.
• fixmap graph exports the same Impact Graph as Mermaid or versioned JSON, preserving imports, imported-by, test-route, and co-change direction and evidence.

Exclusion pattern syntax

--exclude and .fixmapignore use repository-relative gitignore-style patterns. /docs/** anchors at the repository root, docs/** matches the same root directory and nested occurrences, !docs/keep.md re-includes a path after an earlier exclusion, and trailing / targets a directory. *, ?, and ** are supported; brace groups such as {src,test} are literal text, not alternation. Pass repeated --exclude flags or put one pattern per .fixmapignore line so commas in literal names stay unambiguous.

• Produces Markdown for people, versioned JSON for tools, or --format agent for compact EDIT CANDIDATE/INSPECT/TEST/RISK/AVOID/UNCERTAINTY sections; writes any format with --output.

Explain, Compare, Verify, Validate, and Doctor

• Explain tells you whether a path ranked, fell below the cutoff, was excluded, resolves through a submodule, or was never scanned—and uses the same task and diff evidence as Plan.
• Compare shows files that entered, left, moved, or changed confidence after the task was refined, plus changes in task grounding.
• Verify compares a saved JSON plan with a diff or working tree, recalculates impact, and flags generated edits, unmapped changes, an untouched leading file, source changes without tests, newly reached risk areas, and plan/repository mismatches. It fails on errors by default; --fail-on warning and the Action's fail-on: warning turn advisory findings into an opt-in CI gate.
• Validate checks any saved JSON report with the structural co