Inspect one agent turn from observable context to tool execution and final response — directly from local transcripts.

Codex · Claude · local only · read-only MVP · MIT

One turn, end to end

Velatura turns provider-specific JSONL into an evidence-aware execution path:

user message → observable context → model call → tool call → tool result → final response

• Path shows how context, model calls, tools, and responses relate.
• Events preserves the normalized event stream behind the visualization.
• Model Input separates what is observed, reconstructed, partial, or not observable.
• Raw reveals the corresponding source record on demand, with recognizable credentials masked.

Velatura does not proxy network traffic and does not invent missing prompts. If a fact is absent from the local transcript, the UI says so.

Quick start

Requires Node.js >=22.18 and pnpm 11.x.

pnpm install
pnpm dev

Open http://127.0.0.1:4317.

The viewer binds to loopback and indexes up to 60 recently updated sessions per provider from the last 30 days. It reads metadata and a bounded title probe first; a transcript is parsed only after you select it.

Do not open web/index.html through file://. Velatura needs its local read-only API.

How it works

flowchart LR
    C["Codex<br/>~/.codex/sessions"] --> I["Session catalog<br/>lazy local index"]
    A["Claude<br/>~/.claude/projects"] --> I
    I --> T["Provider adapters"]
    T --> E["CanonicalEvent v0"]
    E --> S["Turn slicer"]
    S --> G["TraceGraph"]
    G --> U["React viewer"]

Loading

Provider adapters absorb source-format differences. The UI consumes only CanonicalEvent v0 and TraceGraph, so adding another coding agent does not require rewriting the presentation layer.

Claude subagents/ files are excluded from discovery because their records already appear inside the parent transcript's execution story.

Accuracy before spectacle

Every event carries an evidence label:

Label	Meaning
observed	Present in the local source record.
reconstructed	Ordering or a model-call boundary inferred from observed events.
partial	Some inputs are known; others are not observable.
not_observable	The local source cannot provide the fact, so Velatura does not guess.

Completion is conservative. A turn is completed or interrupted only when the provider records an explicit terminal marker. A recently modified turn at EOF is running; older ambiguous data remains unknown.

Current provider-specific final-response markers are Codex phase=final_answer and Claude stop_reason=end_turn. Tool call/result edges are observed only when their call IDs match.

Privacy boundary

• The server accepts only GET requests and binds to 127.0.0.1.
• Real transcripts stay in ~/.codex and ~/.claude; Velatura does not copy them into this repository.
• Known credential fields and recognizable token formats are masked in tool payloads and Raw records before they leave the data layer.
• User-authored messages remain arbitrary free text and can contain user-defined secrets. Inspect Raw or exported data before sharing it.
• Public source references replace the current home directory with ~; internal file access still uses the real path.

The JSONL files under tests/fixtures/ are small synthetic test inputs. Standalone trace exports are ignored by Git.

Standalone trace

Generate a portable trace.v0 document without opening the viewer:

pnpm trace -- \
  --provider codex \
  --input tests/fixtures/codex/basic-turn.jsonl \
  --output trace.json \
  --session-id demo

--provider accepts codex or claude.

Local read-only API

GET /api/health
GET /api/sessions
GET /api/sessions?provider=codex|claude
GET /api/sessions/:sessionId
GET /api/sessions/:sessionId/turns/:turnId
GET /api/sessions/:sessionId/raw/:line

Session IDs are stable hashes of indexed provider paths. Raw lookup is limited to indexed session IDs and numeric source lines; arbitrary filesystem paths are never accepted.

Production and verification

Build and serve the viewer and API from one loopback origin:

pnpm build
pnpm start --port 4317 --days 30 --limit 60

Run the release checks:

pnpm test
pnpm typecheck
pnpm build
pnpm security:scan

GitHub Actions runs the same test, typecheck, build, and sensitive-file gates on every push and pull request.

License

MIT © 2026 yearthmain