Skip to main content
A trace is a group of events that share a traceId — the agent’s full response to one user prompt, from the first reasoning step to the final tool call.

​
Trace lifecycle

  1. UserPromptSubmit fires — a new traceId is generated (t_<base36-timestamp>_<8-hex-random>) and persisted to $TMPDIR/voight-traces/<sessionId>.txt.
  2. Tool events inherit the traceId — PreToolUse, PostToolUse, and any reasoning steps read the file and stamp their events with the same traceId.
  3. Stop event ends the trace — the Stop hook fires when the agent’s turn is done.
  4. Next UserPromptSubmit starts a new trace — the file is overwritten with a fresh traceId. The cycle repeats.
One trace equals one logical task the agent worked on, regardless of how many tool calls or reasoning steps it took.

​
What a trace looks like

A trace card on /dashboard/traces shows: 
● Voight dev agent                     49s ago
  "refactor src/auth.ts to use JWT"
  t_mp01q1r2_8e3...                            2m18s
  9 tools · 0 err · 0 files
Clicking opens a full timeline of every event in the trace, with:
  • Prompt at the top (masked by default — click the eye to reveal)
  • Each tool call inline with timing + outcome
  • Reasoning steps interleaved
  • Cost USD aggregated
  • Files touched listed
  • Git context (branch + sha) pinned

​
Text-response traces

If the agent answers conversationally (no tool calls), the trace contains only the prompt + a Stop event with responseText. The dashboard shows these as “Text response” traces with a distinct badge so you can scan past them quickly.

​
Wakeup / autonomous traces

ScheduleWakeup callbacks (the autonomous-loop mechanism in Claude Code’s /loop mode) arrive as UserPromptSubmit events. To distinguish them from real user prompts:
  • The SDK records the wakeup parameters (delaySeconds, reason) when the agent calls ScheduleWakeup
  • When the next UserPromptSubmit matches a pending wakeup, the event is tagged promptSource: 'system'
  • The dashboard renders these traces with a SYSTEM badge so you can spot autonomous loop ticks at a glance

​
Privacy chips per-trace

Every event in a trace ships with metadata.privacyLevel (Minimal / Standard / Full). The dashboard renders a chip per-event so you can audit retroactively: did this specific trace get captured under the level I expected? Useful when you change your privacy level mid-project — the old events keep their chip, the new ones get the new level.

​
Trace search + filter

The Traces page (/dashboard/traces) supports:
  • Time window: 24h / 7d / 30d / all
  • Free-text search: matches agent label, project path, prompt text, trace ID
  • Per-card eye toggle: reveal individual prompts without exposing all of them at once
  • Global Show/Hide: bulk reveal for private review, bulk hide before going on-camera
Default is masked. Refresh / navigate-away resets to masked.

​
API

To fetch traces programmatically: 
curl -H "Authorization: Bearer $PRIVY_JWT" \
  "https://api.voight.xyz/v1/me/traces?since=7d"
See the /me/traces reference for full schema.

​
Next

  • Sessions — traces grouped by sessionId, one session per process lifetime
  • Events — the atomic unit; every event carries a traceId