WaveX OS

Open-source operating system for running an AI agent company on your localhost.

WaveX OS is a localhost-first wizard that materializes an AI agent company in about an hour. You answer five questions (the 5 pillars), the wizard picks an agent roster from 165 vetted templates, builds a workflow plan, runs a Monte Carlo simulation against your goal, and activates the fleet into a real Paperclip runtime — where each agent gets heartbeats, KPIs, budgets, and a board.

Your data and inference stay on your machine. Spawned agents use your Claude Max OAuth via a wrapper that reads the system keychain — no API keys, no remote inference, no telemetry.

After the wizard you're on a Mission Control dashboard with a live fleet graph + KPI scoreboard. An optional System Optimizer subscription (Phase F) can inject board-level reasoning on a daily cadence using your same OAuth — code is free, hosted optimizer is a tier on top.

Walkthrough — what you actually see

▶ Open the interactive walkthrough — single-page wizard with autoplay, keyboard nav, and step-by-step captions. Source: docs/wizard.html (no build step; open the file directly).

The screenshots below come straight out of the e2e suite — every one is the real wizard against a real pnpm dev. Reproducible via pnpm test:e2e e2e/screenshot-walkthrough.spec.ts.

Step	Screen
Start — pick a company name (or resume a draft)
Pillar 1 — Who you are. Tell the wizard what you're building, in plain text. T2 enrichment infers the 10 fields you'd otherwise type yourself.
Pillar 1 confirm. Review what was inferred + correct anything. The wizard signs the result and persists.
Pillar 2 — Setup verification. Probes your local Claude CLI + plan tier. Defaults to Max 5×.
Pillar 3 — Product state. Pre-product / live customers / 10K-100K MRR / etc. Drives matrix-based template selection.
Pillar 4 — GTM motion. Lead sources × sales motion → KPI tree shape.
Pillar 5 — Comms. Telegram, Slack, email — where board signals land.
Phase 2 — Connectors. Decision-matrix recommends required + suggested integrations based on your pillar answers.
Credential Concierge. Either paste OAuth tokens now, or click Skip per-connector. Vault encrypts everything before disk.
Phase 3 — Swarm. Reactflow org chart of your generated roster. Drag, swap templates per slot, add specialist agents under any chief.
Phase 4 — Workflow. Each agent's initial workload + bundle allocation.
Finalize — Imprint + Monte Carlo. Click Finalize + sign: the simulator projects KPI movement against your goal over N cycles. Signed company manifest written to disk.
Summary before inception. Imprint review + signed manifest summary. Activate fleet → enables once the signature lands. This is your last chance to inspect before agents go live.
Mission Control — Paperclip live. Activate hands the 35-agent fleet off to the running Paperclip instance and lands you here: KPI scoreboard + live reactflow fleet graph that polls every 8s. Click any agent to see runs, comments, budget.

What works today (v0.2.0)

The wizard (5 pillars + 3 phases + finalize)

Owned by op-omega — a full-fidelity onboarding pipeline (12K LOC plugin + 2.4K LOC server + 5.4K LOC UI) vendored at vendor/op-omega/. It does:

• 10-field Pillar 1 inference with T2 enrichment + confirm/correct preview
• Phase 2 decision matrix for connector recommendation, with Composio fold-in when the live integration is configured
• Phase 3 swarm generation from a 33-slot base roster, 165 agent templates (165 ingested via op-omega + WaveX-authored), and a matrix that overrides defaults based on stage + GTM
• Phase 4 workflow allocation with budget enforcement
• Finalize → signed company.manifest.json + Monte Carlo simulation

The runtime (Paperclip-backed)

Activate hits POST /api/instance/:companyId/activate which:

1. Bridges the signed manifest into the wavex DB (Drizzle, PGlite in dev / Postgres in prod) — companies + agents tables get their rows
2. Optionally hands off the C-Suite to a running Paperclip instance via paperclip-handoff.ts — opt-in via PAPERCLIP_HANDOFF_URL. Each agent gets:
   • The role's full vendored skill bundle as AGENTS.md (~60KB for CEO)
   • The company's auth wrapper as adapter command
   • reportsTo chain wired in dependency order
   • Auto-approval if Paperclip raised a board-approval gate

Once handed off, agents heartbeat every 5min via Paperclip's launchd timer, spawn claude CLI under the wrapper, post comments + KPI snapshots back to issues, and get observed by the fleet-observer.

What v0.2.0 added (Phase H)

After Phase H, fleet burn dropped 96% on the production deployment that produced this release. Single-agent burn dropped 95% on the heaviest agent. Spinner patterns became visible and auto-pauseable in one click.

What v0.3 added (V2 fresh-start, 2026-05-12)

A clean-slate rebuild that backports five weeks of production-fleet learnings into the templates + adds the monetization + reliability layers. The full manifest is at docs/V2_MANIFEST.md.

Full launch runbook: docs/V2_LAUNCH_RUNBOOK.md.

See docs/ROADMAP.md for the phase plan and docs/ARCHITECTURE.md for the design.

Quickstart

You need Node ≥18, pnpm ≥9, git, and a Claude Max subscription on the same machine (the wizard reads from the system keychain).

If you have corepack enabled (corepack enable), pnpm is pinned automatically via the packageManager field — you don't need to install pnpm separately.

git clone https://github.com/aimerdoux/wavex-os.git
cd wavex-os
pnpm install
pnpm -r --filter "./vendor/op-omega/*" build   # build the vendored op-omega packages
pnpm dev

pnpm dev also re-runs pnpm install --prefer-offline automatically as a safety net — so if you skip the explicit install step, pnpm dev will still bootstrap cleanly the first time.

Note on a benign warning. During pnpm install you'll see two WARN lines about a pnpm field in packages/core/package.json. That's expected — packages/core is the vendored Paperclip subtree with its own install lifecycle (cd packages/core && pnpm install), and its patchedDependencies / overrides apply there, not at the outer wavex workspace. Safe to ignore.

This boots two servers in parallel:

• http://localhost:5173 — onboarding wizard + Mission Control (Vite + React)
• http://localhost:3101 — mock-core (Fastify, hosts /api/* + op-omega routes)

Open http://localhost:5173 and you'll land on Mission Control. Click Start onboarding to begin the wizard.

Optional — hand off to a running Paperclip instance

If you've got Paperclip running locally, point WaveX OS at it and the wizard's activate step will also hire your C-Suite as real Paperclip agents:

PAPERCLIP_HANDOFF_URL=http://127.0.0.1:3100 \
PAPERCLIP_HANDOFF_WRAPPER=/abs/path/to/claude-anthropic-direct.sh \
  pnpm dev

Without those env vars, activate writes to the wavex DB only — the agents exist as rows but don't run heartbeats. With them, the full inception loop closes.

npx wavex-os init ships from apps/installer/ — Phase F will publish it to npm. For now, pnpm dev is the supported path.

Pair this machine with the cloud console

The cloud console at wavexcard.com/os shows a
device-pairing step that asks you to run a terminal command. That command is
wavex-os login.

install.sh / install.ps1 put the wavex-os command on your PATH (symlinked
into ~/.local/bin). If you cloned the repo manually, link it once:

pnpm wavex:link        # pnpm link --global of the wavex-os bin
# …or run it without linking:
pnpm wavex:os login    # equivalent to `wavex-os login`

Then:

wavex-os login         # opens the browser, prints a pairing code, polls until claimed
wavex-os status        # show local pairing state (add --refresh to rotate the token)
wavex-os logout        # remove the local device token

wavex-os login runs the full device-pairing flow: it POSTs os-link-device,
opens wavexcard.com/os/link?code=…, polls os-device-token until you click
Pair this device in the browser, then writes the device JWT + refresh token
to ~/.wavex-os/device-token.json (chmod 600). After that the local instance is
synced to the console. init / doctor / audit / reset are delegated to the
wavex-os-installer bin, so a single wavex-os command covers the whole surface.

What's in the box

wavex-os/
├── apps/installer/                       # npx wavex-os init CLI (doctor + spawn dev:full)
├── packages/
│   ├── core/                             # Paperclip vendored via git subtree
│   ├── db/                               # PGlite (dev) / Postgres (prod) + Drizzle schema
│   ├── plugin-sdk-shim/                  # Re-exports @paperclipai/plugin-sdk surface
│   ├── auth-shim/                        # assertBoard / assertCompanyAccess gates
│   ├── composio-shim/                    # listConnections + featured toolkits
│   ├── inference-adapter/                # tier-router claudeBin (OAuth vs API key mode)
│   ├── op-omega-server/                  # Fastify routes for vendored onboarding + activate + handoff
│   ├── onboarding-ui/                    # Vite + React wizard + Mission Control v2
│   │   └── public/agent-templates/       # 165 role-specific skill packs (CEO, CoS, CMO, CRO, …)
│   ├── mock-core/                        # In-memory stand-in for Paperclip; Fastify on :3101
│   ├── standard-skills/                  # Cross-cutting skills every agent loads
│   ├── healing/                          # OAuth refresh + worker restart reference impl
│   ├── observability/                    # bottlenecks, attribution, budget, mission-control
│   └── onboarding-server-client/         # Typed stub for future hosted backend
├── vendor/op-omega/                      # vendored op-omega @ d84983a1 (2026-05-03)
│   ├── plugin-sdk/                       # @paperclipai/plugin-sdk
│   ├── shared/                           # @paperclipai/shared
│   ├── tier-router/                      # @op-omega/plugin-tier-router
│   ├── flywheel-kernel/                  # @op-omega/plugin-flywheel-kernel
│   ├── onboarding/                       # @op-omega/plugin-onboarding (50 src files)
│   └── VENDOR.md                         # source SHA + vendor exceptions + update procedure
├── scripts/
│   ├── wrappers/
│   │   ├── claude-anthropic-direct.sh    # macOS keychain → OAuth wrapper
│   │   └── claude-spawn.sh               # Per-spawn execution wrapper with 401 self-heal
│   ├── render-launchd-templates.mjs      # Materialize launchd plists
│   ├── provision-chief-of-staff.sample.mjs   # Kernel completion
│   └── setup-hierarchy-and-kpis.sample.mjs   # Hierarchy + KPI registration
├── templates/launchd/                    # 6 .plist.tmpl with placeholders
├── examples/                             # config + KPI registry samples
├── docs/
│   ├── ARCHITECTURE.md
│   ├── CLAUDE_MAX_HANDOFF.md
│   ├── MINIMAL_INCEPTION.md
│   ├── SELF_HEALING.md
│   ├── ROADMAP.md
│   ├── onboarding/migration-plan.md
│   ├── ops/surface-tuning-map.md         # 40 tunables (auto-generated)
│   └── images/wizard/                    # The screenshots in this README
└── e2e/
    ├── onboarding.spec.ts                # full wizard walk
    ├── flow-variants.spec.ts             # 11 variants (reset, resume, swap, conflict, …)
    ├── bug-hunt.spec.ts                  # 14 composition + edge-case scenarios
    ├── dashboard.spec.ts                 # Mission Control behavior
    ├── screenshot-walkthrough.spec.ts    # capture for this README
    └── screenshot-mission-control.spec.ts

Architecture

       ┌──── localhost (your machine) ─────────────────────────────────┐
       │                                                                │
       │  Browser  ──HTTP──▶  Vite UI  ──proxy──▶  mock-core (3101)    │
       │                       (5173)                  │                 │
       │                                                ▼                 │
       │                                         macOS Keychain           │
       │                                  via wavex-claude wrapper         │
       │                          (token never leaves this box)            │
       │                                                                   │
       │                       (optional) ──HTTP──▶  Paperclip (3100)     │
       │                                              │ heartbeats,        │
       │                                              │ claude CLI,        │
       │                                              │ KPI snapshots,     │
       │                                              ▼ fleet-observer     │
       │                                         your live agents          │
       └────────────────────────────────────────────────────────────────┘
                                       ▲
                                       │  Phase F: optional, paid
                                       │  System Optimizer cron pulls
                                       │  KPI digest, posts board-level
                                       │  injection back as a comment
                                       ▼
                            api.wavex-os.com  (planned)

Three design principles:

1. Your data, your inference. Spawned agents use your Claude Max plan via the wrapper. Token never crosses the wire.
2. Open-source first, paid optimizer second. The full local product is MIT. Hosted optimizer is a tier on top.
3. Subtractive over additive. Every phase has a single exit criterion. We cut features that don't pull their weight.

Full design: docs/ARCHITECTURE.md. OAuth handoff details: docs/CLAUDE_MAX_HANDOFF.md. Paperclip integration: packages/op-omega-server/src/bridge/paperclip-handoff.ts.

Pricing

• Code: free, MIT, fork it.
• System Optimizer (optional cloud subscription, Phase F):
  • Trial — 14 days free
  • Founder — $29/mo (1 daily injection, 500K tokens/mo)
  • Growth — $99/mo (hourly during business hours, 2M tokens, on-demand asks)
  • Custom — $299/mo (unlimited, dedicated optimizer)

You can self-host the optimizer too — docs/SELF_HOSTING.md lands with Phase F.

Credits

WaveX OS stands on the shoulders of:

• Paperclip — the agent runtime engine, vendored via git subtree at packages/core/.
• op-omega — the full-fidelity onboarding pipeline, vendored at vendor/op-omega/ (source SHA tracked in VENDOR.md).
• agency-agents by @msitarzewski — 207 agent templates (MIT). 165 templates are vendored into packages/onboarding-ui/public/agent-templates/ with per-file attribution.
• Anthropic — Claude Max powers the spawned agents.
• reactflow — drives the onboarding swarm chart and the Mission Control fleet graph.
• Fastify — the mock-core + op-omega-server HTTP layer.

Full attribution: CREDITS.md.

Status

v0.2.0 — Phase H (Minimal inception kernel + four-layer self-healing). Production patterns from a 7-day deployment crystallized into open-source skills, services, and operational templates. Phase D (Paperclip handoff bridge) just shipped in this commit. Phase E completes OAuth handoff (Linux + Windows). Phase F adds Stripe + the hosted Optimizer.

See docs/ROADMAP.md for the full plan and what's done.

License

MIT. See LICENSE.