DiffMind

Your AI writes the code. DiffMind makes sure it explains why.

English · 简体中文

Vibe coding lets AI ship features fast. DiffMind makes sure you still own the project.

When you tell your AI agent "add user authentication", it writes the code and the feature works. Three weeks later you want to change the logout flow, but you don't know where sessions are stored, how token refresh works, or why it didn't use OAuth. You've become a stranger to your own codebase.

This is the hidden cost of vibe coding: you know what features exist, but not why they were designed this way, what trade-offs were made, or how to safely change them. You lose ownership. Maintenance becomes archaeology. Technical debt piles up because you're afraid to touch code you don't understand.

DiffMind closes this gap. It's an MCP server for Claude Code that forces AI agents to explain every decision — not just "what I did", but "why this approach", "what I rejected", and "what trade-offs I accepted". You get the speed of AI-assisted development with the deep understanding of hand-written code.

Why existing tools fall short

Git history tells you what changed. Chat logs record a conversation that's forgotten next session. Code review catches problems after the fact, when changing course is expensive.

DiffMind is the only tool that captures the AI's reasoning before the code is saved — and rejects it if the reasoning is vague.

Related MCP server: reforge-mcp

How it works

Developer starts a session → AI writes code → AI calls explain_change()
       ↓                                              ↓
  goal recorded                    rationale + rejected alternatives + trade-offs
                                   pass quality gate → saved to .diffmind/
                                   ↓
                              session closed → digest Markdown generated
                                              call chain diff (Mermaid)
                                              commit message drafted

Every explanation lives in .diffmind/ — plain JSON + Markdown, commitable alongside your code, diffable in PRs, readable without any tooling.

Quick start

One-click installation:

curl -fsSL https://raw.githubusercontent.com/akay1121/DiffMind/main/install.sh | bash

Or manually:

1. Add to your Claude Code project

# In your project directory
npm install -g diffmind   # or: npx diffmind

Merge hooks/settings-fragment.json into your project's .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "diffmind session auto-start" }] }],
    "Stop":       [{ "matcher": "",           "hooks": [{ "type": "command", "command": "diffmind session auto-close" }] }]
  },
  "mcpServers": {
    "diffmind": {
      "command": "npx",
      "args": ["-y", "diffmind"],
      "env": { "DIFFMIND_ROOT": "${workspaceFolder}" }
    }
  }
}

Drop templates/CLAUDE.md into your project's CLAUDE.md (or append it).

2. Add .diffmind/ to git

echo "/.diffmind/sessions/" >> .gitignore   # optional: exclude raw session files
# explanations/ and digests/ are worth commiting — that's the point
git add .diffmind/

3. Start a session

The hooks handle this automatically. Or manually:

start_session("Refactor auth to use JWT refresh tokens")

See realistic examples: docs/examples.md shows full workflows for adding features, fixing bugs, and refactoring.

MCP tools

Quality gate

DiffMind blocks or warns when explanations are vague. You can't save:

• A rationale under the minimum length for the change scale

• A rationale that just repeats the summary (Jaccard similarity > 0.7)

• Filler phrases: "better maintainability", "cleaner code", "improved readability"

• A structural or architectural change with no rejected alternatives

• confidence: "verified" with no verification steps listed

Warnings (non-blocking) catch things like missing call chain on structural changes, suspiciously many files for a "local" scale, or opening the rationale with an action verb.

See it in action

Want the full picture before installing? A worked walkthrough of implementing login takes a single request — "帮我完成登录功能" — through the whole DiffMind workflow: session start, three explain_change calls with genuine trade-offs (bcrypt over plaintext, sessions over JWT, a deliberately vague 401 to block email enumeration), the generated digest with its Mermaid call chain diff, the terminal box, the drafted commit message, and — three weeks later — recall_change and search_changes handing the reasoning back just as the developer needs it to add OAuth.

Storage layout

.diffmind/
├── conventions.json        project coding conventions
├── sessions/               one JSON per session (start → close)
├── explanations/           one JSON per explain_change call
└── digests/                Markdown digest per session, with Mermaid call chain diff

All files are human-readable. digests/ is the main artifact for code review.

Roadmap

• Phase 1 — MCP server, 9 tools, quality gate, session model

• Phase 1.5 — diffmind CLI, Claude Code hook auto-trigger, terminal explanation picker

• Phase 2 — Call chain diff visualization (Mermaid, changed nodes in red)

• Phase 2.5 — Git commit message injection (prepare-commit-msg)

• Phase 3 — Web UI for browsing sessions and explanation history

Contributing

Issues and PRs welcome. This project follows its own conventions — run start_convention_interview() in DiffMind before contributing code.

License

MIT