Architecture Overview
START HERE. This page describes who Luci is, where she runs, and how the multi-agent system works.
Identity
- Luci is an always-on Claude Code instance (Opus 4.6, 1M context) running on a Hetzner cloud server
- IP: 204.168.188.33 | Tailscale: 100.118.207.3
- Runs in a tmux session ("claude") with auto-restart via
~/.local/bin/claude-persistent
- Persistent session with
--resume to maintain conversation context across restarts
- Telegram bot (8524865055) for direct communication with Elmar
Multi-Agent Topology
Elmar (human)
├── Telegram DM ──→ Luci (this server, Hetzner)
│ ├── Mission Control (port 3001, Board v2)
│ ├── Hermes Gateway (agent runtime + Kanban)
│ │ └── Iris profile (personal Life assistant)
│ ├── Control Room dispatcher (replaces legacy pickup)
│ ├── Ticket Workers (up to 2 parallel + Control Room cr/)
│ ├── Scheduler (147 tasks)
│ └── Services (Spotify Radio, Smart Money, etc.)
│
├── Local Mac ──→ Lucienne (Chief of Staff)
│ ├── CoWork project management
│ ├── SecondBrain vault
│ └── PKA repo sync ←──→ Luci (every 15 min)
│
├── Office Windows ──→ DESKTOP-601MKF8 (100.118.210.89)
│ └── FlightAware + FinDash data pulls
│
└── Coolify VPS ──→ Larry (46.225.208.1)
├── LegalMind-Explorer
└── SafairBru (rewrite)
Key Relationships
- Luci ↔ Lucienne: Share PKA repo via git (every 15 min). Lucienne assigns work, Luci executes. vault.db is Lucienne-owned (Luci reads via git pull, never writes). mc.db is Luci-owned (Lucienne queries via MC API, never writes directly). ticket_context table in mc.db bridges operations↔knowledge.
- Luci ↔ Larry: Luci dispatches tickets via SSH. Larry works LegalMind/SafairBru. Luci reviews Larry's output. Nightly council reviews.
- Luci ↔ Echo: Echo was the previous server. WhatsApp, BTC Swing Trader, Crypto Trader migrated to Luci (2026-04-03/04). Echo is being retired.
Server Infrastructure
| Component |
Detail |
| OS |
Ubuntu 22.04, Linux 6.8.0-85-generic |
| Claude Code |
v2.1.92 at ~/.local/bin/claude |
| Python |
3.12 |
| Node.js |
v22.22.1 |
| Other CLIs |
Codex (GPT-5.3), Gemini, Kimi — all YOLO mode |
| Working dir |
~/workspace/ |
| MCP servers |
brave-search, tavily, telegram (plugin), firecrawl, gbrain, iris-tools (Iris only), mc-coordination (Iris + MC workers) |
Databases
| Database |
Location |
Purpose |
Mode |
| mc.db |
~/workspace/mission-control/mc.db |
Tickets, comments, sessions, task runs, heartbeats, ticket_context |
WAL, read-write |
| vault.db |
~/workspace/PKA/Vault/vault.db |
Knowledge graph, files index, edges, FTS5, activity log |
READ-ONLY (owned by Lucienne) |
| email.db |
~/workspace/data/email/email.db |
Email index |
read-write |
| whatsapp-messages.db |
~/workspace/data/whatsapp/whatsapp-messages.db |
WhatsApp archive |
read-write |
| brain.pglite |
~/.gbrain/brain.pglite |
GBrain semantic index (PGLite + pgvector) |
read-write |
Services (systemd)
| Service |
Port |
Purpose |
| luci-dashboard.service |
3001 (127.0.0.1 + Tailscale) |
Mission Control — external via Tailscale Serve (https://openclaw.tailb2ba18.ts.net). Board v2 cutover 2026-06-02. |
| hermes-gateway.service |
— |
Hermes messaging gateway for Luci. RTK rewrite plugin enabled. Kanban mc-internal board for internal orchestration. |
| hermes-iris-gateway.service |
— |
Iris personal Life assistant gateway; isolated Hermes profile with approval-gated Life/email wrappers (MC-4220) |
| smart-money-dashboard.service |
5051 |
Smart Money Tracker |
| price-watch-dashboard.service |
5050 |
Property/car search |
| luci-token-dashboard.service |
8080 |
Claude Code token usage analytics |
| pka-dashboard.service |
8787 |
PKA dashboard hub — reports, brain explorer, wiki, vault stats |
| auth-portal.service |
8788 |
OAuth re-auth portal for GWS + M365 |
| whatsapp-monitor.service |
— |
Baileys WebSocket, logs WA messages |
| ccgram.service |
— |
CCGram — Telegram remote control for Claude Code (MC-2617) |
| chrome-harness.service |
9222 (127.0.0.1) |
Headed Chrome on DISPLAY=:1 with CDP for browser-harness (MC-3923) |
| xvfb@1.service |
— |
Headless X server on display :1, 1920x1080x24 — backing display for Chrome Harness |
| x11vnc-display1.service |
5901 (127.0.0.1) |
VNC bridge from Xvfb :1 for noVNC auth flows |
| bun-zombie-watchdog.service |
— |
Kills runaway bun server.ts processes spinning at >60% CPU |
Git Repos
| Path |
Repo |
Access |
| ~/.claude-repo/ |
conrelma/claude |
Read-only (skills, vault, rules) |
| ~/workspace/PKA/ |
conrelma/PKA |
Read-write (shared with Lucienne) |
| ~/workspace/mission-control/ |
conrelma/mission-control |
Read-write |
| ~/workspace/ |
conrelma/luci-workspace |
Read-write |
Key Rules (from CLAUDE.md)
- You are infrastructure, not an independent agent
- Log every action to vault.db activity_log
- On task failure, send Telegram notification immediately
- Git sync runs every 15 min via PKA repo
- Skills first — check ~/.claude/skills/ before doing anything from scratch
- Always commit after completing work
- ALL code changes go through the dev-loop skill
Key Takeaways
- Luci is a CLOUD SERVER, not a local machine. Never ask "is this running on your machine?"
- Three agents in the ecosystem: Luci (cloud), Lucienne (local Mac), Larry (LegalMind/SafairBru)
- mc.db is the source of truth for tickets and all operational data (task_runs, sessions, heartbeats). vault.db is read-only on Luci.
- ticket_context table bridges tickets↔vault knowledge. queue_reaper.py prevents stuck messages.
- GBrain (PGLite + pgvector) provides hybrid keyword+vector retrieval for wiki and docs
- MC is exposed externally via Tailscale Serve only (raw HTTP on 204.168.188.33:3001 retired by MC-2676)
- CCGram provides Telegram remote control for Claude Code (replaced mc-telegram-bridge, MC-2617)
- Everything is managed via systemd. Restart services with
sudo systemctl restart <service>
- The dev-loop skill is mandatory for all code changes — it classifies and routes automatically