mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: add task lifecycle and agent compatibility pages (#22222)
Closes coder/internal#1359 Closes coder/internal#1329
This commit is contained in:
Mathias Fredriksson
@@ -0,0 +1,92 @@
|
||||
# Agent compatibility
|
||||
|
||||
Coder Tasks works with a range of AI coding agents, each with different levels
|
||||
of support for preserving conversation context across pause and resume cycles.
|
||||
This page covers which agents support resume, what session data they store,
|
||||
and what to watch out for when configuring persistent storage.
|
||||
|
||||
## Compatibility levels
|
||||
|
||||
Agents with **full support** automatically resume the previous session when a
|
||||
task resumes. The conversation history, tool calls, and context are all
|
||||
preserved, so the agent picks up exactly where it left off.
|
||||
|
||||
Agents with **partial support** have resume wiring in the module but it is
|
||||
either off by default or has known bugs. A module update is needed before resume
|
||||
works reliably. See the linked tracking issue for details.
|
||||
|
||||
Agents with **planned support** have native session persistence but the registry
|
||||
module does not wire it yet. These agents start a fresh conversation on each
|
||||
resume until the module is updated.
|
||||
|
||||
Agents marked **not supported** cannot resume a previous session. They start a
|
||||
fresh conversation on each resume, even if some chat history is visible in the
|
||||
UI.
|
||||
|
||||
## Compatibility matrix
|
||||
|
||||
| Agent | Module | Min version | Support | Tracking | Session data paths | Min storage |
|
||||
|-----------------|----------------------------------------------------------------------------------|-------------|---------------|--------------------------------------------------------------|------------------------------------------------------|---------------------------|
|
||||
| Claude Code | [claude-code](https://registry.coder.com/modules/coder/claude-code) | >= 4.8.0 | Full | - | `~/.claude/` | 100 MB (can grow to GB) |
|
||||
| Codex | [codex](https://registry.coder.com/modules/coder-labs/codex) | - | Partial | [registry#740](https://github.com/coder/registry/issues/740) | `~/.codex/`, `~/.codex-module/` | 100 MB |
|
||||
| Copilot | [copilot](https://registry.coder.com/modules/coder-labs/copilot) | - | Partial | [registry#741](https://github.com/coder/registry/issues/741) | `~/.copilot/` | 50 MB |
|
||||
| OpenCode | [opencode](https://registry.coder.com/modules/coder-labs/opencode) | - | Partial | [registry#742](https://github.com/coder/registry/issues/742) | `~/.local/share/opencode/`, `~/.config/opencode/` | 50 MB |
|
||||
| Auggie | [auggie](https://registry.coder.com/modules/coder-labs/auggie) | - | Planned | [registry#743](https://github.com/coder/registry/issues/743) | `~/.augment/` | 50 MB |
|
||||
| Goose | [goose](https://registry.coder.com/modules/coder/goose) | - | Planned | [registry#744](https://github.com/coder/registry/issues/744) | `~/.local/share/goose/sessions/`, `~/.config/goose/` | 50 MB |
|
||||
| Amazon Q | [amazon-q](https://registry.coder.com/modules/coder/amazon-q) | - | Planned | [registry#746](https://github.com/coder/registry/issues/746) | `~/.local/share/amazon-q/`, `~/.aws/amazonq/` | 50 MB |
|
||||
| Gemini | [gemini](https://registry.coder.com/modules/coder-labs/gemini) | - | Planned | [registry#745](https://github.com/coder/registry/issues/745) | `~/.gemini/` | 200 MB (can reach 400 MB) |
|
||||
| Cursor CLI | [cursor-cli](https://registry.coder.com/modules/coder-labs/cursor-cli) | - | Planned | [registry#747](https://github.com/coder/registry/issues/747) | `~/.cursor/` | 50 MB |
|
||||
| Sourcegraph Amp | [sourcegraph-amp](https://registry.coder.com/modules/coder-labs/sourcegraph-amp) | - | Planned | [registry#748](https://github.com/coder/registry/issues/748) | `~/.config/amp/` (config only) | 10 MB |
|
||||
| Aider | [aider](https://registry.coder.com/modules/coder/aider) | - | Not supported | [registry#739](https://github.com/coder/registry/issues/739) | `.aider.chat.history.md` (workdir) | 50 MB |
|
||||
|
||||
## Persistent storage
|
||||
|
||||
Every agent's session data lives under the home directory, so persisting the
|
||||
home directory with a volume mount is the simplest way to cover all agents at
|
||||
once. This also preserves the AgentAPI state file that Coder uses to stream chat
|
||||
content between the agent and the Tasks UI.
|
||||
|
||||
See
|
||||
[Resource persistence](../admin/templates/extending-templates/resource-persistence.md)
|
||||
for configuration patterns.
|
||||
|
||||
## Agent-specific notes
|
||||
|
||||
**Claude Code**: Session files are JSONL and grow unbounded. Long-running
|
||||
tasks can accumulate multiple gigabytes of data in `~/.claude/projects/`.
|
||||
Monitor disk usage and consider periodic cleanup.
|
||||
|
||||
**Goose**: Sessions are stored in a SQLite database with WAL mode enabled. You
|
||||
must preserve the `-wal` and `-shm` sidecar files alongside the main database,
|
||||
or the session database may become corrupted.
|
||||
|
||||
**Amazon Q**: The Amazon Q Developer CLI has been rebranded to Kiro CLI. The
|
||||
existing module pins a specific CLI version. An authentication tarball is stored
|
||||
alongside session data; if it is lost, the agent must re-authenticate.
|
||||
|
||||
**Gemini**: Session data can reach 400 MB for long-running tasks. You can set
|
||||
the `general.sessionRetention` configuration value to control how long sessions
|
||||
are retained.
|
||||
|
||||
**Sourcegraph Amp**: Conversation threads are stored server-side on
|
||||
Sourcegraph servers, so only local configuration in `~/.config/amp/` needs
|
||||
persistence. The workspace must have network connectivity to Sourcegraph for
|
||||
resume to work.
|
||||
|
||||
**Auggie**: May require connectivity to the Augment cloud backend for session
|
||||
resume. Behavior in fully headless or network-restricted environments is not
|
||||
fully verified.
|
||||
|
||||
**Aider**: The `--restore-chat-history` flag performs a lossy reconstruction
|
||||
from a Markdown log file, but the agent loses full conversation context on each
|
||||
restart and does not support MCP for status reporting. When
|
||||
`enable_state_persistence` is enabled in the module, the Coder UI preserves chat
|
||||
history across pause and resume, but Aider itself starts each session fresh with no
|
||||
memory of previous conversations.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Task lifecycle](./tasks-lifecycle.md) for how pause and resume work and
|
||||
what your template needs.
|
||||
- [Set up Coder Tasks](./tasks.md) in your template.
|
||||
- [Build a custom agent](./custom-agents.md) with MCP support.
|
||||
@@ -6,7 +6,9 @@ The Tasks CLI documentation has moved to the auto-generated CLI reference pages:
|
||||
- [task create](../reference/cli/task_create.md) - Create a task
|
||||
- [task delete](../reference/cli/task_delete.md) - Delete tasks
|
||||
- [task list](../reference/cli/task_list.md) - List tasks
|
||||
- [task logs](../reference/cli/task_logs.md) - Show task logs
|
||||
- [task logs](../reference/cli/task_logs.md) - Show a task's logs
|
||||
- [task pause](../reference/cli/task_pause.md) - Pause a task
|
||||
- [task resume](../reference/cli/task_resume.md) - Resume a task
|
||||
- [task send](../reference/cli/task_send.md) - Send input to a task
|
||||
- [task status](../reference/cli/task_status.md) - Show task status
|
||||
|
||||
|
||||
@@ -33,6 +33,27 @@ This will start the MCP server and report activity back to the Coder control pla
|
||||
> [!NOTE]
|
||||
> See [this version of the Goose module](https://github.com/coder/registry/blob/release/coder/goose/v1.3.0/registry/coder/modules/goose/main.tf) source code for a real-world example of configuring reporting via MCP. Note that in addition to setting up reporting, you'll need to make your template [compatible with Tasks](./tasks.md#option-2-create-or-duplicate-your-own-template), which is not shown in the example.
|
||||
|
||||
## Pause and resume
|
||||
|
||||
Custom agents can support task pause and resume by enabling state
|
||||
persistence on the agentapi module. Set `enable_state_persistence = true`
|
||||
so that AgentAPI saves and restores conversation history across pause and
|
||||
resume cycles:
|
||||
|
||||
```hcl
|
||||
module "agentapi" {
|
||||
source = "registry.coder.com/coder/agentapi/coder"
|
||||
version = ">= 2.2.0"
|
||||
agent_id = coder_agent.main.id
|
||||
enable_state_persistence = true
|
||||
# ...
|
||||
}
|
||||
```
|
||||
|
||||
Your template also needs persistent storage and a sufficient graceful
|
||||
shutdown timeout. See [Task lifecycle](./tasks-lifecycle.md) for the full
|
||||
requirements.
|
||||
|
||||
## Contributing
|
||||
|
||||
We welcome contributions for various agents via the [Coder registry](https://registry.coder.com/modules?tag=agent)! See our [contributing guide](https://github.com/coder/registry/blob/main/CONTRIBUTING.md) for more information.
|
||||
|
||||
@@ -0,0 +1,190 @@
|
||||
# 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](../user-guides/workspace-scheduling.md) for the
|
||||
full list of activity types.
|
||||
|
||||
## What gets preserved
|
||||
|
||||
Three things survive a pause:
|
||||
|
||||
1. **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.
|
||||
|
||||
1. **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.
|
||||
|
||||
1. **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](./agent-compatibility.md) 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](../admin/templates/extending-templates/resource-persistence.md)
|
||||
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:
|
||||
|
||||
```hcl
|
||||
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](./agent-compatibility.md) 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](./custom-agents.md#pause-and-resume),
|
||||
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:
|
||||
|
||||
```hcl
|
||||
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:
|
||||
|
||||
```hcl
|
||||
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.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Agent compatibility](./agent-compatibility.md) for session persistence
|
||||
support and minimum module versions.
|
||||
- [Resource persistence](../admin/templates/extending-templates/resource-persistence.md)
|
||||
for configuring persistent storage in templates.
|
||||
- [Workspace scheduling](../user-guides/workspace-scheduling.md) for how
|
||||
auto-stop and activity detection work.
|
||||
@@ -141,6 +141,17 @@ Coder can automatically generate a name your tasks if you set the `ANTHROPIC_API
|
||||
|
||||
If you tried Tasks and decided you don't want to use it, you can hide the Tasks tab by starting `coder server` with the `CODER_HIDE_AI_TASKS=true` environment variable or the `--hide-ai-tasks` flag.
|
||||
|
||||
## Pausing and resuming tasks
|
||||
|
||||
Tasks automatically pause when the workspace reaches its idle timeout,
|
||||
freeing compute resources. While paused, you can view a snapshot of the
|
||||
last conversation messages. When you resume or send a new message, the
|
||||
workspace restarts and the agent picks up where it left off if the agent
|
||||
and template support session persistence.
|
||||
|
||||
For details on how pause and resume works and what your template needs,
|
||||
see [Task lifecycle](./tasks-lifecycle.md).
|
||||
|
||||
## Command Line Interface
|
||||
|
||||
See [Tasks CLI](./cli.md).
|
||||
|
||||
Reference in New Issue
Block a user