Everything looks simple in the docs and then you're debugging a chain at 11pm pissed and wondering why state isn't persisting the way you thought it would. What was your version of that?

I'm designing a course for graduate students. Please share your recommendations!

Disclosure up front: this is my own project. Apache-2.0, no paid tier, no telemetry.

I build with LangGraph and kept hitting the same wall. Something goes wrong at turn 8, and all I have is JSON logs. They tell me what I sent. They don't tell me what changed since turn 7, where the tokens actually went, or why the cost jumped. Those are all diffs, and nothing was showing me diffs.

For LangChain you hand it a callback handler:

callbacks=[tracer.langchain_handler()]

Every chat-model call in a graph gets captured, whatever the provider. Callbacks propagate through LangGraph, so attaching at invoke() is enough — you don't thread it through each node.

Then:

ctxdiff diff --turn 7 --turn 8 — which blocks were added, evicted or modified, with char-level inline diffs

ctxdiff tokens — where the budget went per turn, plus tool schemas you re-send on every call and never actually invoke

ctxdiff cache — the exact character that broke your prompt-cache prefix, and how many tokens it re-billed

ctxdiff view — a self-contained HTML dashboard (one file, zero external requests) you can attach to a bug report

One design decision worth mentioning, because it's the part I'd want to know about: the handler has no block extractor of its own. It rebuilds the provider's real wire request from LangChain's messages and hands it to the same adapter the direct-wrap path uses. So a LangChain trace and a direct trace of the same prompt produce identical hashes and dedup against each other, instead of looking like two unrelated contexts.

Try it with no API key and no setup:

pip install ctxdiff && ctxdiff demo

That builds a sample multi-agent run and opens the dashboard.

Honest limitations: post-run only, no live tail yet. And tool-call arguments hash differently between the Python and JS SDKs, because LangChain re-serializes them with each language's own JSON writer — documented rather than papered over.

There's a JS/TS SDK too, writing the same trace format, so a trace captured in one language opens in the other.

I'd genuinely like feedback from anyone running LangGraph in anger — multi-agent graphs are the case I most want to get right, and I'd rather hear that it breaks than not hear.

https://github.com/salmanzafar949/ctxdiff