HomeRun AI Coding Agents in CoderCoder TasksTask Lifecycle

Task Lifecycle

Tasks can pause when idle and resume when you interact with them again. Pausing frees compute resources while preserving conversation context, so the agent can pick up where it left off. This page covers how pause and resume work, what gets preserved, and what your template needs.

Note

Task pause and resume is in beta. Some details may change in future releases.

How tasks pause

Tasks pause in two ways:

Auto-pause: The workspace idle timeout expires. Tasks use the template's existing default_ttl and activity_bump settings, the same ones that control regular workspace auto-stop. When a task auto-pauses, the build reason is recorded as "idle timeout" and a notification is sent to the task owner.
Manual pause: You can pause a task through the CLI with coder task pause, the API, or the pause button in the Tasks UI.

When a task pauses, the workspace stops. Compute resources are freed and persistent storage remains intact. Stopping a task workspace manually (via the workspace UI or coder stop) triggers the same pause behavior, including log snapshot capture and state persistence. Similarly, starting the workspace (coder start) resumes the task.

Activity detection for tasks

AI agent activity extends the workspace deadline just like SSH or IDE connections do. When an agent reports "working" status through Coder Tasks, the workspace deadline is bumped by the template's activity_bump duration. This prevents auto-pause while the agent is actively working.

See Workspace scheduling for the full list of activity types.

What gets preserved

Three things survive a pause:

Log snapshot: Up to 30 of the last messages from the conversation are captured during shutdown and stored server-side. While paused, coder task logs and the Tasks UI show this snapshot so you can see what the agent was working on.
AgentAPI state: When state persistence is enabled, the full conversation history is saved to a file on persistent storage. After resume, the Tasks UI shows the complete chat history.
AI agent session: Agents that support session persistence (such as Claude Code via ~/.claude/) retain their own context on persistent storage. On resume, the agent picks up where it left off with full memory of the previous conversation.

Note

Log snapshots and AgentAPI state persistence are best-effort. If the shutdown script is interrupted or times out, the workspace still stops normally, but the snapshot may not be captured and chat history may be empty after resume.

If enable_state_persistence is true but the AI agent does not support session resume, the UI shows previous messages but the agent starts fresh with no memory of the conversation. This is expected behavior. See Agent compatibility for which agents support full session resume.

Resuming a task

You can resume a paused task in several ways:

CLI: coder task resume <task>
UI: Click the Resume button on the task page or in the tasks list

Resume starts the workspace, runs startup scripts, starts AgentAPI (which loads its state file if state persistence is enabled), and starts the AI agent (which resumes its session if supported).

Note

Resume requires a full workspace build, which can take several minutes depending on your template.

Requirements

Persistent storage

Templates must have persistent storage (Docker volume, Kubernetes PVC, or similar) that survives workspace stop and start cycles. Without it, the AI agent's session files and the AgentAPI state file are lost on stop.

See Resource persistence for configuration patterns.

Compatible module version

AI agent registry modules handle shutdown scripts and state persistence through the agentapi base module. To enable pause and resume, use a module version that includes this support.

For Claude Code, update the module version in your template:

module "claude-code" {
  source   = "registry.coder.com/coder/claude-code/coder"
  version  = ">= 4.8.0" # Minimum version with pause/resume support
  agent_id = coder_agent.main.id
  # ...
}

Versions 4.8.0 and above set enable_state_persistence = true, which configures the shutdown script and state file automatically.

See Agent compatibility for the minimum module version per agent.

The `enable_state_persistence` variable

The enable_state_persistence variable controls whether AgentAPI saves and restores conversation history across pause and resume cycles. It defaults to false in the agentapi base module. Agent modules that support session persistence, like claude-code, override this to true in their module definition.

When enable_state_persistence is false, the shutdown script still runs to capture log snapshots, but skips saving AgentAPI state. On resume, chat history is not restored.

If you are building a custom agent, set this variable on the agentapi module directly.

Graceful shutdown timeout

Warning

Without this configuration, log snapshots and state persistence may silently fail. The container runtime can terminate the container before the shutdown script finishes.

The shutdown script runs inside the workspace container. The container runtime controls how long the process has to shut down before it is force-terminated. The defaults are often too short:

Docker: 10 seconds
Kubernetes: 30 seconds

The grace period covers not just this shutdown script but also the workspace agent's own graceful shutdown and any other modules that run shutdown scripts. Set at least 1 minute as a baseline. 5 minutes is recommended to account for slow disks, multiple shutdown scripts, and other modules performing cleanup.

Docker: Add to your docker_container resource:

resource "docker_container" "workspace" {
  # Both attributes are needed for graceful shutdown.
  destroy_grace_seconds = 300 # 5 minutes
  stop_timeout          = 300
  stop_signal           = "SIGINT"
  # ...
}

Kubernetes: Add to your kubernetes_pod resource:

resource "kubernetes_pod" "main" {
  timeouts {
    delete = "6m" # Must exceed the grace period below.
  }
  spec {
    termination_grace_period_seconds = 300 # 5 minutes
  }
}

If the container is terminated before the shutdown script finishes, the workspace still stops normally but log snapshots may be missing and chat history may not be restored after resume.