Discord

The Discord integration connects your Discord server with Almirant to execute agent commands, receive project event notifications, and control work sessions directly from the chat.

How it works

Almirant integrates with Discord through a bot that uses OAuth2 to connect to your server. The bot can:

• Execute slash commands -- Commands like /implement and /plan to launch agent jobs from Discord.
• Send notifications -- Almirant notifies via Discord about relevant events (work items, sprints, PRs, CI/CD).
• Control sessions -- Interactive buttons to stop, pause, or respond to agent questions.
• Create automatic threads -- Each agent job creates a dedicated thread to track its progress.

Setting up the Discord integration

1. Connect via OAuth

Unlike other bots, Discord uses OAuth2 for a secure connection:

1. Go to Settings > Integrations > Discord.
2. Click Connect Discord.
3. Discord will ask you to select a server where you have administrator permissions.
4. Authorize the requested permissions (send messages, create threads, use slash commands).
5. Almirant will automatically register the slash commands on your server.

2. Configure default channel

After connecting:

1. Go to Settings > Integrations > Discord.
2. Select the default channel where the bot will send notifications.
3. Save the configuration.

3. Verify the connection

1. In the Discord settings, click Send test message.
2. Verify that the message appears in the selected channel.

Slash commands

The Discord bot supports slash commands to interact with Almirant:

Command	Description
/implement [work_item_id]	Launches an implementation job for the specified work item
/plan [work_item_id]	Launches a planning job for the specified work item
/status	Shows active jobs (queued, running, waiting_for_input)
/status [job_id]	Shows detailed status of a specific job

Command options

The /implement and /plan commands accept additional options:

Option	Description
work_item_id	(Required) The work item ID (e.g., A-123)
provider	(Optional) The agent provider: claude-code, codex, or zipu

Usage example

/implement work_item_id:A-1189
/implement work_item_id:A-1189 provider:claude-code
/plan work_item_id:A-1190
/status job_id:abc123-def456

Automatic threads

When you execute a slash command, the bot automatically creates a private thread for that job:

• The thread name indicates the job type and task ID
• All agent progress messages go to the thread
• Control buttons (Stop, Shutdown) appear in the thread
• The thread auto-archives after 24 hours of inactivity

Interactive buttons

During job execution, the bot displays buttons to control the session:

Button	Action
Stop	Stops the current job but maintains state
Shutdown	Completely stops and closes the session

When the agent has a question, options appear as buttons or a selection menu. Select the desired option to respond.

Notifications

Configure which project events you want to receive as Discord notifications:

Event	Description
Work item created	A new work item is created
Work item moved	A work item changes column on the board
Work item assigned	A work item is assigned to someone
Work item completed	A work item is marked as done
Sprint started/closed	A sprint begins or ends
Milestone completed	A milestone is completed
PR opened/merged	A pull request is opened or merged
CI failed	A CI build fails
Agent job completed/failed	An agent job finishes

To configure notifications:

1. Go to Settings > Integrations > Discord.
2. Click Configure notifications.
3. Enable or disable the desired events.
4. Save the changes.

Linking projects to channels

You can configure specific channels for different projects:

1. Go to the project settings.
2. In the Discord section, select the target channel.
3. Notifications and threads for that project will go to the configured channel.

If there's no specific channel, the organization's default channel is used.

Disconnecting Discord

To disconnect the bot:

1. Go to Settings > Integrations > Discord.
2. Click Disconnect.
3. Confirm the disconnection.

warning

Disconnecting the bot will stop slash commands and notifications via Discord. Jobs in progress will not be automatically cancelled.

For Developers

Integration architecture

The Discord integration consists of two main routes:

• OAuth routes (/api/integrations/discord): Handles the OAuth2 flow, connection management, channels, and notification preferences.
• Interactions webhook (/webhooks/discord/interactions): Receives and processes slash commands, buttons, and selection menus.

OAuth flow

User --> GET /authorize --> Discord OAuth --> GET /callback
                                                    |
                                  +------------ Token exchange
                                  |
                          Create connection + Register slash commands

Interactions flow

Discord --> POST /webhooks/discord/interactions --> Verify signature
                                                         |
                              +--------------------------+
                              |           |              |
                            PING     Command        Component
                              |           |              |
                           PONG    Queue job      Process action

Registered slash commands

Commands are automatically registered in the guild during OAuth:

• implement: Launches implementation job
• plan: Launches planning job
• status: Queries job status

Signature verification

All interactions are verified using Ed25519 with Discord's public key (DISCORD_PUBLIC_KEY). This ensures requests originate from Discord.

Environment variables

Variable	Description
DISCORD_CLIENT_ID	Discord application ID
DISCORD_CLIENT_SECRET	Application secret
DISCORD_PUBLIC_KEY	Public key for signature verification
DISCORD_BOT_TOKEN	Bot token for sending messages
DISCORD_APPLICATION_ID	Application ID (for slash commands)
DISCORD_OAUTH_REDIRECT_URI	OAuth callback URI