Local Trace Storage, File Layout, and Run Naming

AgentDbg stores all trace data as plain files on your local machine — nothing is sent to any external service. Every run produces two files in a dedicated directory you can inspect, move, or delete with any standard tool. This page explains where those files live, what they contain, and how to customize the storage location and run naming.

Default storage location

By default, AgentDbg writes trace data to ~/.agentdbg/runs/. Each run gets its own subdirectory named after its run ID:

~/.agentdbg/
└── runs/
    └── <run_id>/
        ├── run.json        # run metadata (status, counts, timing, run_name)
        └── events.jsonl    # append-only event log (one JSON object per line)

File layout

run.json

run.json holds high-level metadata about the run. It is updated at run end and contains:

run_id — unique UUID for the run
run_name — display name shown in agentdbg view and agentdbg list
started_at / ended_at — ISO 8601 timestamps
duration_ms — total run duration in milliseconds
status — one of running, ok, or error
counts — aggregate counts of llm_calls, tool_calls, errors, and loop_warnings
last_event_ts — timestamp of the most recent event

Example run.json:

{
  "spec_version": "0.1",
  "run_id": "a1b2c3d4-...",
  "run_name": "my-experiment-v1",
  "started_at": "2026-02-18T14:12:00Z",
  "ended_at": "2026-02-18T14:12:30Z",
  "duration_ms": 30000,
  "status": "ok",
  "counts": {
    "llm_calls": 5,
    "tool_calls": 3,
    "errors": 0,
    "loop_warnings": 0
  },
  "last_event_ts": "2026-02-18T14:12:29Z"
}

events.jsonl

events.jsonl is an append-only log. Each line is a complete JSON object representing one event. Events are written in chronological order as they occur, so you can stream or tail the file while the agent is running. Each event includes:

event_type — one of RUN_START, RUN_END, LLM_CALL, TOOL_CALL, STATE_UPDATE, ERROR, LOOP_WARNING
ts — ISO 8601 timestamp
payload — event-type-specific data (model, prompt, response, tool args, etc.)
meta — freeform metadata

Because the format is plain JSONL, you can read it with any JSON-aware tool:

# Print all events for a run
cat ~/.agentdbg/runs/<run_id>/events.jsonl

# Filter to LLM calls only
grep '"LLM_CALL"' ~/.agentdbg/runs/<run_id>/events.jsonl

# Pretty-print the first event
head -1 ~/.agentdbg/runs/<run_id>/events.jsonl | python -m json.tool

All string values in both files are subject to redaction and truncation before being written. See Redact Secrets from Agent Traces for details.

Change the data directory

To store traces somewhere other than ~/.agentdbg, set AGENTDBG_DATA_DIR. This is useful for keeping traces alongside your project, pointing to a larger disk, or separating traces from different projects.

Env var
YAML

export AGENTDBG_DATA_DIR=/path/to/my/agentdbg/data

# .agentdbg/config.yaml  or  ~/.agentdbg/config.yaml
data_dir: /path/to/my/agentdbg/data

Runs will then be stored at /path/to/my/agentdbg/data/runs/<run_id>/. The directory is created automatically on the first run.

Name your runs

By default, AgentDbg derives a run name from the script path and timestamp (for example, path/to/script.py:main - 2026-02-18 14:12). You can override this in two ways: Environment variable — applies to the current process:

export AGENTDBG_RUN_NAME="my-experiment-v1"

name parameter to @trace or traced_run — applies to that specific run and overrides everything else:

from agentdbg import trace

@trace(name="my-experiment-v1")
def run_agent():
    ...

AGENTDBG_RUN_NAME is an environment-only setting. It cannot be set in YAML config files.

Delete a run

Because runs are plain directories, you can delete one by removing its directory:

rm -rf ~/.agentdbg/runs/<run_id>

You can also delete runs from the agentdbg view UI using the delete button in the run sidebar.

Loop detection settings

AgentDbg continuously scans recent events for repeated patterns. Two settings control sensitivity:

Env var	YAML key	Default	Description
`AGENTDBG_LOOP_WINDOW`	`loop_window`	`12`	Number of recent events to scan for patterns. Minimum: 4.
`AGENTDBG_LOOP_REPETITIONS`	`loop_repetitions`	`3`	Consecutive repetitions needed to emit a `LOOP_WARNING`. Minimum: 2.

Increase loop_window if your agent has long natural cycles that are triggering false warnings. Increase loop_repetitions to require more evidence before a warning fires.

Env vars
YAML

export AGENTDBG_LOOP_WINDOW=20
export AGENTDBG_LOOP_REPETITIONS=4

loop_window: 20
loop_repetitions: 4

Storage settings reference

Env var	YAML key	Default	Description
`AGENTDBG_DATA_DIR`	`data_dir`	`~/.agentdbg`	Base directory for run storage.
`AGENTDBG_RUN_NAME`	(env only)	(derived)	Display name for the current run.
`AGENTDBG_LOOP_WINDOW`	`loop_window`	`12`	Event window for loop pattern detection.
`AGENTDBG_LOOP_REPETITIONS`	`loop_repetitions`	`3`	Repetitions required to trigger a loop warning.

For a complete list of all AgentDbg settings including redaction and guardrails, see Configuration overview.

Get Started

SDK

Integrations

Configuration

Reference

Local Trace Storage, File Layout, and Run Naming

Default storage location

File layout

run.json

events.jsonl

Change the data directory

Name your runs

Delete a run

Loop detection settings

Storage settings reference

​Default storage location

​File layout

​run.json

​events.jsonl

​Change the data directory

​Name your runs

​Delete a run

​Loop detection settings

​Storage settings reference

Default storage location

File layout

run.json

events.jsonl

Change the data directory

Name your runs

Delete a run

Loop detection settings

Storage settings reference