Local Trace Storage, File Layout, and Run Naming

AgentDbg stores every trace as plain JSON files on your machine. Learn where files land, how to move the data directory, and how to name and delete runs.

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

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

YAML

# .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

export AGENTDBG_LOOP_WINDOW=20
export AGENTDBG_LOOP_REPETITIONS=4

YAML

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.