_                     _ _
   ___| | __ ___      __ __| (_)_   _ ___
  / __| |/ _` \ \ /\ / / _` | | | | / __|
 | (__| | (_| |\ V  V / (_| | | |_| \__ \
  \___|_|\__,_| \_/\_/ \__,_|_|\__,_|___/

Self-hosted AI agent platform. Deploy agents with tools, cron, economy, and Discord — in one command.

Installation · Quick Start · Architecture · Features · CLI · GUI · Contributing

Why Clawdius?

You want AI agents that actually work — not one-shot ChatGPT sessions that forget everything. You want agents that run on a schedule, coordinate with each other, track their costs, and live on YOUR machine.

| | Clawdius | ChatGPT / Claude | LangChain | AutoGPT | |---|---|---|---|---| | Self-hosted | ✅ Your machine | ❌ Cloud only | ✅ | ✅ | | Multi-agent | ✅ 33 agents | ❌ Single | ✅ Manual | ✅ | | Cron / automation | ✅ Built-in | ❌ | ❌ DIY | ❌ | | Per-agent tool control | ✅ Engine-level | ❌ | ❌ | ❌ | | Cost tracking | ✅ Nexium economy | ❌ | ❌ | ❌ | | Discord native | ✅ In + out | ❌ | ❌ | ❌ | | GUI dashboard | ✅ Port 4892 | ✅ Web | ❌ | ❌ | | Dependencies | pnpm monorepo | N/A | Heavy | Heavy |

Installation

# npm (recommended)
npm i -g clawdius

# From source
git clone https://github.com/exisz/clawdius.git clawdius
cd clawdius
pnpm install
cd packages/cli && npm link

Quick Start

1. Set up authentication:

Clawdius uses GitHub Copilot OAuth tokens. Place your ghu_* token:

mkdir -p ~/.clawdius/.auth
echo "ghu_your_token_here" > ~/.clawdius/.auth/copilot-token

Or set it in ~/.clawdius/.env:

COPILOT_OAUTH_TOKEN=ghu_your_token_here

2. Start the gateway:

clawdius gateway start

🤖 Clawdius Gateway is live!
   API:     http://localhost:4891
   GUI:     http://localhost:4892
   Agents:  33 | Cron: 7
   ✅ Auto-restarts on crash and login

3. Open the GUI:

Visit http://localhost:4892 — chat with agents, monitor cron, manage the economy.

4. Chat from CLI:

clawdius chat treasury "What's the daily brief?"

Architecture

~/clawdius/                         ← pnpm monorepo
├── packages/
│   ├── gateway/                    ← Express API (port 4891) — THE BRAIN
│   │   └── src/
│   │       ├── agent/              ← Agent loop, tools, auth, Discord
│   │       ├── routes/             ← API endpoints
│   │       ├── cron/               ← Cron scheduling
│   │       └── store/              ← Session persistence (JSONL)
│   ├── cli/                        ← Commander CLI (`clawdius`)
│   └── gui/                        ← Vite + React + Tailwind + DaisyUI
└── ~/.clawdius/                    ← Runtime data
    ├── agents/<name>/              ← Agent workspaces (AGENT.md, TOOLS.md, config.json)
    ├── cron/                       ← jobs.json + runs.json
    ├── economy/                    ← Nexium ledger (accounts, transactions)
    ├── knowledge/                  ← Shared knowledge base
    ├── sessions/                   ← JSONL session files
    └── skills/                     ← Workspace-level skills

Features

🤖 Multi-Agent System

33 pre-configured agents with role-based specialization: scrum-master, engineer, QA, tech-lead, treasury, and more. Each agent has its own workspace with persistent memory.

⚡ Cron Jobs

Schedule agent runs with node-cron. Agents wake up, do their job, and go back to sleep. Daily briefs, automated scans, periodic cleanup — all on autopilot.

💰 Nexium Economy

Built-in agent cost tracking with per-tool pricing. Agents earn Nexium (₦) for completing work and spend it on tool calls. Track ROI per agent. Forbes Rich List included.

🔧 Per-Agent Tool Control

Whitelist or blacklist tools at the engine level via config.json:

{ "tools": ["read_file", "exec", "post_to_discord"] }

No token-wasting prompt instructions — capability removed at the engine level.

💬 Discord Integration

Full Discord bot with inbound listener + outbound posting. Persistent threads per agent per channel. Trigger agents via Discord messages.

🧠 Knowledge Base

File-based encyclopedia in ~/.clawdius/knowledge/. Agents read and write articles — shared organizational memory. GUI editor with live preview.

🔄 Sub-Agent Spawning

Any agent can spawn a child agent via spawn_agent tool. Parent waits for child's result. Build agent hierarchies — scrum-master delegates to engineers.

📋 Task Board

File-based kanban in ~/.clawdius/tasks/. Agents create and consume tasks — the communication layer between agents. GUI with drag-and-drop.

CLI

clawdius gateway start|stop|status   # Manage the gateway service
clawdius chat <agent> "<message>"    # Chat with an agent
clawdius agents list|detail          # List/inspect agents
clawdius cron list|trigger|history   # Manage cron jobs
clawdius economy status|forbes       # Check the Nexium economy
clawdius knowledge list|read|add     # Manage knowledge base
clawdius tasks list|add|move         # Manage task board
clawdius sessions list               # List active sessions

GUI

The dashboard runs on port 4892 with:

• 💬 Chat interface with streaming
• 🕹️ Mission Control (live agent monitoring)
• 👥 Multi-agent chat (sequential collaboration)
• ⏰ Cron dashboard with countdown timers
• 💰 Economy dashboard with Forbes Rich List
• 📚 Knowledge base editor
• 📋 Kanban task board

Ports

| Service | Port | |---------|------| | Gateway API | 4891 | | GUI Dashboard | 4892 |

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT © Exis Zhang