# 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

```bash
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:

```bash
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:

```bash
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