coder · bpmct · Jun 30, 2025 · Jun 30, 2025 · Jun 30, 2025 · Jun 30, 2025
diff --git a/docs/ai-coder/coming-soon.md b/docs/ai-coder/coming-soon.md
@@ -0,0 +1 @@
+Coming soon
diff --git a/docs/ai-coder/custom-agents.md b/docs/ai-coder/custom-agents.md
@@ -1,16 +1,6 @@
 # Custom Agents
 
-> [!NOTE]
->
-> This functionality is in beta and is evolving rapidly.
->
-> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
-> Always review AI-generated content before using it in critical systems.
->
-> Join our [Discord channel](https://discord.gg/coder) or
-> [contact us](https://coder.com/contact) to get help or share feedback.
-
-Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder.
+Custom agents beyond the ones listed in the [Coder registry](https://registry.coder.com/modules?tag=agent) can be used with Coder Tasks.
 
 ## Prerequisites
 

diff --git a/docs/ai-coder/ide-agents.md b/docs/ai-coder/ide-agents.md
@@ -0,0 +1 @@
+Document coming soon on how to pre-install IDE agents, configure your LLM provider, etc.
diff --git a/docs/ai-coder/index.md b/docs/ai-coder/index.md
@@ -1,37 +1,19 @@
-# Use AI Coding Agents in Coder Workspaces
+# Run AI Coding Agents in Coder
 
-> [!NOTE]
->
-> This functionality is in beta and is evolving rapidly.
->
-> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
-> Always review AI-generated content before using it in critical systems.
->
-> Join our [Discord channel](https://discord.gg/coder) or
-> [contact us](https://coder.com/contact) to get help or share feedback.
+Learn how to run & manage coding agents with Coder, both alongside existing workspaces and for background task execution.
 
-AI Coding Agents such as [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), [Goose](https://block.github.io/goose/), and [Aider](https://github.com/paul-gauthier/aider) are becoming increasingly popular for:
+## Agents in the IDE
 
-- Protyping web applications or landing pages
-- Researching / onboarding to a codebase
-- Assisting with lightweight refactors
-- Writing tests and draft documentation
-- Small, well-defined chores
+Coder [integrates with IDEs](../user-guides/workspace-access/index.md) such as Cursor, Windsurf, and Zed that include built-in coding agents to work alongside developers. Additionally, template admins can [pre-install extensions](https://registry.coder.com/modules/coder/vscode-web) for agents such as GitHub Copilot and Roo Code.
 
-With Coder, you can self-host AI agents in isolated development environments with proper context and tooling around your existing developer workflows. Whether you are a regulated enterprise or an individual developer, running AI agents at scale with Coder is much more productive and secure than running them locally.
+These agents work well inside existing Coder workspaces as they can simply be enabled via an extension or are built-into the editor. 
 
-![AI Agents in Coder](../images/guides/ai-agents/landing.png)
+## Agents with Coder Tasks (Beta)
 
-## Prerequisites
+In cases where the IDE is secondary, such as protyping or long-running background jobs, agents like Claude Code or Aider are better for the job and new SaaS interfaces like [Devin](https://devin.ai) and [ChatGPT Codex](https://openai.com/index/introducing-codex/) are emerging.
 
-Coder is free and open source for developers, with a [premium plan](https://coder.com/pricing) for enterprises. You can self-host a Coder deployment in your own cloud provider.
+[Coder Tasks](./tasks.md) is a new interface inside Coder to run and manage coding agents with a chat-based UI. Unlike SaaS-based products, Coder Tasks is self-hosted (included in your Coder deployment) and allows you to run any terminal-based agent such as Claude Code or Codex's Open Source CLI.
 
-- A [Coder deployment](../install/index.md) with v2.21.0 or later
-- A Coder [template](../admin/templates/index.md) for your project(s).
-- Access to at least one ML model (e.g. Anthropic Claude, Google Gemini, OpenAI)
-  - Cloud Model Providers (AWS Bedrock, GCP Vertex AI, Azure OpenAI) are supported with some agents
-  - Self-hosted models (e.g. llama3) and AI proxies (OpenRouter) are supported with some agents
+![Coder Tasks UI](../images/guides/ai-agents/tasks-ui.png)
 
-## Table of Contents
-
-<children></children>
+[Learn more about Coder Tasks](./tasks.md) to how to get started and best practices.
diff --git a/docs/ai-coder/index.old.md b/docs/ai-coder/index.old.md
@@ -0,0 +1,37 @@
+# Use AI Coding Agents in Coder Workspaces
+
+> [!NOTE]
+>
+> This functionality is in beta and is evolving rapidly.
+>
+> When using any AI tool for development, exercise a level of caution appropriate to your use case and environment.
+> Always review AI-generated content before using it in critical systems.
+>
+> Join our [Discord channel](https://discord.gg/coder) or
+> [contact us](https://coder.com/contact) to get help or share feedback.
+
+AI Coding Agents such as [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), [Goose](https://block.github.io/goose/), and [Aider](https://github.com/paul-gauthier/aider) are becoming increasingly popular for:
+
+- Protyping web applications or landing pages
+- Researching / onboarding to a codebase
+- Assisting with lightweight refactors
+- Writing tests and draft documentation
+- Small, well-defined chores
+
+With Coder, you can self-host AI agents in isolated development environments with proper context and tooling around your existing developer workflows. Whether you are a regulated enterprise or an individual developer, running AI agents at scale with Coder is much more productive and secure than running them locally.
+
+![AI Agents in Coder](../images/guides/ai-agents/landing.png)
+
+## Prerequisites
+
+Coder is free and open source for developers, with a [premium plan](https://coder.com/pricing) for enterprises. You can self-host a Coder deployment in your own cloud provider.
+
+- A [Coder deployment](../install/index.md) with v2.21.0 or later
+- A Coder [template](../admin/templates/index.md) for your project(s).
+- Access to at least one ML model (e.g. Anthropic Claude, Google Gemini, OpenAI)
+  - Cloud Model Providers (AWS Bedrock, GCP Vertex AI, Azure OpenAI) are supported with some agents
+  - Self-hosted models (e.g. llama3) and AI proxies (OpenRouter) are supported with some agents
+
+## Table of Contents
+
+<children></children>
diff --git a/docs/ai-coder/mcp-servers.md b/docs/ai-coder/mcp-servers.md
@@ -0,0 +1 @@
+# Docs on MCP Servers
diff --git a/docs/ai-coder/tasks.md b/docs/ai-coder/tasks.md
@@ -0,0 +1,64 @@
+# Coder Tasks (Beta)
+
+Coder Tasks is an interface for running & managing coding agents such as Claude Code and Aider, powered by Coder workspaces.
+
+![Tasks UI](../images/guides/ai-agents/tasks-ui.png)
+
+Coder Tasks is best for cases where the IDE is secondary, such as prototyping or running long-running background jobs. However, tasks run inside full workspaces so developers can [connect via an IDE](../user-guides/workspace-access) to take a task to completion.
+
+> [!NOTE]
+> Coder Tasks is free and open source. If you are a Coder Premium customer or want to run hundreds of tasks in the background, [contact us](https://coder.com/contact) for roadmap information and volume pricing.
+
+## Supported Agents (and Models)
+
+Any terminal-based agent that supports Model Context Protocol (MCP) can be integrated with Coder Tasks, including your own custom agents.
+
+Out of the box, agents like Claude Code, Aider, Goose, and Amazon Q are supported with built-in modules that can be added to a template. [See all agent modules in the Registry](https://registry.coder.com/modules?search=tag%3Aagent)
+
+Enterprise LLM Providers such as AWS Bedrock, GCP Vertex and proxies such as LiteLLM can be used as well in order to keep intellectual property private. Self-hosted models such as llama4 can also be configured with specific agents, such as Aider and Goose.
+
+## Architecture
+
+Each task runs inside its own Coder workspace for isolation purposes. Agents like Claude Code also run in the workspace, and can be pre-installed via a module in the Coder Template. Agents then communicate with your LLM provider, so no GPUs are directly required in your workspaces for inference.
+
+<div class="tabs">
+
+## High-Level
+
+![High-Level Architecture](../images/guides/ai-agents/architecture-high-level.png)
+
+## In-Depth
+
+Coming soon!
+
+</div>
+
+Coder's [built-in modules for agents](https://registry.coder.com/modules?search=tag%3Aagent) will pre-install the agent alongside [AgentAPI](https://github.com/coder/agentapi). AgentAPI is an open source project developed by Coder which improves status reporting and the Chat UI, regardless of which agent you use.
+
+## Getting Started with Tasks
+
+### Option 1&rpar; Import and Modify Our Example Template
+
+Our example template is the best way to experiment with Tasks with a [real world demo app](https://github.com/gothinkster/realworld). The application is running in the background and you can experiment with coding agents.
+
+![Tasks UI with realworld app](../images/guides/ai-agents/realworld-ui.png)
+
+Try prompts such as:
+
+- "rewrite the backend in go"
+- "document the project structure"
+- "change the primary color theme to purple"
+
+To import the template and begin configuring it, follow the [documentation in the Coder Registry](https://comingsoon.com)
+
+### Option 2&rpar; Create or Duplicate Your Own Template
+
+Because Tasks run unpredictable AI agents, often for background tasks, we recommend creating a seperate template for Coder Tasks with limited permissions.
+
+You can always duplicate your existing template, then apply seperate network policies/firewalls/permissions to the template. From there, follow the docs for one of our [built-in modules for agents](https://registry.coder.com/modules?search=tag%3Aagent) in order to add it to your template, configure your LLM provider.
+
+Alternatively, follow our guide for [custom agents](./custom-agents.md)
+
+## Next Steps
+
+<children></children>
diff --git a/docs/ai-coder/use-cases.md b/docs/ai-coder/use-cases.md
@@ -0,0 +1 @@
+Coming Soon
diff --git a/docs/images/guides/ai-agents/architecture-high-level.png b/docs/images/guides/ai-agents/architecture-high-level.png
diff --git a/docs/images/guides/ai-agents/realworld-ui.png b/docs/images/guides/ai-agents/realworld-ui.png
diff --git a/docs/images/guides/ai-agents/tasks-ui.png b/docs/images/guides/ai-agents/tasks-ui.png
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Document coming soon on how to pre-install IDE agents, configure your LLM provider, etc.