claude-task-graph

An MCP server + live graph viewer for Claude Code. Tasks, subtasks, ideas and discussion branches are stored as a graph and rendered live in your browser as a schematic-style diagram with connector lines — so you can skim the structure instead of reading walls of text, and tangents get parked as nodes instead of getting lost.

How it works

• MCP server (stdio) exposes tools to Claude Code: create_node, update_node, link_nodes, get_graph, delete_node.
• Viewer at http://localhost:7300 updates live over WebSocket while Claude works. Node border color = status, node shape = type (task / subtask / idea / discussion / note). Click a node for its full description and note log.
• Storage is a plain JSON file (task-graph.json by default) — one graph per project directory, diffable, committable.

Install

git clone https://github.com/<you>/claude-task-graph.git
cd claude-task-graph
npm install

Hook into Claude Code

From the project directory where you want the graph:

claude mcp add task-graph -- node /path/to/claude-task-graph/src/server.js

Then copy the rules from CLAUDE.md.example into that project's CLAUDE.md. Those rules are what make Claude actually maintain the graph: register tasks before starting, park tangents as linked idea nodes, update status as it goes.

Open http://localhost:7300 and keep it on a second screen.

Configuration

Env var	Default	Purpose
TASK_GRAPH_FILE	./task-graph.json	Where the graph is stored
TASK_GRAPH_PORT	7300	Viewer HTTP/WebSocket port

Set them in the claude mcp add command with -e if needed, e.g. a fixed graph file shared across sessions:

claude mcp add task-graph -e TASK_GRAPH_FILE=$HOME/graphs/myproject.json -- node /path/to/claude-task-graph/src/server.js

Node types and relations

• Types: task, subtask, idea, discussion, note, finding, decision, bug
• Statuses: pending, in-progress, done, blocked, parked
• Relations: subtask-of, depends-on (rendered dashed copper), spawned-from, discussion-of, related-to, found-in, decision-of

License

MIT