io.github.aryamthecodebreaker/fixmap

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 <name> 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 <spec>, --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 compatibility validator shared by Compare, Verify, the Action, and MCP.
• Doctor prints the running version and executable path and diagnoses project, global, PATH, and npm-exec version shadows.
• FIXMAP_PROGRESS controls remote clone/scan progress, and FIXMAP_VERBOSE_USAGE restores full usage text after argument errors.

Agent and automation interfaces

• fixmap setup installs /fixmap discovery for Claude Code, Cursor, GitHub Copilot prompt files, and the open Agent Skills layout; the no-argument command lists every FixMap workflow before making changes.
• The MCP server exposes fixmap_plan, fixmap_context, fixmap_graph, fixmap_explain, fixmap_compare, fixmap_verify, and fixmap_doctor over local stdio and is published in the official MCP Registry.
• The GitHub Action runs Plan or Verify on pull requests, appends within the job summary's remaining 1 MiB budget, bounds its report output and comment, and creates or updates one FixMap comment instead of posting duplicates.
• The Action accepts explicit task input or pull-request context, uses the same report validator as the CLI and MCP server, and fails clearly when a requested diff cannot be resolved.
• The homepage task mapper runs real Plan logic against the bundled sample-api repository and preserves the engine's uncertainty state instead of inventing fallback results.
• The full browser demo runs the real core Plan, Explain, Compare, and Verify logic against the same sample repository without uploading the task.

TypeScript library

• @aryam/fixmap-core exposes repository scanning, exclusion resolution, ranking, Context Pack and Impact Graph construction, BM25 retrieval, task grounding, language/import analysis, test/risk routing, report validation, and Markdown/JSON/agent/Mermaid rendering.
• Its public API also exposes Explain, Compare, and Verify builders and result types, so another tool can compose the same workflow without shelling out to the CLI.
• The @aryam/fixmap-core/browser entry runs the filesystem-free report, comparison, explanation, verification, and rendering logic in a browser bundle.

Trust, compatibility, and evidence

• The core is deterministic and local-first: no account, API key, hosted model, source upload, dependency install, repository script, test execution, or Git hook.
• Public-repository analysis uses a temporary shallow checkout with credentials, inherited Git config, hooks, LFS smudging, symlinks, and submodule traversal disabled.
• reportVersion: 1 defines the JSON compatibility boundary; additive fields are allowed, legacy unmarked reports remain accepted, and unsupported versions fail with an actionable message.
• Checked-in self, external, held-out, adversarial, and performance records power the evidence page; CI checks empty cohorts, confidence gates, generated-asset drift, Action bundle drift, and the 1,000-file benchmark.
• The documentation site includes the live demo, install paths, evidence with misses, release changelog, responsive navigation, keyboard focus, AA contrast, and a persistent system-aware light/dark theme.

What the report contains

• Ranked context files with scores, confidence, and evidence.
• Likely impact files with relationship-specific evidence, confidence, history coverage, and inspection order.
• Test routes that correspond to commands the repository actually declares.
• Six bounded risk areas: authentication, billing, automation, data, public API, and dependencies.
• Diagnostics for uncertainty, unread content, scan boundaries, excluded matches, and unresolved diffs.
• A grounded next action that avoids generated counterparts when maintained source exists.

FixMap is deterministic. It narrows investigation; it does not prove that a ranking or change is correct.

MCP server

Expose Plan, Context, Graph, Explain, Compare, Verify, and Doctor over local stdio:

fixmap mcp

Example client configuration:

{
  "mcpServers": {
    "fixmap": {
      "command": "fixmap",
      "args": ["mcp"]
    }
  }
}

See the MCP setup guide for client-specific instructions.

GitHub Action

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
      - uses: aryamthecodebreaker/FixMap@v0.9.0
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

The Action writes a bounded report to the job summary and maintains one pull-request comment. If GitHub's limits require truncation, the notice points to a local --output plus artifact upload for the complete report. Set no-cache: true when a workflow must bypass the exact-state scan cache, or fail-on: warning when advisory Verify findings must fail the job. Its checked-in bundle and metadata are release-gated.

JSON compatibility

New plans include "reportVersion": 1. Within a report version, fields may be added, but existing fields are not removed or retyped; consumers should ignore unknown fields. Breaking output changes require a new report version. Compare and Verify continue to accept legacy plans without a marker and reject unsupported marker values.

Evidence

The evidence page is generated from the checked-in held-out, regression, baseline, performance, and adversarial records. It publishes misses and confidence intervals alongside hits. CI rejects empty evaluation files, stale rendered artifacts, adversarial regressions, Action bundle drift, and benchmark drift.

Safety boundary

FixMap reads and ranks. It does not install dependencies, run repository scripts, execute tests, invoke git hooks, upload local source, or call a hosted model. Remote clones disable credential helpers, inherited git configuration, hooks, submodules, symlinks, and LFS smudging.

See SECURITY.md for the trust model and reporting process.

Develop locally

npm ci
npm run ci

The workspace contains the deterministic core, CLI/MCP server, GitHub Action, Next.js website, benchmarks, examples, and release scripts. Start with CONTRIBUTING.md; architecture and full usage details live in the documentation site.

Releases

Release notes live in CHANGELOG.md and on the generated website changelog. The publish workflow verifies internal versions, npm packages, MCP Registry metadata, Action metadata and bundle, the GitHub release, and a clean installed CLI before a release is complete.

License

MIT