Connect your AI agent

The ACP connector is a small program you run on your own computer. It plugs your personal Claude or Codex into a Cheers bot so it can read channels, see the files you attach, and reply — all using your own agent subscription. This guide walks a non-developer through it: install, connect, keep it updated, and fix the most common surprise.

1. What the connector is (30-second version)

Cheers has no AI built in. Instead, you bring your own agent and connect it from your machine. Three pieces talk to each other:

your browser ──▶ Cheers gateway (the server) ◀──── connector (runs on your PC) ──▶ your AI agent
                                                    └ one config file = one bot

• The gateway is the Cheers server your team already runs.
• The connector (cce-acp-connector) is the little bridge you install and run.
• Your agent is Claude or Codex, signed in with your own subscription — no extra API key needed.

One config file describes one bot. Want two bots (say a Claude bot and a Codex bot)? Two files, run two of them. They're fully independent.

2. Before you start

That's it — you do not need Rust, Docker, or an API key. Signing into your agent once is enough.

3. Install the connector

Download the prebuilt binary for your OS — no toolchain required. Paste this into a terminal:

# pick the right file for your OS/CPU, download it, make it runnable
os=$(uname -s | tr 'A-Z' 'a-z'); arch=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
mkdir -p ~/.cheers/bin ~/.cheers/workspace   # workspace = where the agent works — must exist, or the connector refuses to start
curl -fsSL -o ~/.cheers/bin/cce-acp-connector \
  "https://github.com/ElePerson/Cheers/releases/latest/download/cce-acp-connector-$os-$arch"
chmod +x ~/.cheers/bin/cce-acp-connector
export PATH="$HOME/.cheers/bin:$PATH"   # add this line to your ~/.zshrc so it sticks
cce-acp-connector --help                # prints help = success

4. Create the bot and get its token

A token is the connector's password to log in to the gateway as your bot. Get one in the UI:

1. Sign in to Cheers and open Settings → Bots.
2. Create a bot (or open an existing one). Give it a name like claude, and set its bridge/provider type to generic / ACP.
3. Issue a token and copy it. Save it into a small file that only you can read:

   mkdir -p ~/.cheers/secrets && chmod 700 ~/.cheers/secrets
   # paste the token in place of PASTE_TOKEN_HERE:
   printf '%s' 'PASTE_TOKEN_HERE' > ~/.cheers/secrets/claude.token
   chmod 600 ~/.cheers/secrets/claude.token

5. Write one config file

Create ~/.cheers/cheers-daemon.claude.toml. This is the minimal form — the rest have sensible defaults. Change the two URLs to match your gateway, and the command to your agent's path:

version = 1

[daemon]
state_path = "state-claude.json"   # these are relative to this file's folder (~/.cheers)
log_dir    = "logs-claude"

[accounts.claude.bridge]
control_url    = "ws://localhost:8000/ws/agent-bridge/control"
data_url       = "ws://localhost:8000/ws/agent-bridge/data"
bot_token_file = "secrets/claude.token"   # the file from step 4 — never paste the token here

[accounts.claude.adapter]
type    = "stdio"
command = "/opt/homebrew/bin/claude-agent-acp"   # output of: command -v claude-agent-acp
args    = []

[accounts.claude.policy.prompt]
allow             = true
allow_attachments = true    # ← lets the bot receive files you attach to a message
allow_images      = true

[accounts.claude.policy.workspace]
default_cwd   = "~/.cheers/workspace"
allowed_roots = ["~/.cheers/workspace"]
backend_may_set_cwd = true

[accounts.claude.policy.env]
inherit = false
allow   = ["HOME", "PATH"]   # HOME lets the agent read your ~/.claude subscription login

[accounts.claude.policy.permission]
forward_to_backend = true    # tool-use asks show up as an approval card in the channel
wait_timeout_ms    = 900000
on_timeout         = "cancel"
auto_allow         = false

[accounts.claude.policy.mcp]
inject_cheers = true         # gives the agent the Cheers tools (read files, post messages…)

The config folder ends up looking like this:

~/.cheers/
├─ cheers-daemon.claude.toml     # one file = one bot
├─ secrets/claude.token          # the token, chmod 600
├─ workspace/                    # where the agent works
└─ logs-claude/                  # its logs

Start it & check it's online

cce-acp-connector start  --config ~/.cheers/cheers-daemon.claude.toml --name claude
cce-acp-connector status --name claude          # → status=running
cce-acp-connector logs   --name claude --lines 40
# expect "initialized ACP agent" + "BridgeRuntime started", no ERROR lines

Now @-mention the bot in a Cheers channel. A reply means you're connected. 🎉 Because the token lives in a file, restarts need no extra steps: cce-acp-connector restart --name claude.

6. Keep it updated (important)

New Cheers features often need a matching connector version. An outdated connector still connects and runs fine — it just silently skips whatever it doesn't understand yet. The most common casualty is attached context: the file chips show in the chat, but your bot never receives them and asks you to upload the files. Updating fixes it.

See whether you're behind

cce-acp-connector status --name claude
# if a newer release exists you'll see an "update available:" line here,
# and a warning in the logs at startup.

Option A — turn on signed auto-update (connector ≥ 0.1.27)

Add this to your config, then restart once. From then on the connector updates itself safely (it checks an ed25519 signature and checksum, waits until it's idle, swaps in place, and rolls back if the new one is unhealthy):

[update]
auto = true

Option B — update by hand

Re-run the download from step 3 (it overwrites the old binary), then restart:

os=$(uname -s | tr 'A-Z' 'a-z'); arch=$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')
curl -fsSL -o ~/.cheers/bin/cce-acp-connector \
  "https://github.com/ElePerson/Cheers/releases/latest/download/cce-acp-connector-$os-$arch"
chmod +x ~/.cheers/bin/cce-acp-connector
cce-acp-connector restart --name claude

Auto-update is off by default on purpose — updating runs downloaded code, so the owner of the machine opts in. You can hard-disable it anytime with CHEERS_ACP_NO_SELF_UPDATE=1.

7. How attaching files works

In the message composer, Add context lets you attach a file (or a line range like review.md:1-1, or a file from a workspace). Each attachment becomes a small chip on your message. When you send, Cheers passes those references to the bot's connector, which puts them into the agent's prompt so it knows what you're pointing at.

• The bot resolves the reference on its side (it reads the file through the Cheers tools) — so it works even for large files without pasting the whole thing.
• For this to happen, the bot's config needs allow_attachments = true (it's in the template above) and a current connector. Old connectors drop the references silently.

8. Troubleshooting

Read more