What your coding agents did, where they wasted time, and whether a run passes: exact answers from the sessions Claude Code, Codex, OpenCode, Pi, Kimi, Factory, Grok Build, Hermes, OpenClaw, NanoClaw and Prime already write to disk, or from the OTLP spans your own system emits. A CLI and an SDK.
Every command except ask runs locally, with no key and no cost. Agents: run traces, never parse a session store yourself; the inspect-agent-traces skill maps each question to its command.
curl -fsSL https://raw.githubusercontent.com/tangle-network/traces/main/install.sh | bash
npm i @tangle-network/traces # as a libraryRequires Node 22 or later. install.sh refuses to overwrite another program's traces and names it. Coming from 0.x: Migrate to 1.0.
traces list --cwd . --last 5 # which sessions ran here
traces facts --current # what this session did: turns, PRs, first failure, cost, $0
traces facts --since 30d --match 'pnpm test' # did we already try X
traces analyze 019a3c7e # where it wasted time, ranked
traces check run.jsonl --contract contract.json # fail CI when a run took a forbidden path| Job | Command | Page |
|---|---|---|
| Compare workflow topologies | graphs |
Graph corpus |
| Find a session | list |
Refs, selection and harnesses |
| What happened, exactly, for $0 | facts |
Session facts |
| What went wrong, ranked, for $0 | analyze |
Analyze a session |
| What each agent did per window, and when it looped or idled, for $0 | behavior |
Behavior windows |
| A question facts cannot answer, with checked citations | ask |
Ask a question |
| The one gate: contracts, conformance, share safety | check |
Check |
| Where two runs split | diff |
Diff two runs |
| Live supervision of sessions or a run tree | watch |
Watch |
| Hand spans to another tool | convert |
Convert |
| Keep a session's evidence | bundle |
Session bundle |
| Send redacted sessions to Intelligence | upload |
Upload |
| Which skills are used | skills |
Skill usage |
| Span tools for an MCP client with no shell | mcp |
MCP server |
Each page embeds its command's --help, and tests/docs-help.test.ts holds them equal to the CLI.
traces: what your agents did, where they wasted time, whether a run passes
Start here for one session: traces facts <ref> (25 lines); one field: add --format json | jq '<path>'
Which graph topologies delivered? traces graphs [--registry DIR]
Which sessions ran? traces list [--cwd .] [--last N]
What happened (turns, PRs, failure, cost)? $0 traces facts <ref> | --current | --since 1d
Did we already try X / what was said? $0 traces facts <ref> | --since 30d --match '<re>'
Where did it waste time or get interrupted? $0 traces analyze <ref>
What was each agent doing, and when did it loop or idle? $0 traces behavior <ref>
A question facts can't answer (model, $) traces ask <ref> --question "…" --budget 1
Does this run pass? (CI) traces check <ref> --contract c.json|conformance
Is this safe to share? traces check <path> --share-safe
Where did two runs diverge? traces diff <a> <b>
What is happening right now? traces watch [<run-dir>] [--once]
Keep a session's evidence traces bundle <ref> --out <dir> · bundle verify <dir>
Hand spans to another tool traces convert <ref> --out <file>
Ship sessions to Intelligence traces upload <ref>|--since T [--dry-run]
Which skills are used? traces skills [--unused]
Serve span tools over MCP traces mcp <ref>|--last N
ref: session id, or 8+ char unique prefix or suffix; session file; OTLP file/dir; bundle dir; run dir; store root
Select: --current --last N --since/--until 2h|1d|ISO --cwd DIR --harness ID --latest-turn
Output: --format text|json|jsonl|junit|github --out PATH --no-content
Exit: 0 yes · 1 no (fail, diverged, unsafe) · 2 could not answer (stderr says why)
traces <command> --help for flags, jq paths and examples · moved from 0.x: traces help moved
import { computeSessionFacts, readOtlpInput } from '@tangle-network/traces'
const input = await readOtlpInput('spans.otlp.jsonl') // or a directory
console.log(input.validation.capabilities) // what this trace can answer
const [facts] = computeSessionFacts(input.spans)The SDK exposes one engine per command: Library (SDK). Runnable code is in examples.
- Commands: the pages in the table above.
- Reference: Library (SDK) · Migrate to 1.0 · Parsers outside traces
- Contribute: Develop and release: local setup, releases and how quality is measured
