Orbital Logo
Orbital projects
st

spantrace

Local-first agent debugger

See what your agent actually did.

spantrace turns multi-step LLM runs into inspectable trace trees, so every model call, tool invocation, result, error, and retry is visible in context.

View on npm View source on GitHub

v0.1.1 · Apache-2.0 · Install with npm or run with npx.

sample.agtrace
LLM_CALLclaude-sonnet-5 — "What's the weather in Dubai?"
TOOL_CALLget_weather({"city":"Dubai"})
TOOL_RESULTget_weather → {"tempC":41,"condition":"sunny"}
TOOL_CALLlog_to_tracker({…})
ERRORconnection reset by tracker service
RETRYattempt 1/3 — connection reset, retrying
TOOL_RESULTlog_to_tracker → {"status":"ok"}

Overview

Chrome DevTools for AI agents.

Feed spantrace a JSONL-based .agtrace file and it reconstructs the full execution tree from parent relationships.

Read the tree in your terminal or open the local viewer for collapsible navigation and a detail panel with the exact payload for each span.

Two ways to inspect

Start in the terminal. Go deeper in the browser.

CLI tree

instant output
npm install -g spantrace
spantrace path/to/trace.agtrace

Interactive viewer

local only
spantrace view path/to/trace.agtrace
spantrace view trace.agtrace --port 4317

The viewer reads the file once at startup. Live and streaming ingestion are not part of the current release.

Feature list

The execution story, without the guesswork.

  1. 01

    Trace tree reconstruction

    Turn parent and child span relationships into a readable execution tree, from the root LLM call to every nested result.

  2. 02

    Five span types

    Inspect LLM calls, tool calls, tool results, errors, and retries with summaries designed for each event type.

  3. 03

    Fast CLI output

    Print a complete trace directly in the terminal for quick debugging, scripts, and CI logs.

  4. 04

    Local web viewer

    Open the same trace as an interactive, collapsible tree with a focused detail panel for every selected span.

  5. 05

    Strict validation

    Malformed JSONL fails loudly with the source file, line number, reason, and offending line so bad traces are easy to fix.

  6. 06

    Simple .agtrace format

    Use one JSON object per line with a compact, documented schema that is straightforward for agent runtimes to emit.

Privacy details

Your traces stay on your machine.

spantrace is local-first software, not a hosted trace service. The current release does not require an account, cloud workspace, or remote trace upload.

A standalone privacy policy has not been published for the package. The details here reflect the behavior documented and implemented in v0.1.1.

Local files

The selected .agtrace file is parsed on the machine where spantrace runs.

Loopback viewer

The browser viewer binds to 127.0.0.1 rather than exposing a public server.

No account

Installation and use do not require authentication or a hosted profile.

No cloud sync

The project does not provide remote storage, workspace syncing, or uploads.

Read once

The viewer reads the trace at startup; it does not watch or stream the file.

Open source

The Apache-2.0 source is available for inspection on GitHub.

Debug the run

Follow every span from prompt to result.

View on npm View source on GitHub