ACP agents

​

Which page do I want?

​

Does this work out of the box?

• Target harness adapters (Codex, Claude, etc.) may be fetched on demand with npx the first time you use them.
• Vendor auth still has to exist on the host for that harness.
• If the host has no npm or network access, first-run adapter fetches fail until caches are pre-warmed or the adapter is installed another way.

​

Operator runbook

1. Spawn — /acp spawn codex --bind here or /acp spawn codex --mode persistent --thread auto
2. Work in the bound conversation or thread (or target the session key explicitly).
3. Check state — /acp status
4. Tune — /acp model <provider/model>, /acp permissions <profile>, /acp timeout <seconds>
5. Steer without replacing context — /acp steer tighten logging and continue
6. Stop — /acp cancel (current turn) or /acp close (session + bindings)

• “Bind this Discord channel to Codex.”
• “Start a persistent Codex session in a thread here.”
• “Run this as a one-shot Claude Code ACP session and summarize the result.”
• “Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread.”

​

ACP versus sub-agents

​

How ACP runs Claude Code

1. FluffBuzz ACP session control plane
2. bundled acpx runtime plugin
3. Claude ACP adapter
4. Claude-side runtime/session machinery

• ACP Claude is a harness session with ACP controls, session resume, background-task tracking, and optional conversation/thread binding.
• CLI backends are separate text-only local fallback runtimes. See CLI Backends.

• want /acp spawn, bindable sessions, runtime controls, or persistent harness work: use ACP
• want simple local text fallback through the raw CLI: use CLI backends

​

Bound sessions

​

Current-conversation binds

• chat surface — where people keep talking (Discord channel, Telegram topic, iMessage chat).
• ACP session — the durable Codex/Claude/Gemini runtime state FluffBuzz routes to.
• child thread/topic — an optional extra messaging surface created only by --thread ....
• runtime workspace — the filesystem location (cwd, repo checkout, backend workspace) where the harness runs. Independent of the chat surface.

• /acp spawn codex --bind here — keep this chat, spawn or attach Codex, route future messages here.
• /acp spawn codex --thread auto — FluffBuzz may create a child thread/topic and bind there.
• /acp spawn codex --bind here --cwd /workspace/repo — same chat binding, Codex runs in /workspace/repo.

• --bind here and --thread ... are mutually exclusive.
• --bind here only works on channels that advertise current-conversation binding; FluffBuzz returns a clear unsupported message otherwise. Bindings persist across gateway restarts.
• On Discord, spawnAcpSessions is only required when FluffBuzz needs to create a child thread for --thread auto|here — not for --bind here.
• If you spawn to a different ACP agent without --cwd, FluffBuzz inherits the target agent’s workspace by default. Missing inherited paths (ENOENT/ENOTDIR) fall back to the backend default; other access errors (e.g. EACCES) surface as spawn errors.

​

Thread-bound sessions

• FluffBuzz binds a thread to a target ACP session.
• Follow-up messages in that thread route to the bound ACP session.
• ACP output is delivered back to the same thread.
• Unfocus/close/archive/idle-timeout or max-age expiry removes the binding.

• acp.enabled=true
• acp.dispatch.enabled is on by default (set false to pause ACP dispatch)
• Channel-adapter ACP thread-spawn flag enabled (adapter-specific)
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true

​

Thread supporting channels

• Any channel adapter that exposes session/thread binding capability.
• Current built-in support:
  • Discord threads/channels
  • Telegram topics (forum topics in groups/supergroups and DM topics)
• Plugin channels can add support through the same binding interface.

​

Channel specific settings

​

Binding model

• bindings[].type="acp" marks a persistent ACP conversation binding.
• bindings[].match identifies the target conversation:
  • Discord channel or thread: match.channel="discord" + match.peer.id="<channelOrThreadId>"
  • Telegram forum topic: match.channel="telegram" + match.peer.id="<chatId>:topic:<topicId>"
  • BlueBubbles DM/group chat: match.channel="bluebubbles" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Prefer chat_id:* or chat_identifier:* for stable group bindings.
  • iMessage DM/group chat: match.channel="imessage" + match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>" Prefer chat_id:* for stable group bindings.
• bindings[].agentId is the owning FluffBuzz agent id.
• Optional ACP overrides live under bindings[].acp:
  • mode (persistent or oneshot)
  • label
  • cwd
  • backend

​

Runtime defaults per agent

• agents.list[].runtime.type="acp"
• agents.list[].runtime.acp.agent (harness id, for example codex or claude)
• agents.list[].runtime.acp.backend
• agents.list[].runtime.acp.mode
• agents.list[].runtime.acp.cwd

1. bindings[].acp.*
2. agents.list[].runtime.acp.*
3. global ACP defaults (for example acp.backend)

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/fluffbuzz",
          },
        },
      },
      {
        id: "claude",
        runtime: {
          type: "acp",
          acp: { agent: "claude", backend: "acpx", mode: "persistent" },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "discord",
        accountId: "default",
        peer: { kind: "channel", id: "222222222222222222" },
      },
      acp: { label: "codex-main" },
    },
    {
      type: "acp",
      agentId: "claude",
      match: {
        channel: "telegram",
        accountId: "default",
        peer: { kind: "group", id: "-1001234567890:topic:42" },
      },
      acp: { cwd: "/workspace/repo-b" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "discord", accountId: "default" },
    },
    {
      type: "route",
      agentId: "main",
      match: { channel: "telegram", accountId: "default" },
    },
  ],
  channels: {
    discord: {
      guilds: {
        "111111111111111111": {
          channels: {
            "222222222222222222": { requireMention: false },
          },
        },
      },
    },
    telegram: {
      groups: {
        "-1001234567890": {
          topics: { "42": { requireMention: false } },
        },
      },
    },
  },
}

• FluffBuzz ensures the configured ACP session exists before use.
• Messages in that channel or topic route to the configured ACP session.
• In bound conversations, /new and /reset reset the same ACP session key in place.
• Temporary runtime bindings (for example created by thread-focus flows) still apply where present.
• For cross-agent ACP spawns without an explicit cwd, FluffBuzz inherits the target agent workspace from agent config.
• Missing inherited workspace paths fall back to the backend default cwd; non-missing access failures surface as spawn errors.

​

Start ACP sessions (interfaces)

​

From sessions_spawn

{
  "task": "Open the repo and summarize failing tests",
  "runtime": "acp",
  "agentId": "codex",
  "thread": true,
  "mode": "session"
}

• runtime defaults to subagent, so set runtime: "acp" explicitly for ACP sessions.
• If agentId is omitted, FluffBuzz uses acp.defaultAgent when configured.
• mode: "session" requires thread: true to keep a persistent bound conversation.

• task (required): initial prompt sent to the ACP session.
• runtime (required for ACP): must be "acp".
• agentId (optional): ACP target harness id. Falls back to acp.defaultAgent if set.
• thread (optional, default false): request thread binding flow where supported.
• mode (optional): run (one-shot) or session (persistent).
  • default is run
  • if thread: true and mode omitted, FluffBuzz may default to persistent behavior per runtime path
  • mode: "session" requires thread: true
• cwd (optional): requested runtime working directory (validated by backend/runtime policy). If omitted, ACP spawn inherits the target agent workspace when configured; missing inherited paths fall back to backend defaults, while real access errors are returned.
• label (optional): operator-facing label used in session/banner text.
• resumeSessionId (optional): resume an existing ACP session instead of creating a new one. The agent replays its conversation history via session/load. Requires runtime: "acp".
• streamTo (optional): "parent" streams initial ACP run progress summaries back to the requester session as system events.
  • When available, accepted responses include streamLogPath pointing to a session-scoped JSONL log (<sessionId>.acp-stream.jsonl) you can tail for full relay history.
• model (optional): explicit model override for the ACP child session. Honored for runtime: "acp" so the child uses the requested model instead of silently falling back to the target agent default.

​

Delivery model

​

Interactive ACP sessions

• /acp spawn ... --bind here binds the current conversation to the ACP session.
• /acp spawn ... --thread ... binds a channel thread/topic to the ACP session.
• Persistent configured bindings[].type="acp" route matching conversations to the same ACP session.

​

Parent-owned one-shot ACP sessions

• The parent asks for work with sessions_spawn({ runtime: "acp", mode: "run" }).
• The child runs in its own ACP harness session.
• Completion reports back through the internal task-completion announce path.
• The parent rewrites the child result in normal assistant voice when a user-facing reply is useful.

​

sessions_send and A2A delivery

• wait for the target session’s reply
• optionally let requester and target exchange a bounded number of follow-up turns
• ask the target to produce an announce message
• deliver that announce to the visible channel or thread

​

Resume an existing session

{
  "task": "Continue where we left off — fix the remaining test failures",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "<previous-session-id>"
}

• Hand off a Codex session from your laptop to your phone — tell your agent to pick up where you left off
• Continue a coding session you started interactively in the CLI, now headlessly through your agent
• Pick up work that was interrupted by a gateway restart or idle timeout

• resumeSessionId requires runtime: "acp" — returns an error if used with the sub-agent runtime.
• resumeSessionId restores the upstream ACP conversation history; thread and mode still apply normally to the new FluffBuzz session you are creating, so mode: "session" still requires thread: true.
• The target agent must support session/load (Codex and Claude Code do).
• If the session ID isn’t found, the spawn fails with a clear error — no silent fallback to a new session.

​

Sandbox compatibility

• If the requester session is sandboxed, ACP spawns are blocked for both sessions_spawn({ runtime: "acp" }) and /acp spawn.
  • Error: Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.
• sessions_spawn with runtime: "acp" does not support sandbox: "require".
  • Error: sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".

​

From /acp command

/acp spawn codex --mode persistent --thread auto
/acp spawn codex --mode oneshot --thread off
/acp spawn codex --bind here
/acp spawn codex --thread here

• --mode persistent|oneshot
• --bind here|off
• --thread auto|here|off
• --cwd <absolute-path>
• --label <name>

​

Session target resolution

1. Explicit target argument (or --session for /acp steer)
   • tries key
   • then UUID-shaped session id
   • then label
2. Current thread binding (if this conversation/thread is bound to an ACP session)
3. Current requester session fallback

​

Spawn bind modes

• --bind here is the simplest operator path for “make this channel or chat Codex-backed.”
• --bind here does not create a child thread.
• --bind here is only available on channels that expose current-conversation binding support.
• --bind and --thread cannot be combined in the same /acp spawn call.

​

Spawn thread modes

• On non-thread binding surfaces, default behavior is effectively off.
• Thread-bound spawn requires channel policy support:
  • Discord: channels.discord.threadBindings.spawnAcpSessions=true
  • Telegram: channels.telegram.threadBindings.spawnAcpSessions=true
• Use --bind here when you want to pin the current conversation without creating a child thread.

​

ACP controls

​

Runtime options mapping

• /acp model <id> maps to runtime config key model.
• /acp permissions <profile> maps to runtime config key approval_policy.
• /acp timeout <seconds> maps to runtime config key timeout.
• /acp cwd <path> updates runtime cwd override directly.
• /acp set <key> <value> is the generic path.
  • Special case: key=cwd uses the cwd override path.
• /acp reset-options clears all runtime overrides for target session.

​

acpx harness support (current)

• claude
• codex
• copilot
• cursor (Cursor CLI: cursor-agent acp)
• droid
• gemini
• iflow
• kilocode
• kimi
• kiro
• fluffbuzz
• opencode
• pi
• qwen

​

Required config

{
  acp: {
    enabled: true,
    // Optional. Default is true; set false to pause ACP dispatch while keeping /acp controls.
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: [
      "claude",
      "codex",
      "copilot",
      "cursor",
      "droid",
      "gemini",
      "iflow",
      "kilocode",
      "kimi",
      "kiro",
      "fluffbuzz",
      "opencode",
      "pi",
      "qwen",
    ],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

• Discord: channels.discord.threadBindings.spawnAcpSessions=true

​

Plugin setup for acpx backend

/acp doctor

fluffbuzz plugins install acpx
fluffbuzz config set plugins.entries.acpx.enabled true

fluffbuzz plugins install ./path/to/local/acpx-plugin

/acp doctor

​

acpx command and version configuration

{
  "plugins": {
    "entries": {
      "acpx": {
        "enabled": true,
        "config": {
          "command": "../acpx/dist/cli.js",
          "expectedVersion": "any"
        }
      }
    }
  }
}

• command accepts an absolute path, relative path (resolved from the FluffBuzz workspace), or command name.
• expectedVersion: "any" disables strict version matching.
• Custom command paths disable plugin-local auto-install.

​

Automatic dependency install

​

Plugin tools MCP bridge

fluffbuzz config set plugins.entries.acpx.config.pluginToolsMcpBridge true

• Injects a built-in MCP server named fluffbuzz-plugin-tools into ACPX session bootstrap.
• Exposes plugin tools already registered by installed and enabled FluffBuzz plugins.
• Keeps the feature explicit and default-off.

• This expands the ACP harness tool surface.
• ACP agents get access only to plugin tools already active in the gateway.
• Treat this as the same trust boundary as letting those plugins execute in FluffBuzz itself.
• Review installed plugins before enabling it.

​

FluffBuzz tools MCP bridge

fluffbuzz config set plugins.entries.acpx.config.openClawToolsMcpBridge true

• Injects a built-in MCP server named fluffbuzz-tools into ACPX session bootstrap.
• Exposes selected built-in FluffBuzz tools. The initial server exposes cron.
• Keeps core-tool exposure explicit and default-off.

​

Runtime timeout configuration

fluffbuzz config set plugins.entries.acpx.config.timeoutSeconds 180

​

Health probe agent configuration

fluffbuzz config set plugins.entries.acpx.config.probeAgent claude

​

Permission configuration

​

permissionMode

​

nonInteractivePermissions

​

Configuration

fluffbuzz config set plugins.entries.acpx.config.permissionMode approve-all
fluffbuzz config set plugins.entries.acpx.config.nonInteractivePermissions fail

Important: FluffBuzz currently defaults to permissionMode=approve-reads and nonInteractivePermissions=fail. In non-interactive ACP sessions, any write or exec that triggers a permission prompt can fail with AcpRuntimeError: Permission prompt unavailable in non-interactive mode. If you need to restrict permissions, set nonInteractivePermissions to deny so sessions degrade gracefully instead of crashing.

​

Troubleshooting

​

Related

• Sub-agents
• Multi-agent sandbox tools
• Agent send