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

# Session management MCP tools reference

> Reference for all 5 dotbot session management MCP tools - initialising sessions, reading state and stats, updating fields, and tracking completed tasks.

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

<ParamField path="session_type" 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.
</ParamField>

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.

<Note>
  `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`.
</Note>

***

## `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.

<ParamField path="current_task_id" type="string">
  ID of the task currently being processed.
</ParamField>

<ParamField path="status" type="string">
  Session status. One of `running`, `paused`, `stopped`.
</ParamField>

<ParamField path="auth_method" type="string">
  Authentication method in use. One of `claude_pro`, `api_key`.
</ParamField>

<ParamField path="tasks_failed" type="integer">
  Cumulative number of failed tasks for this session.
</ParamField>

<ParamField path="tasks_skipped" type="integer">
  Cumulative number of skipped tasks for this session.
</ParamField>

<ParamField path="consecutive_failures" type="integer">
  Number of consecutive task failures. The runtime uses this to trigger circuit-breaker logic when it exceeds a configured threshold.
</ParamField>

***

## `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.

<Warning>
  Always pair `session_increment_completed` with `task_set_status(done)`. Both calls must be made 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.
</Warning>