> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit trail and session logging in dotbot

> Learn what dotbot captures in session logs, how to configure log levels and cost tracking, and how to trace commits back to the tasks that produced them.

Every action dotbot takes — every prompt sent, every answer received, every code change committed — is captured in structured logs that live inside your repository. This makes it straightforward to review what the AI did, how long it took, and what it cost, both for accountability and for continuous improvement of your workflow.

## Session log location

Session data lives under two directories, split by whether it is live runtime state or retained history:

```
.bot/workspace/sessions/runs/      live run state for in-flight sessions
.bot/workspace/sessions/history/   retained session history
```

`sessions/runs/` holds the state of sessions that are currently running. It is gitignored, because it is transient runtime state rather than an audit record. `sessions/history/` holds the retained history and is tracked in git, so the record of past sessions travels with the repository.

Alongside the session directories, the runtime appends one JSON line per state change to the activity log at `.bot/.control/activity.jsonl`. Each line records the timestamp, the event type, the task and run IDs, the `from` and `to` states on a transition, the actor, and an optional reason. The runtime is the sole writer, so the activity log is a single, ordered record of everything that happened. It is gitignored as runtime state.

## What is captured

Each log entry records a specific event in the AI session lifecycle. The fields captured include:

* **Token counts** — input and output tokens consumed per turn
* **Costs** — monetary cost per turn based on provider pricing
* **Turn boundaries** — timestamps marking the start and end of each AI exchange
* **Wall-clock gaps** — idle time between turns, which is useful for detecting blocked or stalled tasks
* **Agent completion reasons** — why the agent stopped (task complete, tool call, error, or limit reached)
* **Error details** — structured error information when a session fails or is interrupted

<Tip>
  Wall-clock gaps are particularly useful when diagnosing tasks that appear to run but make no progress. A large gap between turns often means the AI is waiting on a tool call or an external resource.
</Tip>

## Log levels

dotbot uses separate log levels for the console and for the JSONL file. Configure them in your project's `settings.default.json`:

```json theme={null}
"logging": {
  "console_level": "Info",
  "file_level": "Debug",
  "retention_days": 7,
  "max_file_size_mb": 50
}
```

| Setting            | Values          | Description                                       |
| ------------------ | --------------- | ------------------------------------------------- |
| `console_level`    | `Info`, `Debug` | Minimum level written to terminal output          |
| `file_level`       | `Info`, `Debug` | Minimum level written to the JSONL log file       |
| `retention_days`   | integer         | Number of days before old log files are pruned    |
| `max_file_size_mb` | integer         | Maximum size of a single log file before rotation |

Set `file_level` to `Debug` (the default) to capture full turn-by-turn detail. Use `Info` in high-volume environments where log size is a concern.

## Cost tracking settings

dotbot tracks the AI cost of each task and compares it against an estimated human-equivalent cost. Configure the cost model in `settings.default.json`:

```json theme={null}
"costs": {
  "hourly_rate": 50,
  "ai_cost_per_task": 0.50,
  "ai_speedup_factor": 10,
  "currency": "USD"
}
```

| Setting             | Description                                               |
| ------------------- | --------------------------------------------------------- |
| `hourly_rate`       | Blended developer hourly rate used to estimate human cost |
| `ai_cost_per_task`  | Expected AI API spend per task, used for budget alerts    |
| `ai_speedup_factor` | Multiplier comparing AI throughput to human throughput    |
| `currency`          | Currency for cost display in the dashboard                |

These figures feed into the **Overview** tab's ROI summary, which shows cumulative AI spend alongside the equivalent human-hours saved.

## Viewing session history in the dashboard

The **Decisions** tab in the dashboard surfaces the decision log — the record of architectural and design choices made by the AI during session execution. Each entry includes the decision text, its current status (accepted, deprecated, or superseded), the rationale, and links to any decisions it supersedes.

To trace a specific commit back to the task that produced it, look at the commit message. dotbot tags every commit it authors with a `[task:XXXXXXXX]` identifier, where `XXXXXXXX` is the task ID. You can search the git log for this tag to find all commits associated with a given task:

```powershell theme={null}
git log --all --grep="task:a1b2c3d4"
```

## Version control integration

Retained workspace data — task files, decisions, and `sessions/history/` — is committed to git as part of the `.bot/workspace/` directory. This means:

* Team members can inspect the retained audit trail with `git log` and `git diff`
* Session history is preserved across machine changes and team handoffs
* Task and decision data is available for analysis in any tool that reads git history

<Note>
  Transient runtime state is gitignored: process locks, the worktree map, and the activity log under `.bot/.control/`, and the live run logs under `.bot/workspace/sessions/runs/`. Only the retained workspace data — including `.bot/workspace/sessions/history/` — is version-controlled.
</Note>