docs: slim README to landing page format
Remove internal architecture details, full .env examples, and room assignment model. Keep role overview, tribunal flow, key features, and quick start.
This commit is contained in:
Eyejoker
170
README.md
170
README.md
@@ -8,9 +8,8 @@
|
|||||||
|
|
||||||
Tribunal multi-agent AI assistant (Owner + Reviewer + Arbiter) over Discord with autonomous paired review and Mixture of Agents.
|
Tribunal multi-agent AI assistant (Owner + Reviewer + Arbiter) over Discord with autonomous paired review and Mixture of Agents.
|
||||||
|
|
||||||
Originally derived from [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw), now independently maintained as EJClaw.
|
Originally derived from [qwibitai/nanoclaw](https://github.com/qwibitai/nanoclaw).
|
||||||
Prompt design inspired by [Q00/ouroboros](https://github.com/Q00/ouroboros) and [garrytan/gstack](https://github.com/garrytan/gstack), adapted for EJClaw's Discord and dual-service workflow.
|
Prompt design inspired by [Q00/ouroboros](https://github.com/Q00/ouroboros) and [garrytan/gstack](https://github.com/garrytan/gstack).
|
||||||
Tribunal arbiter system inspired by multi-agent consensus architectures.
|
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
@@ -24,170 +23,45 @@ A single unified service (`ejclaw`) runs a **Tribunal** of three roles:
|
|||||||
|
|
||||||
Each role's agent type and model are independently configurable via `.env` (`OWNER_AGENT_TYPE`, `REVIEWER_AGENT_TYPE`, `ARBITER_AGENT_TYPE`, `*_MODEL`). Three Discord bots provide the identity layer — which bot speaks is determined by the active role, not hardcoded.
|
Each role's agent type and model are independently configurable via `.env` (`OWNER_AGENT_TYPE`, `REVIEWER_AGENT_TYPE`, `ARBITER_AGENT_TYPE`, `*_MODEL`). Three Discord bots provide the identity layer — which bot speaks is determined by the active role, not hardcoded.
|
||||||
|
|
||||||
## Room Assignment Model
|
### Tribunal Flow
|
||||||
|
|
||||||
Per-room routing now uses an explicit assignment model:
|
|
||||||
|
|
||||||
- `room_settings` is the room-level source of truth (SSOT)
|
|
||||||
- Each room stores:
|
|
||||||
- `room_mode`: `single` or `tribunal`
|
|
||||||
- `owner_agent_type`: `codex` or `claude-code`
|
|
||||||
- Public room assignment uses `assign_room`
|
|
||||||
- Legacy `register_group` public interfaces were removed
|
|
||||||
- `registered_groups` remains as a materialized capability/read-model layer and legacy fallback, not the authoritative room configuration
|
|
||||||
|
|
||||||
Operationally:
|
|
||||||
|
|
||||||
- `single` → one owner bot
|
|
||||||
- `tribunal` → per-room owner + globally configured reviewer + optional arbiter
|
|
||||||
|
|
||||||
This means tribunal is no longer inferred from “two bots registered on one room”; it is an explicit room setting.
|
|
||||||
|
|
||||||
## Tribunal 3-Agent System
|
|
||||||
|
|
||||||
```
|
```
|
||||||
User message
|
User message
|
||||||
→ Owner responds (implementation, answer, etc.)
|
→ Owner responds
|
||||||
→ Reviewer auto-triggered (critical review, design check)
|
→ Reviewer auto-triggered (critical review)
|
||||||
→ Verdict:
|
→ DONE → Owner finalizes → @user ✅
|
||||||
DONE → Owner finalizes → Task completed → @user ✅
|
→ Feedback → Owner addresses → loop
|
||||||
DONE_WITH_CONCERNS → Owner addresses feedback → loop
|
→ BLOCKED → Arbiter (if enabled) or @user ⚠️
|
||||||
BLOCKED/NEEDS_CONTEXT
|
→ Deadlock (3+ rounds) → Arbiter summoned → binding verdict
|
||||||
├─ Arbiter enabled → Arbiter judges → PROCEED/REVISE/RESET/ESCALATE
|
|
||||||
└─ Arbiter disabled → Escalate to user → @user ⚠️
|
|
||||||
→ Owner BLOCKED/NEEDS_CONTEXT → Arbiter (same path as reviewer)
|
|
||||||
→ Deadlock (3+ round trips without progress)
|
|
||||||
→ Arbiter summoned → binding verdict → loop resumes
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Mixture of Agents (MoA)
|
### Mixture of Agents (MoA)
|
||||||
|
|
||||||
When enabled, the arbiter collects opinions from configurable external reference models before rendering its verdict:
|
When enabled, the arbiter collects opinions from configurable external reference models before rendering its verdict. No extra SDK processes — lightweight API calls only.
|
||||||
|
|
||||||
```
|
|
||||||
Deadlock detected → MoA reference queries (parallel, configurable via MOA_REF_MODELS)
|
|
||||||
→ Opinions injected into arbiter's prompt
|
|
||||||
→ Arbiter aggregates all perspectives
|
|
||||||
→ Final verdict: PROCEED / REVISE / RESET / ESCALATE
|
|
||||||
```
|
|
||||||
|
|
||||||
No extra SDK processes. External references use lightweight OpenAI/Anthropic-compatible API calls.
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **Tribunal 3-agent system** — Owner/reviewer/arbiter with on-demand deadlock resolution
|
- **Tribunal 3-agent system** — Owner/reviewer/arbiter with on-demand deadlock resolution
|
||||||
- **Discord-independent communication** — Agent-to-agent data flows directly via DB, Discord is display-only
|
- **Per-role model selection** — `OWNER_MODEL`, `REVIEWER_MODEL`, `ARBITER_MODEL` + effort + fallback
|
||||||
- **Mixture of Agents** — Configurable external reference models enrich arbiter verdicts
|
- **Container-isolated reviewer** — Docker container with read-only source mount (supports both Claude and Codex runners)
|
||||||
- **Per-role model selection** — `OWNER_MODEL`, `REVIEWER_MODEL`, `ARBITER_MODEL` + effort + fallback toggle
|
- **Global failover** — Claude exhaustion → automatic codex fallback, auto-recovers
|
||||||
- **Container-isolated reviewer** — Persistent Docker container with read-only source mount
|
- **Mixture of Agents** — External reference models enrich arbiter verdicts
|
||||||
- **Global failover** — Account-level Claude failure → all channels switch to codex, auto-recovers
|
|
||||||
- **Post-approval change detection** — Re-triggers review if owner modifies code after approval
|
|
||||||
- **Auto user notification** — @mention on task completion (✅ done, ⚠️ escalated)
|
|
||||||
- **Loop protection** — Deadlock threshold, merge_ready oscillation guard, arbiter re-invocation limit
|
|
||||||
- **Voice transcription** — Groq Whisper (primary) / OpenAI Whisper (fallback)
|
|
||||||
- **Token rotation** — Multi-account Claude/Codex rotation on rate limits
|
- **Token rotation** — Multi-account Claude/Codex rotation on rate limits
|
||||||
- **Kimi usage dashboard** — Coding plan 5h/7d usage displayed alongside Claude/Codex
|
- **Voice transcription** — Groq/OpenAI Whisper
|
||||||
- **MCP integration** — Memento (persistent memory) + EJClaw host tools
|
- **Session persistence** — Separate sessions per role
|
||||||
- **Session persistence** — Separate sessions per role (owner/reviewer/arbiter)
|
|
||||||
- **Scheduled tasks** — Cron/interval/once via MCP tool
|
|
||||||
- **Mid-turn steering** — Inject follow-up messages while agent is working
|
- **Mid-turn steering** — Inject follow-up messages while agent is working
|
||||||
- **Bun runtime** — Native SQLite (bun:sqlite), fast startup, no native addon builds
|
|
||||||
|
|
||||||
## Architecture
|
## Quick Start
|
||||||
|
|
||||||
```
|
|
||||||
Discord ──► SQLite (WAL) ──► GroupQueue ──┬──► Owner (host process)
|
|
||||||
│ │
|
|
||||||
│ ▼ (auto-trigger)
|
|
||||||
├──► Reviewer (Docker container, :ro mount)
|
|
||||||
│ │
|
|
||||||
│ Verdict routing
|
|
||||||
│ ├─ DONE → change detection → finalize or re-review
|
|
||||||
│ ├─ BLOCKED → Arbiter (if enabled) or User
|
|
||||||
│ └─ Feedback → Owner (loop)
|
|
||||||
│
|
|
||||||
├──► Arbiter (on-demand, fresh session each time)
|
|
||||||
│ │
|
|
||||||
│ ┌───┴─── MoA (if enabled) ───┐
|
|
||||||
│ │ Ref model A ──► opinion │
|
|
||||||
│ │ Ref model B ──► opinion │
|
|
||||||
│ │ → injected into prompt │
|
|
||||||
│ └────────────────────────────┘
|
|
||||||
│ │
|
|
||||||
│ PROCEED/REVISE/RESET/ESCALATE
|
|
||||||
│
|
|
||||||
IPC polling ◄── follow-up messages
|
|
||||||
│
|
|
||||||
┌────────── Router ──────────┐
|
|
||||||
▼ ▼
|
|
||||||
paired_turn_outputs Discord (display only)
|
|
||||||
(agent ↔ agent data) (user observation, @mention)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Setup
|
|
||||||
|
|
||||||
### Prerequisites
|
|
||||||
|
|
||||||
- Linux (Ubuntu 22.04+) or macOS
|
|
||||||
- [Bun](https://bun.sh/) 1.3+
|
|
||||||
- Docker (required for reviewer container isolation)
|
|
||||||
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)
|
|
||||||
- [Codex CLI](https://github.com/openai/codex) (`npm install -g @openai/codex`)
|
|
||||||
- Discord bot tokens (3: Claude, Codex-main, Codex-review/Arbiter)
|
|
||||||
|
|
||||||
### Install
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/phj1081/EJClaw.git
|
git clone https://github.com/phj1081/EJClaw.git
|
||||||
cd EJClaw
|
cd EJClaw
|
||||||
bun install
|
bun install
|
||||||
bun run build:runners
|
bun run build:runners # Build both runners
|
||||||
bun run build
|
bun run build # Build main project
|
||||||
bun run build:container # Build reviewer Docker image
|
bun run build:container # Build reviewer Docker image
|
||||||
```
|
cp .env.example .env # Configure tokens and settings
|
||||||
|
bun run deploy # Or: bun run dev
|
||||||
### Environment
|
|
||||||
|
|
||||||
All configuration in a single `.env` file:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Discord bots (3 tokens for 3 bots)
|
|
||||||
DISCORD_BOT_TOKEN= # Claude bot
|
|
||||||
DISCORD_CODEX_BOT_TOKEN= # Codex-main bot (owner)
|
|
||||||
DISCORD_REVIEW_BOT_TOKEN= # Codex-review bot (arbiter)
|
|
||||||
|
|
||||||
# Agent types
|
|
||||||
OWNER_AGENT_TYPE=codex # codex | claude-code
|
|
||||||
REVIEWER_AGENT_TYPE=claude-code # claude-code | codex
|
|
||||||
ARBITER_AGENT_TYPE=codex # codex | claude-code (optional, enables 3rd agent)
|
|
||||||
|
|
||||||
# Per-role model overrides
|
|
||||||
OWNER_MODEL=gpt-5.4
|
|
||||||
REVIEWER_MODEL=claude-opus-4-6
|
|
||||||
ARBITER_MODEL=gpt-5.4
|
|
||||||
|
|
||||||
# API keys
|
|
||||||
CLAUDE_CODE_OAUTH_TOKEN= # Claude Code OAuth token
|
|
||||||
CLAUDE_CODE_OAUTH_TOKENS= # Comma-separated for multi-account rotation
|
|
||||||
GROQ_API_KEY= # Voice transcription (Groq Whisper)
|
|
||||||
|
|
||||||
# Mixture of Agents (MoA)
|
|
||||||
MOA_ENABLED=true
|
|
||||||
MOA_REF_MODELS=kimi,glm
|
|
||||||
MOA_KIMI_MODEL=kimi-k2.5
|
|
||||||
MOA_KIMI_BASE_URL=https://api.kimi.com/coding
|
|
||||||
MOA_KIMI_API_KEY=sk-kimi-xxx
|
|
||||||
MOA_KIMI_API_FORMAT=anthropic
|
|
||||||
MOA_GLM_MODEL=glm-5.1
|
|
||||||
MOA_GLM_BASE_URL=https://open.bigmodel.cn/api/anthropic
|
|
||||||
MOA_GLM_API_KEY=xxx
|
|
||||||
MOA_GLM_API_FORMAT=anthropic
|
|
||||||
```
|
|
||||||
|
|
||||||
### Deploy
|
|
||||||
|
|
||||||
```bash
|
|
||||||
bun run deploy
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
|||||||
Reference in New Issue
Block a user