Control Claude Code on your Windows PC or Mac from Discord. Send a message in a Discord channel and the bot runs it through the Claude Code CLI on your machine — editing files, running commands, searching the web, and more — then streams the result back to you.
Language: the bot's interface and Claude's replies default to English. Set
BOT_LANG=zh-TWin your.envto switch the whole UI (and Claude's replies) to Traditional Chinese. (Source-code comments are in Chinese.)
- Chat-driven Claude Code — every message in the bound channel becomes a Claude Code turn on your PC, with live "thinking" progress updates.
- Multi-conversation sidebar — each Discord channel under a category maps to its own Claude session, like tabs. Create, rename, and delete conversations.
- Session history —
/sessionslists past conversations and restores any of them into a fresh channel;/searchfinds conversations by meaning, not just keywords. - Voice input — send a voice message and it's transcribed locally with Whisper (no cloud STT), then handled as a normal prompt.
- File transfer — the bot can upload files back to Discord; you can also drop files into the chat for Claude to read.
- Interactive questions — Claude's
AskUserQuestionis rendered as Discord buttons; your click is fed back as the answer. - Transparency & safety — each turn shows the command being processed at the
top so you can verify it's really yours, Claude states its plan before acting,
dangerous actions are flagged with
⚠️ , and destructive commands (delete, git push, shutdown…) can pop a confirm button before they run (off by default — toggle with/confirmor setCONFIRM_DANGEROUS=1). - Scheduling —
/schedulesets up recurring tasks (cron under the hood). - Model & effort control — switch model (Sonnet / Opus / Haiku) and thinking effort on the fly; automatic fallback model when the primary is overloaded.
- Talk to it mid-task — a message sent while a turn is running is injected into that turn, not queued behind it. Claude picks it up at its next step and the message is marked as having cut in.
- Long jobs keep running — background commands report back when they finish and wake Claude to continue on its own, instead of the turn being declared stuck.
- Resilience — waits out rate limits and resumes by itself when the quota resets, context auto-compaction, and per-message error isolation so one bad turn won't kill the session.
- Screenshots, usage stats, PowerPoint→PDF and more.
Most "Claude + chat" bots wrap the Claude API — a stateless chat box. This one drives the Claude Code CLI on your own PC, so every message has real file, shell, and web access with full session state. A few things it does that similar bridges (mostly Telegram, mostly single-session and text-only) generally don't:
- Sessions as channels, not one thread. Each Discord channel under a category is its own persistent Claude Code session — create, rename, restore, and semantic-search across them. Most bridges give you a single conversation.
- Voice in and out, fully local. "Drive mode" transcribes your voice messages with Whisper and speaks Claude's reply back with F5-TTS — all on your own GPU, no cloud STT/TTS. Made for hands-free/driving use.
- Interruptible turns. Send a correction while it's working and it lands in the current turn — most bridges make you wait for the reply, then start over.
- Git worktree parallelism. Spin off an isolated worktree per conversation so parallel edits don't collide, then merge back from Discord.
- Built for trust. It runs with
bypassPermissions, so every turn shows the exact command it's running, states its plan before acting, and can pop a confirm button before destructive actions (opt-in via/confirm; see Security model below). - Runs unattended on Windows. Silent background launcher, a tiny start/stop control panel, crash self-heal, rate-limit retries, and context auto-compaction.
Be clear about what you are deploying: messages in your Discord channels become
arbitrary code execution on your PC, running as your user with
permission_mode=bypassPermissions (Claude does not ask before acting).
What protects you, and from what:
- Access control is exactly two allowlists: your Discord user ID
(
ALLOWED_USER//adduser) and the bound channels. That is a single factor. If your Discord account is compromised, your PC is compromised. Anyone you/addusercan run code on your machine — treat it like handing over SSH keys. - The destructive-command confirm button is advisory, not a sandbox. It is a
regex blocklist over
Bash/PowerShellcommands (delete / format /git push/ shutdown…), off by default, and a determined bypass is trivial (e.g. running the same action through a Python one-liner). It exists to catch accidents and hallucinated commands, not attackers. - Prompt injection is a real surface. Files you drop into chat and web pages
Claude reads can carry instructions. The transparency features (the 📥 command
echo, plan-before-acting,
⚠️ flags) exist so you can catch this — you are the last line of defense.
Deployment recommendations: use a dedicated private server with no other
members; enable 2FA on your Discord account; don't /adduser anyone you wouldn't
give shell access; turn on confirmations (/confirm on or CONFIRM_DANGEROUS=1);
run under a non-administrator Windows account; set DEFAULT_DIR to scope where
work happens by default.
- Windows. On a Mac, skip this whole section and the Setup below —
run
./setup.shinstead; it installs everything and only stops where you have to act (create the bot, paste its token, sign in to Claude). Details in README_mac.md. - Python 3.10+.
- Node.js and the Claude Code CLI, installed and signed in:
You need an account/plan that can use Claude Code.
npm install -g @anthropic-ai/claude-code claude # run once and complete login - A Discord bot application (see Setup below).
- Go to the Discord Developer Portal and create a New Application.
- Open the Bot tab → Reset Token → copy the token (this is your
DISCORD_TOKEN). - Still on the Bot tab, enable Message Content Intent (under "Privileged Gateway Intents"). The bot needs this to read your messages.
- Open OAuth2 → URL Generator, tick
botandapplications.commands, give it permissions (Send Messages, Manage Channels, Read Message History, Attach Files), then open the generated URL to invite the bot to your server.
Enable Developer Mode in Discord (Settings → Advanced → Developer Mode),
then right-click your own name → Copy User ID to get your ALLOWED_USER.
(No channel ID needed — on first launch the bot creates its own category and an entry channel with a New chat button; every conversation you open from there is authorized automatically.)
git clone https://github.com/Burtle-useless/discord-cc-bot.git
cd discord-cc-bot
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
Then open .env and fill in DISCORD_TOKEN and ALLOWED_USER. The rest are
optional (see comments in the file).
The clone already includes the engine (server/) — there is no second repo to
fetch and nothing to point at. See Architecture if you want to
know what lives where.
Model & context: by default the bot uses
default, Claude Code's own alias for the model it currently recommends for your account, so it moves to newer models without any config change. Tell the bot your plan with/planand it applies Anthropic's official rule: on Max / Team / Enterprise, Opus automatically gets the 1M context window with no extra setup. For every other case (Sonnet on any plan, or Opus on Pro), opt into 1M by adding the[1m]alias to the model (e.g.claude-sonnet-4-6[1m]), which requires 1M usage credits. If you ever see "Usage credits required for 1M context", a 1M model was selected without the entitlement.
With the virtualenv active:
python -m lu
To check your configuration without connecting to Discord (useful right after
editing .env), add --check: it loads the engine, resolves the model and
working directory, registers the commands, prints a one-screen summary, and
exits.
To run it silently in the background (no console window), double-click
launch_bot.vbs. It uses the .venv Python if present and logs to
discord_bot.log.
Control panel (optional): double-click control-panel.vbs for a tiny GUI
to Start / Stop / Restart the bot and View Log — no command line needed.
It shows a live running/stopped status and works from the project folder.
Crash self-heal (optional, watchdog): register a scheduled task that checks every 5 minutes and relaunches the bot if it died unexpectedly:
schtasks /create /tn ccbot-watchdog /sc minute /mo 5 /tr "powershell.exe -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File <FULL-PATH-TO>\watchdog.ps1"
(If your project path contains spaces, create the task via the Task Scheduler
GUI instead — schtasks /tr quoting is fragile.) The bot arms the watchdog on
every startup by creating a watchdog_enabled marker file. To stop the bot
without it being auto-revived, double-click stop_bot.vbs — it disarms the
watchdog first, then kills the bot. Any normal start re-arms it automatically.
The watchdog restarts through _restart_now.ps1 rather than restart_bot.vbs,
for two reasons worth knowing if you ever restart the bot yourself. First, every
launch path redirects with a single >, so starting the bot truncates
discord_bot.log — destroying the crash output from the run that just died,
which is the one thing worth reading at that moment; the script rolls it to
discord_bot.log.1 first. Second, the script re-launches itself through WMI
before killing anything: a restart triggered from inside a Claude Code session
would otherwise be reaped by its own taskkill /F /T, since that session is a
child of the bot — the bot gets killed and never comes back. Progress is logged
to restart.log.
Won't start, and the log is empty? The launcher needs a working Python with the dependencies. It looks for a virtualenv named
.venvorvenvin the project folder, and otherwise falls back to thepylauncher. Make sure you created the venv and ranpip install -r requirements.txtinside it. (A barepythonon Windows can be the Microsoft Store stub, which silently does nothing — that's the usual cause of an empty log.)
Now type a message in your bound channel — the bot should respond.
You cloned this repo, so updating is just a pull:
git pull
That brings in the latest code. A release only occasionally changes
dependencies — when it does, re-run pip install -r requirements.txt inside your
virtualenv (the core deps rarely move; optional extras like voice are opt-in).
Then restart the bot. There's no auto-update, so pull whenever you want the
latest.
New models need no update of this repo. The /model list comes from
Anthropic's official model list, so a new model shows up on release day. It
often needs a newer Claude Code than the one bundled with your installed
claude-agent-sdk, though; until you update, /model still lists it but marks
it as needing an update and won't apply it. To update: stop the bot, run
pip install -U claude-agent-sdk inside the virtualenv, then start the bot
again. Stop it first — Windows won't let pip overwrite the claude.exe a running
bot is using, and the install fails halfway.
New conversations are created from the New chat button in the sidebar's entry channel, not with a command.
| Command | What it does |
|---|---|
/continue |
Resume the previous session in this channel |
/rename |
Rename the current conversation (blank = auto-title) |
/sessions |
List past conversations and restore one |
/search |
Search past conversations by meaning (semantic; needs fastembed, else keyword) |
/recall |
Cross-check what you actually said against the records |
/handoff |
Write a handoff brief so another machine can take over |
/guide |
Built-in user manual — pick a topic, get a plain-language walkthrough |
/stop |
Stop the currently running task |
/status |
Show current status |
/model, /effort |
Set the model / thinking effort (this chat, or as the default) |
/plan |
Set your subscription plan (applies the official 1M-context rule) |
/confirm |
Toggle the dangerous-action confirmation prompt |
/drive |
Drive mode: voice in, voice out (on/off) |
/worktree |
Give this channel its own git worktree (isolated branch) |
/cd, /pwd |
Change / show the working directory |
/screenshot |
Capture the PC screen |
/usage |
Show plan usage (5h / 7d) |
/schedule, /schedules |
Create / manage scheduled tasks |
/adduser, /removeuser, /listusers |
Manage who may use the bot |
/addchannel, /removechannel |
Run the bot in additional channels |
/help |
Show all commands |
Some features need extra packages (already listed in requirements.txt):
- Voice transcription →
faster-whisper(downloads a Whisper model on first use). Runs on CPU out of the box. For NVIDIA GPU acceleration, also runpip install nvidia-cublas-cu12 nvidia-cudnn-cu12inside the same venv — a common pitfall is installing them into the system Python instead, which leaves the bot unable to loadcublas64_12.dlland voice transcription fails. /schedule→croniter./screenshot→Pillow./searchby meaning →fastembed(CPU-only, no PyTorch). Without it,/searchsilently falls back to literal keyword matching.
If you don't want a feature, you can skip its dependency.
By default, a file too large to upload is reported by name and local path — no
use to you if you're away from the machine. Set SHARE_SCRIPT in .env to a
PowerShell script and the bot will instead hand back a temporary download link:
SHARE_SCRIPT=C:\path\to\upload-link.ps1
SHARE_HOURS=24
The script is invoked as <script> <file> -As <name> -Hours <n> and must print
the download URL to stdout (anything that opens a temporary tunnel works —
cloudflared, ngrok, an upload CLI…). The bot picks the first https://… in
the output. Only the first oversized file per message is shared, since such
tunnels usually serve one file at a time. Non-ASCII filenames are transliterated
away first — they'd otherwise turn the URL into a long percent-encoded string
that chat clients like to truncate.
Removing voice entirely. All the voice code — Whisper speech-to-text, F5-TTS
text-to-speech, and the GPU helpers — lives in one standalone, optional module:
drive_core.py. The main bot imports it optionally, so if you never want voice
you can simply delete drive_core.py: the bot detects it's gone, runs
text-only with no errors, and /drive just reports that drive mode isn't
installed. Nothing else needs editing.
⚠️ The F5-TTS model is under CC-BY-NC 4.0 — non-commercial use only./driveis off by default; skip this whole section unless you want voice replies (voice input needs onlyfaster-whisper, above).
Voice reply now uses F5-TTS, which is far simpler to set up than the old
XTTS path — no FFmpeg DLLs, no torchcodec, no license env var. Run this
inside your venv:
pip install f5-tts
-
Reference voice — nothing to do. F5-TTS is a zero-shot voice clone, so it needs a short reference clip. This bot reuses the sample that ships inside the
f5-ttspackage, so there's nothing to record, download, or place, and no audio in this repo. The English UI uses the English sample; the Chinese UI (BOT_LANG=zh-TW) uses the Chinese one. -
GPU (recommended). A plain install pulls the CPU build of PyTorch, so synthesis takes minutes per reply. For an NVIDIA GPU, install a CUDA 12.x build of torch, e.g.:
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu126⚠️ Use a cu12x build (cu126 / cu128) — not cu13x, even if your driver supports CUDA 13. Voice input (faster-whisper / ctranslate2) loads CUDA-12 cuDNN, and a cu13 torch build clashes with it in the same process (CUDNN_STATUS_SUBLIBRARY_VERSION_MISMATCH), which makes /drive voice replies silently fall back to text. On GPU, synthesis is a few seconds per reply.
The first /drive on downloads the F5-TTS model (~1.3 GB) and its vocoder.
Two layers, and the split is worth knowing before you change anything:
lu/ Discord front-end: slash commands, the sidebar, rendering a turn
into Discord messages, voice, permissions. No turn logic at all.
server/ The engine: queueing, steering a running turn, rate-limit waits and
auto-resume, context compaction, background-task wake-ups, session
state, model catalogue, personas.
drive_core.py, wt_core.py Optional standalone modules (voice, git worktrees).
server/ is a complete copy that ships with this repo — clone and it works.
Nothing external to install or point at. The same engine also drives a phone-app
front-end the author maintains separately; this repo does not depend on it.
The server/ files are kept identical to that copy, so some comments mention the
phone app or its endpoints (system_api, the in-app SDK updater, PEER_RESTART).
Those parts are simply unused here.
Two rules the code relies on, both of which fail silently if broken:
bootstrap.prepare()must run before anyenginemodule is imported.server/config.pyfreezesDATA_DIRat import time, so a lateBUTLER_DATA_DIRsends your sessions toserver/data/instead ofdata/. That's why everyengineimport insidelu/bootstrap.pyis function-local.- The system-prompt append must not contain a newline. The CLI's initialize
handshake stalls for 60 seconds if it does. See
lu/profile.py.
There is no personality layer, on purpose. This front-end is a plain Claude
Code tool, not a character. What it adds to the system prompt is the
system_prompt string in lu/i18n.py — platform facts and formatting rules,
not a voice. Edit that string if you want to change its behaviour.
(server/personas/*.txt belong to the engine's other front-end. Leave the files
where they are — engine/options.py reads them at import time — but nothing on
the Discord side loads them.)
- Your
.envholds a bot token and is gitignored — never commit it. - The bot runs Claude Code with
bypassPermissions, i.e. it can edit files and run commands on your machine without prompting. Only allow trusted users (ALLOWED_USER) and keep the bot in a private server.