Control Claude Code from your phone — a multi-machine agent hub via Discord. No API key needed — works with your existing Claude Pro or Max subscription.
Anthropic's Remote Control lets you view a running local session from your phone. This bot goes further — it's a multi-machine agent hub that runs as a daemon, creates new sessions on demand, and supports team collaboration.
| This Bot | Official Remote | |
|---|---|---|
| Start new session from phone | ✅ | ❌ |
| Daemon (survives terminal close) | ✅ | ❌ |
| Multi-machine hub | ✅ | ❌ |
| Concurrent sessions per machine | ✅ | ❌ |
| Push notifications | ✅ | ❌ |
| Team collaboration | ✅ | ❌ |
| Native tray app (3 OS) | ✅ | ❌ |
| Zero open ports | ✅ | ✅ |
Create a separate Discord bot per machine, invite them all to the same server, and assign channels:
Your Discord Server
├── #work-mac-frontend ← Bot on work Mac
├── #work-mac-backend ← Bot on work Mac
├── #home-pc-sideproject ← Bot on home PC
├── #cloud-server-infra ← Bot on cloud server
Control every machine's Claude Code from a single phone. The channel list itself becomes your real-time status dashboard across all machines and projects.
Discord isn't just a chat app — it's a surprisingly perfect fit for controlling AI agents:
- Already on your phone. No new app to install, no web UI to bookmark. Open Discord and go.
- Push notifications for free. Get alerted instantly when Claude needs approval or finishes a task — even with the phone locked.
- Channels = workspaces. Each channel maps to a project directory. The sidebar becomes a real-time dashboard of all your projects.
- Rich UI out of the box. Buttons, select menus, embeds, file uploads — Discord provides the interactive components, so the bot doesn't need its own frontend.
- Team-ready by default. Invite teammates to your server. They can watch Claude work, approve tool calls, or queue tasks — no extra auth layer needed.
- Cross-platform. Windows, macOS, Linux, iOS, Android, web browser — Discord runs everywhere.
- 💰 No API key — runs on Claude Code CLI with your Pro or Max subscription
- 📱 Remote control Claude Code from Discord (desktop/web/mobile)
- 🔀 Independent sessions per channel (project directory mapping)
- ✅ Tool use approve/deny via Discord button UI
- ❓ Interactive question UI (selectable options + custom text input)
- ⏹️ Stop button for instant cancellation during progress, message queue for sequential tasks
- 📎 File attachments support (images, documents, code files)
- 🔄 Session resume/delete/new (persist across bot restarts, last conversation preview)
- ⏱️ Real-time progress display (tool usage, elapsed time)
- 🔒 User whitelist, rate limiting, path security, duplicate instance prevention
- 📊 Claude Code usage dashboard in control panel — Session (5hr), Weekly (7day), Weekly Sonnet with progress bars, auto-refresh, click to open usage page
| Category | Technology |
|---|---|
| Runtime | Node.js 20+, TypeScript |
| Discord | discord.js v14 |
| AI | @anthropic-ai/claude-agent-sdk |
| DB | better-sqlite3 (SQLite) |
| Validation | zod v4 |
| Build | tsup (ESM) |
| Test | vitest |
git clone https://github.com/chadingTV/claudecode-discord.git
cd claudecode-discord
# macOS / Linux
./install.sh
# Windows
./install.bat| Platform | Guide |
|---|---|
| macOS / Linux | SETUP.md — terminal-based setup, menu bar / tray app |
| Windows | SETUP-WINDOWS.md — GUI installer, system tray app with control panel, desktop shortcut |
Windows users: install.bat handles everything automatically — installs dependencies, builds, creates a desktop shortcut, and launches the bot with a system tray GUI.
Project Structure
claudecode-discord/
├── install.sh / install.bat # Auto-installers
├── mac-start.sh # macOS background launcher + menu bar
├── linux-start.sh # Linux background launcher + system tray
├── win-start.bat # Windows background launcher + system tray
├── menubar/ # macOS menu bar app (Swift)
├── tray/ # System tray app (Linux: Python, Windows: C#)
├── src/
│ ├── index.ts # Entry point
│ ├── bot/
│ │ ├── client.ts # Discord bot init & events
│ │ ├── commands/ # Slash commands (10)
│ │ └── handlers/ # Message & interaction handlers
│ ├── claude/
│ │ ├── session-manager.ts # Session lifecycle
│ │ └── output-formatter.ts # Discord output formatting
│ ├── db/ # SQLite (better-sqlite3)
│ ├── security/ # Auth, rate limit, path validation
│ └── utils/ # Config (zod)
├── SETUP.md # macOS/Linux setup guide
├── docs/ # Translations, screenshots
└── package.json
| Command | Description | Example |
|---|---|---|
/register <folder> |
Link current channel to a project | /register my-project |
/unregister |
Unlink channel | |
/status |
Check all session statuses | |
/stop |
Stop current channel's session | |
/auto-approve on|off |
Toggle auto-approval | /auto-approve on |
/sessions |
List sessions to resume or delete | |
/last |
Show the last Claude response from current session | |
/usage |
Show Claude Code usage (Session 5hr / Weekly / Sonnet) | |
/queue list |
View queued messages (cancel individually or all) | |
/queue clear |
Cancel all queued messages | |
/clear-sessions |
Delete all session files for the project |
The /register command shows an autocomplete dropdown listing subdirectories under BASE_PROJECT_DIR — just start typing to filter and select.
The first option . registers the base directory itself. You can also type a custom path; absolute paths work too.
Why per-directory? Claude Code manages sessions per project directory — each directory has its own conversation history,
CLAUDE.mdcontext, and tool permissions. By mapping one Discord channel to one directory, each channel gets an independent Claude workspace.
Send a regular message in a registered channel and Claude will respond. Attach images, documents, or code files and Claude can read and analyze them.
- ⏹️ Stop button on progress messages for instant cancellation
- Sending a new message while busy offers message queue — auto-processes after current task completes
/queue listto view queued messages — cancel individually (❌) or all at once/stopslash command also available
Architecture
[Mobile Discord] ←→ [Discord Bot] ←→ [Session Manager] ←→ [Claude Agent SDK]
↕
[SQLite DB]
- Independent sessions per channel (project directory mapping)
- Claude Agent SDK runs Claude Code as subprocess (shares existing auth)
- Tool use approval via Discord buttons (auto-approve mode supported)
- Streaming responses edited every 1.5s into Discord messages
- Heartbeat progress display every 15s until text output begins
- Markdown code blocks preserved across message splits
Session States: 🟢 working · 🟡 waiting for approval · ⚪ idle · 🔴 offline
This bot does not open any HTTP servers, ports, or API endpoints. It connects to Discord via an outbound WebSocket — there is no inbound listener, so there is no network path for external attackers to reach this bot.
Typical web server: External → [Port open, waiting] → Receives requests (inbound)
This bot: Bot → [Connects to Discord] → Receives events (outbound only)
The bot runs entirely on your own PC/server. No external servers involved, and no data leaves your machine except through Discord and the Anthropic API (which uses your own Claude Code login session).
ALLOWED_USER_IDSwhitelist-based authentication — all messages and commands from unregistered users are ignored- Discord servers are private by default (no access without invite link)
- Per-minute request rate limiting
- Tool use default: file modifications, command execution, etc. require user approval each time (Discord buttons)
- Path traversal (
..) blocked - File attachments: executable files (.exe, .bat, etc.) blocked, 25MB size limit
- The
.envfile contains your bot token — never share it publicly. If compromised, immediately Reset Token in Discord Developer Portal auto-approvemode is convenient but may allow Claude to perform unintended actions — use only on trusted projects
Each platform runs the bot as a background service with a native GUI for control — no terminal babysitting needed.
./mac-start.sh # Start (background + menu bar icon)
./mac-start.sh --stop # StopControl panel GUI (left-click icon), Claude Code usage dashboard (Session 5hr / Weekly / Sonnet, click to open usage page), settings dialog, auto-update, auto-restart on crash, auto-start on boot (launchd). → Full guide
./linux-start.sh # Start (systemd + tray icon)
./linux-start.sh --stop # StopGTK3 control panel (left-click tray icon), Claude Code usage dashboard, settings dialog, auto-restart, auto-start on boot (systemd). Works headless too. → Full guide
win-start.bat &:: Start (background + tray + control panel)
win-start.bat --stop &:: StopDesktop shortcut, control panel GUI, Claude Code usage dashboard, settings dialog, auto-update, auto-start on logon (Registry). → Full guide
npm run dev # Dev mode (tsx)
npm run build # Production build (tsup)
npm start # Run built files
npm test # Tests (vitest)
npm run test:watch # Test watch modeMIT License - Free to use, modify, and distribute commercially. Attribution required: include the original copyright notice and link to this repository.
If you find this project useful, please consider giving it a ⭐ — it helps others discover it!