ACP (Agent Client Protocol) runtime plugin for Paperclip. Run Claude Code, Codex, Gemini CLI, and other coding agents from any chat platform through thread-bound sessions.

npm install paperclip-plugin-acp

Then register with your Paperclip instance:

curl -X POST http://127.0.0.1:3100/api/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"packageName":"paperclip-plugin-acp"}'

Agent Client Protocol is a standard for connecting clients to AI coding agents. Created by Zed Industries, it's supported by Claude Code, Codex CLI, Gemini CLI, OpenCode, and 19+ others. This plugin brings ACP to Paperclip.

Chat message (Telegram/Discord/Slack)
    -> Paperclip chat plugin emits acp:message event
    -> ACP plugin routes to bound session
    -> Coding agent (subprocess over stdio)
    -> Agent output emitted as acp:output event
    -> Chat plugin sends response to thread

Chat plugins (Telegram, Discord, Slack) bind threads/topics to ACP sessions via Paperclip's event bus. Each thread becomes a persistent workspace for a coding agent.

Agents must be installed on the Paperclip server. The plugin spawns them as subprocesses.

A single chat thread can run up to 5 concurrent agent sessions (configurable via maxSessionsPerThread). Spawn multiple agents in the same thread - for example, Claude Code reviewing while Codex implements - and route messages to each by session ID.

Active sessions are stored per-thread as an array. Closed or errored sessions don't count toward the cap. The acp_status tool lists all active sessions with uptime, idle time, and binding info.

Existing threads that used the old 1:1 binding format (acp_{chatId}_{threadId} key) are migrated automatically on first access. The old key is read, converted to a single-entry sessions array under the new acp_sessions_{chatId}_{threadId} key, and the old key is deleted. No manual migration needed.

The plugin exposes these tools to Paperclip agents:

• acp_spawn - Start a new coding agent session
• acp_status - List active sessions
• acp_send - Send a prompt to an active session
• acp_cancel - Cancel the current turn
• acp_close - Close a session and remove bindings

Chat plugins communicate with the ACP plugin via namespaced events on Paperclip's event bus. Each platform plugin (Telegram, Slack, Discord) emits events under its own namespace:

plugin.paperclip-plugin-telegram.acp-spawn
plugin.paperclip-plugin-slack.acp-message
plugin.paperclip-plugin-discord.acp-close

The ACP plugin registers listeners for all three platforms on startup. Adding a new platform requires adding its plugin ID to CHAT_PLATFORM_PLUGINS in constants.ts.

pnpm install
pnpm typecheck
pnpm build

Install locally on a Paperclip instance:

curl -X POST http://127.0.0.1:3100/api/plugins/install \
  -H "Content-Type: application/json" \
  -d '{"packageName":"/path/to/paperclip-plugin-acp","isLocalPath":true}'

This plugin follows patterns from OpenClaw's ACP implementation, which has extensive ACP support for Discord, Telegram, Slack, and Matrix with thread-bound sessions, agent spawning, and session lifecycle management.