ThoughtDAG MCP
An MCP server and CLI that find in Claude Code and Codex sessions why a file became what it is: who asked the agent what, when and what changed
- 742 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Reads the logs of all your Claude Code and Codex sessions and returns found text to the agent and model
- Stores a session index in `~/.thoughtdag`, which may hold fragments of private conversations
- `thoughtdag setup rules` modifies the project's `CLAUDE.md` and `AGENTS.md`
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/thoughtdagDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads the logs of all your Claude Code and Codex sessions and returns found text to the agent and model
- Stores a session index in `~/.thoughtdag`, which may hold fragments of private conversations
- `thoughtdag setup rules` modifies the project's `CLAUDE.md` and `AGENTS.md`
This is third-party code. Review the repository files before installing.
What it does
ThoughtDAG indexes agent sessions already on your machine: Claude Code, Codex, DeepSeek Harness and Pi. For each turn it records which files the agent read, wrote or edited. `thoughtdag why src/lib/api.ts` lists the turns that touched a file: when it happened, what changed, what was asked and what the agent answered. Every entry links back to the original conversation. Facts come from tool calls, never from free text or a model. Lines marked `Δ` are observed changes, and lines marked `≈` are read from the answer and stay candidate explanations. `thoughtdag mcp` runs the same questions as a read-only MCP server over stdio. The agent gets four tools: `why_check`, `why_file`, `find` for exact words in questions and answers, and `recall_turn` to bring back a specific turn. `thoughtdag setup mcp` registers the server itself for Claude Code in the project's `.mcp.json` and for Codex in `~/.codex/config.toml`. `thoughtdag setup rules` adds two rules to `CLAUDE.md` and `AGENTS.md`: check history before editing a file and before explaining why code is the way it is. The index lives in `~/.thoughtdag` with permissions 0700 and 0600, session files are only read, and `thoughtdag purge` deletes the index. The desktop canvas with branching conversations ships in the same project but is not needed for history search.
Who it is for. For developers who work a lot with Claude Code or Codex and want the agent to dig up past sessions itself and explain where an odd decision in a file came from.
Good fit when
- You return to a file a month later and forget why it has this workaround: `npx thoughtdag why src/lib/api.ts`
- An agent is about to rewrite a module and should first check whether the file has history: `thoughtdag why --check <path>`
- You need to find a conversation by an exact phrase you or the agent wrote in past sessions: `thoughtdag find "phrase"`
- You need the turns on a file as JSON for a report: `thoughtdag why <path> --json`
- You work in Claude Code and Codex at once and want one search across both histories
Not a fit when
- Agent sessions live on another machine or in the cloud: the index is built from local log files that a cloud copy cannot see
- You want it to edit a canvas or sessions: the four MCP tools only search and return turns
- You need a guaranteed cause of a change: lines marked `≈` stay a guess taken from the agent answer
Example request
Before editing src/lib/api.ts check through ThoughtDAG what we decided earlier about this file and whyMCP
- Transport
- stdio
- Authentication
- not required
Environment variables
THOUGHTDAG_HOME- Index directory instead of `~/.thoughtdag`.
THOUGHTDAG_SESSION_ROOTS- Directories with session logs when you need to set them explicitly (an example from the Docker setup).
Limitations
- Node.js 20 or newer and the logs of supported agents on the machine where the server runs are required.
- A file query works by the path recorded in the session. In a container use absolute paths from the mounted logs.
- Retrieved text is returned to the agent and may enter the model context. Check the client's provider settings before using private history.
- The Codex skill installs separately: `npx skills add chenxiachan/thoughtdag --skill thoughtdag --agent codex`. It adds no MCP tools by itself: it opens a session in the desktop app or runs CLI queries.
How to disable. Remove the `thoughtdag` block from `.mcp.json` and `~/.codex/config.toml`. `thoughtdag setup rules --remove` takes the rules out of `CLAUDE.md` and `AGENTS.md`. `thoughtdag purge` deletes the index and `thoughtdag purge --cache` deletes caches.
FAQ
How do I find out why a file has this code?
Run `npx thoughtdag why <file path>`. The command lists turns from Claude Code, Codex, DeepSeek Harness and Pi sessions that read or changed the file: date, observed change, question and answer. The `--include-read` flag adds turns where the file was only read.
How do I connect ThoughtDAG to Claude Code?
Run `thoughtdag setup mcp` in the project directory: the server is written to `.mcp.json`. Or add a block by hand with the `npx` command and the arguments `-y thoughtdag@0.2.2 mcp`. The agent gets the `why_check`, `why_file`, `find` and `recall_turn` tools.
Does ThoughtDAG change my sessions or files?
No, it only reads session files, and the MCP tools work read-only. It keeps its own index separately and removes it with `thoughtdag purge`. Rules in `CLAUDE.md` and `AGENTS.md` are added only by `thoughtdag setup rules`.
How is ThoughtDAG different from session history viewers?
It answers a question about one file instead of listing conversations. The index is built from the files each turn read, wrote or edited, so `thoughtdag why` returns the relevant turns at once and the agent gets the same answers over MCP.
Can I run the server in Docker?
Yes, the repository has a Dockerfile for a non-root stdio server: `docker build -f cli/Dockerfile -t thoughtdag-mcp cli`. No history is copied into the image. To use it, mount your session directories read-only at `/data/sessions`.
Discussion
No questions or reviews yet.
Related
MCP serversDoodleNote MCP: meeting notes for agents
DoodleNote MCP
A read-only MCP server: Claude Code, Claude Desktop and Codex search local DoodleNote meetings, notes and transcripts
Minutes
minutes
A local-first MCP server for meeting memory: on-device recording and transcription into Markdown, searchable from Claude Code, Codex, Cursor and any MCP client
A CLI and MCP server that tally token spend across 41 tools and agents, break it down by project and model, and help cut wasted tokens
Set up Claude Code and Codex in one conversation: global instructions, rules, plugins, skills, a status line and correction memory
A local Markdown note base with an MCP server and skills: Claude Code, Cursor, Codex and Gemini CLI all read the same context
Cunzhi (寸止)
寸止 (Cunzhi)
MCP server in Rust and Tauri: the agent shows a dialog with options before ending a reply, keeps project rules and searches code
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| ThoughtDAG (this card) | no | not required | 742 | |
| Coding Agent Session Search (cass) | no | 1,200 | searches the text of sessions across agents, while ThoughtDAG indexes turns by the files they touched | |
| Claude Code History Viewer | no | 2,303 | an app for browsing Claude Code history, with no agent queries over MCP |
README in short
The project's main page presents ThoughtDAG as a canvas where model answers become nodes and the wires between them decide which context the next question sees. A launch table lists the desktop app, a DeepSeek Harness plugin, the CLI with MCP and a build from source. Then come the authors' studies on where an agent turn's tokens go, the wires rule and a comparison with plain chat. CLI details live in `cli/README.md`.