convez.ai
AgenteIntegração & APIsAvançado
jbulpitt

Seam ACP

jbulpitt/seam-acp

Bridge Discord ↔ agentes de IA para coding via ACP

Ver no GitHub
InicialPluginScore · de 0 a 100

Bridge que conecta plataformas de chat (Discord, Slack em breve) com agentes de coding compatíveis com ACP (GitHub Copilot, Claude Code e outros). Permite executar sessões de desenvolvimento de código diretamente em threads de chat, com troca dinâmica de modelos e agentes via protocolo padronizado.

Instalação

$npx convez-ai jbulpitt/seam-acp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
—
Issues abertas
23
Contribuidores
3

Casos de uso

  • Colaboração em código via Discord sem sair do chat
  • Integração multi-agent (Copilot, Claude, Gemini) em um único bot
  • Gerenciamento centralizado de múltiplas contas de IA (perfis por agente)

Veredito

Projeto maduro (v0) focado em abstração via ACP, eliminando vendor lock-in. Ideal para times que querem orquestração agnóstica de agentes de IA em fluxos de chat existentes, com suporte a múltiplos agentes e modelos em tempo real.

README

A tradução para o português deste README ainda está na fila.

seam-acp

A bridge between chat platforms (Discord today, Slack tomorrow) and ACP-compatible coding agents (GitHub Copilot today, Claude Code / others tomorrow).

Status: v0 — Discord + GitHub Copilot is the proven path. A Gemini ACP profile ships in the box; the multi-platform / multi-agent abstractions are designed in from day one.

What it does

  • Run a chat bot on a server / home lab / VM.
  • From your phone (Discord), spin up a session per thread.
  • Pick a repo with interactive buttons; chat with a coding agent in the thread.
  • Switch model on the fly (interactive picker). Switch mode (Agent / Plan / Autopilot). Switch agent.

Why ACP

The Agent Client Protocol is the LSP-equivalent for coding agents. Picking ACP means:

  • The agent integration is a typed protocol, not a vendor SDK.
  • Switching to a different ACP-compatible agent is a config change, not a rewrite.
  • We get streaming updates, mode switching, and live model switching as first-class features.

Configure

Copy .env.example to .env and fill it in.

VariableRequiredNotes
DISCORD_BOT_TOKENyesFrom the Discord developer portal
DISCORD_ALLOWED_USER_IDSyesComma-separated Discord user IDs that can control the bot (e.g. 123,456)
DISCORD_ALLOWED_CHANNEL_IDSnoComma-separated parent channel IDs the bot is allowed to operate in. When set, the bot only responds in threads whose parent channel is in this list. When unset, all channels are allowed.
DISCORD_DEV_GUILD_IDnoSet to register slash commands instantly to one guild (good for dev)
REPOS_ROOTyesRoot folder containing repos the agent can touch
ATTACH_ROOTSnoComma-separated extra absolute directories the /seam attach command (and the agent-side fence-to-file shortcut) can read from. REPOS_ROOT is always allowed.
DATA_DIRnoDefaults to ./data (sqlite lives here)
DEFAULT_AGENTnocopilot (default), gemini, or claude. Plus any copilot-<id> / gemini-<id> / claude-<id> registered via the *_PROFILES vars.
DEFAULT_MODELnoDefault Copilot model. Applies to all Copilot profiles (including extras from COPILOT_PROFILES). e.g. gpt-5.4, claude-sonnet-4.5, claude-opus-4.7, auto
COPILOT_CLI_PATHnoIf copilot is not on PATH
COPILOT_PROFILESnoRegister additional Copilot profiles, each with its own auth / config dir. Format: id1:/abs/dir1,id2:/abs/dir2. Each becomes an agent profile named copilot-<id> in /seam agent. Lets one bot serve multiple GitHub accounts; see "Multiple Copilot accounts" below.
GEMINI_CLI_PATHnoIf gemini is not on PATH
GEMINI_DEFAULT_MODELnoDefault Gemini model — applied even when DEFAULT_AGENT is copilot. Default gemini-2.5-pro.
GEMINI_PROFILESnoSame shape as COPILOT_PROFILES. Each entry registers a gemini-<id> profile pinned to its own GEMINI_CLI_HOME (acts as a fake home — Gemini reads <dir>/.gemini/). See "Multiple Gemini accounts" below.
CLAUDE_CLI_PATHnoIf claude-agent-acp is not on PATH
CLAUDE_DEFAULT_MODELnoDefault Claude model — applied even when DEFAULT_AGENT is copilot. Default claude-sonnet-4.5.
CLAUDE_PROFILESnoSame shape as COPILOT_PROFILES. Each entry registers a claude-<id> profile pinned to its own CLAUDE_CONFIG_DIR. See "Multiple Claude accounts" below.
REMOTE_COPILOT_PROFILESnoRegister Copilot profiles running on remote machines via WebSocket bridge. Two formats: id:port:token (server mode — seam-acp hosts WS server) or id:wss://url:token (client mode — seam-acp dials out). See docs/remote-agent.md.
TURN_TIMEOUT_SECONDSnoDefault 900
LOG_LEVELnofatal / error / warn / info / debug / trace
HEALTH_PORTnoDefault 3000 — exposes GET /health
DEFAULT_PERMISSION_POLICYnoask (recommended). Bot-wide default policy for new sessions. One of always (auto-approve), ask (prompt me on Discord), deny (auto-deny). Override per-session with /seam approve.
DEFAULT_AUTO_APPROVEnoDeprecated. When true, forces the bot-wide default to always. Prefer DEFAULT_PERMISSION_POLICY.

You also need the GitHub Copilot CLI installed locally (brew install github/gh/copilot or npm i -g @github/copilot) and authenticated (copilot auth login). The Docker image installs and runs the CLI for you, but you still need to mount auth state or sign in inside the container.

To use the Anthropic Claude profile, install the ACP adapter (and the underlying CLI for auth):

npm i -g @anthropic-ai/claude-code @agentclientprotocol/claude-agent-acp
claude /login

To use the Google Gemini profile, install the Gemini CLI (brew install google-gemini/cli/gemini or npm i -g @google/gemini-cli) and run gemini /auth. Each agent profile is independent — install only the ones you'll use.

Run (local dev)

npm install
cp .env.example .env   # then edit
npm run dev

The bot starts, registers /seam slash commands (guild-scoped if DISCORD_DEV_GUILD_ID is set, global otherwise — global takes up to an hour to propagate), and exposes GET /health on HEALTH_PORT.

Run (Docker)

docker compose up -d --build

Pass --build-arg INSTALL_COPILOT_CLI=false if you want to mount your own Copilot CLI binary.

Run (PM2 — background process, no Docker)

PM2 keeps the bot running in the background, restarts it on crashes, and can auto-start it at login.

npm install -g pm2
npm run build
pm2 start ecosystem.config.cjs  # starts the bot as a background daemon
pm2 save                         # persist the process list
pm2 startup                      # prints a command — run it to enable auto-start at login

After making code changes, use the dedicated redeploy script instead of restarting PM2 directly. A direct pm2 restart would kill the bot mid-reply if an agent issued the command:

npm run redeploy   # builds, then restarts PM2 after a 3-second delay

Other useful commands:

pm2 status              # check if the bot is running
pm2 logs seam-acp       # tail live logs
pm2 stop seam-acp       # stop the bot

Slash commands

All commands are restricted to users listed in DISCORD_ALLOWED_USER_IDS and (where it matters) thread-scoped.

CommandWhat it does
/seam new [name]Create a new public thread, bind a session to it, and post the repo picker — all in one step
/seam initBind the current thread as a session and post the repo picker
/seam repo <path>Set the working repo (relative to REPOS_ROOT or absolute under it)
/seam reposList repos found under REPOS_ROOT (hidden directories are skipped)
/seam agent [id]With no id: posts an interactive picker of registered profiles. With id: switch directly.
/seam model [id]With no id: starts the agent if needed and posts a picker of advertised models. With id: set directly (live if a runtime is active).
/seam mode <id>Set the agent operational mode (e.g. plan / agent / autopilot)
/seam effort <low|medium|high>Set reasoning effort (model-dependent)
/seam tools <allow|exclude> [csv]Tool allow / exclude list (empty list = clear)
/seam approve <always|ask|deny>Permission policy for this thread. always auto-approves every request; ask posts a Discord prompt with buttons (auto-denies after 5 min); deny auto-denies.
/seam abortCancel the in-flight turn
/seam resetEnd the current ACP session for this thread; next message starts a fresh one
/seam configShow the session config JSON
/seam config-set <json>Replace the session config wholesale
/seam sessionsList recent sessions across the bot
/seam attach <path>Upload a host-side file (under REPOS_ROOT or ATTACH_ROOTS) into the channel without involving the agent
/seam whoamiShow which account this thread's agent profile is signed in as (Copilot only — reads <config-dir>/config.json)
/seam avatarRe-push the bot avatar to Discord (force re-upload)
/seam helpShow this list

Interactive pickers use buttons for ≤15 choices (laid out across up to 3 rows of 5) and a select menu for 16–25.

Free-form messages in a thread are sent straight to the agent. You can attach files to a message and they'll be forwarded as ACP content blocks: images and text-ish files (markdown, source code, JSON, CSV, logs, etc.) are inlined when the agent supports it; everything else is sent as a CDN link the agent can fetch. Limits per message: 8 attachments, 5 MB each, text inlined up to 256 KB.

If the agent emits an image, audio file, or embedded resource (in a tool result or its own message stream), the bot uploads it to the thread as a Discord attachment. Discord's free-tier 25 MB upload limit applies.

The bot also auto-uploads two adjacent cases:

  • Streaming fence-to-file. Every fenced code block the agent emits is captured as it streams, stripped from chat, and uploaded as a Discord attachment named snippet-N.<ext> (extension inferred from the language tag; unknown tags fall back to .txt). This keeps long code out of the chat, makes the empty-pill / unclosed-fence runaway bug architecturally impossible, and gives consistent UX for any size snippet.
  • Fence-as-file shortcut. If a fence's entire content is a single line that resolves to a real file under REPOS_ROOT or ATTACH_ROOTS, the bot uploads the referenced file instead of the snippet text. Symlinks are followed and the realpath is re-validated. Useful for "give me back that doc as an attachment" prompts.

Multiple Copilot accounts

You can register more than one Copilot profile, each authenticated as a different GitHub account, by setting COPILOT_PROFILES:

COPILOT_PROFILES=work:/Users/me/.copilot-work,personal:/Users/me/.copilot-personal

For each entry the bot spawns copilot --acp --config-dir <dir>. Copilot keeps all of its state per --config-dir — auth tokens, MCP config, session history — so the two profiles are fully isolated CLIs sharing one binary. They show up in /seam agent as copilot-work and copilot-personal alongside the default copilot profile.

One-time setup per account on the host (or inside the container):

COPILOT_HOME=/Users/me/.copilot-work copilot login
COPILOT_HOME=/Users/me/.copilot-personal copilot login

Verify in a thread with /seam whoami — the bot reads <config-dir>/config.json and reports the GitHub login.

Multiple Gemini accounts

Same pattern, using GEMINI_PROFILES:

GEMINI_PROFILES=work:/Users/me/gemini-work,personal:/Users/me/gemini-personal

For each entry the bot spawns gemini --acp with GEMINI_CLI_HOME=<dir> in the child env. The Gemini CLI treats that as a home directory override and stores all state under <dir>/.gemini/ (auth tokens, credentials, settings, session history). Profiles show up in /seam agent as gemini-work and gemini-personal alongside the default gemini profile.

Note: the path you give is the fake home dir — not the .gemini folder itself. The CLI will create <dir>/.gemini/ for you on first use.

One-time setup per account on the host:

GEMINI_CLI_HOME=/Users/me/gemini-work gemini /auth
GEMINI_CLI_HOME=/Users/me/gemini-personal gemini /auth

/seam whoami reads <dir>/.gemini/google_accounts.json and reports the active Google account email.

Multiple Claude accounts

Same pattern as Copilot, using CLAUDE_PROFILES:

CLAUDE_PROFILES=work:/Users/me/.claude-work,personal:/Users/me/.claude-personal

For each entry the bot spawns claude-agent-acp with CLAUDE_CONFIG_DIR=<dir> in the child env. Each dir holds its own auth and settings. Profiles show up in /seam agent as claude-work and claude-personal alongside the default claude profile.

One-time setup per account on the host:

CLAUDE_CONFIG_DIR=/Users/me/.claude-work claude /login
CLAUDE_CONFIG_DIR=/Users/me/.claude-personal claude /login

/seam whoami is best-effort for Claude — it tries to read the email / account from <config-dir>/.credentials.json (and a couple of fallbacks). If that fails (file format changes upstream, etc.) the command still reports which profile id you're on.

⚠️ Claude model selection & the claude-agent-acp resolver

Claude model handling has a sharp edge: the claude-agent-acp wrapper resolves model strings inconsistently — some aliases and full IDs silently resolve to the wrong model or the wrong context window. For example, the alias opus[1m] resolves to Sonnet, and the full ID claude-sonnet-4-6[1m] silently gives a 200K window instead of 1M.

Because of this:

  • The CLAUDE_MODELS picker in .env contains only empirically verified entries (each one checked against JSONL ground truth, not the model's self-report). Don't add a model without verifying it.
  • A small local patch — scripts/patch-claude-agent-acp.mjs, run via npm run patch-acp — makes full claude-* IDs bypass the broken resolver so they resolve to exactly themselves (and unlocks e.g. Opus 4.6 @ 1M). It is wiped by any global npm update of the package and must be re-applied.
  • The status card shows the resolved API model id and the current reasoning effort on every turn, so a wrong-model regression is visible immediately.

Anyone updating claude-agent-acp / @anthropic-ai/claude-code, changing the model picker, or touching effort handling must follow docs/model-management-runbook.md — the authoritative, step-by-step empirical process (pull versions → read changelogs → update → re-apply patch → verify against JSONL → confirm new/resumed sessions).

Remote agent profiles (Mac / off-server machine)

You can run an agent CLI on a separate machine — one that cannot accept inbound connections — and expose it as a regular agent profile via a WebSocket bridge. Two modes are supported:

  • Server mode: seam-acp hosts the WS server (and cloudflared); remote machine dials in outbound.
  • Client mode: remote machine hosts the WS server (and cloudflared); seam-acp dials out.
# Server mode (.env on seam-acp):
REMOTE_COPILOT_PROFILES=mac:9999:your-secret-token
# Run on remote machine: node scripts/remote-agent-bridge.mjs wss://tunnel-url your-token

# Client mode (.env on seam-acp):
REMOTE_COPILOT_PROFILES=mac:wss://random.trycloudflare.com:your-secret-token
# Run on remote machine: node scripts/remote-agent-bridge.mjs --server 9999 your-token
#   then: cloudflared tunnel --url ws://localhost:9999

The profile appears in /seam agent as copilot-remote-mac. Neither machine needs an open inbound port — both modes use Cloudflare Tunnel for the outbound-only connection. See docs/remote-agent.md for full setup instructions.

MCP servers

The bot can attach Model Context Protocol servers globally to every session. Configure them via env vars:

Env varServerWhat it adds
MCP_PLAYWRIGHT_ENABLED=true@playwright/mcpReal Chromium browser. Lets the agent navigate sites and take screenshots; screenshots flow back as Discord attachments via the agent-file pipeline. Chromium (~150 MB) is downloaded by Playwright on first run.

Add new servers in src/mcp.ts. Anything that emits image / audio / embedded resource content blocks will be picked up automatically and uploaded to the thread.

Architecture

ChatAdapter          (Discord today, Slack tomorrow)
   ↓
Orchestrator   ──→   Renderer  (platform-specific text formatting)
   ↓
SessionRouter  ──→   SessionStore  (sqlite via better-sqlite3)
   ↓
AgentRuntime         (one per session; auto-resumes on restart)
   ↓
AgentProfile         (Copilot today, Claude Code tomorrow — adds via `src/agents/profiles/`)
  • src/platforms/chat-adapter.ts — generic chat platform interface.
  • src/platforms/discord/ — discord.js v14 implementation + slash commands + repo picker.
  • src/agents/agent-runtime.ts — wraps @agentclientprotocol/sdk + a child process running an ACP server. Handles initialize, session/new, session/load, session/prompt, session/cancel, model / mode / config option setters, and emits typed events.
  • src/agents/profiles/copilot.ts — spawns copilot --acp. Supports configDir for multi-account use and exposes whoami(). Sibling profiles ship for Google Gemini (gemini.ts) and Anthropic Claude Code (claude.ts, via the claude-agent-acp adapter). remote.ts provides a WebSocket-backed profile for agent CLIs running on separate machines (see docs/remote-agent.md). Add a new profile by writing one of these.
  • src/core/ — pure utilities: text chunker, path safety, sqlite store, session router, status panel.

Testing

npm test         # unit tests + 1 integration test against `copilot --acp`
npm run typecheck
npm run build

The ACP integration test is automatically skipped if copilot is not on PATH.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados