██╗ ██╗██╗ ██╗███╗ ██╗ ██████╗ ███╗ ███╗██╗ █████╗
╚██╗ ██╔╝██║ ██║████╗ ██║██╔═══██╗████╗ ████║██║██╔══██╗
╚████╔╝ ██║ ██║██╔██╗ ██║██║ ██║██╔████╔██║██║███████║
╚██╔╝ ██║ ██║██║╚██╗██║██║ ██║██║╚██╔╝██║██║██╔══██║
██║ ╚██████╔╝██║ ╚████║╚██████╔╝██║ ╚═╝ ██║██║██║ ██║
╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═════╝ ╚═╝ ╚═╝╚═╝╚═╝ ╚═╝
One brain. Many hands. No waste.
A lean, browser-based command centre that runs a team of Claude Code agents from your terminal. One CEO thinks. Temporary workers execute. Everything streams live to localhost:4600. You stay in control.
We started with a question: why does multi-agent AI orchestration burn through token limits in minutes?
We dug into the leading orchestrators. Read the GitHub issues, the Reddit complaints, the source code. Found three root causes:
- Session accumulation. Every heartbeat resumes the full conversation history. By heartbeat 10, you're carrying millions of tokens of stale context.
- Skill file bloat. Tens of thousands of tokens of instruction files and tool definitions loaded on every cycle, even when the agent needs 10% of them.
- No memory, just re-briefing. Agents don't learn. They get told everything, every time.
So we asked: what if agents were employees, not contractors?
Contractors need a full brief every engagement. Employees build institutional knowledge. They have a role (SOUL.md), targets (GOALS.md), and working memory (MEMORY.md). They read files when they need context instead of being force-fed everything on every turn.
The result:
- CEO persists. One long-running session with auto-compaction. Context lives in files, not in bloated conversation history.
- Workers are disposable. Spawned for one task, scoped to one directory, killed on completion. Clean context every time.
- 7 tools, not 240. ~600 tokens of tool overhead per turn.
- TASKS.md is the board. No database. A markdown file both human and AI read natively.
- Safety is not optional. 13 guardrails enforced at the SDK level, not by polite instructions in a prompt.
Prerequisites: Node.js 22+, Claude Code CLI installed and authenticated.
git clone https://github.com/phaddad90/yunomia.git
cd yunomia/app
npm install
npm run dev -- --project /path/to/your/codeOpen http://localhost:4600. Yunomia scans your project, generates context files, and starts the CEO. You'll see the terminal streaming within seconds.
| Option | Default |
|---|---|
--project <path> |
required |
--port <number> |
4600 |
--model <name> |
claude-sonnet-4-6 |
cd yunomia
git pull
cd app && npm installThen restart the server. Your project data (TASKS.md, SOUL.md, MEMORY.md, metrics) is stored in your project folder, not in the Yunomia repo - updates are non-destructive.
You point Yunomia at a project folder. It spins up a CEO agent in your browser. The CEO reads its soul and goals, checks the task board, and starts planning.
When something needs building, it spawns a temporary worker - a separate Claude Code session sandboxed to its own directory. The worker does the job and dies. The CEO reviews the output, updates the board, and moves on.
You watch it all live in a dashboard with live terminals, task tracking, and cost breakdowns. Prompt the CEO by typing, voice dictation, or dropping in screenshots. Schedule tasks for later. Pause when you walk away. Kill workers that go sideways. Every message is timestamped.
┌─────────────────────────────────┐
│ localhost:4600 (browser) │
│ │
│ Terminals │ Tasks │ Status │
│ ┌──────────────────────────┐ │
│ │ > You: build the API │ │
│ │ CEO: On it. Spawning... │ │
│ └──────────────────────────┘ │
│ [$4.20 today] [Pause] [Stop] │
└──────────────┬──────────────────┘
│
┌──────────────┴──────────────────┐
│ Yunomia Server │
│ │
│ agent-adapter ── SDK wrapper │
│ ├── CEO (persistent session) │
│ └── Workers (spawn & kill) │
│ │
│ tasks ────── TASKS.md cache │
│ mcp-server ─ 7 tools for CEO │
│ heartbeat ── adaptive (10m-60m) │
│ safety ───── 13 SDK guardrails │
│ metrics ──── analytics + reports │
└──────────────┬──────────────────┘
│
┌──────────────┴──────────────────┐
│ Your Project │
│ │
│ PROJECT.md ── the mission │
│ TASKS.md ──── the board │
│ ceo/ │
│ ├── SOUL.md ── who it is │
│ ├── GOALS.md ─ what it targets │
│ └── MEMORY.md what it learned │
│ workers/ │
│ └── task-042/ │
│ └── output/ ── the work │
└─────────────────────────────────┘
The CEO loop: Check the board. Plan. Delegate. Review. Write lessons. The heartbeat starts at 10 minutes, doubles after 3 idle cycles, caps at 60 minutes, resets instantly when work arrives.
The human loop: Watch the terminal. Prompt when needed - type, dictate via voice, or drop in screenshots. Schedule tasks for later. Walk away - the inactivity pause stops spending after 60 minutes. Come back, hit resume, carry on.
Most agent tools treat the UI as an afterthought - a log viewer bolted onto an API. We think the interface is the product. If you're trusting AI to manage your codebase, you need to see what it's doing, intervene naturally, and never feel like you're fighting the tool.
That's why Yunomia has native voice input (no external service - Web Speech API runs locally), image attachments via drag-and-drop (paste a screenshot of a bug, the CEO sees it), multi-line prompts with Shift+Enter, message timestamps, live running cost per task, a network status indicator, and an onboarding wizard that gets you from zero to running without touching a config file.
The Status tab gives you inline editors for PROJECT.md, SOUL.md, and GOALS.md - edit your agent's personality and targets without leaving the dashboard. A running project total shows lifetime cost across all sessions.
Every interaction was designed around one question: what would make this feel like a tool you actually want open all day?
Thirteen guardrails. All SDK-enforced. Not prompt-based suggestions.
| Guard | What happens | Default |
|---|---|---|
| Concurrency cap | Rejects spawn if at limit | 3 workers |
| Daily budget | Warns at 80%, hard stops at 100% | $50/day |
| Stall detection | Nudge at 2min, kill at 5min silence | Always on |
| Hard timeout | Kills worker regardless of activity | 15 min |
| Retry limit | Marks task failed, needs human | 2 retries |
| Inactivity pause | Pauses heartbeat when you're away | 60 min |
| Working hours | Pauses outside hours, auto-resumes | Off |
| Write isolation | Blocks Write/Edit outside worker dir | Always on |
| Bash sandboxed | Workers can use Bash, dangerous commands blocked | Always on |
| CEO file guard | CEO cannot modify its own SOUL.md or GOALS.md | Always on |
| CEO session age | Saves memory, restarts fresh | 8 hours |
| CEO crash recovery | Auto-restarts, notifies dashboard | Always on |
| Spawn approval | Optional human approve/reject gate | Off |
| Orphan cleanup | Marks stale tasks failed on restart | Always on |
Workers are sandboxed at the SDK level: disallowedTools: ['Bash'] plus a canUseTool path guard on every Write/Edit/MultiEdit that returns { behavior: 'deny' } for anything outside the worker's folder.
The CEO is also guarded - it cannot rewrite its own rules. Server binds to 127.0.0.1 only. Safety config updates are validated with type and range bounds.
Drop an yunomia.config.json in your project directory. Everything is optional - see full config reference.
Key settings: maxConcurrentWorkers (1-10), maxDailyBudgetUsd (1-500), heartbeatIntervalMinutes (1-60), requireApprovalForSpawn (true/false), workingHours ({ start, end, timezone }).
Edit these in your project's ceo/ folder:
SOUL.md - Who the CEO is. Keep under 50 lines. Human-written context outperforms AI-generated by ~7% in controlled studies.
GOALS.md - KPIs and sprint targets. Update as your project evolves.
PROJECT.md - Auto-generated on first run. Edit to add what the scanner missed.
Every event is tracked to date-partitioned metrics/metrics-YYYY-MM-DD.jsonl:
- Heartbeat fired/skipped, with interval and token counts
- Worker spawned/completed/killed, with model, duration, cost, success rate
- Human interactions, cost milestones, CEO restarts, session summaries
Daily reports auto-generate to reports/YYYY-MM-DD.md on shutdown. The CEO writes a "lessons learned" entry to MEMORY.md covering what worked and what to change.
POST /api/daily-review Trigger CEO lessons learned (no shutdown needed)
GET /api/metrics/summary JSON summary of today's session
GET /api/metrics/report Markdown daily report
Honest numbers. Stress-tested.
| Setup | Daily cost |
|---|---|
| Opus CEO + Sonnet workers | $60 - $120 |
| Sonnet CEO + Sonnet workers | $30 - $70 |
| Sonnet CEO + Haiku workers | $20 - $50 |
A single Claude Code session runs $5-15/day. Yunomia runs 4-6x that for multi-agent throughput.
5 runtime deps. 0 client-side deps. No React. No database.
| Agent runtime | @anthropic-ai/claude-agent-sdk |
| Server | Express 5 + ws |
| Terminals | xterm.js via CDN |
| Logs | pino |
| Build | tsx (dev), tsup (prod) |
Current version: v1.3.0 - fully functional, 6 rounds of red-team review (risk score 14/125), actively in use.
v1.1 - Sharper CEO shipped
- Context-aware heartbeat prompts (includes board state when tasks change)
- Worker auto-completion (tasks marked done with cost data when workers finish)
- Configurable cold-start prompt templates
- Live running cost per active task in Tasks tab
v1.2 - Preset Agents + Skills shipped
- 7 CEO presets: Default, Branding, Website, App Dev, Copywriting, Architecture, Security
- Preset selector at project init (
--preset branding) - Skills framework: callable workflows with prompt templates and config
- Built-in skills: Red Team, Security Scan, Code Review, Brand Audit, Content Review, Test Suite
- CEO can invoke skills via MCP tool (
run_skill) - Dashboard Skills tab with click-to-run cards
v1.3 - Smarter Workers + Deploy shipped
- Sandboxed Bash for workers (dangerous commands blocked, cwd scoped)
- Task dependency chains (dependsOn field, CEO can chain tasks)
- Worker-to-worker file handoff (dependency output copied to input/ dir)
- Deploy skills: SSH and FTP with per-project config
- Git auto-commit on successful worker completion
v2.0 - Better Visibility + Multi-project
- Historical cost graph on Status tab (last 7 days)
- Worker success rate trends
- Browser notifications on worker completion and safety alerts
- Command palette in prompt input (
/pause,/status,/spawn,/skill red-team) - Project switching in dashboard
- Cross-project CEO memory
v3.0 - Team Mode
- Multiple humans, role-based access
- Goal hierarchy with progress rollup
- Confirmation mode (CEO proposes, human approves)
- Remote deployment (run Yunomia on a server, access from anywhere)
MIT
Built by Peter Haddad. Designed with Claude Opus 4.6. Six rounds of red-team review. Risk score: 14/125.