103 lines
3.9 KiB
Markdown
103 lines
3.9 KiB
Markdown
# DisClaw
|
|
|
|
DisClaw is a Discord-bot-powered multi-agent workspace manager built on Claude Code.
|
|
It turns a Discord server into a multi-agent development environment where each channel
|
|
maps to a local workspace folder with its own Claude Code agent identity.
|
|
|
|
## How It Works
|
|
|
|
1. A Node.js Discord bot receives messages and slash commands
|
|
2. Messages in agent channels are routed to the Claude Code CLI
|
|
3. Each agent workspace has its own `CLAUDE.md` that defines the agent's identity
|
|
4. Claude Code reads the workspace's `CLAUDE.md` automatically -- no API key needed
|
|
5. Responses are sent back to the Discord channel
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Discord Server
|
|
|
|
|
v
|
|
Discord Bot (Node.js, discord.js v14)
|
|
|
|
|
v
|
|
Message Router (channel_id -> workspace mapping via SQLite)
|
|
|
|
|
+---> Management Channel (#disclaw) ---> /new-agent command handler
|
|
|
|
|
+---> Agent Channel ---> Claude Code CLI (spawned as child process)
|
|
|
|
|
v
|
|
Workspace Directory
|
|
- CLAUDE.md (agent identity)
|
|
- agent.yaml (DisClaw metadata)
|
|
- .claude/ (Claude Code config)
|
|
- ... (agent work files)
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
disclaw/
|
|
src/
|
|
index.ts Entry point -- load config, init DB, start bot
|
|
bot.ts Discord bot setup and event handlers
|
|
router.ts Message router -- channel_id to agent dispatch
|
|
commands/
|
|
new-agent.ts /new-agent slash command handler
|
|
agent/
|
|
runner.ts Spawns claude CLI as child process
|
|
identity.ts Creates/loads agent.yaml, CLAUDE.md, .claude/ config
|
|
db/
|
|
database.ts SQLite connection and queries (better-sqlite3)
|
|
config/
|
|
loader.ts Loads .env and disclaw.yaml configuration
|
|
workspaces/ One subdirectory per agent (created dynamically)
|
|
agent-name/
|
|
CLAUDE.md Agent identity (read by Claude Code automatically)
|
|
agent.yaml DisClaw routing metadata (name, role, channel_id)
|
|
.claude/
|
|
commands/ Agent-specific custom slash commands
|
|
settings.json Agent-specific Claude Code settings
|
|
.claude/
|
|
commands/
|
|
setup.md /setup -- guided first-time setup
|
|
new-agent.md /new-agent -- create agent from CLI
|
|
disclaw.yaml Global configuration
|
|
.env DISCORD_BOT_TOKEN, DISCORD_GUILD_ID, CLAUDE_PATH
|
|
package.json
|
|
tsconfig.json
|
|
ARCHITECTURE.md Detailed architecture documentation
|
|
```
|
|
|
|
## Key Design Decisions
|
|
|
|
- **Claude Code CLI as engine**: No API key needed. Works with Claude Pro/Max subscription.
|
|
The `claude -p "prompt" --output-format json` command is spawned per message.
|
|
- **CLAUDE.md as identity**: Each workspace's CLAUDE.md defines the agent's personality,
|
|
role, and instructions. Claude Code reads it automatically.
|
|
- **SQLite for state**: Channel-to-workspace mappings and conversation history are stored
|
|
in SQLite via better-sqlite3. Synchronous API matches the message handler model.
|
|
- **Single process**: One Node.js bot process manages all agents. Claude CLI processes
|
|
are spawned on demand and terminate after each response.
|
|
|
|
## Custom Commands
|
|
|
|
- `/setup` -- Guided setup walkthrough (prerequisites, Discord bot creation, config)
|
|
- `/new-agent` -- Create a new agent workspace from the CLI (without Discord)
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm install # Install dependencies
|
|
npm run build # Compile TypeScript
|
|
npm run start # Start the bot
|
|
npm run dev # Build and start in one step
|
|
```
|
|
|
|
## Configuration
|
|
|
|
- `disclaw.yaml` -- Global settings (workspace root, management channel, claude command)
|
|
- `.env` -- Secrets (Discord bot token, optional guild ID, optional claude path)
|
|
- Per-workspace `agent.yaml` -- Agent routing metadata
|
|
- Per-workspace `CLAUDE.md` -- Agent identity and instructions
|