GraphIDE

Turn implementation intent, code references, comments, and agent plans into reviewable graph files.

What it does  |  Quick Start  |  MCP Adapter  |  VS Code  |  Format  |  Development

---

What it does

GraphIDE is a visual planning and comprehension layer for AI coding agents. It gives Codex, Claude Code, and similar tools a shared .graphide file they can create, validate, update, and hand back to humans for visual review.

GraphIDE is not trying to replace your compiler, language server, or IDE. The MVP is a lightweight planning surface: agents still read code and make code changes, while GraphIDE captures the plan, references, comments, and intent that would otherwise disappear into chat text.

Planning problem	GraphIDE answer
Agent plans are hard to audit after the fact	Store the plan as a .graphide graph with nodes, edges, comments, and references
Mermaid and prose lose implementation context	Keep code references and intent metadata attached to graph elements
Humans need a faster way to review agent thinking	Open the same file in a VS Code custom editor with a visual graph canvas
Agent tools need a stable integration point	Launch graphide-mcp as a thin stdio MCP adapter
MVP should stay language-agnostic	Validate graph consistency, not compiler correctness

Architecture

flowchart LR
  U[User request] --> A[AI coding agent]
  A --> M["graphide-mcp"]
  M --> C["graphide-core"]
  C --> F[".graphide file"]
  F --> V[VS Code custom editor]
  V --> W["graphide-webview"]
  W --> H[Human visual review]
  H --> A

Loading

The durable pieces are the .graphide file format, shared validation/model logic, the MCP adapter, and the reusable graph renderer. IDE integrations are adapters, starting with VS Code.

Quick Start

Create a graph plan:

npx graphide init ./plan.graphide

Validate it:

npx graphide validate ./plan.graphide

Use the MCP adapter from an MCP client:

npx -y graphide-mcp

The current public release line is an early 0.0.2 preview. Expect the format and UI to move while the core workflow gets sharper.

MCP Adapter

graphide-mcp is a thin stdio adapter launched by the MCP client. It is not a daemon and does not need a serve command.

Example client config:

{
  "mcpServers": {
    "graphide": {
      "command": "npx",
      "args": ["-y", "graphide-mcp"]
    }
  }
}

Initial tools:

Tool	Purpose
read	Read and parse a .graphide file
validate	Return structured validation issues
create	Create a starter .graphide document
update	Validate and replace a complete graph file

VS Code Editor

The VS Code extension registers a custom editor for *.graphide files. The current editor shell includes:

• React Flow canvas
• node creation
• edge creation
• node selection and detail editing
• comments attached to graph elements
• validation issue panel
• reserved graph diff panel

The extension bundles the shared core and webview code when packaged. Updating npm packages does not update installed VS Code extensions; extension updates are published through the VS Code Marketplace or Open VSX release flow.

GraphIDE Format

The v1 .graphide format is JSON with a custom extension:

{
  "version": 1,
  "metadata": {
    "title": "Example Plan",
    "description": "Human-readable purpose"
  },
  "nodes": [
    {
      "id": "read-context",
      "type": "task",
      "label": "Read current code",
      "intent": "Understand behavior before editing",
      "refs": ["README.md"]
    }
  ],
  "edges": [],
  "comments": []
}

Validation currently checks document shape, duplicate IDs, dangling edges, missing parent nodes, and missing comment targets.

Packages

graphide/
├── apps/
│   └── vscode-extension/     # VS Code custom editor
├── packages/
│   ├── core/                 # .graphide model, parser, serializer, validator
│   ├── mcp/                  # thin stdio MCP adapter
│   └── webview/              # React Flow editor shell
├── examples/
│   └── sample.graphide
└── package.json              # npm package: graphide

Package	Role
graphide	Root CLI and public npm package
graphide-core	Shared schema, parser, serializer, and validator
graphide-mcp	Thin MCP stdio adapter
graphide-webview	React Flow graph editor shell
graphide-vscode	VS Code extension package

Development

Use Corepack if pnpm is not installed globally:

corepack pnpm install
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build

Validate the sample graph:

node dist/cli.js validate examples/sample.graphide

Package the VS Code extension:

corepack pnpm --filter graphide-vscode package

Check npm package contents before publishing:

corepack pnpm pack:dry
corepack pnpm --filter graphide-core pack --dry-run
corepack pnpm --filter graphide-mcp pack --dry-run

Status

GraphIDE is an early preview. The immediate goal is to make visual agent plans useful enough that humans can inspect them before, during, and after code changes.