---
title: Traces
description: Record what agent-desktop did with session traces or --trace, read the timeline with trace show and trace export, and capture visual debug files without leaking private data.
url: "https://agent-browser.dev/desktop/guides/traces"
docs_index: /desktop/llms.txt
lastUpdated: 2026-10-30
navTitle: "Traces"
---

> For an index of all documentation, see [/desktop/llms.txt](/desktop/llms.txt).

A trace is an append-only JSONL record of what agent-desktop did: each command, its outcome and duration, and each snapshot it saved. Use one to debug a run or to audit what an agent did. There are two ways to record: a [session](/desktop/sessions), which also lets you read the trace back, and `--trace PATH`, which writes one file.

## Record a run in a session

A session records a trace by default. `session start` does not activate the session for later commands, so export its id:

```bash
export AGENT_DESKTOP_SESSION="$(agent-desktop session start --name trace-demo | jq -er '.data.session_id')"
agent-desktop snapshot --app gnome-calculator -i --compact
agent-desktop status                                  # session_id is set and tracing is true
```

Each process that runs a command writes its own segment under `<state root>/sessions/<id>/trace/`, named `<pid>-<process start>.jsonl`, starting with a `trace.meta` line. `session start --no-trace` creates a session without one. On PowerShell, see [Windows](/desktop/platforms/windows#use-powershell) for the equivalent of `export`.

## Read the timeline

`trace show` merges every segment into one ordered timeline and needs no OS permission:

```bash
agent-desktop trace show --limit 20                   # the last 20 events
agent-desktop trace show --event command.             # only command.start and command.end
agent-desktop trace show --limit 0 | jq -r '.data.events[] | select(.event == "command.end") | [.command, .ok, .duration_ms] | @tsv'
```

These are three real events from the session above:

```json
[
  { "command": "snapshot", "duration_ms": 109, "event": "command.end", "ok": true, "segment": "23161-1793353372418", "seq": 3, "session_id": "run-1793353372413-23159-0", "ts_ms": 1793353372528, "writer_pid": 23161, "writer_proc_start_ms": 1793353372418 },
  { "event": "trace.meta", "os": "linux", "pid": 23176, "proc_start_ms": 1793353372533, "schema": 1, "segment": "23176-1793353372531", "seq": 0, "session_id": "run-1793353372413-23159-0", "ts_ms": 1793353372533, "version": "1.0.1", "writer_pid": 23176, "writer_proc_start_ms": 1793353372533 },
  { "command": "trace", "event": "command.start", "segment": "23176-1793353372531", "seq": 1, "session_id": "run-1793353372413-23159-0", "ts_ms": 1793353372534, "writer_pid": 23176, "writer_proc_start_ms": 1793353372533 }
]
```

`trace export` writes a self-contained HTML viewer, by default `trace-<session>.html` in the session directory:

```bash
agent-desktop trace export --out /tmp/run.html
```

Both need an active session and read session segments only, not a `--trace PATH` file. Flags and result fields are in the [`trace` reference](/desktop/commands/system#trace).

### Event names

<table>
  <thead>
    <tr>
      <th>Event</th>

      <th>Written when</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>trace.meta</code></td>

      <td>A segment opens. Carries <code>schema</code>, the version, <code>os</code>, and the writer pid.</td>
    </tr>

    <tr>
      <td><code>command.start</code>, <code>command.end</code></td>

      <td>A command begins and ends. <code>command.end</code> has <code>ok</code>, <code>duration_ms</code>, and <code>code</code> on failure.</td>
    </tr>

    <tr>
      <td><code>snapshot.saved</code>, <code>snapshot.root.saved</code></td>

      <td>A snapshot or a drill-down is saved.</td>
    </tr>

    <tr>
      <td><code>locator.resolve</code></td>

      <td>A <code>find</code> finished its search.</td>
    </tr>

    <tr>
      <td><code>ref.resolve.ok</code>, <code>ref.resolve.error</code></td>

      <td>A ref action re-identified its target, or failed to.</td>
    </tr>

    <tr>
      <td><code>actionability.check.ok</code>, <code>actionability.check.error</code></td>

      <td>The pre-dispatch checks passed or failed.</td>
    </tr>

    <tr>
      <td><code>action.artifacts</code></td>

      <td>A screenshot-enabled session captured, or skipped, the before and after images.</td>
    </tr>
  </tbody>
</table>

Other events and fields can appear; ignore the ones you do not know.

## Trace to a single file

`--trace PATH` appends events to one file and needs no session:

```bash
agent-desktop --trace /tmp/run.jsonl find --app gnome-calculator --role button --name 7 --exact --count
jq -c 'select(.event == "command.end")' /tmp/run.jsonl
```

The file is created private. While `--trace` is set, the session's trace directory receives nothing. A trace write failure does not fail the command unless you add `--trace-strict`.

## Capture screenshots with a session

`session start --screenshots` stores a before and after PNG of the target window for each ref action, and a copy of each refmap, under the session's `trace/screens/` and `trace/refmaps/`. `trace export` embeds the images. When an image cannot be taken, the `action.artifacts` event records why. Screenshots need tracing on, and on macOS the Screen Recording permission.

A session's recording budget is 32 MiB, 100,000 events, and 4,096 directory entries. When it is spent, existing events stay readable and new ones are dropped; start a new session to keep recording.

## Make a visual debug file

Visual debug writes one HTML file that pairs a window screenshot with labeled element bounds:

```bash
agent-desktop --debug --screenshot /tmp/calc-debug.html snapshot --app gnome-calculator -i
agent-desktop --debug --screenshot /tmp/click-debug.html click @s8f3k2p9:e12
```

- `--debug` requires `--screenshot PATH.html`, a new file ending in `.html`. It is created with owner-only permissions.
- It supports `snapshot` (window surface only) and `click`.
- The result gains `data.debug` with `path` and `format`. If the window cannot be captured, the command still succeeds and `data.debug.warning` says why; on the openbox test desktop it read `No X11 window of the window manager matches this window`.
- The before and after images of a click are two separate observations, not proof that the click was delivered.

## Keep private data private

> **Traces and debug files contain desktop content:**
>
> Snapshot trees, window titles, clipboard reads, notifications, screenshots, and command results contain what you asked agent-desktop to inspect. Treat these files as private.

- Trace lines replace sensitive fields, such as `text`, `value`, `name`, `title`, `url`, `label`, `description`, and `password`, with `{ "redacted": true }`. Command names, app names, ref and snapshot ids, error codes, and durations stay readable.
- Session screenshots, the exported HTML that embeds them, and visual debug files are not redacted.
- Keep these files, and the transcripts of the calling agent, out of public repositories and issue reports.

`session end` seals a session, and `session gc --ended` removes ended sessions with their traces.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)