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 logs are written as JSONL files (one JSON object per line) to:
Because .bot/workspace/ is version-controlled, the full history of every AI session is available to all team members via git log. You can inspect past sessions on any machine that has cloned the repository — no external logging service required.
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:
"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 |
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:
"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 |
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:
git log --all --grep="[task:XXXXXXXX]"
Version control integration
Every session log file is committed to git as part of the .bot/workspace/ directory. This means:
- Team members can inspect the full audit trail with
git log and git diff
- Session history is preserved across machine changes and team handoffs
- Cost and token data is available for analysis in any tool that reads git history
Runtime state — process locks and active worktree maps — lives in .bot/.control/, which is gitignored. Only the auditable workspace data in .bot/workspace/ is version-controlled.