ExoClaw

Discord bot + cron scheduler + web terminal for Claude Code.

Claude Code 的 Discord 机器人 + 定时任务 + Web 终端

Quick Start

npx exoclaw            # one-shot: download, setup wizard, start
# or
npm install -g exoclaw
exoclaw setup          # interactive configuration wizard
exoclaw start          # launch the server

Features

• Discord chat relay -- bidirectional Claude conversations in any Discord channel
• Scheduled tasks (cron) -- define recurring Claude tasks with cron expressions via croner
• Web terminal (PTY) -- full interactive terminal sessions powered by node-pty
• Log viewer (SSE streaming) -- real-time JSONL log streaming with replay
• Dashboard -- task management, execution history, session overview
• Cloudflare Tunnel integration -- expose your local instance to the internet securely

Architecture

ExoClaw (port 3456)
  ├── Express + WebSocket server
  ├── Discord Gateway client (ws)
  ├── croner scheduled tasks
  ├── node-pty terminal sessions
  ├── Claude CLI wrapper (spawn)
  └── Web UI (Dashboard + Shell + Log Viewer)

All components run in a single Node.js process. Discord connects via Gateway WebSocket. Scheduled tasks invoke the Claude CLI in the background and stream output to JSONL log files. The web terminal provides full PTY sessions over WebSocket, and the log viewer uses Server-Sent Events for real-time streaming.

Installation

Prerequisites

• Node.js >= 20
• Claude Code CLI -- installed at ~/.local/bin/claude (or specify path in config)

Install

# Option A: run directly (downloads temporarily)
npx exoclaw

# Option B: install globally
npm install -g exoclaw

Setup Wizard

Run exoclaw setup to launch the interactive configuration wizard:

1. Discord bot token -- paste your bot token (from Discord Developer Portal)
2. Discord channel ID -- the channel where the bot listens for messages
3. Application ID -- your Discord application ID (for identifying bot messages)
4. Tunnel setup -- optionally configure a Cloudflare Tunnel for external access
5. Project directory -- the default working directory for Claude sessions

The wizard writes configuration to ~/.exoclaw/config.json. You can re-run it at any time to update settings.

Usage

Dashboard

Open http://localhost:3456 in your browser. The dashboard shows:

• All scheduled tasks with their cron expressions and next run times
• Execution history with status, duration, and links to logs
• Active terminal sessions

Discord Commands

Send messages in the configured Discord channel. The bot will:

• Relay your message to Claude Code as a prompt
• Stream the response back to Discord
• Provide a link to the full session log

Web Terminal

Navigate to http://localhost:3456/session/new to open a new terminal session. Each session runs in its own PTY with full terminal emulation. Sessions persist across browser reconnections via a replay buffer.

Log Viewer

Access logs at http://localhost:3456/logs/<sessionId>. The viewer streams JSONL events in real time via SSE, replaying the full history on connect and then tailing new output.

CLI Commands

| Command | Description | |---------------------|----------------------------------------------| | exoclaw | Start the server (default command) | | exoclaw setup | Run the interactive configuration wizard | | exoclaw start | Start the server in the background | | exoclaw stop | Stop the background server | | exoclaw status | Show server status and active sessions | | exoclaw logs | Tail the server log output | | exoclaw tunnel | Manage the Cloudflare Tunnel connection |

Configuration

Configuration is stored in ~/.exoclaw/config.json. Loading priority: environment variables > config file > defaults.

{
  "discordToken": "your-bot-token",
  "discordChannelId": "123456789",
  "applicationId": "987654321",
  "mentionUserId": "111222333",
  "externalUrl": "https://your-tunnel.example.com",
  "port": 3456,
  "claudeBin": "~/.local/bin/claude",
  "defaultProject": "~/claude-workspace",
  "schedulesFile": "~/.exoclaw/schedules.json",
  "tunnel": null
}

Environment Variable Overrides

| Environment Variable | Config Key | Description | |--------------------------|--------------------|--------------------------------------| | DISCORD_BOT_TOKEN | discordToken | Discord bot authentication token | | DISCORD_CHANNEL_ID | discordChannelId | Channel ID for message relay | | DISCORD_APP_ID | applicationId | Discord application ID | | DISCORD_MENTION_USER | mentionUserId | User ID to mention in notifications | | EXOCLAW_URL | externalUrl | Public URL (for session links) | | PORT | port | Server listen port (default: 3456) | | CLAUDE_BIN | claudeBin | Path to Claude CLI binary | | EXOCLAW_PROJECT | defaultProject | Default project working directory | | EXOCLAW_SCHEDULES | schedulesFile | Path to schedules JSON file | | EXOCLAW_DATA | dataDir | Data directory (default: ~/.exoclaw)|

API Reference

| Method | Endpoint | Description | |--------|------------------------------|-----------------------------------------| | GET | /api/tasks | List all scheduled tasks and settings | | POST | /api/tasks | Create a new scheduled task | | PUT | /api/tasks/:id | Update an existing task | | DELETE | /api/tasks/:id | Remove a scheduled task | | POST | /api/tasks/:id/run | Trigger immediate execution of a task | | GET | /api/history | Query execution history (supports ?limit=, ?taskId=, ?triggeredBy=) | | GET | /api/sessions | List active terminal sessions | | GET | /logs/:sessionId | Log viewer page (HTML) | | GET | /logs/:sessionId/stream | SSE stream of JSONL log events | | WS | /ws/shell?sessionId=<id> | WebSocket terminal (PTY) session |

Development

Setup

git clone <repo-url> && cd claude-hub
npm install
npm link                 # makes `exoclaw` available globally

After npm link, any change to the source files takes effect immediately -- just restart the server.

Running in Development

# Start the server directly (foreground, see logs in terminal)
node server.js

# Or via CLI
exoclaw start

# Check status
exoclaw status

# Stop
exoclaw stop

Testing

The server must be running before you run tests.

# Run all 7 test suites
npm test

# Quick mode (skip slow scheduler + integration suites)
npm run test:fast

# Run a single suite
node tests/run-all.js api          # REST API endpoints
node tests/run-all.js ui           # Web UI HTML validation
node tests/run-all.js sse          # SSE log streaming
node tests/run-all.js ws           # WebSocket shell terminal
node tests/run-all.js discord      # Discord integration
node tests/run-all.js scheduler    # Cron scheduler & execution
node tests/run-all.js integration  # End-to-end flows

# Combine multiple suites
node tests/run-all.js api,ui,ws

Project Structure

claude-hub/
  bin/exoclaw.mjs        CLI entry point (commander)
  lib/
    config.js              Unified config center
    discord.js             Discord Gateway client
    scheduler.js           Cron task scheduler
    claude-runner.js       Claude CLI wrapper
    pty-manager.js         PTY terminal sessions
    history.js             Execution history
    tunnel.js              Cloudflare Tunnel management
    setup-wizard.js        Interactive setup wizard
  public/
    index.html             Dashboard
    session.html           Web terminal
    viewer.html            Log viewer
  server.js                Express + WebSocket server
  tests/                   Test suites (7 suites, ~100 tests)

Packaging

# Preview what gets included in the npm package
npm pack --dry-run

# Build the tarball
npm pack                 # -> exoclaw-1.0.0.tgz

# Test install from tarball (simulates real npm install)
cd /tmp && npm install -g ~/claude-hub/exoclaw-1.0.0.tgz
exoclaw --help
npm uninstall -g exoclaw

Publishing to npm

npm login
npm publish

After publishing, users install with:

npx exoclaw            # one-shot
npm install -g exoclaw # global

Troubleshooting

| Problem | Cause | Solution | |--------------------------------------|-----------------------------------------------------|--------------------------------------------------------------| | Discord bot does not respond | Missing or invalid bot token | Run exoclaw setup and re-enter your token | | claude command fails inside session| CLAUDECODE env var set (nested Claude session) | The runner automatically unsets CLAUDECODE before spawning | | --output-format stream-json errors | Missing --verbose flag | Ensure --verbose is passed alongside --output-format | | Discord API returns 403 | Missing User-Agent header | Already handled -- the client sends DiscordBot (...) UA | | Tunnel not accessible | Cloudflare Tunnel not configured or not running | Run exoclaw tunnel to set up or restart the tunnel | | node-pty fails to install | Missing build tools for native module | Install build essentials: xcode-select --install (macOS) or apt install build-essential (Linux) | | Port 3456 already in use | Another instance running | Run exoclaw stop first, or set a different PORT |

License

MIT