claude-code-discord-bot-hooks

Discord Hook for Claude Code

Routes Claude Code hook events to a Discord channel — approval requests, notifications, and session stop signals — with interactive Approve/Deny buttons. Also provides slash commands to inspect active sessions and conversation history.

Highlights

• No Claude subscription required — runs entirely on Claude Code's hook system; all you need is a Discord bot token.
• Not a full Discord-based Claude replacement — this is a remote monitor and permission handler with bidirectional sync support. Use the /sync command to forward prompts from a forum thread to your running Claude Code session via tmux, and receive responses back in the thread.
• Remote session monitoring — approve or deny permission requests from your phone while away from your computer. Requests time out after 120 seconds with graceful fallback.
• Session sync — /sync mirrors a Claude Code session's conversation to a Discord forum post. Type in the forum thread to send prompts back to the running session, with responses posted back as replies.
• AskUserQuestion support — Claude's multi-choice questions appear as Discord Select menus; an "Answer with text" button opens a Modal for free-text responses.
• ExitPlanMode support — plan approval requests show the full plan content in Discord with Approve, Reject, and Give Feedback buttons. "Give Feedback" opens a Modal so you can type revision instructions directly.
• History view with tail — the /history slash command supports an optional tail parameter to see only the latest updates from your session, rendered in a Discord thread.
• Thread-based organization — each session gets its own Discord thread, labeled with the hostname and session name (e.g., Session tony-mbp-my-project), keeping your server tidy even across multiple machines.

Architecture

Claude Code hook event
        │
        ▼
notify_discord.py          ← thin hook shim (spawned per-event, exits fast)
        │  writes decision file
        ▼
~/.claude/discord-decisions/   ← shared decision directory
        ▲
        │  reads/writes
discord_bot.py             ← persistent bot process (long-lived, holds connection)
        │
        ▼
Discord channel / thread

notify_discord.py — the hook entry point. Claude Code invokes it for every registered event. For PermissionRequest events it polls ~/.claude/discord-decisions/<request_id>.json until the bot writes a decision; all other events are fire-and-forget.

discord_bot.py — a long-lived discord.py bot. It listens for button interactions from Discord, writes decision files to ~/.claude/discord-decisions/, and exposes slash commands for session inspection.

Supported Hook Events

Event	Behaviour
PermissionRequest	Posts Approve / Deny / permission-suggestion buttons; also handles AskUserQuestion (Select menus + text modal) and ExitPlanMode (plan content + Approve / Reject / Give Feedback)
Stop	Posts the assistant's final message to the session thread
SubagentStop	Same as Stop, labelled with the agent type

Slash Commands

Command	Channel	Description
/sessions	Inspect channel	List active/recent Claude Code sessions
/history [session]	Inspect channel	Show conversation history for a session in a thread
/summary [date]	Summary channel	Post daily project usage (tokens, models, duration)
/sync [session]	Inspect channel	Sync a session to a forum thread for bidirectional control

session can be a numeric index (default 0) or a sessionId prefix.

Setup

1. Install uv (required)

The hook scripts use uv run to auto-manage the Python environment.

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify: uv --version

2. Install from Claude Code Marketplace

In Claude Code, run:

/plugins install TonyWu20/my-claude-marketplace#claude-code-discord-bot-hooks

This automatically installs the plugin and registers all hook events in your Claude Code configuration.

2. Create a Discord Bot

1. Go to https://discord.com/developers/applications and create a new application.
2. Under Bot, enable Message Content Intent.
3. Under OAuth2 → URL Generator, select scopes bot and permissions Send Messages, Create Public Threads, Read Message History.
4. Invite the bot to your server with the generated URL.
5. Copy the bot token.

3. Set Environment Variables

Add these to your shell profile (e.g. ~/.config/fish/config.fish, ~/.zshenv):