Automaton

Native GPUI staff over Puppetmaster. Named automata speak, then dispatch. Durable state is queried first. Jobs stay out of chat. One local Docker Linux is the shared computer; automata are screens, not VMs.

Docs

• Staff surface — rail, composer, factory, inspector
• Token provenance — measured chrome numbers; Brand / MotionSpec / P1 surfaces
• Computer — Docker Linux box, screens, Take control
• Jobs — analyze, implement, box-shell, land, and ship
• Durable state — store, claims, keys
• Mouth compaction — working set summary + recent turns; Compact now
• Routines — schedule/event mouth wakes (product; app must be open for MVP ticks)
• Channels — Slack mention/DM wake + reply (Settings connect; inbox drop MVP)
• Rooms — local multi-agent rooms + SendToAgent-class async peer notes
• MCP catalog — curated in-app MCP install / auth / schema hints (Settings)
• Secrets — secret-request card, masked entry, vault (never chat-paste)
• Version / releases — installed chrome, GitHub Latest notify (no auto-upgrade), doctor plist WARN
• Skills — Settings library, local authoring, offer-once pin widget
• Idle CPU — park inventory + Mac idle proof checklist
• Cloud agent / Origin — optional public Cloud Agents API + Origin forge (parked when unavailable)
• Providers — mouth vs Jobs/PM vs cloud map; sanctioned auth per provider
• Contributor contract — invariants for agents and humans

Run

Needs Bun, Docker, and a Puppetmaster CLI on PATH. OpenRouter is configured in Settings (or ~/.automaton/keys.json).

bun install
bun test
bun run app          # cold default (Dock face; reclaim zombies)
# bun run dev        # opt-in --hot remounts only; can zombie — prefer app

On macOS, bun run app opens macos/Automaton.app so the Dock and the menu bar say Automaton. That wrapper is a Mach-O stub plus bun copied into the bundle; Homebrew bun in the Dock is a terminal tile. bun src/main.tsx still works, but a bun process spawned from Cursor stays under Cursor's menu (Cmd+Plus / Cmd+Minus go to the editor). The in-window titlebar paints Automaton next to the focused mouth.

Cold launch is bun run app (default / Update relaunch). bun run dev (bun --hot src/main.tsx) is dev-only / opt-in — remounts can leave a zombie window. Cold open reclaims prior Automaton windows for this install before focusing or opening the face (no default open -n stack). If clicks miss or doctor WARNs on leftovers, quit them and kick cold with bun run app.

bun test is the suite. CI runs that job on macOS. bun scripts/replay-repeated-work.ts is a bench for synthetic repeated-domain recall (measured 19/20 under a seeded claim) — not a live product guarantee. bun scripts/replay-tough-eval.ts measures recall safety (avoidance, false-hit rate, stale-hit rate, cost) on a seeded mixed workload; it is separate from that bench. bun run doctor checks Puppetmaster. bun scripts/probe-kernel.ts launches a read-only analyze job. Never run an implement worker against this checkout; implement work uses a sandbox.

Layout:

• @gpuix/react on Zed GPUI (src/main.tsx), pinned to file:vendor/gpuix-react-0.6.2.tgz plus matched file:vendor/gpuix-native-0.6.2.tgz (native spring passthrough). Stay vendored until park publishes — docs/gpuix.md / remorses/gpuix#34. Automaton consumes @gpuix; it does not publish that npm scope.
• Idle parks: native motion.rs 420ms hard park on living marks, src/runtime/feed-pin.ts / feed-row.ts (tail pin + row fingerprints); proof checklist docs/idle-cpu.md / bun run sample:idle-cpu
• Domain and session: src/domain.ts, src/session.ts
• Durable SQLite: src/runtime/store.ts
• Mouth: src/runtime/mouth.ts
• Jobs: src/runtime/pm.ts, src/runtime/jobs.ts
• Optional cloud / Origin: src/runtime/cloud-origin.ts, src/cloud-origin-panel.tsx
• Tokens: src/theme/ (useTokens()); src/tokens.ts re-exports the default snapshot. Provenance: docs/tokens-provenance.md
• Mark: brand/mark.svg (control-bar marionette)
• Box image: box/Dockerfile

License

MIT. See LICENSE.