Before Your Coding Agent Edits a File, Let It Ask Why

AI coding agents can modify an unfamiliar file in seconds. The slower question is often more important:

Why does this code look this way?

The answer may be scattered across old local sessions: one turn investigated the bug, another rejected an approach, and a later turn made the edit. Git preserves the code change, but not necessarily the surrounding agent conversation.

I added a local query layer to ThoughtDAG so a developer—or a coding agent—can deliberately retrieve that history before editing:

npx thoughtdag why src/lib/api.ts

It searches supported local agent transcripts for turns that changed, read, or discussed the file and returns links to the matching source turns.

Observation is not explanation

The difficult part was not text search. It was avoiding a false claim of causality.

If a session record shows a file edit, ThoughtDAG can report that as an observed change:

Δ storedProviders → storedProviders, storedVision…

If the agent later says why it made the change, that is useful—but it is still the agent's account, not a verified causal fact. ThoughtDAG marks that separately:

≈ candidate explanation from the agent response

This distinction matters when old session history becomes input to another agent. A fluent explanation should not silently harden into ground truth just because it was retrieved.

Retrieval stays deliberate

For regular use, the same index can be exposed through read-only MCP tools:

npm install -g thoughtdag
thoughtdag setup mcp

The agent can then call why_check, why_file, find, and recall_turn before changing code. Retrieval is explicit; matching history is not automatically injected into every prompt.

The index stays on the local machine, and source session files are never modified. The current CLI covers local Claude Code, Codex, and ThoughtDAG canvas conversations.

What this does not prove

This is a developer preview, not a complete audit trail.

• An observed edit proves that the recorded session changed a file, not that every reason for the change was captured.
• A matching turn can be relevant without being sufficient.
• External session formats can drift.
• Missing or unrecorded actions remain missing.

Those limits are why the output keeps provenance visible and separates observations from candidate explanations.

I am now testing a stricter workflow: before editing an old file, an agent first checks whether there is relevant local history, opens the exact turn when needed, and only then decides what belongs in its current context.

What would you want such a pre-edit check to surface: rejected alternatives, linked issues, tests that once failed, or something else?

Source: github.com/chenxiachan/thoughtdag

Disclosure: I maintain ThoughtDAG. This article was drafted with AI assistance and manually checked against the released CLI and documentation.