FixMap

Inspiration

FixMap started from a problem I kept noticing with AI coding agents.

Tools like Codex, Cursor, Claude Code, and Copilot are getting extremely good at writing code, but writing code is only part of the job. An agent can produce a perfectly reasonable-looking change while reading the wrong files, missing an important test, or misunderstanding how the repository is structured.

I wanted something that could answer a simpler question before the agent starts coding:

Does it actually know where to look?

That became FixMap.

What it does

FixMap is an open-source repo intelligence tool for AI coding workflows.

Give it a GitHub issue, task description, pull request, diff, or local repository and it can generate:

• ranked files and symbols worth inspecting first
• relevant test routes based on the repository
• risk areas such as authentication, billing, data, APIs, and dependencies
• diagnostics showing uncertainty or missing context
• verification of a completed diff against the original plan

The goal is to give both AI agents and human reviewers a clearer map of the repository before and after changes are made.

How I built it

FixMap is built primarily with TypeScript and Node.js.

The project includes a deterministic core analysis engine, CLI, MCP server, GitHub Action, and a Next.js website.

Instead of relying on another hosted LLM to analyze the repository, FixMap scans and ranks repository information locally. The same core functionality can then be used through the CLI, MCP-compatible agents, GitHub Actions, or as a TypeScript library.

Challenges I ran into

One of the biggest challenges was avoiding false confidence.

Finding some related files is easy. Determining which files are actually important — while explaining why they were selected — is much harder.

I also had to think about:

• monorepos and different project structures
• generated files versus maintained source
• identifying real test commands
• handling incomplete or ambiguous tasks
• safely analyzing remote repositories
• keeping output deterministic and useful to other tools

The goal wasn't just to output a list of files. FixMap needed to explain what it knows and, importantly, what it doesn't know.

Accomplishments that I'm proud of

FixMap has grown from a small experiment into a tool with multiple ways to integrate it into real development workflows.

It now includes:

• CLI support
• an MCP server for AI agents
• a GitHub Action
• Plan, Explain, Compare, Verify, and Doctor workflows
• structured JSON output
• a browser demo
• a reusable TypeScript core
• deterministic, local-first repository analysis

I'm especially proud that FixMap doesn't need an account, API key, or hosted AI model to analyze a local repository.

What I learned

Building FixMap made me realize how much of good AI coding is actually a context problem.

Making an AI model smarter isn't always the answer.

Sometimes you can improve the result by giving the agent better information about where to start, what assumptions it's making, what tests matter, and what still hasn't been verified.

I also learned that developer tooling needs to be very explicit about uncertainty. A tool saying "I don't know" can sometimes be much more useful than confidently returning the wrong answer.

What's next for FixMap

FixMap is still early, and there is a lot I want to improve.

The next steps are mainly around better repository understanding, stronger agent integrations, better ranking and verification, support for more project structures, and learning from real repositories where FixMap gets things wrong.

Long term, I want FixMap to become a small intelligence layer between a codebase and whatever AI coding agent you're using.

The idea is simple:

AI coding should be less about guessing and more about grounded verification.

GitHub: https://github.com/aryamthecodebreaker/FixMap

Website: https://usefixmap.vercel.app

Built With

• agents
• ai
• aicoding
• automation
• cli
• codequality
• codereview
• coding
• developer
• developerexperience
• devtools
• fixmap
• github
• githubactions
• llm
• mcp
• node.js
• opensource
• productivity
• programming
• softwareengineering
• testing
• tooling
• typescript
• webdev