Consolidated reference for Claude Code sessions in this repo. This is the index and current-state summary; the detailed research/design docs it's built from live at the paths listed in Source documents — read one of those directly when you need full depth on that subsystem.
Public product name: Pyxis. Internal/dev codename: GeckoOS. Both names are used interchangeably across the codebase (crate names use geckoOS-*, systemd units and docs say pyxis/Pyxis).
A full desktop Linux OS built from scratch, architecturally descended from two real systems: Firefox OS/B2G (web-tech app runtime, IPC-centric service bus) and webOS's LunaSysMgr (layer-based Wayland compositing, card-style window management). Core system components are Rust; all shell/app UI is web tech (React/Vite) rendered through Gecko/Firefox.
Central design principle — compositor-first, IPC-driven: every subsystem talks over one message bus (Echo); all windowing goes through one Wayland compositor (Evo); the desktop shell (Bloom) is web tech; apps — web or native — are ordinary Wayland clients. Nothing renders by being reparented into anyone else's process or DOM; Evo composites every window directly.
| Name | Role | Crate/repo path | Status |
|---|---|---|---|
| Evo | Wayland compositor & window manager (formerly "Ouranos" — a stale ouranos.service unit still exists, should be removed) |
evo/ (workspace member) |
Real, mature (~17.5k lines). Real two-step window-create/claim contract bound to Echo sessions. |
| Echo | IPC message bus (D-Bus/LS2-style: destination+interface+method routing, service registration) |
echo/ (workspace member) |
Real. Routing, registration, forwarding all functional. |
| Bloom | Desktop shell UI (wallpaper/status-bar/dock/launcher/overlay layers) | pyxis-experience/ (sibling repo; package.json name is literally "bloom") |
Visually complete, richly interactive, 100% simulated — see Bloom status below. |
| Flow | React component/design-system library for Bloom's 2000s-adjacent aesthetic | — | Aspirational naming only — Bloom currently uses plain MUI + framer-motion, no separate Flow library exists yet. |
| Synergy | Native-to-web IPC bridge; equivalent of Firefox OS's mozApps / webOS's window.PalmSystem |
gecko/bridge/ (native host geckoOS-native-host.rs + WebExtension gaia-bridge.js/content.js) |
Real for dev/extension use: genuine Unix-socket client to Echo, full window.geckoOS API surface (filesystem, appManager, power, events). Does not run on the planned pyxis:// scheme (WebExtensions don't match custom schemes) — production apps need a compiled-in JSWindowActor bridge instead (see scheme plan). |
| Rockhopper | Hardware abstraction + legacy (FirefoxOS-era) compat layer (formerly "Persephone", then briefly "Shift" — "Shift" is now the system orchestrator's name instead, see below) | rockhopper/ (workspace member) |
Real, substantial (~2,900 lines): wayland.rs, dbus_session.rs, elf_loader.rs, compatibility.rs. |
| Shift | System orchestrator: process supervision, boot ordering, power states (formerly "Cronus") | shift/ (workspace member) |
Real, substantial (~2,250 lines). Own echo_ipc.rs for supervision signals. |
| Vroom | Pyxis SDK/PDK packaging toolchain — builds/packages/installs web (SDK) and native (PDK) apps as .ipk via pyxis/pyxis-sdk/pyxis-pdk CLIs (repurposed 2026-07-25; its previous life as a "GPU acceleration / perf monitoring" layer, formerly "Kratos", was audited and confirmed 100% simulated — hardcoded dashboard numbers, fake GPU structs, zero consumers — and deleted) |
vroom/ (workspace member; spec vroom/docs/pyxis-sdk-pdk-spec.md, schemas vroom/schemas/, reference script vroom/tools/) |
Real: pyxis.json project config + validation, appinfo.json/CONTROL/control generation, staging tree, .ipk emission (opkg-build when present, built-in root-owned tar.gz writer otherwise), web builders (static/vite/webpack via npm), native builders (cmake/meson/cargo/make/qmake), device profiles + scp/ssh opkg install, new templates, doctor/lint/inspect. Phase 3 done 2026-07-25 (vroom/docs/pyxis-phase3-implementation.md): service packaging (pyxis.json services[], policy-gated activation via /etc/pyxis/allow-packaged-services), upgrade-aware maintainer scripts (postinst/prerm/postrm + packaging/ overrides), and the registry/launcher side — which is Nova + pyxis-appctl (a thin Echo client in echo/src/bin/appctl.rs), deliberately not the spec's standalone registry daemon. |
| Installer | .ipk/opkg package installation service (org.geckoOS.installer): discovery, metadata-without-install, opkg install/remove, each followed by a Nova registry refresh. Frontend is the Remochi App Installer app (pyxis-experience/packages/apps/installer, Wizard-based). |
echo/src/services/installer.rs (in-process in echo-daemon) |
Real (added 2026-07-25). Owns the package layer only — opkg owns files + status db, Nova owns identity/launch (hence Nova::uninstall refusing ipk apps and pointing at opkg remove). Install paths are canonicalized and confined to /var/lib/pyxis/incoming, /media, /tmp, /home, /root. See vroom/docs/pyxis-phase3-implementation.md §7. |
| Nova | App runtime host: manifest/origin/install/launch-composition layer above appHost (formerly conceptual "pyxis-hostd") |
echo/src/services/nova.rs (in-process in echo-daemon, not a standalone nova/ crate) |
Real (~800 lines), registered in echo/src/bin/daemon.rs (register_nova_handlers). Does manifest.webapp discovery/validation, pyxis:// origin mapping (origins.map), native-manifest generation, launch composition (delegates to appHost), install/uninstall (sha256 integrity + atomic swap), and Evo-visibility-driven suspend/resume. Built in-process rather than as the standalone daemon nova-runtime-host-plan.md §8 specifies (deliberate: reuses the one proven request-dispatch path; standalone-crate extraction is a tracked follow-up per the user's "wire in now, extract later" call). At reload it pre-generates each app's native manifest.json (a setpriv-wrapped vela launch that drops to geckouser + grants video/render groups) so appHost.ListApps/LaunchApp see the full app set. Since 2026-07-25 it is also the ipk-app registry (SDK/PDK spec §10): scans /usr/palm/applications/*/appinfo.json (both web and native runtimes — native apps get a setpriv-wrapped direct-exec manifest, no vela/profile), writes derived manifests to the Nova-owned /var/lib/pyxis/nova/native/ (AppHost's third scan root; never into the opkg-owned app dir), maps appinfo's §19 permission vocabulary onto the bridge capabilities (deny-by-default for unmapped ones), and refuses Uninstall for opkg-owned apps. Driven from devices by pyxis-appctl (rescan/list/info/launch/close/focus). |
| gecko | Gecko/Firefox integration + native bridge host process | gecko/ (workspace member) |
Native-messaging host (native-host.rs) is real and working. gecko/src/gecko.rs's libxul-FFI-embedding scaffolding is obsolete direction — no maintained desktop libxul embedding API exists (GeckoView is Android-only, EmbedLite is Sailfish-only/stale). Superseded by the from-source custom-Gecko-build plan (see below); gecko.rs should be repurposed as launcher/supervisor, not an embedder. |
| Puppis | Gecko native-app lifecycle management (launch/suspend/resume/terminate, resource tracking) | puppis/ (workspace member) |
Real (~700 lines), used by Rockhopper's daemon (GeckoAppLauncher). Extracted 2026-07-07 from the old gaia crate — gaia was a full legacy shell (its own actix-web HTTP/WebSocket server serving a static JS UI, long superseded by Bloom, plus several source files that turned out to be entirely orphaned — never even wired into its own module tree). Only gecko_app_launcher.rs, the one piece of gaia genuinely still in use, was kept; the rest (ui_server.rs, static assets, its own now-unused node_modules/ JS build pipeline) was deleted rather than carried forward under a new name. suspend_app/resume_app (real webOS-style freeze/thaw logic) already live in this crate — still worth wiring into Nova/appHost per the roadmap below, just not discarded. |
pyxis-evo |
— | sibling repo pyxis-evo/ |
Dead end, not part of the build. Confirmed 100% unmodified fork of upstream cosmic-comp (System76) — zero Pyxis commits, zero Echo/embedding code, never referenced in the Makefile. Not to be confused with the real compositor, evo/. Candidate for archival. |
| mini | Prebuilt kernel build (bzImage/init.cpio consumed by create-rootfs.sh --kernel-prebuilt) |
mini/ |
Build-support only, out of scope of the Pyxis-specific docs. (gonk/ removed 2026-07-07: a single orphaned gonk.rs describing itself as an Android-HAL-replacement — never a workspace member, never compiled, fully superseded by Rockhopper's real hardware-abstraction layer.) |
Apps — web or native — are independent Wayland clients that Evo composites directly, never DOM-embedded surfaces reparented into Bloom. This retires an earlier framing (in PYXIS_ASSESSMENT.md) that treated Bloom's WaylandSurfaceView placeholder as a gap to fill in; per pyxis-webos-parity-analysis.md it should instead be deleted — Bloom's card view should be chrome/metadata only (title, icon, thumbnail via wlr-screencopy, which evo/src/enhancements/screencopy.rs already provides), with Evo owning all real compositing.
App serving is the biggest newly-scoped workstream. There is no maintained way to embed Gecko in a native host anymore, so the plan is to build a customized Gecko from source (vela, pinned to an ESR branch) with three compiled-in additions:
- A native
pyxis://<app-id>/<path>protocol handler (nsIProtocolHandler, backed bynsIStandardURLso each app gets a real, isolated, secure-context origin —pyxis://<app-id>— mapped to<apps-root>/<app-id>/webroot/). - A compiled-in
window.geckoOSbridge viaJSWindowActor(since WebExtension content scripts can't run onpyxis://), matching Synergy's existing API shape exactly. - A
vela --app=<id>chromeless kiosk run mode — one Wayland toplevel per app,WM_CLASS/title stamped withPYXIS_APP_IDso Evo's existing two-step window-create/claim contract binds it deterministically.
Full implementation plan: pyxis-gecko-embedding-plan.md (why/approach) and pyxis-scheme-and-kiosk-plan.md (protocol handler + kiosk mode, file-by-file).
Nova (real, in-process at echo/src/services/nova.rs — see the component table above; the standalone nova/ crate nova-runtime-host-plan.md §8 describes was not built, in-process was chosen instead) sits above echo's existing appHost and owns what appHost intentionally leaves out: web-app manifest.webapp parsing/validation, pyxis:// origin mapping, install/uninstall with integrity verification, single-instance policy, and composing the concrete vela --pyxis-app=<id> launch command (wrapped in setpriv to drop to geckouser). It does not duplicate process supervision or surface binding — those stay in appHost/evo. Full design: nova-runtime-host-plan.md.
Visually complete desktop shell (draggable/resizable windows, taskbar, launcher, terminal/files/settings/browser apps) but entirely simulated client-side:
src/services/EchoClient.tschecks forwindow.__gecko_ipc, which nothing in the stack ever sets. Synergy's actual bridge exposeswindow.geckoOS(viapostMessage/custom events in the WebExtension form). EveryEchoClientcall silently falls through to an in-memory mock (setTimeout-staged fake sessions,Math.random()PIDs). This is the single most impactful fix — a rename/adapter task, not new architecture — and it would make Bloom talk to Synergy's already-real bridge today, even beforepyxis:///Nova exist.DesktopWindow.tsx'sWaylandSurfaceViewis a placeholder<div>— per the target model above, this should be deleted, not implemented, and replaced with chrome-only card metadata.- Known code health issues:
useEcho.ts:317has a real react-hooks/refs violation (ref mutated during render); 12@typescript-eslint/no-explicit-anylint errors; zero test coverage; dead code (AppLauncher.tsx,Sidebar.tsx,FilesModal.tsx,Background.tsx, five orphaned.scssfiles, an orphanedtsconfig-json.json);AppDrawer.tsxhas three phantom launcher entries (chrome,code,music) with no backing app component; README is still the stock Vite template. - Git branches: all five remote feature branches are fully merged into
mainor stale pre-merge snapshots — no unmerged work is at risk, thoughfeature/app-host-clientandfeature/app-surface-embed's remote-ref tips are confusingly swapped and worth pruning.
echo/src/dbus.rs:637-640— a unit test constructs a struct usingtodo!()for four fields; panics if run.echo/src/services/appmanager.rs:102— no signature verification before tarball extraction (Nova's install plan formalizes the fix; not yet implemented).echo/src/services/apphost.rs's doc comment is stale — it lists "real Wayland surface registration" as not-in-MVP, butevo/src/enhancements/echo_ipc.rs(commitba8be49) already does real surface binding.evoTODOs: minimize not implemented (shell/ssd.rs), HiDPI scale not read from render surface (udev.rs:1426), hardcoded fps/memory in status reporting (enhancements/echo_ipc.rs:404-405), X11 override-redirect ordering (shell/x11.rs).- Systemd ships both
evo.serviceand a staleouranos.service(Evo's old name) — the latter should be removed. - No permission/capability model exists anywhere in the stack yet — see next section.
webOS's LS2 bus enforced a JSON role-file allow-list per identity at the bus itself, before any message was delivered. Echo has no equivalent today (apphost.rs's own doc comment lists "permissions enforcement" as not-in-MVP). This is called out across multiple docs as the single biggest security-model gap, and the plan is to add a per-app capability allow-list (from manifest.webapp's permissions[]) enforced at the Synergy/bridge boundary — see nova-runtime-host-plan.md §5/§7 and pyxis-webos-parity-analysis.md §4 item 6.
- Decide + build the app-serving strategy —
pyxis://scheme + from-sourcevelaGecko build. Blocking prerequisite for real web-app launching; the biggest unplanned workstream. (pyxis-gecko-embedding-plan.md,pyxis-scheme-and-kiosk-plan.md) - Unify the JS bridge contract — ✅ done: Bloom talks to the real
window.geckoOSbridge (now an@pyxis/app-sdkmonorepo package withEchoClient/useEcho/useAppHost). - Build Nova — ✅ done (in-process at
echo/src/services/nova.rs, not the standalone cratenova-runtime-host-plan.md§8 describes). Registry/discovery, launch composition (setpriv-wrappedvela, delegates toappHost), install/uninstall, suspend/resume, origins map, permissions vocabulary all real. Remaining wiring: Bloom'suseAppHostshould launch vianova.Launch(single-instance + profile setup) rather thanappHost.LaunchAppdirectly — seedocs/internal/nova-shell-wiring.md. Standalone-crate extraction is a deferred follow-up. - Wire Puppis's card lifecycle (
suspend_app/resume_app, already real code, not yet called by anything) behindappHost/Nova, driven by Evo visibility/focus events, wired to Gecko's own background-tab throttling. (Nova's ownhandle_window_minimized/handle_window_restoredalready driveappHost.suspend/resumeoff Evo'sWindowMinimizedsignal — this item now covers wiring Puppis's freeze/thaw specifics on top.) - Wire real status/notifications — replace Bloom's static mock battery/network values with real Rockhopper Echo signals.
- Delete
WaylandSurfaceView— replace with chrome-only card metadata +wlr-screencopythumbnails. - Build the security/capability model — per-app permission allow-list at the bridge boundary, tarball signature verification, sandboxing/cgroups for spawned apps.
- Finish Evo's rough edges — minimize, HiDPI scale, real fps/memory stats, X11 ordering.
- Housekeeping — fix the panicking
echo/dbus.rstest; updateapphost.rs's stale doc comment; update the architecture recap for Vroom's new SDK/PDK role; decidepyxis-evo's fate (archive recommended); remove the staleouranos.serviceunit; clean up Bloom's dead code/lint errors/phantom launcher entries and add test coverage. (Thegaia/staticuncommitted-deletion item is resolved:gaia/itself was retired 2026-07-07 — see the Puppis entry above.)
Read these directly for full depth — this file is a summary, not a replacement:
PROJECT_STATUS.md— living status board: per-module overview (what/where/how) plus done / in-progress / to-do / backlog / nice-to-have status, the alpha2 punch-list snapshot, and a per-session change log. Start here for "what's the current state and what's next."PYXIS_ASSESSMENT.md— original code-grounded audit distinguishing the deadpyxis-evofork from the real, mocked-but-maturepyxis-experience/Bloom shell. Its "surface embedding gap" framing is superseded bypyxis-webos-parity-analysis.md's recommendation to delete rather than fill the placeholder.vroom/docs/pyxis-architecture-recap.md— canonical component-name map and system diagram (Evo/Echo/Bloom/Synergy/Rockhopper/Shift/pyxis-hostd); note it predates Nova's naming and describes Vroom's retired GPU-layer role, not its current SDK/PDK role.vroom/docs/pyxis-sdk-pdk-spec.md— the Pyxis packaging-system spec (.ipk/opkg,pyxis.json,appinfo.json, SDK/PDK CLI model) thatvroom/implements; JSON Schemas invroom/schemas/, reference shell packager invroom/tools/.pyxis-webos-parity-analysis.md— grounds the architecture against real webOS/LunaSysMgrinternals component-by-component; identifies the app-serving gap; the source of the "deleteWaylandSurfaceView" recommendation.webos-lunasysmgr-architecture.md— background research: how webOS 3.0.5 actually booted and ran apps (LS2 bus,LunaSysMgr's three hats, app packaging/launch flow), pulled from the real TouchPad rootfs/binaries.webos-webkit-upgrade-plan.md— background research: a hypothetical WPE-WebKit replacement plan for webOS's system WebKit; established that no maintained desktop embedding API exists for modern engines, which fed directly into the Gecko approach below.pyxis-gecko-embedding-plan.md— commits to thepyxis://custom-scheme + from-source Gecko build ("Approach A") over libxul FFI embedding ("Approach B", rejected).pyxis-scheme-and-kiosk-plan.md— file-by-file implementation plan for thepyxis://protocol handler andvelakiosk run mode.nova-runtime-host-plan.md— full crate design fornova/(app manifest/install/launch-composition layer).