unguibus

Agent orchestration platform. Local-first, multi-host.

Latin: claws. How you grip things.

Quick Start

# Start the system service (manages agents locally)
cd ~/Code/system-service && bun install && bun run src/index.ts

# In another terminal, start the Electron app
cd ~/Code/electron-app && npm install && npm start

# Or use the startup script
./start.sh                  # system-service only
./start.sh --with-exchange  # + cross-host messaging

Components

| Component | Repo | Port | Purpose | |-----------|------|------|---------| | System Service | Unguibus/system-service | 7272 | Agent lifecycle, messaging, runtime | | Exchange | Unguibus/exchange | 8080 | Cross-host message broker | | Electron App | Unguibus/electron-app | — | Slack-like control surface |

API Quick Reference

# Create an agent
curl -X POST http://localhost:7272/agents \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent","model":"haiku","effort":"low"}'

# List agents
curl http://localhost:7272/agents

# Send a message to an agent
curl -X POST http://localhost:7272/messages \
  -H "Content-Type: application/json" \
  -d '{"to":"<agent-id>","body":"Hello!"}'

# Health check
curl http://localhost:7272/health

Design

Full spec: docs/SPEC.md

Key principles:

• The .claude/ directory IS the agent. Filesystem is the state machine.
• No per-agent credentials. Simple shared secret for Exchange auth.
• Reserved IDs: 0 (Operator), 1 (User), 911 (Security)
• Messages: {to, from, type, body, timestamp}. Fire-and-forget.
• RBAC enforced at spawn time + API level.