ACP server

fx acp connects fx to editors that support Agent Client Protocol (ACP). The editor sends prompts and displays replies and tool activity; fx runs the agent.

Configure an ACP client

Configure your client to launch fx with the acp argument. Use the executable and arguments fields in its agent settings:

{
  "command": "/absolute/path/to/fx",
  "args": ["acp"]
}

Set the server process's working directory to your project. fx uses it as the primary workspace; launch a separate process for each project.

fx acp accepts two options:

Option	Description
`--model <id>`	Set the startup model, overriding the saved model when loading a session.
`--log-file <path>`	Write ACP diagnostics to an absolute file path.

Global workspace flags such as --add-dir, --no-additional-dirs, and --context-limit must appear before acp.

Authentication and fx settings

Connect a provider before starting the client. ACP uses your fx provider settings and credentials.

Project instructions and personal settings also apply when you use fx through an editor. MCP servers follow the client-specific rules below.

Supported ACP methods

The client must call initialize first. fx responds with ACP protocol version 1 and supports these methods:

Method	Description
`initialize`	Negotiate protocol capabilities and initialize the connection.
`session/new`	Create and activate a saved session.
`session/load`	Load an exact session ID and replay its history.
`session/resume`	Reconnect to a saved session without replaying its history.
`session/close`	Close the active session.
`session/list`	List saved sessions across workspaces, or filter by an absolute `cwd`.
`session/prompt`	Run one turn in the active session.
`session/cancel`	Cancel the active prompt.
`session/set_config_option`	Change provider, model, mode, or supported reasoning effort.
`session/set_mode`	Change the active mode.

Each connection runs one session and one prompt at a time. Wait for the prompt response, including after cancellation, before sending another prompt.

Sessions, models, and permissions

Clients can select a provider, model, and mode. Models that support reasoning also expose an effort selector. Provider, model, and effort choices are saved with the session.

ACP mode	Permission mode
`ask`	`ask`: ask for approval.
`code`	`auto`: run routine work and review other actions.

Mode changes apply to the active session. When creating or loading a session, fx starts with the configured permission mode until the client selects one.

Allow for this session approvals last until the session closes and are not restored on load.

session/prompt accepts text, embedded resources, and inline images. Images use the selected model's image support or the vision fallback and are saved for history replay. Unsupported images return -32602; audio is not supported.

Session updates

Clients receive streamed messages, tool activity, permission requests, session titles, and context usage.

Update	Content
Message chunks	Text with a stable `messageId`, also used during history replay.
`tool_call`	Tool name, kind, pending status, and redacted JSON arguments.
`tool_call_update`	Tool completion or failure.
`session_info_update`	Session title after a prompt or when loading history.
`usage_update`	Provider-confirmed context usage when the context window is known; cost when fully available.

Cancellation also stops pending permission and MCP input requests.

MCP servers

Clients can supply stdio, HTTP, or SSE servers through mcpServers. fx combines them with approved servers from the project's .mcp.json; a client entry wins a same-name project entry.

Profile servers from ~/.fx/mcp.json are not inherited. See MCP protocol reference for authentication and isolation details.

Protocol limits

ACP uses newline-delimited JSON-RPC 2.0 over stdin and stdout. Input messages are limited to 8 MiB; each inline image's padded base64 data is limited to 5 MiB. Oversized images return -32602 before they are saved or sent to the model.

Stdout carries ACP messages. Send diagnostics to --log-file or FX_TRACE_LOG.