npx @jnmetacode/tracelet

Your agent is a black box. It calls an LLM, the LLM asks for a tool, the tool returns something weird, the next LLM call does something dumb — and all you see in your terminal is the final answer (or a stack trace).

tracelet is the missing inspector for that loop. Point any OpenTelemetry exporter at localhost:4318, and watch your agent's execution tree stream in live: every LLM call, every tool invocation, prompts in, completions out, token counts, latency, and errors — in a clean local UI that opens instantly.

Nothing ever leaves your machine.

Quick start

# 1. Start tracelet (opens http://localhost:4321)
npx @jnmetacode/tracelet

# 2. See it work with a synthetic agent trace
npx @jnmetacode/tracelet & sleep 1 && node examples/demo.js

Then point your real agent's OpenTelemetry exporter at the ingest endpoint:

http://localhost:4318/v1/traces

That's the standard OTLP/HTTP port — most setups need only:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Both OTLP/HTTP encodings work: protobuf (the exporter default) and JSON. No OTEL_EXPORTER_OTLP_PROTOCOL needed.

Works with what you already use

tracelet speaks the three common tracing vocabularies on the same spans, so it "just works" no matter who emitted the trace:

No SDK lock-in: tracelet is just an OTLP endpoint + a viewer.

Why another one?

There are great LLM observability tools. None of them own the inner debug loop for a JS/TS agent developer:

tracelet isn't trying to be your production analytics warehouse. It's the thing you keep open in a second window while you're building the agent — like the Network tab, but for agent runs.

Outgrew local? tracelet emits/relays standard OTLP, so graduate to any of the tools above for production without re-instrumenting.

How it works

your agent ──OTLP/HTTP (pb|json)──▶  :4318  ──▶  in-memory store  ──SSE──▶  UI :4321
                                          (ring buffer, never persisted off-box)

• Zero dependencies. Pure Node built-ins. The whole thing is a few hundred lines you can read.
• Two ports. 4318 ingests OTLP (the convention), 4321 serves the UI.
• In-memory ring buffer. Last 500 traces. Restart = clean slate — unless you opt in to --persist <file>, which keeps history in a local JSONL file (still your disk, still nothing sent anywhere; Clear wipes it too).
• Cost estimates. Traces and LLM spans show a ~$ figure computed from published list prices for common models (Claude/GPT/Gemini); unknown models simply show none — it never guesses.

CLI

npx @jnmetacode/tracelet [options]
  -p, --port <n>      OTLP/HTTP ingest port   (default 4318)
      --ui-port <n>   Web UI port             (default 4321)
      --persist <f>   opt-in local history (JSONL; reloaded on start)
      --no-open       don't auto-open browser

Roadmap

• Opt-in local history (--persist traces.jsonl) — done
• Diff two runs side by side
• Cost estimates per model (list-price ~$ on traces and LLM spans) — done
• protobuf OTLP ingest (zero-dep decoder) — done
• Waterfall flamegraph zoom
• One-line wrappers: tracelet/vercel, tracelet/langchain

PRs welcome. This is early — issues and ideas are the most useful contribution right now.

Status

Early MVP. The ingest + live UI work today (node examples/demo.js to see it). Star/watch to follow along.

Sibling projects

Part of a small, local-first, zero-dependency toolkit for building AI agents — see the toolkit overview & end-to-end recipe:

• 🔭 tracelet — local DevTools to debug agent runs (this repo)
• 🍳 skillet — a package manager for agent skills
• 🧠 engram — a local, private memory layer for agents (and you)

License

MIT — see LICENSE.