Skip to content

About

Run Claude Code on your Windows PC from Discord -- multi-session channels, local voice in/out (drive mode), git worktrees, and confirm-gated dangerous actions.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

101 Commits

Folders and files

Repository files navigation

Discord CC Bot

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-TW in your .env to switch the whole UI (and Claude's replies) to Traditional Chinese. (Source-code comments are in Chinese.)


Features

  • 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 — /sessions lists past conversations and restores any of them into a fresh channel; /search finds 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 AskUserQuestion is 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 /confirm or set CONFIRM_DANGEROUS=1).
  • Scheduling — /schedule sets 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.

How this compares

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.

Security model — read this before you install

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 /adduser can 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/PowerShell commands (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.


Prerequisites

  1. Windows. On a Mac, skip this whole section and the Setup below — run ./setup.sh instead; 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.
  2. Python 3.10+.
  3. Node.js and the Claude Code CLI, installed and signed in:
    npm install -g @anthropic-ai/claude-code
    claude            # run once and complete login
    
    You need an account/plan that can use Claude Code.
  4. A Discord bot application (see Setup below).

Setup

1. Create the Discord bot

  1. Go to the Discord Developer Portal and create a New Application.
  2. Open the Bot tab → Reset Token → copy the token (this is your DISCORD_TOKEN).
  3. Still on the Bot tab, enable Message Content Intent (under "Privileged Gateway Intents"). The bot needs this to read your messages.
  4. Open OAuth2 → URL Generator, tick bot and applications.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.

2. Get the IDs you need

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.)

3. Install and configure

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 /plan and 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.


Running

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 .venv or venv in the project folder, and otherwise falls back to the py launcher. Make sure you created the venv and ran pip install -r requirements.txt inside it. (A bare python on 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.


Updating

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.


Commands

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

Optional features

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 run pip install nvidia-cublas-cu12 nvidia-cudnn-cu12 inside the same venv — a common pitfall is installing them into the system Python instead, which leaves the bot unable to load cublas64_12.dll and voice transcription fails.
  • /schedule → croniter.
  • /screenshot → Pillow.
  • /search by meaning → fastembed (CPU-only, no PyTorch). Without it, /search silently falls back to literal keyword matching.

If you don't want a feature, you can skip its dependency.

Files bigger than Discord's upload limit (SHARE_SCRIPT)

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.

Drive mode (voice reply, F5-TTS)

⚠️ The F5-TTS model is under CC-BY-NC 4.0 — non-commercial use only. /drive is off by default; skip this whole section unless you want voice replies (voice input needs only faster-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
  1. 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-tts package, 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.

  2. 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.


Architecture

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 any engine module is imported. server/config.py freezes DATA_DIR at import time, so a late BUTLER_DATA_DIR sends your sessions to server/data/ instead of data/. That's why every engine import inside lu/bootstrap.py is 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.)


Security notes

  • Your .env holds 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.

License

MIT

About

Run Claude Code on your Windows PC from Discord -- multi-session channels, local voice in/out (drive mode), git worktrees, and confirm-gated dangerous actions.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages