-
-
-
- Dual-agent AI assistant running Claude Code + Codex as parallel services over Discord. -
+Dual-agent AI assistant (Claude Code + Codex) over Discord. -- Based on qwibitai/nanoclaw -
+Forked from [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw), heavily customized for production use. ## Overview -Two AI agents running as parallel systemd services, communicating over Discord: +Two AI agents running as parallel systemd services on a single host: -- **Claude Code** — powered by Claude Agent SDK, trigger `@claude` -- **Codex** — powered by Codex app-server (JSON-RPC), trigger `@codex` +- **Claude Code** (`@claude`) — Anthropic Agent SDK, adaptive thinking, Opus/Sonnet +- **Codex** (`@codex`) — OpenAI Codex app-server (JSON-RPC), GPT-5.4, xhigh reasoning -Each agent has its own store, data, and groups directories. Discord channels can be registered with either agent, or both (`both` agent type for shared channels). +Both share the same codebase (`dist/index.js`), differentiated by environment variables. No containers — direct host processes for zero overhead. -### Key Features +## Features -- **Direct host processes** — no container overhead, agents run natively -- **Bidirectional image support** — receive images as multimodal input, send as Discord attachments -- **Skill sync** — single source of truth (`~/.claude/skills/`), auto-synced to all sessions -- **OAuth auto-refresh** — token lifecycle managed automatically for headless environments -- **Priority queue** — per-group serialization, global concurrency limit, idle preemption -- **Auto-continue** — Codex text-only turns automatically retried to enforce task execution +- **Dual-agent architecture** — Claude Code + Codex as parallel services, shared SQLite (WAL mode) +- **Browser automation** — [gstack browse](https://github.com/garrytan/gstack) skill, headless Chromium daemon, ~100ms/command +- **Voice transcription** — Groq Whisper (primary) / OpenAI Whisper (fallback), shared file cache with dedup +- **Bidirectional images** — receive Discord attachments as multimodal input, send screenshots back +- **MCP integration** — Memento (persistent cross-session memory) +- **Skill sync** — single source of truth, auto-synced to all agent sessions +- **Priority queue** — per-group serialization, global concurrency limit +- **Session persistence** — resume conversations across restarts +- **Scheduled tasks** — cron/interval/once via MCP tool +- **Mid-turn steering** — inject follow-up messages while agent is working (both agents) ## Architecture ``` -Discord ──► SQLite ──► GroupQueue ──┬──► Claude Agent SDK (host process) - └──► Codex App-Server (JSON-RPC stdio) - ├── thread/start, thread/resume - ├── turn/start (streaming, multimodal) - ├── turn/steer (mid-turn injection) - ├── Auto-approval (bypass sandbox) - └── Auto-continue (text-only turn retry) +Discord ──► SQLite (WAL) ──► GroupQueue ──┬──► Claude Agent SDK + └──► Codex App-Server (JSON-RPC) + ├── thread/start, thread/resume + ├── turn/start (streaming, multimodal) + └── turn/steer (mid-turn injection) + +Agent ──► Bash ──► agent-browser (gstack browse) + ├── goto, snapshot, click, fill + ├── screenshot, pdf, responsive + └── persistent Chromium daemon (~100ms/cmd) ``` -### Directory Layout +## Directory Layout ``` -nanoclaw/ +ejclaw/ ├── src/ -│ ├── index.ts # Orchestrator: state, message loop, agent invocation -│ ├── agent-runner.ts # Spawns agent processes, manages env/sessions/skills -│ ├── group-queue.ts # Per-group concurrency, priority queue, idle preemption -│ ├── group-folder.ts # Group directory resolution and management -│ ├── router.ts # Outbound message formatting and routing -│ ├── sender-allowlist.ts # Security: sender-based access control -│ ├── session-commands.ts # Session commands (/compact) -│ ├── token-refresh.ts # OAuth auto-refresh + session directory sync -│ ├── task-scheduler.ts # Scheduled tasks (cron/interval/once) -│ ├── ipc.ts # IPC watcher and task processing -│ ├── db.ts # SQLite operations -│ ├── config.ts # Paths, intervals, trigger patterns +│ ├── index.ts # Orchestrator: state, message loop, agent invocation +│ ├── agent-runner.ts # Spawns agent processes, manages env/sessions/skills +│ ├── group-queue.ts # Per-group concurrency, priority queue +│ ├── router.ts # Outbound message formatting and routing +│ ├── db.ts # SQLite operations (WAL mode, shared access) +│ ├── config.ts # Paths, intervals, trigger patterns │ └── channels/ -│ ├── registry.ts # Channel self-registration system -│ └── discord.ts # Discord: mentions, images, typing, file attachments +│ └── discord.ts # Discord: mentions, images, typing, voice transcription ├── runners/ -│ ├── agent-runner/ # Claude Code runner (Agent SDK, multimodal input) -│ ├── codex-runner/ # Codex runner (app-server JSON-RPC, auto-continue) -│ └── skills/ # Shared agent skills (browser, etc.) -├── store/ # Claude Code service DB -├── store-codex/ # Codex service DB -├── data/ -│ ├── sessions/ # Per-group Claude sessions (.claude/) -│ └── attachments/ # Downloaded Discord image attachments -├── data-codex/sessions/ # Per-group Codex sessions (.codex/) -├── groups/ # Per-group memory and workspace (Claude Code) -├── groups-codex/ # Per-group memory and workspace (Codex) -└── logs/ # Service logs +│ ├── agent-runner/ # Claude Code runner (Agent SDK) +│ ├── codex-runner/ # Codex runner (app-server JSON-RPC) +│ └── skills/ +│ └── agent-browser/ # Browser automation (gstack browse wrapper) +├── groups/{name}/ # Per-group memory (CLAUDE.md) +├── data/sessions/ # Per-group agent sessions +├── store/ # SQLite database +└── prompts/ # Platform-level system prompts ``` -### Codex App-Server Integration - -The Codex runner (`runners/codex-runner/`) communicates with `codex app-server` via JSON-RPC over stdio: - -- **Session persistence**: Thread IDs stored in DB, sessions saved as JSONL on disk -- **Streaming**: `item/agentMessage/delta` notifications for real-time text -- **Mid-turn steering**: IPC messages injected via `turn/steer` during execution -- **Auto-approval**: `approvalPolicy: "never"` + `sandbox: "danger-full-access"` -- **Auto-continue**: Detects text-only turns (no tool execution) and automatically retries up to 5 times to nudge the agent into actually executing tasks -- **Multimodal input**: Image attachments converted to `localImage` input blocks in `turn/start` -- **Per-group config**: Model, effort, MCP servers configured per channel - -### Image Handling - -Bidirectional image support through Discord: - -- **Receiving** (user → agent): Discord image attachments are downloaded to `data/attachments/`, then passed as base64 `ImageBlockParam` content blocks (Claude Code) or `localImage` input blocks (Codex) -- **Sending** (agent → user): Markdown image links `[name.png](/path)` in agent responses are automatically parsed and sent as Discord file attachments. Non-image file links are converted to readable filenames (`BuildPanel.tsx:320`) - -### Skill Sync - -Skills are managed from a single source of truth (`~/.claude/skills/` on the server) and automatically synced to all agent session directories at process start: - -- Claude Code sessions: `~/.claude/skills/` + project `runners/skills/` -- Codex sessions: Same sources, synced to per-group `.codex/` directories -- Skills auto-register as slash commands (`/name`) in Claude Code and `$name` in Codex - -### GroupQueue - -`src/group-queue.ts` manages agent execution with: - -- **Per-group serialization**: Only one agent process per group at a time -- **Global concurrency limit**: Configurable max concurrent agents across all groups -- **Task priority**: Scheduled tasks drain before message processing -- **Idle preemption**: Idle agents are terminated when higher-priority tasks arrive -- **Exponential backoff**: Retries with backoff on processing failure - ## Setup ### Prerequisites - Linux (Ubuntu 22.04+) or macOS -- Node.js 20+ +- Node.js 20+ (fnm recommended) - [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) - [Codex CLI](https://github.com/openai/codex) (`npm install -g @openai/codex`) -- Two Discord bot tokens (one per agent) — create at [Discord Developer Portal](https://discord.com/developers/applications) +- Bun 1.0+ (for browser automation) +- Discord bot token -### 1. Clone and Install +### Install ```bash -git clone https://github.com/phj1081/nanoclaw.git -cd nanoclaw +git clone https://github.com/phj1081/EJClaw.git +cd EJClaw npm install -npm run build:runners # installs + builds both agent-runner and codex-runner -npm run build # builds main project +npm run build:runners +npm run build ``` -### 2. Authenticate CLIs +### Environment ```bash -# Claude Code — opens browser for OAuth login -claude login - -# Codex — set API key -export OPENAI_API_KEY=sk-... - -# Groq — for fast voice transcription (free at console.groq.com) -export GROQ_API_KEY=gsk_... -``` - -### 3. Environment Variables - -Create `.env` in the project root: - -```bash -# .env — shared config (read by both services) -DISCORD_BOT_TOKEN= # Claude Code Discord bot token +# .env +DISCORD_BOT_TOKEN= # Discord bot token ASSISTANT_NAME=claude # Bot trigger name (@claude) -ANTHROPIC_API_KEY= # Or use OAuth (claude login) +CLAUDE_CODE_OAUTH_TOKEN= # Claude Code OAuth token OPENAI_API_KEY= # For Codex -GROQ_API_KEY= # For voice transcription (Groq Whisper, fast + free) +GROQ_API_KEY= # Voice transcription (Groq Whisper) ``` -For dual-service setup, create `.env.codex` for Codex-specific overrides: +### Systemd Services (Linux) ```bash -# .env.codex — Codex service secrets (loaded via systemd EnvironmentFile) -DISCORD_BOT_TOKEN= # Codex Discord bot token (different from above) -``` - -> **Security**: Never put tokens in systemd service files or commit them to git. Use `.env` files with restricted permissions (`chmod 600`). - -### 4. Systemd Services (Linux) - -Create `~/.config/systemd/user/nanoclaw.service`: - -```ini -[Unit] -Description=NanoClaw Claude Code -After=network.target - -[Service] -Type=simple -ExecStart=/path/to/node /path/to/nanoclaw/dist/index.js -WorkingDirectory=/path/to/nanoclaw -Restart=always -RestartSec=5 -Environment=HOME=/home/youruser -Environment=PATH=/path/to/node/bin:/usr/local/bin:/usr/bin:/bin - -[Install] -WantedBy=default.target -``` - -Create `~/.config/systemd/user/nanoclaw-codex.service`: - -```ini -[Unit] -Description=NanoClaw Codex -After=network.target - -[Service] -EnvironmentFile=/path/to/nanoclaw/.env.codex -Type=simple -ExecStart=/path/to/node /path/to/nanoclaw/dist/index.js -WorkingDirectory=/path/to/nanoclaw -Restart=always -RestartSec=5 -Environment=HOME=/home/youruser -Environment=PATH=/path/to/node/bin:/usr/local/bin:/usr/bin:/bin -Environment=ASSISTANT_NAME=codex -Environment=NANOCLAW_STORE_DIR=/path/to/nanoclaw/store-codex -Environment=NANOCLAW_DATA_DIR=/path/to/nanoclaw/data-codex -Environment=NANOCLAW_GROUPS_DIR=/path/to/nanoclaw/groups-codex - -[Install] -WantedBy=default.target -``` - -Then enable and start: - -```bash -systemctl --user daemon-reload systemctl --user enable nanoclaw nanoclaw-codex systemctl --user start nanoclaw nanoclaw-codex @@ -226,46 +108,13 @@ journalctl --user -u nanoclaw -f journalctl --user -u nanoclaw-codex -f ``` -### 5. Register Discord Channels - -Channels are stored in each service's SQLite database (`registered_groups` table). Use the IPC auth endpoint or insert directly: - -```bash -# Example: register a channel for Claude Code -sqlite3 store/nanoclaw.db "INSERT INTO registered_groups (jid, name, folder, agent_type, trigger_pattern) VALUES ('dc:CHANNEL_ID', 'my-channel', 'my-channel', 'claude-code', '@claude');" - -# Example: register a channel for Codex -sqlite3 store-codex/nanoclaw.db "INSERT INTO registered_groups (jid, name, folder, agent_type, trigger_pattern) VALUES ('dc:CHANNEL_ID', 'my-channel', 'my-channel', 'codex', '@codex');" -``` - -Fields: - -| Field | Description | -|-------|-------------| -| `jid` | `dc: