Discord control
Start tasks, send follow-ups, answer approvals and get notified from Discord. The bot controls the same tasks as the web app, and only you can use it.
Set this up after a browser task works. The bot connects out to Discord, so it needs no public webhook, and it needs no extra model API key.
Discord is an extra way in, not a replacement. The web app and your phone keep working exactly as before, on the same tasks: start a task in Discord and follow it in the browser, or the other way round. An approval can be answered from either place; the first answer counts and the other is rejected. Enabling the bot doesn't make the web app public either.
Choose a task with /ccr sessions, then continue with ordinary messages in the bot’s private DM. Public channel messages are never forwarded.
#Set up from the PWA
Sign in using the server owner token, then open ⋯ → Settings → Messaging. On a phone signed in with a pairing link, the page explains that it needs the owner token instead. Paired-device tokens cannot read or change these settings. On a phone, use the owner token if you need to configure a channel.
- Follow the developer-portal link to create a dedicated Discord application and bot. Creating the application remains a manual Discord step.
- Paste its bot token once and choose Save bot token, then Connect / reconnect. The host validates the token with Discord and stores it privately; the browser never receives the saved token. An invalid replacement leaves existing settings intact.
- Choose Add bot to Discord and add it to your server. The link requests only
botandapplications.commands, with no Administrator permission or privileged intents. - Choose Create pairing code → Copy code. In Discord, type
/ccr pair, select the bot’s slash command, and paste only the code into its code field. The one-use code expires after five minutes. Keep it private: the account that redeems it receives access to your tasks. Wrong attempts are limited per Discord account, so other guild members cannot exhaust your attempts; new codes replace old ones and are throttled to one every 30 seconds. - Choose Send test message and check your Discord DMs. Try
/ccr sessions.
You can disconnect, reconnect, or forget the token without restarting the server. A pending connection can be cancelled with Disconnect or Forget; saving a replacement token also cancels it before validating the new token. Disconnect retains local credentials but disables automatic startup. Forget removes local credentials; revoke/reset the token in Discord if it may have been exposed. Connect returns immediately with a Connecting status; the page polls until ready or an actionable failure. Global slash-command registration can take time to appear.
The private file is DATA_DIR/messaging-discord.json (mode 0600). Pairing codes live only in memory and are invalidated by disconnect, reconnect or server restart. Do not publish the data directory.
If any of DISCORD_BOT_TOKEN, DISCORD_OWNER_ID, or DISCORD_GUILD_ID is set, the page shows Managed by server.env and cannot replace or remove that configuration. Existing environment-based setups keep their owner and behavior. Remove these variables and restart once to move configuration to the PWA.
#Set up the bot manually
- Create an application in https://discord.com/developers/applications and create its bot. Use a dedicated application for this server. Copy the bot token into your private server configuration; never put it in a repository or chat.
- In Discord, turn on Settings → Advanced → Developer Mode, then right-click your own name and select Copy User ID. Use your user ID (not a username, server ID or bot ID). Only that numeric user ID can read or control tasks through the bot. This is the manual alternative to the PWA pairing code.
- In the application's Installation/OAuth2 settings, add the bot to a private server using the
botandapplications.commandsscopes. Do not grant Administrator. No privileged intents, Message Content intent or public Interactions Endpoint URL are needed. Allow the bot to send you DMs. Add these lines to
server.envin your data directory (~/.local/share/ccr-cloud/server.envby default):SHELLDISCORD_BOT_TOKEN='YOUR_BOT_TOKEN' DISCORD_OWNER_ID='YOUR_NUMERIC_USER_ID' # Optional: register commands in this guild for quicker development testing. DISCORD_GUILD_ID='YOUR_PRIVATE_SERVER_ID' # Optional link button; use a URL reachable from your phone/browser. CCR_CLOUD_PUBLIC_URL='https://your-private-host.example'Restart the service and check that the bot connected:
SHELLtmux capture-pane -pt ccr-cloud -S - | grep discordLook for
[discord] connected; owner-only /ccr commands ready. Global registration (without a guild ID) may take time to appear. Guild-only commands appear in that guild, not in DMs. All guild responses are ephemeral.
Commands are registered at startup using the bot application's identity. The adapter only updates its /ccr command and leaves unrelated application commands alone. When switching from guild-only to global registration, remove the old guild command in Discord to avoid seeing both registrations. Removing the configuration stops the integration but does not unregister its commands on Discord.
#Chat privately with a task
- Run
/ccr sessionsand choose a task from the dropdown. - Choose Open private chat to enter the bot’s DM.
- Send ordinary text. The bot forwards it to the selected task and sends the completed reply automatically; you do not need to poll status.
Use Switch task to change the active task, or Refresh status to inspect it. The DM has one active task, remembered across reconnects; each reply identifies its task. /ccr chat session:SESSION_ID selects a task directly. A stopped task must be resumed explicitly. Questions and tool approvals still need their dedicated controls or commands; ordinary text does not approve a tool or answer a pending question.
#Commands
/ccr pair code:YOUR_CODE
/ccr new prompt:Fix the failing tests repo:https://github.com/you/project.git
/ccr sessions
/ccr chat session:s-...
/ccr status session:s-...
/ccr say session:s-... text:Add a regression test for the edge case
/ccr interrupt session:s-...
/ccr stop session:s-...
/ccr resume session:s-...
/ccr permission session:s-... request:REQUEST_ID decision:allow
/ccr answer session:s-... request:REQUEST_ID text:2
new without repo creates a scratch workspace. Tasks started from Discord use the server's default permission mode and response style; to choose Auto or Concise for a task, start it from the web app or the HTTP API. Session IDs are displayed in command responses and in the PWA. Follow-ups go directly to that Claude session. Ordinary public-channel messages are ignored. In the bot’s DM, ordinary text goes only to your selected task. Inspect a permission using /ccr status before answering; DM approval buttons are tied to an exact session and request. A decision already submitted from either Discord or the PWA is rejected until the request resolves.
When Claude asks a question, /ccr status and the DM list it with numbered options. Answer with /ccr answer: an option number, several comma-separated for a multi-choice question, or your own words; for several questions, separate the answers with ; in question order, for example text:2; 1,3. The DM has a Skip question button but no button that picks an answer, and decision:allow is refused for questions.
#Notifications
By default the adapter DMs the owner when a new turn finishes, a session fails, a tool needs approval, or Claude asks a question. It does not stream every token or send routine status updates. Turn completion means Claude ended a turn, not independent verification that tests passed. Messages may include repository names, tool inputs and model output: enabling this option sends that content to Discord.
Use DISCORD_NOTIFICATIONS=0 to disable notices from other tasks. Replies and approval notices for your selected chat task still arrive. On first setup or first account pairing, old notifications are skipped. An already-paired bot retains saved notification positions across restarts and reconnects, so notices raised while disconnected are delivered when it returns. After a long disconnect this may deliver many DMs; disable notifications before reconnecting if you prefer to inspect tasks manually. Use status to inspect any already-pending approval. Later scan progress is persisted in discord-cursors.json. Delivery failures retry; a crash between sending and persisting progress can duplicate a notification.
Routine gateway reconnects are handled automatically. The settings page reports Needs attention for terminal authentication/configuration disconnects or an invalidated session. Environment-managed bots use DISCORD_OWNER_ID; /ccr pair explains this instead of directing you to unavailable pairing controls.
#Troubleshooting
- No commands: check guild ID, installation scopes and bot membership; restart the control plane. Ensure the host can reach Discord's HTTPS API and Gateway.
- Paired to another user: verify
DISCORD_OWNER_IDis your user ID. Every command and button checks this identity, including in shared servers. - No DMs: enable DMs from the bot/shared server and check server logs. The PWA and slash commands remain usable when notification delivery fails.
- Link opens nowhere: set
CCR_CLOUD_PUBLIC_URLto your real HTTPS/VPN URL; the bot cannot open a laptop SSH tunnel or configure server networking for you. - A stale approval button fails: refresh task status; another surface may already have answered it. The adapter never silently approves a different request.
#Next steps
- Notifications in the browser and installed app
- Configuration