DEV Community: Ruca.

I Built an Investigation-First Debugger for AI Agents — TraceMotive v0.3

Ruca. — Sun, 16 Aug 2026 08:15:03 +0000

I Built an Investigation-First Debugger for AI Agents — TraceMotive v0.3

I just released TraceMotive v0.3.0.

TraceMotive is an open-source, local-first debugging tool for AI agent executions.

GitHub:

https://github.com/doraemonfv-glitch/tracemotive

The problem

Imagine you have two agent executions.

One worked.

One didn't.

Traditional tracing gives you the raw execution data, which is useful — but you still have to answer the hard question yourself:

Where should I start looking?

That is the problem I wanted v0.3 to focus on.

Good run vs bad run

The new workflow is:

reference run
      vs
changed run
      ↓
structural alignment
      ↓
first evidence-supported behavioral divergence
      ↓
deterministic findings
      ↓
investigation starting point

The important word here is supported.

TraceMotive does not try to guess the root cause.

It identifies the first behavioral difference that can be supported by the available structural evidence.

What can it detect?

v0.3 can produce deterministic findings such as:

tool input changed
tool output changed
new error observed
error resolved
tool added
tool removed
execution subtree added or removed
tool repetition changed

It can also surface context-only changes such as:

model changed
request parameters changed
trace status changed

Those context changes do not automatically become the investigation starting point.

Uncertainty is a feature

A debugger shouldn't pretend to know something it doesn't.

For example, repeated calls can be difficult to align safely.

Consider:

Run A:
weather()
weather()
weather()

Run B:
weather()
weather()
weather()

Pairing the first call on the left with the first call on the right simply because they have the same position can create false matches.

TraceMotive deliberately avoids that.

When evidence is ambiguous, incomplete, redacted, or unavailable, the result may be:

uncertain

instead of inventing an answer.

Investigation-first UI

v0.3 also introduces a new comparison interface.

Instead of showing the full raw comparison first, the UI prioritizes:

the investigation state
the first supported investigation point
evidence observed there
additional behavioral observations
context
uncertainty
detailed raw comparison

The existing detailed comparison remains available through /api/v2.

The new investigation API lives at:

GET /api/v3/compare/{left_trace_id}/{right_trace_id}

Try it without an API key

v0.3 includes a deterministic local demo.

Install:

pip install tracemotive==0.3.0

Start TraceMotive:

tracemotive serve

Then open another terminal:

tracemotive demo

The demo creates a reference execution and a changed execution and prints a URL that opens directly in the investigation UI.

No OpenAI API key is required for the demo.

Still local-first

The privacy model remains important to me.

TraceMotive keeps:

loopback-only Collector/UI serving
local SQLite persistence
privacy-controlled content capture
redaction before transport
no TraceMotive analytics
no external TraceMotive telemetry

What TraceMotive does NOT claim

TraceMotive does not prove causality.

It does not say:

This change caused the failure.

It says something closer to:

This is the first behavioral divergence supported by the evidence. This is a reasonable place to begin investigating.

That distinction became one of the biggest design principles in v0.3.

What's next?

The next big area is broader real-world integration validation.

OpenAI Agents SDK is currently the primary validated adapter.

I also want to keep testing whether this investigation workflow is actually useful on real agent failures instead of just adding more observability features.

If you build AI agents, I'd love feedback — especially examples where TraceMotive becomes too conservative or points you somewhere unhelpful.

GitHub:

https://github.com/doraemonfv-glitch/tracemotive

PyPI:

pip install tracemotive==0.3.0

I released TraceMotive v0.1, got roasted, and rebuilt the biggest problems in v0.2

Ruca. — Fri, 14 Aug 2026 16:41:12 +0000

A few days ago, I released TraceMotive v0.1.

TraceMotive is an open-source, local-first tool for tracing and debugging AI agent execution.

The first version worked.

But after releasing it, I got some pretty harsh feedback — and most of it was fair.

The biggest problems were:

traces disappeared when the Collector restarted
trying the UI required multiple terminals and Node/npm
it felt more like a trace viewer than a debugger

So instead of adding more frameworks or bigger features, I made those problems the scope of v0.2.

What changed in v0.2

TraceMotive v0.2 now has persistent local SQLite storage.

If you restart TraceMotive, your traces are still there.

The normal setup is also much simpler now:

pip install "tracemotive[server]"
tracemotive serve

Then open:

http://127.0.0.1:8765

The production UI is packaged with TraceMotive, so normal users no longer need Node, npm, Vite, or a separate frontend dev server.

The other big addition is trace-to-trace comparison.

You can select two agent runs in the UI and compare things like status, errors, latency, token usage, model/request parameters, tool inputs/outputs when captured, and spans that only exist in one run.

There is also a Changed only filter and side-by-side field comparison.

One problem I found while building comparison

Repeated tool calls looked simple at first.

If the same tool appeared multiple times, I thought I could just match the first call with the first call, the second with the second, and so on.

That turned out to be a bad assumption.

Before shipping the production comparison API, I built an evaluation set and tested what happened when repeated tool calls were inserted, removed, or reordered.

The naive ordinal approach produced incorrect matches:

inserted call: 4 incorrect matches
removed call: 2 incorrect matches
reordered calls: 4 incorrect matches

The problem was that the matcher could look completely confident while pairing the wrong logical calls.

So I changed the production behavior.

If repeated calls cannot be deterministically paired, TraceMotive does not guess. It reports them as an ambiguous group instead of pretending they are exact matches.

After the change, the production regression results became:

insertion: 0 false exact matches
removal:   0 false exact matches
reorder:   0 false exact matches

I may experiment with suggested or heuristic matches later, but if I do, I want them clearly separated from exact matches.

Still local-first

The privacy model from v0.1 is still there.

Content capture is disabled by default, redaction happens before events enter the transport queue, and tracemotive serve binds only to 127.0.0.1.

TraceMotive also does not send its own analytics or telemetry to an external service.

v0.2 does not claim to provide automatic root-cause analysis, causal proof, replay, or first-divergence detection.

For now, the goal is simpler:

keep the traces, make the debugger easy to start, and make differences between two executions easy to inspect.

GitHub:

https://github.com/doraemonfv-glitch/tracemotive

If you build AI agents, I'd be interested to hear what still feels annoying, confusing, or missing.

Concrete failure cases are especially useful right now.

[Boost]

Ruca. — Thu, 13 Aug 2026 18:34:22 +0000

Ruca.

Aug 13

I built TraceMotive: a local-first debugger for AI agent execution

#ai #opensource #python #agents

2 min read

I built TraceMotive: a local-first debugger for AI agent execution

Ruca. — Thu, 13 Aug 2026 18:32:50 +0000

I’ve been building an open-source project called TraceMotive.

It started from a problem I kept running into with AI agents:

When an agent run fails, the place where the error appears isn’t always where the execution first started going wrong.

That makes debugging agent workflows harder than it looks.

So I built TraceMotive, a local-first tracing and debugging tool for AI agent execution.

What TraceMotive does

The current v0.1 includes:

Python SDK
canonical traces and spans
a local Collector backed by SQLite
a React UI for inspecting agent runs
optional OpenAI Agents SDK integration

TraceMotive is local-first, and content capture is disabled by default.

I’m intentionally keeping the first version small. I’m not trying to add replay, automatic root-cause analysis, cloud sync, or support for every agent framework yet.

Why?

I’d rather get real feedback before adding a lot of features.

Right now I want people who actually build AI agents to try it and tell me:

where setup is confusing
what breaks
what information is missing from traces
what feels awkward in the API

The longer-term direction is:

“The causal debugger for AI agents.”

Eventually, I want TraceMotive to help identify where an agent execution first started going in the wrong direction, instead of only showing where the final error appeared.

But first, I want to make the basic observation and debugging layer solid.

Try it

PyPI:

pip install tracemotive

GitHub:

https://github.com/doraemonfv-glitch/tracemotive

If you build AI agents, I’d really appreciate you trying it for a few minutes and telling me what you run into.

Even small feedback is useful.

I built TraceMotive, a local-first debugger for AI agent execution

Ruca. — Wed, 12 Aug 2026 15:02:52 +0000

I just released TraceMotive v0.1, an open-source, local-first tracing and debugging tool for AI agent execution.

I built it because I kept running into the same problem:

When an agent behaves incorrectly, the final error often doesn't tell you enough about how the execution actually got there.

TraceMotive records agent runs as traces and spans so you can inspect the execution step by step.

What v0.1 includes

Trace and Span collection
Parent/child Span hierarchy
Execution Timeline
Span Inspector
SQLite-backed local Collector
OpenAI Agents SDK integration
Privacy-first content capture defaults
Bounded local transport and failure isolation

Install

pip install tracemotive

GitHub:
https://github.com/doraemonfv-glitch/tracemotive

PyPI:
https://pypi.org/project/tracemotive/

TraceMotive's own tracing data stays local by default. Model-provider traffic still depends on how the agent itself is configured.

Why I built it

v0.1 is intentionally focused on observation and debugging rather than automatic diagnosis.

The longer-term direction is to move from:

“Where did the error happen?”

toward:

“Where did the execution first start going wrong?”

That is the idea behind the long-term goal:

“The causal debugger for AI agents.”

I'd especially appreciate feedback from people building agents:

What information do you usually wish you had when debugging an agent execution?