Cortex Code CLI Agent Client Protocol (ACP) support

Cortex Code CLI implements the Agent Client Protocol (ACP), an open standard that lets editors and IDEs embed an external agent as a local subprocess. When you run Cortex Code in ACP mode, your editor drives the session and Cortex Code streams agent responses, tool calls, and file diffs back over stdin/stdout.

ACP support lets you use Cortex Code inside editors that speak ACP without leaving your development environment.

Supported ACP clients

Cortex Code CLI can be used as the agent backend for any ACP-compatible client, including:

  • Zed

  • JetBrains IDEs

  • Visual Studio Code

  • Neovim

  • Goose

  • SnowWork

Refer to your editor’s documentation for the exact steps to configure an external ACP agent.

Prerequisites

Before you configure an ACP client to use Cortex Code, make sure that:

  • Cortex Code CLI is installed and available on your PATH. Run cortex --version to confirm.

  • You have at least one Snowflake connection configured. Run cortex auth login or configure a connection in ~/.snowflake/connections.toml.

  • Your ACP client supports external agents over stdio using newline-delimited JSON (ndjson).

Note

ACP mode does not prompt for authentication. Cortex Code uses the Snowflake connection that you pass with -c (or the default cortexAgentConnectionName from your settings). Authenticate before launching your editor.

Starting Cortex Code in ACP mode

Editors start Cortex Code as a subprocess using the acp serve command. You do not run this command directly in a terminal for normal use; your editor runs it for you based on its configuration.

cortex acp serve -c <connection_name> [--bypass] [-m <model>] [-w <workdir>]

Command options

Option

Description

-c, --connection <name>

Snowflake connection to use. Defaults to the cortexAgentConnectionName setting if omitted.

--bypass

Auto-approve all tool calls for the session. Gated by your administrator’s policy; see managed settings.

-m, --model <model>

Override the default model for the session.

-w, --workdir <path>

Working directory for the agent. Defaults to the process’s current working directory.

Important

Cortex Code speaks ACP over the process’s stdin and stdout. Do not write to stdout from wrapper scripts, shell init files, or pre-run hooks when launching cortex acp serve — any extra output on stdout corrupts the protocol stream. Log to stderr or a file instead.

Configuring an ACP client

Most ACP clients accept a JSON or TOML block describing the subprocess to launch. The minimum configuration specifies the cortex command and the acp serve arguments.

{
  "command": "cortex",
  "args": ["acp", "serve", "-c", "my_connection"]
}

If your editor exposes environment variables for the agent subprocess, you can pass Snowflake credential overrides (for example SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER) through that mechanism. Cortex Code inherits the environment of the ACP client process.

Sessions and conversation history

Sessions started in ACP mode are stored in the same location as sessions created from the Cortex Code CLI:

~/.snowflake/cortex/conversations/<sessionId>.json
~/.snowflake/cortex/conversations/<sessionId>.history.jsonl

The <sessionId>.json file contains a complete snapshot of the session, including metadata and conversation history, written on save. The <sessionId>.history.jsonl file is an append-only log of chat messages that provides incremental durability between snapshots. Both files belong to the session and are managed together.

This means that:

  • You can open the same session later from the Cortex Code CLI with /resume, or from a different ACP client.

  • When an ACP client requests loadSession, Cortex Code replays the full conversation history as ACP SessionUpdate notifications so the editor can repopulate its UI.

  • The /wipe-session command removes the full session trace, including any messages added from ACP clients.

Session configuration options

When a session is created or loaded, Cortex Code reports configuration options that ACP clients render as dropdowns. You can change these options at any time during the session; changes apply to subsequent prompts.

Option

Values

Description

mode

standard, plan, bypass

Controls tool-approval behavior. standard prompts for sensitive actions; plan produces a plan before taking action; bypass auto-approves all tool calls.

model

Any model returned by Cortex Code’s supported-models list

Selects the underlying model for the session. If no model is set, Cortex Code uses its automatic selection (reported as auto).

Note

The bypass option is available only when your administrator has allowed dangerous mode. In managed environments, selecting bypass returns an error and the session’s previous mode is retained. See managed settings.

Extending the agent with editor tools

ACP clients can expose their own tools to Cortex Code by passing a _meta.clientTools array in the newSession or loadSession request. Cortex Code registers each entry as a client tool: when the agent invokes one, Cortex Code calls back to the editor over the ACP connection, the editor executes the tool locally, and the result is returned to the agent.

A client tool definition contains:

Field

Required

Description

name

Yes

Unique tool name. By convention, names should not start with mcp__, which is the reserved prefix for MCP tools.

description

No

Natural-language description shown to the agent.

inputSchema

No

JSON schema describing the tool’s inputs. Defaults to an empty object schema.

Client tools are registered per-session and are removed automatically when the session ends or the ACP connection closes. Permissions for client tools follow the active session mode — bypass auto-approves them, standard and plan prompt the user through the editor.

Streaming updates

While a prompt is in flight, Cortex Code emits ACP SessionUpdate notifications that map to the following events:

Update

Emitted when

agent_message_chunk

The agent streams response text.

agent_thought_chunk

The agent streams internal reasoning (for models that support thinking).

tool_call

The agent invokes a tool. Includes a tool-call identifier, a human-readable title derived from the tool name, a kind, and the raw input.

tool_call_update

A tool call progresses, completes, or fails. For file edits, the update includes a diff content block with the original and new file contents.

plan

Plan mode generates or updates a list of planned steps.

user_message_chunk

A prior user message is replayed during loadSession.

File-edit tools (for example edit, str_replace_editor, and write) emit diff updates so that your editor can render a visual diff inline.

Canceling a prompt

ACP clients can cancel an in-flight prompt by sending a cancel notification for the active session. Cortex Code aborts any running tool calls, stops streaming, and returns a cancelled stop reason. The session itself remains open and can be reused for the next prompt.

Limitations

  • The listSessions method is currently exposed as unstable_listSessions and may change as the ACP specification evolves.

  • Cortex Code slash commands are not yet exposed to ACP clients as first-class commands; use them by typing them as part of a prompt (for example, /skill list).

  • ACP does not provide a separate authentication flow. Cortex Code uses the Snowflake connection configured at launch.

Troubleshooting

The editor reports that the agent exited immediately

Run the same command from a terminal:

cortex acp serve -c <connection_name>

If Cortex Code prints an authentication or connection error, fix the underlying connection before relaunching your editor. Cortex Code exits before speaking ACP if it cannot initialize the Snowflake connection.

The agent hangs on startup or produces garbled output

Confirm that no shell startup file (.bashrc, .zshrc, etc.) or wrapper script writes to stdout. ACP uses stdout as the protocol channel; any stray output breaks the ndjson framing. Redirect diagnostic output to stderr or a log file.

Tool approvals never appear

Check the session mode. In bypass mode, tool calls are auto-approved and no prompts are sent. Switch to standard or plan in your editor’s session settings to restore approvals.

The model dropdown is empty

The model list is fetched from Snowflake at session creation. An empty list usually indicates that the Snowflake connection is invalid or that the account has no models enabled. Verify with cortex auth status and retry.