Why FixMap?
Coding agents are fast once they have the right context. The expensive mistakes happen earlier:
- reading a plausible file instead of the owning module
- missing the test that would catch the regression
- treating an unresolved git diff as “no changes”
- leaving reviewers to guess what was actually verified
FixMap is a transparent routing layer for that gap. It works locally, needs no account or API key, and does not send repository source to a third-party service.
Quick start
Run from a JavaScript or TypeScript repository:
npx @aryam/fixmap plan --issue "password reset emails fail"
Use a real branch diff:
npx @aryam/fixmap plan --diff main...HEAD
Machine-readable output:
npx @aryam/fixmap plan --base main --head HEAD --format json --output fixmap-report.json
Example result:
## Context Files
- src/auth/reset-password.ts (high confidence): path and content match
- src/email/send-reset.ts (medium confidence): content match
## Test Route
- npm --prefix apps/api run test
## Risk Map
- high authentication: authentication-related files are affected
MCP server
FixMap ships as a Model Context Protocol server, so coding agents can request a plan themselves instead of you pasting reports around. One tool is exposed: fixmap_plan.
Claude Code:
claude mcp add fixmap -- npx -y @aryam/fixmap mcp
Cursor, Windsurf, or any MCP client:
{
"mcpServers": {
"fixmap": {
"command": "npx",
"args": ["-y", "@aryam/fixmap", "mcp"]
}
}
}
The agent calls fixmap_plan with an issue description or a diff spec (main...HEAD) and receives the same report as the CLI: context files with confidence and reasons, test routes, risk notes, and diagnostics. Everything runs locally over stdio; no repository content leaves the machine.
Interactive demo
The live website includes a browser-only sample repository: change the task and watch the context pack update. It is deliberately labeled as a sample; the CLI scans real local repositories.
Run the site locally:
npm ci
npm run dev -w @fixmap/web
GitHub Action
Add FixMap to pull requests with a versioned release:
name: FixMap
on:
pull_request:
permissions:
contents: read
issues: write
pull-requests: write
jobs:
fixmap:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- id: fixmap
uses: aryamthecodebreaker/FixMap/packages/action@v0.4.0
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
Pin the Action to the latest release tag; a floating v1 major tag is planned after wider acceptance testing. The Action upserts one marked PR comment, writes Markdown to the step summary, and exposes report, context-count, and test-route-count outputs.
Permissions and forked pull requests
The workflow above grants pull-requests: write so FixMap can upsert its comment. On pull requests from forks, GitHub hands the workflow a read-only GITHUB_TOKEN regardless of that permissions block. FixMap detects the rejected comment call, emits a warning instead of failing, and keeps the job green — the full report is still in the step summary and the report output.
Do not switch the trigger to pull_request_target and check out the fork's head to restore commenting: that pattern runs untrusted pull-request code with a write-scoped token and is a well-known secret-exfiltration vector. If comments on fork PRs matter, keep this workflow read-only and post the comment from a separate trusted workflow_run job — or simply rely on the step summary.
What it uses
The ranker is deterministic and inspectable:
- task and identifier overlap in paths and file samples
- real changed files from a resolved git diff, including untracked files in working-tree diffs
.gitignore-aware scanning, so generated output does not outrank source- static JavaScript/TypeScript import-graph proximity to high-confidence files
- code, test, documentation, and configuration classification
- nearby paths and workspace package boundaries
- npm, pnpm, Yarn, and Bun script routing
- explicit confidence and diagnostic messages
It intentionally does not claim correctness, execute suggested commands, or hide failed diff resolution.
Evaluation
Ranking changes must pass a checked-in task-to-file evaluation gate in addition to unit tests:
The current suite covers Action failures, invalid diffs, authentication, the web demo, workspace test routing, and contributor documentation. The cases and full ranked results are visible in benchmarks/.
A separate cross-repository evaluation runs FixMap against six real, already-fixed issues in permissively licensed repositories (Express, Axios, debug, ky, Zod, Pino) pinned to exact commits, and reports honest top-1/3/5 hit rates — currently 33% / 67% / 67%. The dataset, methodology, and results live in benchmarks/external/; a scheduled workflow reruns it weekly.
Repository layout
packages/core scanner, ranking, routing, reports
packages/cli npx/CLI entry point and MCP server
packages/action bundled GitHub Action
apps/web interactive Next.js product site
benchmarks transparent ranking evaluation cases
examples inspectable sample input and output
Development
Requires Node.js 20.11 or newer.
npm run ci runs the complete test suite, typechecking, ESLint, production builds, Action bundle drift verification, CLI/Action smoke checks, the ranking evaluation gate, and a deterministic scanner correctness check. Scanner performance at large repository sizes is measured by npm run benchmark:scan and published in docs/BENCHMARKS.md — timing is never a CI assertion.
Status and roadmap
FixMap is an early public release focused on JavaScript and TypeScript repositories. The changelog records what each released version shipped, most recently the MCP server mode and scanner/ranking fixes in v0.3.x. Near-term work:
- git co-change and ownership signals
- adapters and examples for popular monorepo layouts
- growing the cross-repository evaluation dataset beyond six cases
- stable
v1 Action tag after wider acceptance testing
See open issues for scoped work. Contributions are welcome.
License
MIT © FixMap contributors.
