Skip to main content
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. 
export AGENTDBG_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 varYAML keyDefaultDescription
AGENTDBG_LOOP_WINDOWloop_window12Number of recent events to scan for patterns. Minimum: 4.
AGENTDBG_LOOP_REPETITIONSloop_repetitions3Consecutive 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. 
export AGENTDBG_LOOP_WINDOW=20
export AGENTDBG_LOOP_REPETITIONS=4

​
Storage settings reference

Env varYAML keyDefaultDescription
AGENTDBG_DATA_DIRdata_dir~/.agentdbgBase directory for run storage.
AGENTDBG_RUN_NAME(env only)(derived)Display name for the current run.
AGENTDBG_LOOP_WINDOWloop_window12Event window for loop pattern detection.
AGENTDBG_LOOP_REPETITIONSloop_repetitions3Repetitions required to trigger a loop warning.
For a complete list of all AgentDbg settings including redaction and guardrails, see Configuration overview.