Why Sidekicks speaks ACP — explanation

What is this about?

Sidekicks is a desktop application to talk with AI agents, for people who are not developers. It does not contain an agent: it is a client that starts agents as separate programs and talks to them with the Agent Client Protocol (ACP), JSON-RPC over the agent's standard input and output. This page explains that choice and what the first contact with real agents taught us. The detailed decisions are in ADR 0001.

Why a protocol rather than an integration

The owner's goal is an application that is agnostic of the agent. Integrating one agent's library would tie Sidekicks to it; speaking a protocol means any agent that implements ACP — mm today, the agents Zed or JetBrains support tomorrow — can be added with three lines of YAML. ACP also already models what a conversation with an agent needs: streamed answers, tool calls, permission requests, cancellation, slash commands.

What the spike learnt from real agents

Reading a specification is not the same as watching an agent. The spike drove the test agents and recorded the traffic (traces). Four findings shape the product:

mm speaks ACP version 1. The site already documents a version 2; Sidekicks targets v1 and isolates the protocol in one package so v2 can be added later.
mm cannot reload a session. After a restart, Sidekicks must give the agent the context of the conversation again; the agent's memory of the conversation is Sidekicks' job.
Skills are slash commands. Garfield's skills arrive as commands, and /idioms Il pleut des cordes. sent as plain text runs the skill. In a channel with several agents, /garfield:idioms … only needs Sidekicks to strip the agent's name and send the rest to Garfield.
A small model does not take no for an answer. Refused once, Riker retried the same action forty times in different forms until mm gave up with an error. A permission dialog that only offers "allow" and "reject" leaves a non-technical user facing forty dialogs; hence "never in this conversation" and "stop the agent" (see the wireframe).

Rejected alternatives

Writing the JSON-RPC layer by hand: possible, but the Go SDK by Coder is generated from the official schema, covers every v1 message, and has no dependencies. Owning that code would be cost without benefit.
Waiting for ACP v2: no agent we use speaks it yet.
Advertising file and terminal access to agents: mm uses its own tools and never asked; it stays a later, optional feature.

How it relates to the rest

Only the internal/acp package will know about ACP; the rest of the application sees Sidekicks' own events (see Architecture). The four test agents and their memory constraints are covered in Memory and local models.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# Why Sidekicks speaks ACP — explanation

## What is this about?

Sidekicks is a desktop application to talk with AI agents, for people who are not developers. It does not contain an agent: it is a **client** that starts agents as separate programs and talks to them with the [Agent Client Protocol](https://agentclientprotocol.com) (ACP), JSON-RPC over the agent's standard input and output. This page explains that choice and what the first contact with real agents taught us. The detailed decisions are in [ADR 0001](../../adr/0001-acp.md).

## Why a protocol rather than an integration

The owner's goal is an application that is **agnostic of the agent**. Integrating one agent's library would tie Sidekicks to it; speaking a protocol means any agent that implements ACP — mm today, the agents Zed or JetBrains support tomorrow — can be added with three lines of YAML. ACP also already models what a conversation with an agent needs: streamed answers, tool calls, permission requests, cancellation, slash commands.

## What the spike learnt from real agents

Reading a specification is not the same as watching an agent. The spike drove the test agents and recorded the traffic ([traces](../../spikes/acp/README.md)). Four findings shape the product:

- **mm speaks ACP version 1.** The site already documents a version 2; Sidekicks targets v1 and isolates the protocol in one package so v2 can be added later.
- **mm cannot reload a session.** After a restart, Sidekicks must give the agent the context of the conversation again; the agent's memory of the conversation is Sidekicks' job.
- **Skills are slash commands.** Garfield's skills arrive as commands, and `/idioms Il pleut des cordes.` sent as plain text runs the skill. In a channel with several agents, `/garfield:idioms …` only needs Sidekicks to strip the agent's name and send the rest to Garfield.
- **A small model does not take no for an answer.** Refused once, Riker retried the same action forty times in different forms until mm gave up with an error. A permission dialog that only offers "allow" and "reject" leaves a non-technical user facing forty dialogs; hence "never in this conversation" and "stop the agent" (see the [wireframe](../../design/04-permission.png)).

## Rejected alternatives

- **Writing the JSON-RPC layer by hand**: possible, but the Go SDK by Coder is generated from the official schema, covers every v1 message, and has no dependencies. Owning that code would be cost without benefit.
- **Waiting for ACP v2**: no agent we use speaks it yet.
- **Advertising file and terminal access to agents**: mm uses its own tools and never asked; it stays a later, optional feature.

## How it relates to the rest

Only the `internal/acp` package will know about ACP; the rest of the application sees Sidekicks' own events (see [Architecture](architecture.md)). The four test agents and their memory constraints are covered in [Memory and local models](memory-and-local-models.md).