<!-- Source: https://console.uubright.com/docs/discord/ -->
# 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](https://console.uubright.com/docs/getting-started/). 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.

> [!NOTE]
> 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.

1. Follow the developer-portal link to create a dedicated Discord application and
   bot. Creating the application remains a manual Discord step.
2. 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.
3. Choose **Add bot to Discord** and add it to your server. The link requests only
   `bot` and `applications.commands`, with no Administrator permission or privileged intents.
4. 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.
5. 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

1. 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.
2. 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.
3. In the application's Installation/OAuth2 settings, add the bot to a private
   server using the `bot` and `applications.commands` scopes. Do not grant
   Administrator. No privileged intents, Message Content intent or public
   Interactions Endpoint URL are needed. Allow the bot to send you DMs.
4. Add these lines to `server.env` in your data directory
   (`~/.local/share/ccr-cloud/server.env` by default):

   ```sh
   DISCORD_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'
   ```

5. [Restart the service](https://console.uubright.com/docs/operations/#restart-the-service) and check that the bot
   connected:

   ```sh
   tmux capture-pane -pt ccr-cloud -S - | grep discord
   ```

   Look 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

1. Run `/ccr sessions` and choose a task from the dropdown.
2. Choose **Open private chat** to enter the bot’s DM.
3. 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](https://console.uubright.com/docs/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_ID` is 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_URL` to 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](https://console.uubright.com/docs/notifications/) in the browser and installed app
- [Configuration](https://console.uubright.com/docs/configuration/#discord)
