Skip to main content
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:
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
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.

​
Log levels

dotbot uses separate log levels for the console and for the JSONL file. Configure them in your project’s settings.default.json:
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:
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:

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