docs(www): add CLI, ACP, Zed, RPC and plugin docs

CLI section with ACP, Zed setup, RPC server and reference pages, a Customize section with plugin guides, Zed screenshots and a Placeholder component for media still to come. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
sanchitrk · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026 · Oct 10, 2026 · 06be85de67de568fd7cf5b1c2d769954c0a5fb6a
commit 06be85de67de568fd7cf5b1c2d769954c0a5fb6a
diff --git a/sites/www/content/docs/cli/acp.mdx b/sites/www/content/docs/cli/acp.mdx
@@ -0,0 +1,164 @@
+---
+title: ACP
+description: Use CodeWork as the agent inside your editor. The CLI speaks the Agent Client Protocol, so Zed and any other ACP client can drive it.
+---
+
+## Overview
+
+The [Agent Client Protocol](https://agentclientprotocol.com) (ACP) is an open standard for connecting coding agents to editors. The editor owns the interface: the chat panel, the file picker, the diff view. The agent owns the work: models, tools, and sessions.
+
+`codework acp` turns the CLI into an ACP server. Your editor launches it as a child process and talks to it over stdio. You get the same agent, models, plugins, and session history you have in the terminal, inside the editor you already use.
+
+![CodeWork building a Snake game in Zed's Agent Panel](/images/docs/zed/zed-thread.png)
+
+## Start the ACP server
+
+```bash
+codework acp
+```
+
+You don't normally run this yourself. You tell your editor to run it, as in the [Zed setup](#zed) below. It accepts the [global flags](/docs/cli/reference#global-flags) `--home`, `--database`, and `--user-config-dir`.
+
+## Transport and message format
+
+- **Transport:** stdio. The editor writes requests to CodeWork's stdin and reads responses and notifications from its stdout.
+- **Messages:** JSON-RPC 2.0, one message per line (newline-delimited JSON).
+- **Protocol version:** ACP v1.
+- **Logs:** written to stderr, since stdout is reserved for the protocol.
+
+## Request flow
+
+1. `initialize`: CodeWork reports its name, version, and capabilities.
+2. `session/new`: CodeWork creates a session rooted at the editor's project folder. That folder's `.codework/settings.jsonc` applies, as if you'd run the CLI from it.
+3. `session/prompt`: CodeWork streams its answer, reasoning, and tool calls back as `session/update` notifications, then returns a stop reason.
+4. `session/cancel`: interrupts the running prompt.
+5. `session/list` and `session/load`: list past sessions for the folder and reopen one, replaying its full history.
+
+When the editor closes the connection, CodeWork interrupts anything still running and stops any sandboxes it manages.
+
+## Authentication
+
+ACP sessions use the credentials already in your CodeWork home. The editor can't sign you in, so do it once from the terminal before connecting:
+
+```bash
+codework auth login --openai-codex
+```
+
+Or pass an API key in the environment the editor launches CodeWork with, such as `OPENROUTER_API_KEY` or `GEMINI_API_KEY`. See [Models & Pricing](/docs/models) for every provider.
+
+## Sessions and configuration
+
+ACP sessions are regular CodeWork sessions, stored in the same database as the ones you start with `codework run`. Your editor's history and the CLI see the same sessions.
+
+Each session exposes two selectors the editor shows as pickers:
+
+- **Model:** every model from the providers CodeWork has credentials for. The session's current model stays listed even if its credentials are gone.
+- **Thinking Effort:** the reasoning levels the current model supports. Hidden for models without reasoning.
+
+New sessions start on the default model from your [settings](/docs/cli/using#models-and-settings). CodeWork titles a session from its first prompt and tells the editor.
+
+## Permissions
+
+CodeWork has no permission prompts. It runs every tool, including shell commands and file edits, without asking the editor first, and works on files directly rather than through the editor.
+
+ACP sessions run locally in your project folder. Use [`codework run --sandbox-driver`](/docs/cli/using#sandboxes) when you want isolation.
+
+## Prompt content
+
+| Content                     | Support                                       |
+| --------------------------- | --------------------------------------------- |
+| Text                        | Yes                                           |
+| Images                      | Yes, for models that accept images            |
+| Mentioned files, selections | Yes, sent as embedded context with the prompt |
+| Resource links              | Yes, passed to the model as a link            |
+| Other binary files          | No                                            |
+
+If a plugin in your settings fails to load, CodeWork shows a warning in the conversation so you see it without digging through logs.
+
+## Zed
+
+[Zed](https://zed.dev) has built-in ACP support. Register CodeWork once and it shows up next to Zed's own agent in the Agent Panel.
+
+### 1. Find the CodeWork binary
+
+Zed may not see your shell's `PATH` when it's opened from the Dock or Start menu. Get the absolute path to be safe:
+
+```bash
+which codework
+```
+
+You'll get something like `/Users/you/Library/pnpm/bin/codework`. Use that wherever the config below says `codework`.
+
+### 2. Add CodeWork as a custom agent
+
+Open **Agent Settings**, go to **External Agents**, click **Add Agent**, and choose **Add Custom Agent**. Zed opens your settings file with a new `agent_servers` entry. Fill it in like this:
+
+```json title="~/.config/zed/settings.json"
+{
+	"agent_servers": {
+		"CodeWork": {
+			"type": "custom",
+			"command": "codework",
+			"args": ["acp"],
+			"env": {}
+		}
+	}
+}
+```
+
+- `command` is the CodeWork binary. Use the absolute path from step 1 if `codework` alone doesn't work.
+- `args` must include `acp`. Add any global flags after it, such as `["acp", "--home", "/Users/you/.codework-zed"]`.
+- `env` is passed to CodeWork. Put an API key here if Zed wouldn't otherwise see it, for example `{ "OPENROUTER_API_KEY": "..." }`. Then pick a model such as **DeepSeek V4.1 Flash** from the model picker.
+
+![Zed settings with the CodeWork agent server](/images/docs/zed/zed-settings.png)
+
+### 3. Start a thread
+
+1. Open a project folder in Zed. CodeWork works in this folder.
+2. Open the Agent Panel from the status bar or the command palette.
+3. Open the new-thread menu and choose **CodeWork** under External Agents.
+4. Type a prompt and press `enter`.
+
+![Choosing CodeWork from the new thread menu](/images/docs/zed/zed-new-thread.png)
+
+You can bind a key to `agent: new external agent thread` to jump straight into a new thread.
+
+### Working in a thread
+
+- **Add context:** type `@` to mention a file or symbol, or add a selection to the thread. Paste or drop images if your model accepts them.
+- **Switch models and thinking effort:** use the pickers at the bottom of the panel. Search the model picker by display name, such as "DeepSeek V4.1 Flash", not by its `openrouter/...` ID. Changes apply from the next prompt, and Zed remembers your choice as `default_config_options.model` in the CodeWork entry of its settings.
+- **Set a project default:** to start every thread in a project on the same model, set `model` in that project's [`.codework/settings.jsonc`](/docs/cli/using#models-and-settings).
+- **Stop a turn:** click stop. The partial answer stays in the thread.
+- **Pick up where you left off:** open the Threads Sidebar (`cmd-alt-j` on macOS, `ctrl-alt-j` on Linux and Windows), open **Thread History**, click **Import Threads**, and select CodeWork. Opening an imported thread replays the full conversation.
+
+<Placeholder type="video" title="A CodeWork session in Zed, start to finish">
+	Video: prompt CodeWork to fix a small bug, watch it read files and run tests, switch the model mid-thread, then
+	reopen the thread from history.
+</Placeholder>
+
+## Other editors
+
+Any editor that speaks ACP can run CodeWork with the same command, `codework acp`. See the [list of ACP clients](https://agentclientprotocol.com/overview/clients).
+
+## Troubleshooting
+
+**CodeWork doesn't appear in the Agent Panel.** Check that `agent_servers` is at the top level of your Zed settings and the JSON is valid.
+
+**The thread never starts.** Zed couldn't run the command. Use the absolute path from `which codework`, and make sure the `node` it runs with is version 24 or later.
+
+**The model picker is empty or missing a provider.** CodeWork only lists providers it has credentials for. Run `codework auth status --openai-codex` in a terminal, or add the API key to `env`.
+
+**A plugin warning appears in the thread.** Run `codework plugin install` in the project folder, or `codework plugin list --verbose` to see why it failed.
+
+**Something else.** Run `dev: open acp logs` from Zed's command palette to see the raw messages between Zed and CodeWork.
+
+## Related
+
+<Cards>
+	<Card title="Capabilities" href="/docs/cli/using">
+		Tools, settings, plugins, and sandboxes.
+	</Card>
+	<Card title="RPC Server" href="/docs/cli/rpc">
+		Keep sessions running in a long-lived server.
+	</Card>
+</Cards>
diff --git a/sites/www/content/docs/cli/index.mdx b/sites/www/content/docs/cli/index.mdx
@@ -0,0 +1,86 @@
+---
+title: CodeWork CLI
+sidebarTitle: Overview
+description: Run the CodeWork agent from your terminal, inside your editor over ACP, or as a long-lived server.
+---
+
+The `codework` CLI is the main way to use CodeWork. It runs agent sessions in your repository or in a sandbox, manages models and plugins, and powers every other interface: `codework acp` serves editors and `codework serve` starts the RPC server.
+
+## Getting started
+
+```bash
+pnpm add -g @codeworksh/cli
+```
+
+Then, from your project folder:
+
+```bash
+codework run "Explain how this repository is structured"
+```
+
+<Placeholder type="video" title="Your first CodeWork run">
+	Video: `codework run` exploring a repository, streaming tool calls, then continuing the same session with
+	`--session`.
+</Placeholder>
+
+See [Installation](/docs/cli/installation) for requirements, signing in, and updates.
+
+## Running a prompt
+
+`codework run` sends one prompt, streams CodeWork's answer and tool calls to your terminal, and exits when the turn is done. It prints the session ID so you can continue later.
+
+```bash
+codework run "Inspect the failing tests"
+```
+
+Start the session somewhere other than the current directory with `--cwd`:
+
+```bash
+codework run --cwd ~/work/api "Add a health check endpoint"
+```
+
+## Sessions
+
+Every run is a session, stored in your CodeWork home. Continue one by passing its ID:
+
+```bash
+codework run --session <session-id> "Now fix them"
+```
+
+Sessions are shared across interfaces. A session started with `codework run` can be continued from an [editor](/docs/cli/acp) or through the [RPC server](/docs/cli/rpc), as long as they use the same home.
+
+## Models
+
+Pick a model per run with `--provider` and `--model`. Add `--thinking` to set reasoning effort on models that support it.
+
+```bash
+export OPENROUTER_API_KEY="..."
+
+codework run --provider openrouter --model deepseek/deepseek-v4.1-flash "Plan the database migration"
+```
+
+Browse what's available with `codework models`. Set a default in your settings so you don't have to pass flags every time; see [Capabilities](/docs/cli/using#models-and-settings).
+
+## Sandbox controls
+
+By default CodeWork works directly in your folder. Pass `--sandbox-driver` to run a new session in an isolated remote sandbox instead:
+
+```bash
+codework run --sandbox-driver daytona "Inspect the repository"
+```
+
+The run prints the sandbox ID. Reuse the same sandbox for another session with `--sandbox-id`.
+
+<Placeholder type="video" title="Running CodeWork in a Daytona sandbox">
+	Video: a run with `--sandbox-driver daytona`, showing the sandbox being created, the agent working in it, and the
+	sandbox ID printed at the end.
+</Placeholder>
+
+## Editors and servers
+
+| Command          | Use it for                                                                |
+| ---------------- | ------------------------------------------------------------------------- |
+| `codework acp`   | Using CodeWork as the agent in an [ACP editor](/docs/cli/acp) such as Zed |
+| `codework serve` | Keeping sessions running in a [long-lived server](/docs/cli/rpc)          |
+
+Every command and flag is listed in the [Reference](/docs/cli/reference).
diff --git a/sites/www/content/docs/cli/installation.mdx b/sites/www/content/docs/cli/installation.mdx
@@ -0,0 +1,73 @@
+---
+title: Installation
+description: Install the CodeWork CLI, connect a model, and keep it up to date.
+---
+
+## Requirements
+
+- Node.js 24 or later
+- pnpm
+
+## Install
+
+```bash
+pnpm add -g @codeworksh/cli
+```
+
+Check that it's on your path:
+
+```bash
+codework --help
+```
+
+Every command is `codework <command>`. Add `--help` to any command to see its flags.
+
+## Connect a model
+
+CodeWork needs access to at least one model provider. Sign in with a subscription:
+
+```bash
+codework auth login --openai-codex
+codework auth login --github-copilot
+```
+
+Or set an API key:
+
+```bash
+export OPENROUTER_API_KEY="..."
+export GEMINI_API_KEY="..."
+```
+
+Credentials from `codework auth login` are stored in your CodeWork home (`~/.codework` by default) and refreshed automatically. See [Models & Pricing](/docs/models) for every provider.
+
+Check what CodeWork can see:
+
+```bash
+codework auth status --openai-codex
+codework models
+```
+
+## Where CodeWork keeps its files
+
+| Path                                 | What's in it                                      |
+| ------------------------------------ | ------------------------------------------------- |
+| `~/.codework/settings.jsonc`         | User settings: default model, plugins             |
+| `~/.codework/aikit/auth.json`        | Subscription credentials                          |
+| `~/.codework/models.gen.json`        | The model catalog, refreshed every 15 minutes     |
+| `<project>/.codework/settings.jsonc` | Project settings, layered over your user settings |
+
+Use `--home` on any command to point CodeWork at a different home.
+
+## Update
+
+```bash
+pnpm add -g @codeworksh/cli@latest
+```
+
+## Uninstall
+
+```bash
+pnpm remove -g @codeworksh/cli
+```
+
+This leaves `~/.codework` in place. Delete it too if you want to remove your sessions, settings, and credentials.
diff --git a/sites/www/content/docs/cli/meta.json b/sites/www/content/docs/cli/meta.json
@@ -0,0 +1,4 @@
+{
+	"title": "CLI",
+	"pages": ["index", "installation", "using", "acp", "rpc", "reference"]
+}