Claw-Empire

Command Your AI Agent Empire from the CEO Desk
A local-first AI agent office simulator that turns Claude Code, Codex CLI, Gemini CLI, OpenCode, GitHub Copilot, and Antigravity into a virtual company of autonomous agents.

Quick Start · AI Install Guide · Release Notes · OpenClaw · $ Command · Features · Screenshots · Tech Stack · Providers · Security

English | 한국어 | 日本語 | 中文

What is Claw-Empire?

Claw-Empire transforms your CLI-based AI coding assistants — Claude Code, Codex CLI, Gemini CLI, OpenCode, and more — into a fully simulated virtual software company. You are the CEO. Your AI agents are the employees. Watch them collaborate across departments, hold meetings, deliver tasks, and level up — all visualized through a charming pixel-art office interface.

Why Claw-Empire?

One interface, many AI agents — Manage Claude Code, Codex, Gemini CLI, and others from a single dashboard
Local-first & private — All data stays on your machine. SQLite database, no cloud dependency
Visual & intuitive — Pixel-art office view makes AI orchestration fun and transparent
Real autonomous collaboration — Agents work in isolated git worktrees, attend meetings, and produce deliverables

Latest Release (v1.0.3)

End-to-end idempotent delivery hardened for /api/messages, /api/announcements, /api/directives, and /api/inbox
Client send APIs now use postWithIdempotency() with timeout + retry backoff/jitter for transient failures
Endpoint-scoped idempotency hashing added to prevent cross-route key collisions
Security audit chain verification command added: npm run audit:verify
Review workflow guardrails added to cap revision loops and force finalization on duplicate-only blocker rounds
Full notes: docs/releases/v1.0.3.md

Install with AI

Just paste this to your AI coding agent (Claude Code, Codex, Gemini CLI, etc.):
Install Claw-Empire following the guide at:
https://github.com/GreenSheep01201/claw-empire
The AI will read this README and handle everything automatically.

Screenshots

Dashboard — Real-time KPI metrics, agent rankings, and department status at a glance	Kanban Board — Drag-and-drop task management with department and agent filters
Skills Library — Browse and assign 600+ agent skills across categories	Multi-Provider CLI — Configure Claude Code, Codex, Gemini CLI, OpenCode with model selection
OAuth Integration — Secure GitHub & Google OAuth with encrypted token storage	Meeting Minutes — AI-generated meeting summaries with multi-round review approval
Messenger Integration — Send `$` CEO directives from Telegram, Discord, Slack and receive real-time task updates via OpenClaw	Settings — Configure company name, CEO name, default CLI provider, and language preferences

Features

Feature	Description
Pixel-Art Office	Animated office view with agents walking, working, and attending meetings across 6 departments
Kanban Task Board	Full task lifecycle — Inbox, Planned, Collaborating, In Progress, Review, Done — with drag-and-drop
CEO Chat & Directives	Direct communication with team leaders; `$` directives support meeting choice plus project path/context routing (`project_path`, `project_context`)
Multi-Provider Support	Claude Code, Codex CLI, Gemini CLI, OpenCode, Antigravity — all from one dashboard
OAuth Integration	GitHub & Google OAuth with AES-encrypted token storage in local SQLite
Real-time WebSocket	Live status updates, activity feed, and agent state synchronization
Agent Ranking & XP	Agents earn XP for completed tasks; ranking board tracks top performers
Skills Library	600+ categorized skills (Frontend, Backend, Design, AI, DevOps, Security, etc.)
Meeting System	Planned and ad-hoc meetings with AI-generated minutes and multi-round review
Git Worktree Isolation	Each agent works in isolated git branches, merged only on CEO approval
Multi-Language UI	English, Korean, Japanese, Chinese — auto-detected or manually set
Messenger Integration	Telegram, Discord, Slack and more — send `$` CEO directives and receive task updates via OpenClaw gateway
PowerPoint Export	Generate presentation slides from meeting minutes and reports
Department Management	Planning, Development, Design, QA/QC, DevSecOps, Operations

Tech Stack

Layer	Technology
Frontend	React 19 + Vite 7 + Tailwind CSS 4 + TypeScript 5.9
Pixel Art Engine	PixiJS 8
Backend	Express 5 + SQLite (zero-config embedded DB)
Real-time	WebSocket (ws)
Validation	Zod 4
Icons	Lucide React
Routing	React Router 7
Export	PptxGenJS (PowerPoint generation)

## AI Installation Guide

This section is for AI coding agents. Execute each step and run verification commands before moving to the next step.

Step 0: Verify prerequisites

# Node.js 22+
node -v

# pnpm (or enable corepack)
pnpm -v || corepack enable

# git
git --version

Step 1: Clone and run one-click setup

git clone https://github.com/GreenSheep01201/claw-empire.git
cd claw-empire
bash install.sh

Windows PowerShell:

git clone https://github.com/GreenSheep01201/claw-empire.git
cd claw-empire
powershell -ExecutionPolicy Bypass -File .\install.ps1

Step 2: Verify setup output

macOS/Linux:

# Required files after setup
[ -f .env ] && [ -f scripts/setup.mjs ] && echo "setup files ok"

# AGENTS orchestration rules installed
grep -R "BEGIN claw-empire orchestration rules" ~/.openclaw/workspace/AGENTS.md AGENTS.md 2>/dev/null || true

Windows PowerShell:

if ((Test-Path .\.env) -and (Test-Path .\scripts\setup.mjs)) { "setup files ok" }
$agentCandidates = @("$env:USERPROFILE\.openclaw\workspace\AGENTS.md", ".\AGENTS.md")
$agentCandidates | ForEach-Object { if (Test-Path $_) { Select-String -Path $_ -Pattern "BEGIN claw-empire orchestration rules" } }

Step 3: Start and health-check

pnpm dev:local

In another terminal:

curl -s http://127.0.0.1:8790/healthz

Expected: {"ok":true,...}

Step 4: Optional OpenClaw gateway verification

curl -s http://127.0.0.1:8790/api/gateway/targets

If OPENCLAW_CONFIG is valid, this returns available messenger sessions.

Quick Start

Prerequisites

Tool	Version	Install
Node.js	>= 22	nodejs.org
pnpm	latest	`corepack enable` (built into Node.js)
Git	any	git-scm.com

One-Click Setup (Recommended)

Platform	Command
macOS / Linux	`git clone https://github.com/GreenSheep01201/claw-empire.git && cd claw-empire && bash install.sh`
Windows (PowerShell)	`git clone https://github.com/GreenSheep01201/claw-empire.git; cd claw-empire; powershell -ExecutionPolicy Bypass -File .\install.ps1`

If the repo is already cloned:

Platform	Command
macOS / Linux	`bash scripts/openclaw-setup.sh`
Windows (PowerShell)	`powershell -ExecutionPolicy Bypass -File .\scripts\openclaw-setup.ps1`

Manual Setup (Fallback)

macOS / Linux

# 1. Clone the repository
git clone https://github.com/GreenSheep01201/claw-empire.git
cd claw-empire

# 2. Enable pnpm via corepack
corepack enable

# 3. Install dependencies
pnpm install

# 4. Create your local environment file
cp .env.example .env

# 5. Generate a random encryption secret
node -e "
  const fs = require('fs');
  const crypto = require('crypto');
  const p = '.env';
  const content = fs.readFileSync(p, 'utf8');
  fs.writeFileSync(p, content.replace('__CHANGE_ME__', crypto.randomBytes(32).toString('hex')));
"

# 6. Setup AGENTS.md orchestration rules (teaches your AI agent to be a Claw-Empire project manager)
pnpm setup -- --port 8790

# 7. Start the development server
pnpm dev:local

Windows (PowerShell)

# 1. Clone the repository
git clone https://github.com/GreenSheep01201/claw-empire.git
cd claw-empire

# 2. Enable pnpm via corepack
corepack enable

# 3. Install dependencies
pnpm install

# 4. Create your local environment file
Copy-Item .env.example .env

# 5. Generate a random encryption secret
node -e "const fs=require('fs');const crypto=require('crypto');const p='.env';const c=fs.readFileSync(p,'utf8');fs.writeFileSync(p,c.replace('__CHANGE_ME__',crypto.randomBytes(32).toString('hex')))"

# 6. Setup AGENTS.md orchestration rules (teaches your AI agent to be a Claw-Empire project manager)
pnpm setup -- --port 8790

# 7. Start the development server
pnpm dev:local

Open your browser:

URL	Description
`http://127.0.0.1:8800`	Frontend (Vite dev server)
`http://127.0.0.1:8790/healthz`	API health check

AGENTS.md Setup

The pnpm setup command injects CEO directive orchestration rules into your AI agent's AGENTS.md file. This teaches your AI coding agent (Claude Code, Codex, etc.) how to:

Interpret $ prefix CEO directives for priority task delegation
Call the Claw-Empire REST API to create tasks, assign agents, and report status
Work within isolated git worktrees for safe parallel development

# Default: auto-detects AGENTS.md location
pnpm setup

# Custom path
pnpm setup -- --agents-path /path/to/your/AGENTS.md

# Custom port
pnpm setup -- --port 8790

OpenClaw Integration Setup (Telegram/Discord/Slack)

install.sh / install.ps1 (or scripts/openclaw-setup.*) will auto-detect and write OPENCLAW_CONFIG when possible.

Default config paths:

OS	Path
macOS / Linux	`~/.openclaw/openclaw.json`
Windows	`%USERPROFILE%\.openclaw\openclaw.json`

Manual commands:

# macOS / Linux
bash scripts/openclaw-setup.sh --openclaw-config ~/.openclaw/openclaw.json

# Windows PowerShell
powershell -ExecutionPolicy Bypass -File .\scripts\openclaw-setup.ps1 -OpenClawConfig "$env:USERPROFILE\.openclaw\openclaw.json"

Verify messenger sessions:

curl -s http://127.0.0.1:8790/api/gateway/targets

`$` Command -> OpenClaw Chat Delegation Logic

When a chat message starts with $, Claw-Empire handles it as a CEO directive:

Orchestrator asks whether to hold a team-leader meeting first.
Orchestrator asks for project path/context (project_path or project_context).
It sends the directive to POST /api/inbox with the $ prefix.
If meeting is skipped, include "skipPlannedMeeting": true.
Server stores it as directive, broadcasts company-wide, then delegates to Planning (and mentioned departments when included).

With meeting:

curl -X POST http://127.0.0.1:8790/api/inbox \
  -H "content-type: application/json" \
  -d '{"source":"telegram","author":"ceo","text":"$Release v0.2 by Friday with QA sign-off","project_path":"/Users/me/Projects/climpire"}'

Without meeting:

curl -X POST http://127.0.0.1:8790/api/inbox \
  -H "content-type: application/json" \
  -d '{"source":"telegram","author":"ceo","text":"$Hotfix production login bug immediately","skipPlannedMeeting":true,"project_context":"existing climpire project"}'

Environment Variables

Copy .env.example to .env. All secrets stay local — never commit .env.

Variable	Required	Description
`OAUTH_ENCRYPTION_SECRET`	Yes	Encrypts OAuth tokens in SQLite
`PORT`	No	Server port (default: `8790`)
`HOST`	No	Bind address (default: `127.0.0.1`)
`DB_PATH`	No	SQLite database path (default: `./claw-empire.sqlite`)
`LOGS_DIR`	No	Log directory (default: `./logs`)
`OAUTH_GITHUB_CLIENT_ID`	No	GitHub OAuth App client ID
`OAUTH_GITHUB_CLIENT_SECRET`	No	GitHub OAuth App client secret
`OAUTH_GOOGLE_CLIENT_ID`	No	Google OAuth client ID
`OAUTH_GOOGLE_CLIENT_SECRET`	No	Google OAuth client secret
`OPENAI_API_KEY`	No	OpenAI API key (for Codex)

Run Modes

# Development (local-only, recommended)
pnpm dev:local          # binds to 127.0.0.1

# Development (network-accessible)
pnpm dev                # binds to 0.0.0.0

# Production build
pnpm build              # TypeScript check + Vite build
pnpm start              # run the built server

# Health check
curl -fsS http://127.0.0.1:8790/healthz

CLI Provider Setup

Claw-Empire works with multiple CLI-based AI coding assistants. Install at least one:

Provider	Install	Auth
Claude Code	`npm i -g @anthropic-ai/claude-code`	`claude` (follow prompts)
Codex CLI	`npm i -g @openai/codex`	Set `OPENAI_API_KEY` in `.env`
Gemini CLI	`npm i -g @google/gemini-cli`	OAuth via Settings panel
OpenCode	`npm i -g opencode`	Provider-specific

Configure providers and models in the Settings > CLI Tools panel within the app.

Project Structure

claw-empire/
├── server/
│   └── index.ts              # Express 5 + SQLite + WebSocket backend
├── src/
│   ├── App.tsx                # Main React app with routing
│   ├── api.ts                 # Frontend API client
│   ├── i18n.ts                # Multi-language support (en/ko/ja/zh)
│   ├── components/
│   │   ├── OfficeView.tsx     # Pixel-art office with PixiJS agents
│   │   ├── Dashboard.tsx      # KPI metrics and charts
│   │   ├── TaskBoard.tsx      # Kanban-style task management
│   │   ├── ChatPanel.tsx      # CEO-to-agent communication
│   │   ├── SettingsPanel.tsx  # Company and provider settings
│   │   ├── SkillsLibrary.tsx  # Agent skills management
│   │   └── TerminalPanel.tsx  # Real-time CLI output viewer
│   ├── hooks/                 # usePolling, useWebSocket
│   └── types/                 # TypeScript type definitions
├── public/sprites/            # 12 pixel-art agent sprites
├── scripts/
│   ├── openclaw-setup.sh      # One-click setup (macOS/Linux)
│   ├── openclaw-setup.ps1     # One-click setup (Windows PowerShell)
│   ├── preflight-public.sh    # Pre-release security checks
│   └── generate-architecture-report.mjs
├── install.sh                 # Wrapper for scripts/openclaw-setup.sh
├── install.ps1                # Wrapper for scripts/openclaw-setup.ps1
├── docs/                      # Design & architecture docs
├── .env.example               # Environment variable template
└── package.json

Security

Claw-Empire is designed with security in mind:

Local-first architecture — All data stored locally in SQLite; no external cloud services required
Encrypted OAuth tokens — User-specific OAuth tokens are stored server-side only in SQLite, encrypted at rest using OAUTH_ENCRYPTION_SECRET (AES-256-GCM). The browser never receives refresh tokens
Built-in OAuth Client IDs — The GitHub and Google OAuth client IDs/secrets embedded in the source code are public OAuth app credentials, not user secrets. Per Google's documentation, client secrets for installed/desktop apps are "not treated as a secret." This is standard practice for open-source apps (VS Code, Thunderbird, GitHub CLI, etc.). These credentials only identify the app itself — your personal tokens are always encrypted separately
No personal credentials in source — All user-specific tokens (GitHub, Google OAuth) are stored encrypted in the local SQLite database, never in source code
No secrets in repo — Comprehensive .gitignore blocks .env, *.pem, *.key, credentials.json, etc.
Preflight security checks — Run pnpm run preflight:public before any public release to scan for leaked secrets in both working tree and git history
Localhost by default — Development server binds to 127.0.0.1, not exposed to network

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

Apache 2.0 — Free for personal and commercial use.

Built with pixels and passion.

Claw-Empire — Where AI agents come to work.

Name		Name	Last commit message	Last commit date
Latest commit History 45 Commits
Sample_Img		Sample_Img
docs		docs
public		public
scripts		scripts
server		server
src		src
templates		templates
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README_jp.md		README_jp.md
README_ko.md		README_ko.md
README_zh.md		README_zh.md
index.html		index.html
install.ps1		install.ps1
install.sh		install.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

Navigation Menu

Repository files navigation

Claw-Empire

What is Claw-Empire?

Why Claw-Empire?

Latest Release (v1.0.3)

Install with AI

Screenshots

Features

Tech Stack

Step 0: Verify prerequisites

Step 1: Clone and run one-click setup

Step 2: Verify setup output

Step 3: Start and health-check

Step 4: Optional OpenClaw gateway verification

Quick Start

Prerequisites

One-Click Setup (Recommended)

Manual Setup (Fallback)

AGENTS.md Setup

OpenClaw Integration Setup (Telegram/Discord/Slack)

`$` Command -> OpenClaw Chat Delegation Logic

Environment Variables

Run Modes

CLI Provider Setup

Project Structure

Security

Contributing

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Claw-Empire

What is Claw-Empire?

Why Claw-Empire?

Latest Release (v1.0.3)

Install with AI

Screenshots

Features

Tech Stack

Step 0: Verify prerequisites

Step 1: Clone and run one-click setup

Step 2: Verify setup output

Step 3: Start and health-check

Step 4: Optional OpenClaw gateway verification

Quick Start

Prerequisites

One-Click Setup (Recommended)

Manual Setup (Fallback)

AGENTS.md Setup

OpenClaw Integration Setup (Telegram/Discord/Slack)

$ Command -> OpenClaw Chat Delegation Logic

Environment Variables

Run Modes

CLI Provider Setup

Project Structure

Security

Contributing

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`$` Command -> OpenClaw Chat Delegation Logic