Workers, watches, later checks, peer communication and browser reports around the native Codex CLI/TUI. Keep your continuing conversation and its existing daemon; choose explicit worker workflows or ask for useful follow-up in ordinary language.
Install or manage with your agent: give it the agent guide and say “Install Codex Plus” or “Upgrade my existing installation.” The HTML guide has copyable requests for inspection, configuration, rollback, cleanup and uninstall too.
Use the agent guide for installation and maintenance; the setup overview explains workers, monitoring and reporting for reference. With the relevant components installed, open an ordinary Codex session and say, for example:
- “$luna-task Investigate the importer failure and return a reproduction.”
- “$luna-goal-loop Complete the approved importer migration and verify it.”
- “Watch the session doing the packaging work and tell me when it is ready.”
- “Tell that session the handoff should include the risks.”
- “Watch this run and tell me if it stalls or fails.”
- “Check this endpoint again later.”
- “Stop watching it.”
- “Make a browser report of what we learned.”
The model selects the source, filtering, cadence and continuation. It discovers independent peers from context and clarifies ambiguity; no UUID, exact title, JSON prompt or polling recipe is required from you.
Read the daily-use guide, open the browser walkthrough, or see how the package works.
Workers, monitoring and reporting share one Codex Plus version and release. Choose the component archives you need in the setup guide; an existing managed setup can use these requests directly. The public site includes the walkthrough and nine HTML guides. Their Markdown sources and technical evidence are linked below.
The preview is ready for daily-use trials. Choose workers, follow useful changes or publish a browser handoff around your existing Codex conversation.
v0.1.0-preview.21 includes seven worker workflows and four current roles.
Preview.21 keeps coordinator status accurate after repeated handoffs, tracks slow callbacks after early acknowledgement, clarifies invalid options and preserves partial peer inspection when native ephemeral history/goals are unsupported. It retains preview.20's MCP launch and read-only doctor fixes. See the qualification receipt and current handoff for delivery and adoption.
It retains daemon restart recovery, preserving historical uncertainty and continuing only eligible observations within their original bounds. Commands and MCP checks need their original replay-safe restart policy; legacy intent without a trustworthy lease anchor stays quarantined.
It retains explicit $sol-task, $astra-task and GPT-6.1 $terra-task for bounded
review, validation, investigation or implementation without changing your primary.
The old worker-name compatibility entries remain removed.
It retains optional primary-aware escalation in the two
adaptive worker workflows, the astra-xhigh role, read-only primary selection
and graceful reporting-only metadata fallback. Escalation defaults off and uses
your request or existing instructions; explicit Luna workflows remain Luna-only.
It retains the native-control discovery fix, readable diagnostics, watch history
and preview rollback support. See released and source features.
Updating a guide or checkout does not upgrade an installed runtime.
Use --human with the existing read-only doctor for a readable summary; JSON
remains the default. Pages builds check current-release guide claims. A native plugin
spike is a partial fit: discovery prefixes skill names and worker registration
remains unqualified. Existing archives and chezmoi remain the distribution path.
See the review and packaging results.
Preview.11 adds explicit diagnosis and clean recovery after a native owner incarnation changes, with immutable history and refusal of unsettled work. Older installed releases require an explicit upgrade. See the recovery contract and acceptance.
The October 31 qualification pass checks preview.11 on Snap's native 0.166.0 pair and records the preview.12 correction for cancelled source errors in current watch attention. A separate review follow-up qualifies ordinary endpoint setup and cancellation of a running observer. The declared compatibility baseline remains unchanged.
| Capability | What is available |
|---|---|
| Watches | Quiet command/script observation, authenticated endpoint access, passive peer reads and configured MCP inspection. |
| Later checks | One-shot reassessment and model-selected continuation, with status and cancellation. |
| Returning to work | “What am I still waiting on?” combines this conversation's stored watches, reminder outcomes and outgoing receipts, with stale or missing evidence explained. |
| Peer coordination | Contextual independent-session discovery, attributed information/requests and handling receipts within one daemon. |
| Browser reports | Immutable static HTML, project catalog, four report MCP tools, a report skill and independent HTTP hosting. |
| Workers | Four native roles and seven worker workflows; explicit named tasks, selective Luna and one optional escalation target. |
Command polling can stay quiet without a model turn per read. Configured MCP checks use scheduled native model turns under normal authentication/approval; each check has model cost. Explicit stop cancels selected observation without stopping the observed work. Esc interrupts the foreground turn and leaves independent registrations within their bounds.
Bounded synthetic native qualification is separate from real-source reliability,
credential/provider recovery, long unattended operation and personal UX acceptance.
Cross-host native messaging,
a recurring calendar and native /exit confirmation interception are outside
this preview. Use the soak checklist to collect actual-use
evidence without manufacturing workloads.
Managed deployment details: Snap, Starship and Carbon
Use codex for Snap OSS and codex-work for work, including their agents
subcommands. The old codex-oss compatibility entry point is retired. These are
separate homes and daemons; native --profile alone does not separate state.
See multiple environments for portable defaults and the
existing explicit Snap paths.
Managed configuration selects v0.1.0-preview.21 for workers, monitoring and
reporting from source 0d01779 through chezmoi 0d53a91. The 2026-11-12 rollout
verifies Snap OSS/work, Starship and Carbon: exact payloads, copied roles/skills,
doctor output and fresh 17/four-tool stdio protocols all match. Native configuration,
credentials, bindings and old releases are preserved.
Delivery evidence
separates installed files from loaded code: sampled Snap/Starship connections
still report preview.20. Carbon's native owner is unavailable, so no loaded-version
claim is made there. Existing helpers/coordinators retain captured code until
normal adoption; no daemon restart or global MCP refresh was issued.
The implementation handoff records source,
release and installed state.
Desktop notification delivery and terminal customization are outside Codex Plus. Native Codex alerts remain selected. Notification enrichment and lifecycle inspection are parked; native terminal formatting is managed with Kitty/chezmoi.
| HTML guide | For | Markdown source |
|---|---|---|
| Install & manage | Give your agent one guide for the installation lifecycle. | Source |
| Get started | Choose components and follow the right setup path. | Source |
| Daily use | Natural requests, useful follow-up, stopping and reports. | Source |
| Luna & workers | Tasks, goal loops, adaptive delegation and worker installation. | Source |
| Multiple environments | Home selection, separate stores and same-daemon boundaries. | Source |
| How it works | Components, permissions, costs, receipts and Claude-workflow coverage. | Source |
| Monitoring installation | Immutable releases, MCP loading, managed setup and rollback. | Source |
| Browser reports | Publication, catalog, storage and independent hosting. | Source |
| Daily-use trial | Record real outcomes and friction during ordinary work. | Source |
For development and qualification, see the implementation handoff, managed activation results, source-access results and technical watch reference. The presentation notes and Pages deployment guide explain authoring and publication.
This repository was previously Codex Worker Kit. Compatible agent/skill paths remain in place. Current GitHub documentation tracks main; documentation changes do not repin qualified installed artifacts or update managed source archives. The implementation plan labels completed contracts and current work; Claude context retains the historical usage study. Active sessions supplied passive evidence; experimental messaging/delivery used owned synthetic sessions. Agent Observer is not a runtime dependency.
Preview.15 adds one optional escalation target to the two adaptive workflows
and packages astra-xhigh. The qualification and limits
separate native execution evidence, conditional Terra routes and ordinary-use acceptance.
Reusable workers and execution workflows keep your native user-selected primary with selective Luna Max delegation. The primary owns decisions, integration, review, and acceptance. Adaptive workflows keep work in the primary when the benefit of a handoff is uncertain. Workflows preserve the selected primary model.
| Role | Model | Reasoning | Responsibility |
|---|---|---|---|
| Current primary | Selected by you in Codex | Selected by you | Decisions, difficult portions, integration, and acceptance |
Cheaper worker luna-max |
gpt-6-luna |
max |
Clear, bounded investigation and implementation with practical verification |
Optional worker sol-xhigh |
gpt-6.1-sol |
xhigh |
Configured escalation from Terra or explicitly assigned independent execution |
Optional worker astra-xhigh |
gpt-6-astra |
xhigh |
Configured escalation from Sol/Terra or explicitly assigned work |
Delegate to Luna when the objective, responsibility boundary, and acceptance check are clear and expected savings justify packaging, review, and possible corrections. Confidence concerns the assignment and verification; the primary need not solve every implementation detail first. A substantial specified migration or focused investigation can qualify. Evolving diagnosis, shared decisions, and small remainders often fit primary execution better.
Automatic escalation defaults to none. In the adaptive workflows, Terra can opt in to Sol XHigh OR Astra XHigh, and Sol can opt in to Astra XHigh. Set the single target in the request or existing applicable user guidance. Reviews and implementation share that target; children return gaps to the initiating primary without an escalation chain. No automatic Sol-to-Terra offload is introduced. Unknown primary metadata holds automatic escalation while primary/Luna work remains useful. See examples and configuration.
Escalation requires evidence: an unresolved decision, contradictory observations, a verification gap, or repeated failure without new evidence. Cross-module work, migrations, concurrency, security, file count, or unfamiliarity alone do not exclude Luna. A worker may reason about options; the primary retains authority over decisions outside the execution contract.
| Workflow | Scope | Delegation |
|---|---|---|
$luna-task |
One bounded task; no goal management | Luna only; primary handles difficult portions |
$luna-goal-loop |
A substantial goal across cohesive assignments | Luna only; primary handles difficult portions |
$adaptive-task |
One bounded task; no goal management | Primary or selective Luna; one opt-in escalation target |
$adaptive-goal-loop |
A substantial goal, routed per assignment | Primary or selective Luna; one opt-in escalation target |
$sol-task |
One bounded task; no goal management | Exact Sol XHigh worker; primary accepts the result |
$astra-task |
One bounded task; no goal management | Exact Astra XHigh worker; primary accepts the result |
$terra-task |
One bounded task; no goal management | Exact GPT-6.1 Terra XHigh worker; primary accepts the result |
The named tasks preserve your primary and need no automatic escalation setting. Review and investigation return evidence without source fixes. For example:
$sol-task Review the current changes and run appropriate validation.
Return findings and evidence; leave source fixes to the primary.
These three skills require preview.18; older installations need an explicit upgrade.
See the named-task contract and examples.
The current Terra task uses a distinct terra-6-1-xhigh role; the legacy task of
the same name remains GPT-5.6-only. Install only the deliberately selected variant.
Preview.17 removes $worker-task and $worker-goal-loop. Update old prompts to
the corresponding adaptive name; no alias or forwarding layer remains. The
four canonical workflow instructions, Luna names and native model roles are
unchanged. Managed upgrades remove the retired installed directories explicitly.
The Luna workflows preserve the explicit worker choice without requiring a workflow switch when the primary needs to help. The adaptive workflows choose whether delegation helps and which worker to use. An unavailable optional worker returns work to the primary; an explicitly requested unavailable Luna worker is reported without silently substituting another model.
Inspect actual native tool declarations before reporting worker unavailability.
Collaboration controls are called directly in their declared namespace; an empty
Code Mode ALL_TOOLS search does not establish their absence. Select Luna with
agent_type="luna-max" and fork_turns="none". The
availability guide separates
missing controls, spawn failures and worker/model execution errors.
Activate adaptive workflows with $adaptive-task, $adaptive-goal-loop, or an
explicit request to use the named skill. A generic "goal loop" uses the ordinary
workflow. Discussing or editing a skill does not activate it. The adaptive skills
disable implicit invocation in their metadata. Skills are enabled by default
when installed; an existing local disable preference must be changed separately.
Use one cohesive assignment and one writer by default. Reuse workers for related corrections, keep context compact, and transfer write ownership before taking over. Ordinary defects usually call for corrections. Failed attempts without new evidence call for primary diagnosis rather than repeated worker cycling.
Use the agent lifecycle guide as the primary setup and maintenance procedure. Choose components in the setup overview. The worker installation steps install four agents and seven worker workflows; the HTML report skill is a separate optional addition. The runtime guide and report guide cover their independent artifacts. With a dotfile manager, update its source and published pins through that owner.
Bryan's chezmoi distribution uses .chezmoiexternals/codex-plus.toml with pinned
Codex Plus URLs and checksums. It retains ~/.local/share/codex-worker-kit as the
managed archive location for compatibility; native skill and agent paths remain
ordinary managed files. This upgrade does not activate a watcher or change
worker routing.
Select the primary separately in your client or configuration:
model = "gpt-6.1-sol"
model_reasoning_effort = "xhigh"Each custom agent pins both its model and reasoning effort. The client and account must support these models, custom agents, and skills. A task label alone does not select a model; workflows use the named custom agent with a compact execution contract and minimal inherited context. See the official custom agent documentation.
GPT-5.6 Terra compatibility files under legacy/ retain the deprecated
terra-xhigh, $terra-task and $terra-goal-loop identities. They do not alias
the current GPT-6.1 role terra-6-1-xhigh. Preview.17 contains only the legacy
Terra variant; preview.18 includes the current variant by default.
Both task variants use the $terra-task invocation. Select one deliberately;
do not install both into discoverable skill roots or recursively merge their
directories. Identify an existing variant from its retained manifest and exact
role pin before any migration. Preserve local edits and restrictions, and use
the owning configuration manager for reviewed replacement or removal. Never
blanket-delete terra-task: it may be the chosen current workflow. Check both
supported personal skill roots if earlier installations used different ones.
Publish a new release before updating managed URLs/checksums or installed files.
Run rtk proxy scripts/check after changing the kit. It validates the default and legacy
inventory, agent model/effort selections, skill metadata, and explicit-only
adaptive invocation policies. It does not prove
routing quality or runtime model availability.
Run rtk proxy python3 -B tests/test_check.py for metadata regression checks. The validator
accepts the kit's two-level interface and policy mappings, quoted strings,
and lowercase booleans. Unsupported YAML forms are rejected; extend the validator
deliberately before adding other metadata formats or fields.
Review representative behavior as well:
- A specified migration with clear boundaries and useful checks can suit Luna.
- An unclear failure stays in the primary until a useful investigation can be confidently assigned and verified.
- A deeply coupled design decision stays in the primary, which may delegate resulting implementation when the savings justify the handoff.
- A useful independent review or demanding slice can use the configured target; explicit requests for separate native workers retain their own authority.
- An ordinary failed test goes back for correction; repeated failure without new evidence returns to the primary.
- An explicit Luna workflow delegates only to Luna, even when escalation is allowed.
Compare total primary-plus-worker usage, corrections, elapsed time, and accepted results on representative tasks. Use runtime cost data when available; do not infer savings from the number of Luna assignments or from token rates alone.
HTML report design and the v1 implementation plan retain the original defaults, interfaces, publication recovery and staged acceptance. The implemented and installed behavior is described in the usage guide and report results.
Worker routing design records selective Luna delegation, the separate purpose of Sol workers, and the rollout plan. Worker routing research reviews the evidence, its limits, and a lightweight policy to assess in practice. The active workflow instructions above describe the current implementation.