ACP editors

empryo acp lets an editor drive Empryo over the Agent Client Protocol. ACP runs through the shared Empryo engine, including its tools, session journal and context management. The editor owns the chat interface.

This command is available in ACP development builds. A released build that reports an unknown command does not include this integration.

Connect from the desktop appLink to this section

ACP-enabled desktop builds include the engine. You do not need a separate CLI installation, Bun or Node.

1. Open Empryo, sign in to a provider and choose your default model.
2. Open Settings and search for ACP.
3. Choose Set up Zed or Set up T3 Code. Empryo adds itself to that editor's settings (Zed's agent_servers, T3 Code's providers) and keeps everything else in the file. Choose Open Zed or Open T3 Code to start it.
4. For any other ACP editor, choose Other editors to copy the agent command, or the Zed settings block, and open the setup guide.

The copied configuration uses the installed application's absolute path with --acp. The editor starts its bundled engine over stdio without opening another Empryo window. You can close the desktop window while using the editor. If you move the application, copy its connection configuration again.

Development builds copy a connection to the local checkout and require its dependencies. A published build without the ACP settings entry does not include this integration.

Connect from the CLILink to this section

Run empryo in your project. Sign in through /login or configure credentials through /keys, then choose your default model with /model. Both desktop and CLI connections use Empryo's credentials, not API keys stored in the editor.

With the CLI installed, an editor launches this process:

empryo acp

Stdout contains only newline-delimited JSON-RPC. Diagnostics go to stderr. Do not wrap the command in a script that prints a banner to stdout.

For a source checkout, use the absolute path to Bun as the command and these arguments:

["/absolute/path/to/empryo/apps/cli/src/boot.tsx", "acp"]

One-command setupLink to this section

empryo acp setup zed
empryo acp setup t3

setup zed adds Empryo to your Zed settings under agent_servers (~/.config/zed/settings.json, or %APPDATA%\Zed\settings.json on Windows), pointing at the Empryo you ran it with, keeps your other settings and comments, then opens Zed in the current folder. setup t3 adds an Empryo local ACP provider (providerInstances.acpRegistry_empryo) to T3 Code's settings (~/.t3/userdata/settings.json, or $T3CODE_HOME/userdata/settings.json), which a running T3 Code picks up without a restart, then opens T3 Code. Add --no-open to only write the settings. Running either command again updates the same entry instead of adding another.

ZedLink to this section

Run empryo acp setup zed, or open Agent Settings, select External Agents, and add a custom agent. Zed stores it under agent_servers:

{
  "agent_servers": {
    "Empryo": {
      "type": "custom",
      "command": "empryo",
      "args": ["acp"],
      "env": {}
    }
  }
}

Use an absolute executable path if Zed cannot find empryo. Open your project, then choose Empryo from the Agent panel's new-thread menu. The model and mode selectors come from Empryo.

Zed's provider sign-in is separate. An Empryo thread does not require a Zed-hosted model subscription. See Zed's external-agent documentation.

For an isolated test instance, launch Zed with --user-data-dir. Its settings belong in that directory's config/settings.json, not your normal Zed settings file.

T3 CodeLink to this section

Verified with T3 Code Nightly `0.0.46-nightly.20261015.3176` on macOS arm64, Linux arm64 and Windows x64. Versions with Local ACP command in Add provider support these steps without patches.

The fastest way is Settings → ACP → Set up T3 Code in the Empryo app, or empryo acp setup t3. To add it by hand instead:

1. In Empryo, open Settings → ACP → Other editors and choose Copy agent command. This copies JSON containing command and args.
2. In T3 Code, open Settings → Providers. Select the computer where Empryo is installed, then choose Add provider → Local ACP command.
3. Put the JSON's command value in Executable, without the surrounding JSON quotes. Choose Add argument for each args entry, in order. Put one literal argument in each row; do not paste the JSON array or join everything into a shell command.
4. Choose Next, set Label to Empryo, then choose Add instance. Leave the generated instance ID unchanged. No T3-hosted model subscription is required for this local agent.
5. Return to the workspace. Choose Add project → Local folder, enter your project's path, and open a new thread. In its model picker, choose Empryo and one of your configured Empryo models.
6. Send a prompt. T3 starts Empryo's bundled engine, displays its tool activity and streams the answer. The Empryo window can be closed.

For a typical macOS installation, the copied values are:

{
  "command": "/Applications/Empryo.app/Contents/MacOS/Empryo",
  "args": ["--acp"]
}

Use the values copied from your own installation, not the example path. Windows and Linux use their own executable paths. With a separately installed CLI, Executable can instead be its absolute empryo path and the argument row is acp.

Verified clients and platformsLink to this section

Each run below registered Empryo through the editor's own UI, sent a prompt, watched Empryo call its read tool on a file in the project and show that file's exact content as the answer.

The ACP Test Compatibility Kit (acp-tck 0.2.0) reports CONFORMANT for both protocol v1 and v2 on macOS arm64, Linux arm64, Linux x64 and Windows x64, with zero failures. Session delete and fork are tested and pass. Its skipped items are capabilities Empryo does not advertise: audio input, additional workspace roots and the logout and authentication flows.

Other ACP clientsLink to this section

Use stdio transport with command: "empryo" and args: ["acp"]. Send an absolute workspace path in session/new.cwd. Each process serves one workspace; start another process for a different workspace.

The same stdio entrypoint supports ACP v1 and native ACP v2 through the official SDK protocol router. Zed uses the v1 path; the tested latest T3 Code runtime uses native v2. Each connection negotiates one version, and its subsequent frames follow that version.

Models, modes and commandsLink to this section

The server returns model and mode configuration options during session setup. Clients change them through session/set_config_option. On v1, session/set_mode and the compatibility endpoint session/set_model remain available. Native v2 uses grouped configuration options instead of the retired mode/model methods.

Modes: Code, Architect, Plan, Socratic, Challenge, Autonomous, Orchestrate and Duck. They behave as in the desktop app, because the mode lives in the engine. Orchestrate runs its agent graphs as ordinary tool calls; the visual graph view is a desktop-app panel. Morph is not offered, because it builds desktop Cells.

An Effort option (ACP category thought_level) appears when the current model has reasoning levels; T3 Code shows it next to the mode, as in "Code · Medium".

The model picker includes the current model, configured models and cached or bundled choices from available providers. Large provider groups show a bounded set of choices rather than fetching the entire remote catalog during startup.

Commands arrive as prompt text. Empryo announces available commands to the editor: /compact plus your installed skills and custom agents. /compact summarises earlier turns of the session. Commands that open Empryo's own terminal or desktop panels do not open those panels inside an external editor.

File access and permissionsLink to this section

On v1, when the client advertises fs.readTextFile, Empryo requests file contents through the client, including unsaved text buffers. File paths are absolute and line numbers are 1-based. No client filesystem method is called without its advertised capability. Native v2 uses engine-owned filesystem access; it does not use the retired v1 client filesystem delegation.

Tool notifications contain a title, the tool's programmatic name, kind, status and file locations when available.

During a turn Empryo reports context usage and session cost with usage_update, and the session title with session_info_update.

When the client advertises elicitation.form, questions from the agent open as a form with the offered answers instead of a permission prompt.

Clients that advertise session.notices receive provider retries and engine notices as notice updates; others receive them as thoughts. Clients that advertise session.compaction receive one ID-addressed compaction_update per compaction, including automatic ones; others receive a short message. Reasoning uses the separate thought channel. Task and implementation plans use ACP plan updates.

Gated destructive operations, writes outside the workspace and supported interactive choices go to the client's permission interface. Allow and reject apply to that request. A denied external edit leaves the file unchanged.

The shared engine's existing policy permits external reads and writes inside its configuration and OS temporary directories without an outside-workspace prompt. The ACP adapter does not impose a different policy.

Sessions and cancellationLink to this section

ACP session identifiers are opaque. Keep the whole identifier when storing it or sending it back. Multiple sessions in one workspace share the engine, but only one prompt runs on a connection at a time. A conflicting request returns an error rather than switching the running turn's workspace.

The shared engine writes the canonical session journal. On v1, session/load restores a saved conversation and replays its text to the client; session/resume restores it without replay. On v2, session/list discovers persisted sessions and session/resume restores them. The next provider request contains the restored conversation, not just a replay in the editor. Closing an in-memory session does not delete its journal. session/fork copies a session's conversation into a new session that the next turn continues from. session/delete removes a session from session/list (v1 and v2); once every tab of a saved session is deleted, its journal is deleted too.

On v1, session/prompt completes with a stop reason and session/cancel is a notification. Native v2 accepts a prompt with its message identifier before generation completes, then reports message/tool updates and running, requires-action or idle state. Cancellation reaches the same shared engine and ends the active turn. Tool calls left unfinished are reported as failed instead of leaving a progress indicator running.

Connection lifecycleLink to this section

Session creation, restoration and model/mode changes reserve the connection while they are in progress. Conflicting control requests receive an error rather than racing the same engine; cancellation remains available immediately.

Protocol output respects editor backpressure. If a protocol write fails or the editor disconnects, Empryo cancels the active work and closes its owned engine instead of leaving an idle background process. Diagnostics, including startup diagnostics, go to stderr rather than the JSON-RPC stream.

A protocol write that does not complete within 30 seconds closes the connection. Native-v2 turns retain their 30-minute turn deadline; cancellation cleanup and engine shutdown have five-second grace periods. If the engine cannot stop, the connection closes rather than advertising a misleading idle state.

Supported input and limitsLink to this section

Text, text-resource context and PNG, JPEG, WebP and GIF images use the engine's prompt input. Audio is not advertised. Unsupported image formats return an error.

Client-supplied MCP servers use stdio or HTTP on v2; v1 also retains SSE support. Definitions are converted into the shared engine's MCP configuration. MCP-over-ACP is not advertised or supported.

Client terminals are optional. Empryo's engine runs commands itself; do not infer that it delegates terminal ownership to an editor merely because that editor advertises terminal support.

TroubleshootingLink to this section

• No model configured. Choose a model in Empryo before starting the editor thread.
• Provider rejects a turn. Check stderr and the provider's sign-in or quota. A failed model call returns an error, not a successful empty answer.
• Wrong workspace or missing directory. Supply a valid absolute path. Empryo refuses to continue against a different directory when adoption fails.
• Connection closes on startup. Check the executable path, ensure stdout contains no wrapper output, and read the editor's agent log.
• Empty resumed transcript. Use the exact saved ACP identifier. The canonical journal, not the old snapshot files, holds current history.

See the ACP protocol reference for client-side message shapes and capability negotiation.