Whygraph

The graph of why. So your agent knows before it touches anything.

Whygraph captures the architectural decisions behind your codebase — the tradeoffs accepted, the alternatives rejected, the patterns you deliberately chose — and makes them queryable by AI agents before they write a single line.

The Problem

You're vibe-coding. The agent is fast. Features ship in minutes. Then three sessions later, it confidently rebuilds something you already tried and abandoned. It re-introduces the pattern you explicitly rejected. It optimizes for the local signal — passing tests, satisfying the prompt — while losing the thread of why the architecture is shaped the way it is.

This isn't a hallucination problem. It's a memory problem. The agent isn't wrong. It just doesn't know the why.

Quickstart

npm install --save-dev whygraph
npx whygraph init
npx whygraph up

init walks you through two prompts — app name and environment — then registers the MCP server and writes agent instructions to CLAUDE.md (Claude Code) or AGENTS.md (Cursor, Copilot, other).

Initialized whygraph in .whygraph/
  App node: wg-ab12
  Config: /your/project/.whygraph/config.yaml
  MCP: registered

Run 'whygraph up' to start the server.

up starts the server in the background:

whygraph server running at http://localhost:4777 (pid 12345)

From here, agents capture decisions automatically as they work. Run whygraph viz to open the graph visualization.

What Agents See

When an agent is about to modify src/auth/session.ts, it calls whygraph_context and gets back the decisions that shaped that code:

{
  "nodes": [
    { "id": "wg-sess", "label": "Component", "name": "Session Management" }
  ],
  "decisions": [
    {
      "id": "wg-d001",
      "title": "JWT over server-side sessions",
      "status": "active",
      "context": "Needed stateless auth to support horizontal scaling...",
      "decision": "Use short-lived JWTs with silent refresh via interceptor.",
      "tradeoffs": "Gained: stateless, horizontally scalable. Lost: cannot invalidate tokens server-side.",
      "alternatives": "Server-side sessions — rejected: requires sticky sessions or shared store."
    }
  ]
}

The agent knows what was decided, why, what was traded away, and what was rejected — before it touches anything.

MCP Tools

Whygraph exposes six MCP tools for agent integration. Read tools are always available. Write tools require strict mode (whygraph config --mcp-mode strict).

| Tool | Mode | Description | | --------------------------------- | ----- | ------------------------------------------------------- | | whygraph_context(file, symbol?) | read | Get decisions affecting the code you're about to modify | | whygraph_get_decisions(filters) | read | Query decisions by status, tags, or date range | | whygraph_get_gaps(limit?) | read | Find structural nodes with no recorded decisions | | whygraph_list_nodes(filters) | read | List app, feature, and component nodes | | whygraph_create_decision(...) | write | Create a decision with full validation | | whygraph_create_node(...) | write | Create a structural node |

In default mode, write tools are not registered. Agents write decision files directly to .whygraph/graph/ as markdown. The file watcher picks them up, validates, and flags issues as JSON sidecars that the whygraph issues command can resolve.

Platform Integration

Whygraph works with any AI development environment.

| Platform | Agent Instructions | MCP Registration | | ----------- | ------------------ | --------------------------------------- | | Claude Code | CLAUDE.md | Auto-registered via claude mcp add | | Cursor | AGENTS.md | .cursor/mcp.json (written by init) | | Copilot | AGENTS.md | .vscode/mcp.json (written by init) | | Other | AGENTS.md | MCP_SETUP.md with manual instructions |

Claude Code gets the deepest integration: MCP auto-registration, strict mode write tools, and instructions baked directly into CLAUDE.md.

The Graph

Whygraph models your application as a hierarchy of nodes with decisions attached to the nodes they affect.

App: MyProject
├── Feature: Auth
│   ├── Component: Session Management
│   │   └── ◆ JWT over sessions (active)
│   └── Component: Token Refresh
│       └── ◆ Silent refresh via interceptor (active)
└── Feature: API Layer
    ├── Component: Rate Limiting
    │   └── ◆ Redis-backed sliding window (active)
    └── ◆ REST over tRPC (active)

Node types: App → Feature → Component, with Decision nodes attached via AFFECTS edges.

Decision fields: title, date, context, decision, tradeoffs, alternatives, status, affects, tags

Tags (fixed taxonomy): arch, data, security, performance, integration, infra, ux

Decisions are never deleted. A superseded decision stays in the graph with a SUPERSEDES edge explaining how the architecture evolved.

CLI

| Command | Description | | ------------------------------ | --------------------------------------------------------------------------- | | whygraph init | Set up whygraph: choose environment, register MCP, write agent instructions | | whygraph up | Start the server in the background | | whygraph down | Stop the server | | whygraph restart | Stop and restart the server | | whygraph serve | Start the server in the foreground | | whygraph status | Check server status and entity counts | | whygraph viz | Open the graph visualization in a browser | | whygraph issues | List and interactively resolve validation issues | | whygraph validate | Validate all entities and cross-references | | whygraph config [--flag val] | View or modify configuration | | whygraph mcp | Start the MCP stdio server |

All commands accept --json for programmatic output.

Philosophy

The why is not in the code. You can read a codebase and understand what it does. You cannot read it and understand what was tried before, what was rejected, and what trade-offs were accepted.

Decisions, not documentation. Structured records — context, choice, tradeoffs, alternatives — not prose. Structure is what makes decisions queryable by agents.

Append-only. Superseded decisions stay in the graph. They explain the path, not just the destination.

Repo-native. The graph lives in .whygraph/, versioned with your code. No external service. No account required.

Agent-first. The MCP tools and agent instructions are the primary interface. The CLI and visualization exist so humans can inspect what agents will read.

Never lose data. Entity files are always written, even if validation fails. Issues are tracked in sidecars, not by rejecting writes.

Limitations

• The server must be running for MCP read tools and live visualization to work. In default mode, agents can write decision files directly to .whygraph/graph/ without the server — they'll be picked up when it starts.
• Multi-agent worktree support detects divergence but does not auto-merge. Conflict resolution follows standard git workflow.
• The fixed tag taxonomy (arch, data, security, performance, integration, infra, ux) is intentional — it keeps decisions queryable. Custom tags are not supported in v1.
• No cloud sync or hosted option. The graph is local to your repo.

Multi-Agent / Worktree Support

Whygraph runs one server per repo and watches all git worktrees. When agents work in parallel:

• Each worktree's .whygraph/graph/ is watched independently
• ETag-based dirty tracking detects divergence from the main graph
• Entity IDs use NanoIDs to prevent collisions across concurrent agents
• Conflict resolution happens at git merge time

Acknowledgments

• Matt Pocock — the development workflow used to build this project (TDD, PRD-first, simplify) is based on his 5 Skills for Claude Code

License

MIT © Geovanie Ruiz