docs: add task lifecycle and agent compatibility pages (#22222)

Closes coder/internal#1359 Closes coder/internal#1329
2026-09-24 15:04:27 +08:00 · 2026-03-04 02:39:48 +02:00
parent 47199ab475
commit 13411c8a8a
7 changed files with 331 additions and 2 deletions
@@ -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.