99 Operator Onboarding

This is the operator-side package for local-first 99 skills. It is the part an operator would clone or install locally. The hosted broker remains on 99 servers.

Command

npx @jxutaposition/operator-onboarding onboard

That one command guides the operator through:

• choosing a detected local skill to wrap and connect
• adding plugin.toml beside the selected SKILL.md
• saving the selected hostable plugin path in the local operator config
• creating ~/.codex/99-client-stream.config.toml for the 99-client-stream Codex profile when the default Codex harness is used
• authenticating this device with a 99 account through browser OAuth
• opening the catalog UI at https://www.99human.dev/catalog
• ending with instructions to invoke $operator inside the Codex session you want to capture and verify that the session trace appears

After onboarding, keep the local host running from a terminal:

npx @jxutaposition/operator-onboarding host

Then invoke the skill inside the Codex session you want to capture:

$operator

The skill only prints a unique marker such as 99_OPERATOR_TRACE_<uuid>. It does not start uploaders, create runs, or inspect the local host.

Codex writes structured JSONL files under ~/.codex/sessions/YYYY/MM/DD/. Run record-session separately with the printed marker. The recorder finds the recent JSONL file containing that marker, creates or resumes the same 99 run for that marker, uploads only complete lines after its saved cursor, and ticks once per minute until the run is stopped from the trace UI.

Detection during onboarding checks the standard Codex/agent/Claude skill roots and nearby workspaces for copied skill repositories, including owners/<name>/skills and system/skills layouts. After the operator selects and wraps a skill, the package saves the selected plugin manifests in %APPDATA%\operator-agent\config.json on Windows, or ~/.config/operator-agent/config.json elsewhere. Later host runs use those exact saved manifest paths.

Wrapping means writing one plugin.toml beside the selected SKILL.md. During onboarding, the wrapper asks the 99 broker to generate YAML frontmatter and 3-5 human-facing triggers from the skill file. For Codex-backed skills, the wrapper also creates ~/.codex/99-client-stream.config.toml for the 99-client-stream profile if it does not already exist, and migrates any legacy 99-client-stream profile block out of ~/.codex/config.toml. The wrapper does not edit a central manifest. The onboarding command is the only step that syncs the selected plugin snapshot to the broker; later heartbeats update only host presence.

The scripts default to:

• Broker API: https://99-lele-production.up.railway.app
• Trace UI: https://www.99human.dev

The underlying command is:

npx @jxutaposition/operator-onboarding record-session --trigger operator --marker 99_OPERATOR_TRACE_<uuid>

What Gets Traced

There are two trace sources:

• Session recording: invoking $operator inside the session the operator wants to capture marks the transcript. The separate record-session command owns matching, run creation, cursored uploads, and stop detection.
• Broker-dispatched runs: the local host polls for queued runs whose trigger matches a local skill, launches the configured harness, and appends trace events to /api/local-runs/<run-id>/trace. The host command is a foreground terminal command that uses the exact hostPlugins entries saved in config. There is no hidden watcher or service process.

The 99 hosted backend is the broker. Cargo only starts local Rust binaries from the package; it is not the broker. The browser UI reads runs and traces from 99, while the local package writes to 99 over HTTPS with the saved operator token.

For broad operator use, publish signed prebuilt local_agent_host binaries from a GitHub Release and have the npm package download the right binary for the OS. Running from source with Cargo is acceptable for this MVP, but prebuilt binaries are better for non-developer operators.