> ## Documentation Index > Fetch the complete documentation index at: https://refinehq.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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.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`: ```json theme={null} { "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: ```bash theme={null} # Print all events for a run cat ~/.agentdbg/runs//events.jsonl # Filter to LLM calls only grep '"LLM_CALL"' ~/.agentdbg/runs//events.jsonl # Pretty-print the first event head -1 ~/.agentdbg/runs//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](/docs/configuration/redaction) 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. ```bash theme={null} export AGENTDBG_DATA_DIR=/path/to/my/agentdbg/data ``` ```yaml theme={null} # .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//`. 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: ```bash theme={null} export AGENTDBG_RUN_NAME="my-experiment-v1" ``` **`name` parameter to `@trace` or `traced_run`** — applies to that specific run and overrides everything else: ```python theme={null} 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: ```bash theme={null} rm -rf ~/.agentdbg/runs/ ``` 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. ```bash theme={null} export AGENTDBG_LOOP_WINDOW=20 export AGENTDBG_LOOP_REPETITIONS=4 ``` ```yaml theme={null} 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](/docs/configuration/overview).