Skip to main content
dotbot tracks each autonomous run as a session. A session captures the AI provider used, which tasks were processed, token and cost metrics, turn boundaries, error details, and wall-clock timing. Session records are stored in .bot/workspace/sessions/ and are version-controlled, giving your team a complete history of every autonomous run. The runtime uses these 5 tools in a strict order: session_initialize at the start, session_update and session_increment_completed throughout, and session_get_state or session_get_stats for monitoring.

​
session_initialize

Initialises a new autonomous session, sets up state tracking, and acquires the session lock to prevent concurrent runs within the same workflow slot. This tool must be called at the start of every autonomous execution before any task tools are used. Required: session_type.
​
session_type
string
required
Type of session. One of:
  • autonomous — Full autonomous execution loop managed by the runtime.
  • manual — Single-task or interactive session initiated by the user.
Returns the new session_id that must be passed to steering_heartbeat throughout the session.

​
session_get_state

Returns the full current session state, including all accumulated metrics for the active session. Takes no parameters. The returned state object includes: session ID, start time, current task ID, status, auth method, tasks completed, tasks failed, tasks skipped, and consecutive failure count. Use this tool when you need granular detail about the current run. For a lighter-weight snapshot, use session_get_stats instead.

​
session_get_stats

Returns comprehensive session statistics including total runtime, completion rate, failure rate, and aggregated token and cost data. Takes no parameters.
session_get_stats returns aggregate statistics across the current session. For a high-level snapshot without detail overhead, call this instead of session_get_state.

​
session_update

Updates specific fields of the current session state. All parameters are optional — only the fields you supply are changed. Call this tool whenever the session moves to a new task, changes status, or encounters a failure.
​
current_task_id
string
ID of the task currently being processed.
​
status
string
Session status. One of running, paused, stopped.
​
auth_method
string
Authentication method in use. One of claude_pro, api_key.
​
tasks_failed
integer
Cumulative number of failed tasks for this session.
​
tasks_skipped
integer
Cumulative number of skipped tasks for this session.
​
consecutive_failures
integer
Number of consecutive task failures. The runtime uses this to trigger circuit-breaker logic when it exceeds a configured threshold.

​
session_increment_completed

Increments the tasks_completed counter by one and resets consecutive_failures to zero. Call this tool immediately after successfully completing a task. Takes no parameters.
Always pair session_increment_completed with task_mark_done. Both tools must be called to keep session statistics and the task queue in sync. Calling one without the other will cause dashboard metrics to diverge from the actual task state.