Cord

A Discord harness for Claude Code. Thread-based conversations, interactive elements, works anywhere you already run Claude.

cord /kôrd/ — a connection between two things.

Uses Discord threads for individual Claude Code sessions. No exposed ports — runs outbound over the Discord bot API. Works with your Max plan on any machine that can run Claude Code CLI.

What You Get

• Thread-based sessions — Each @mention spawns a Claude Code session in its own thread with full context preserved
• Rich interactions — Embeds, buttons, file attachments, status tracking
• Status visibility — See "Processing → Done" right in the channel without opening threads
• Claude Code skill — Teaches your assistant the commands. No MCP server needed.

Quick Start

# Create a new Cord project
bunx create-cord my-bot
cd my-bot

# Start Redis (if not already running)
redis-server &

# Start Cord
cord start

git clone https://github.com/alexknowshtml/cord.git my-bot
cd my-bot
bun install
cord setup
cord start

Prerequisites

• Bun runtime
• Redis server
• Claude Code CLI installed and authenticated
• Discord bot token (see setup below)

Discord Bot Setup

1. Go to Discord Developer Portal
2. Click New Application, give it a name
3. Go to Bot tab → Click Add Bot
4. Under Privileged Gateway Intents, enable:
   • Message Content Intent (required to read message text)
5. Click Reset Token → Copy the token (this is your DISCORD_BOT_TOKEN)
6. Go to OAuth2 → URL Generator:
   • Scopes: bot
   • Bot Permissions: Send Messages, Create Public Threads, Send Messages in Threads, Read Message History, Add Reactions
7. Copy the generated URL → Open in browser → Invite bot to your server

Note: This runs 100% locally. The bot connects outbound to Discord's gateway - no need to expose ports or use ngrok.

Architecture

Discord Bot  →  BullMQ Queue  →  Claude Spawner
 (Node.js)       (Redis)          (Bun)

• Bot (src/bot.ts): Catches @mentions, creates threads, sends to queue
• Queue (src/queue.ts): BullMQ job queue for reliable processing
• Worker (src/worker.ts): Pulls jobs, spawns Claude, posts responses
• Spawner (src/spawner.ts): The Claude CLI integration (the core)
• DB (src/db.ts): SQLite for thread→session mapping

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DISCORD_BOT_TOKEN | Yes | - | Your Discord bot token | | REDIS_HOST | No | localhost | Redis server host | | REDIS_PORT | No | 6379 | Redis server port | | CLAUDE_WORKING_DIR | No | cwd | Working directory for Claude | | DB_PATH | No | ./data/threads.db | SQLite database path |

CLI Commands

Once running, Cord provides CLI commands for interacting with Discord:

cord send <channel> "message"           # Send a message
cord embed <channel> "text" --title "T" # Send formatted embed
cord file <channel> ./report.md         # Send file attachment
cord buttons <channel> "Pick:" --button label="Yes" id="yes" style="success"
cord typing <channel>                   # Show typing indicator
cord edit <channel> <msgId> "new text"  # Edit message
cord delete <channel> <msgId>           # Delete message
cord reply <channel> <msgId> "reply"    # Reply to message
cord react <channel> <msgId> "emoji"    # Add reaction
cord thread <channel> <msgId> "name"    # Create thread
cord rename <threadId> "new name"       # Rename thread
cord state <channel> <msgId> done       # Update status (processing, done, error, etc.)
cord health                             # Check bot connection status

See skills/cord/SKILL.md for full CLI documentation.

Auto-Complete Threads

When a user adds a ✅ reaction to the last message in a thread, Cord automatically updates the thread starter to "✅ Done". This provides a quick way to signal "conversation complete" without explicit commands.

HTTP API

Cord also exposes an HTTP API on port 2643 for external scripts and webhooks.

See skills/cord/HTTP-API.md for API documentation.

License

MIT