overcodex 0.1.0__tar.gz → 0.2.0__tar.gz

{overcodex-0.1.0 → overcodex-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: overcodex
-Version: 0.1.0
+Version: 0.2.0
 Summary: Codex CLI, overclocked — cold multi-account switching, context-threshold handoff, instrumented statusline, and AGENTS.md routing policy for multi-agent workflows
 Project-URL: Homepage, https://github.com/arthur-bump-pm/overcodex
 Project-URL: Repository, https://github.com/arthur-bump-pm/overcodex
@@ -30,8 +30,7 @@ Description-Content-Type: text/markdown
 codex-swap work         # register/list accounts, then switch — restart required
 /prompts:handoff        # package this session's state, resume fresh next launch
 
-ctx [████░░░░░░] 42% remaining | 5h limit 71% | weekly limit 18%
-└ get_context_remaining      └ native Codex statusline items
+native footer: model with reasoning | current directory | project name | context remaining | 5h limit | weekly limit
 ```
 
 ## Install
@@ -50,7 +49,13 @@ codex-swap add personal    # then log in to each: CODEX_HOME=~/.codex-accounts/w
 codex-swap work             # cold switch: writes auth.json, then restart codex
 ```
 
-Start a **new** Codex CLI session (hooks and AGENTS.md load at session start) and confirm the statusline shows the context/limit meters. Run `/prompts:handoff` inside Codex to hand off before you hit auto-compact.
+Start a **new** Codex CLI session (hooks and AGENTS.md load at session start) and confirm its native footer shows the configured fields; Codex may omit unavailable usage-limit fields. Run `/prompts:handoff` inside Codex to hand off before you hit auto-compact.
+
+The same routing policy is packaged as a portable skill for OpenClaw. Install it from a packaged overcodex build with `openclaw skills install "$(overcodex skill-path)" --global`, then configure the four role agent IDs described in `skill/overcodex-ultracode/references/openclaw-adapter.md`.
+
+For agent-assisted setup, tell OpenClaw:
+
+> Install and activate Overcodex UltraCode. Run `curl -fsSL https://raw.githubusercontent.com/arthur-bump-pm/overcodex/main/install-openclaw.sh | bash`, verify it with `openclaw skills list` and `openclaw agents list`, then configure the scout, worker, reviewer, and judge roles. Do not change credentials or existing agent settings without showing me the proposed diff first.
 
 <details>
 <summary>Other install methods, requirements, upgrading</summary>
@@ -86,7 +91,7 @@ Each account gets its own isolated `CODEX_HOME` (a separate `auth.json`, never a
 
 ```mermaid
 flowchart LR
-    A[Context fills up] --> B[get_context_remaining / statusline flags it]
+    A[Context fills up] --> B[Native footer shows context remaining]
     B --> C[You run /prompts:handoff]
     C --> D[Codex packages goals, state, next steps]
     D --> E[Session ends]
@@ -98,13 +103,29 @@ flowchart LR
 You lose the token bloat, not the thread. Combine with a `codex-swap` restart when you're also switching accounts.
 
 ### Statusline
-Codex's native statusline already covers the meters — run `/statusline` inside Codex and enable the context, five-hour, and weekly items (or set `tui.status_line` in config.toml yourself). The kit deliberately ships no statusline config: the native picker is authoritative, and the exact config-key vocabulary is undocumented — nothing to clobber, nothing to break.
+The kit ships conservative defaults for Codex's native footer, in this order: `model-with-reasoning`, `current-dir`, `project-name`, `context-remaining`, `five-hour-limit`, and `weekly-limit`, with colors enabled. Codex renders these native fields and may omit usage-limit fields that are unavailable. Installation adds the defaults only when you do not already have `tui.status_line`; an existing user setting is preserved. Start a new Codex CLI session after installation for the footer to reload.
+
+OverCodex hooks use rollout data separately to issue handoff warnings as context fills. They cannot inject a custom statusline command or replace Codex's native footer.
+
+### AGENTS.md routing policy + custom agents
+A policy block appended to `$CODEX_HOME/AGENTS.md` (loaded globally, then project `AGENTS.md` files concatenate root-down) tells Codex when to delegate and enforces read-parallel/write-serial coordination, verification floors, escalation, and final synthesis. Four custom-agent definitions under `$CODEX_HOME/agents/`, registered in `[agents]`, pin bulk scouting to Luna, implementation to Terra, review to Sol/high, and adjudication to Sol/xhigh. Routed dispatches use an explicit `agent_type` and `fork_turns = "none"`; a task name alone does not route models.
+
+For an explicit trigger inside Codex, run `/prompts:ultracode` and include the objective. For qualifying complex tasks, the global policy also defaults to delegation and requires the parent to explain any decision to stay serial.
+
+When Codex opens this GitHub checkout, the root `AGENTS.md` supplies the repository-local instruction layer. Prompt it with `Activate Overcodex UltraCode in this repository` to have it inspect the global marker and run `./install.sh` when activation is requested. For OpenClaw, prompt it to run `./install-openclaw.sh`; the portable `SKILL.md` then supplies the same orchestration policy.
 
-### AGENTS.md routing policy
-A policy block appended to `$CODEX_HOME/AGENTS.md` (loaded globally, then project `AGENTS.md` files concatenate root-down): bulk work rides cheap models/effort, verification rides a stronger reasoning tier, only final judgment spends the top tier. Routing table, hard floors, escalation rules included.
+The detailed agent-facing activation contract is in [`AGENT-SETUP.md`](AGENT-SETUP.md). Short prompts are enough because the repository's `AGENTS.md` directs the agent to read that contract:
+
+**Codex:** `Activate Overcodex UltraCode for Codex from https://github.com/arthur-bump-pm/overcodex. Clone it if needed, follow AGENT-SETUP.md, preserve unrelated settings, verify the roles and smoke test, then report the restart step.`
+
+**OpenClaw:** `Activate Overcodex UltraCode for OpenClaw from https://github.com/arthur-bump-pm/overcodex. Clone it if needed, follow AGENT-SETUP.md, show configuration diffs before applying them, verify the skill and agents, then run a harmless scout check.`
+
+The complete copy-paste versions are in [`overcodex-instructions.md`](overcodex-instructions.md).
+
+For full proactive orchestration, select a supported Codex reasoning effort in the model controls. GPT-5.5 supports `none`, `low`, `medium`, `high`, and `xhigh`; GPT-5.6 Sol/Terra/Luna also support `max`. The bundled judge uses portable `xhigh`; use `max` only for a GPT-5.6 quality-critical adjudication. `ultra` is not a Codex effort value. Installing Overcodex does not silently replace your existing model or effort preference.
 
 ### Hooks + prompts
-`PreToolUse`/`PostToolUse`/`SessionStart`/`Stop` hooks wired via an inline `[hooks]` table in `config.toml`, plus `/prompts:*` markdown prompts under `$CODEX_HOME/prompts/` (YAML frontmatter, `$1`-`$9` placeholders) for the handoff flow and other repeatable operations.
+`SessionStart`/`UserPromptSubmit`/`Stop`/`PreCompact` hooks wired via an inline `[hooks]` table in `config.toml`, plus `/prompts:*` markdown prompts under `$CODEX_HOME/prompts/` (YAML frontmatter, `$1`-`$9` placeholders) for the handoff flow and other repeatable operations.
 
 ## Cheat sheet
 
@@ -117,6 +138,8 @@ A policy block appended to `$CODEX_HOME/AGENTS.md` (loaded globally, then projec
 | `overcodex install` | (Re)install/refresh the kit — idempotent |
 | `overcodex uninstall` | Remove exactly what install added |
 | `overcodex path` | Print the bundled payload directory |
+| `overcodex skill-path` | Print the portable OpenClaw/Codex skill directory |
+| `install-openclaw.sh` | Install the packaged skill into OpenClaw |
 
 Or skip memorizing and **paste a prompt**:
 
@@ -135,7 +158,9 @@ flowchart TD
     HK --> PR[/prompts:handoff and friends]
     PR --> CS[codex-swap: isolated CODEX_HOME per account]
     CS --> RS[Cold restart adopts the new account]
-    SL[Statusline: get_context_remaining + native limit items] --> HK
+    SL[Native footer: context-remaining + available usage limits] --> PR
+    HK --> RW[Hooks read rollout data for handoff warnings]
+    RW --> PR
 ```
 
 <details>
@@ -157,8 +182,11 @@ flowchart TD
 | `bin/codex-swap` | `~/.local/bin/` | Cold account switcher: register, list, point `$CODEX_HOME` at an account |
 | `hooks/*.sh` | `$CODEX_HOME/hooks/` | SessionStart / UserPromptSubmit / Stop handlers |
 | `config/hooks-block.toml.tpl` | inline `[hooks]` table appended to `config.toml` (markers) | Hook wiring — only if no `hooks` key exists |
+| `config/agents-block.toml.tpl` | `[agents]` block appended to `config.toml` (markers) | Registers the four routed roles |
 | `codex/AGENTS-ULTRACODE.md` | appended to `$CODEX_HOME/AGENTS.md` (markers) | Model/effort routing policy |
 | `prompts/*.md` | `$CODEX_HOME/prompts/` | `/prompts:*` custom prompts (handoff, etc.) |
+| `agents/*.toml` | `$CODEX_HOME/agents/` | Pinned Luna/Terra/Sol custom subagent roles |
+| `skill/overcodex-ultracode/` | OpenClaw skill root (or packaged payload) | Portable policy, role prompts, and platform adapters |
 
 | `shell/zshrc-snippet.sh` | `~/.zshrc` (markers) | `codex-swap` PATH/alias wiring |
 
@@ -168,6 +196,7 @@ flowchart TD
 <summary>Maintainer workflow</summary>
 
 ```bash
+./tests/smoke.sh     # isolated install/hooks/reinstall/uninstall verification
 ./sync.sh            # live setup -> repo: scrub-gated diff, commit, push
 ./sync.sh --release  # + version bump + GitHub release -> PyPI (trusted publishing)
 ./sync.sh --dry-run  # preview either
@@ -181,6 +210,10 @@ A plain `git push` updates git installs only — **PyPI users get changes only v
 
 overcodex is the Codex CLI sibling of **[overclaude](https://github.com/arthur-bump-pm/overclaude)** (same author, same packaging shape) — overclaude does hot account swapping for Claude Code; Codex CLI's credential model only allows a cold switch, so this kit is built around that constraint instead of hiding it.
 
+### Hot-swap and the codext fork
+
+True hot account switching exists on Codex only via [codext](https://github.com/Loongphy/codext) — an Apache-2.0 hard fork of the Codex CLI that polls `auth.json` and reloads it in-process at idle turn boundaries (verified in its source: `tui/src/auth_watch.rs`, `login/src/auth/manager.rs`). It works, with two trade-offs `codex-swap` deliberately doesn't make: it requires running a single-maintainer fork that rebases onto each upstream release, and it still doesn't solve cross-copy refresh-token rotation — switching back to an account whose token rotated elsewhere can force a re-login (codext issue #1 confirms). `codex-swap` stays cold-but-bulletproof by isolating accounts in separate `CODEX_HOME`s where tokens never move. If OpenAI ships auth live-reload upstream, `codex-swap` grows hot for free.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

{overcodex-0.1.0 → overcodex-0.2.0}/README.md

@@ -10,8 +10,7 @@
 codex-swap work         # register/list accounts, then switch — restart required
 /prompts:handoff        # package this session's state, resume fresh next launch
 
-ctx [████░░░░░░] 42% remaining | 5h limit 71% | weekly limit 18%
-└ get_context_remaining      └ native Codex statusline items
+native footer: model with reasoning | current directory | project name | context remaining | 5h limit | weekly limit
 ```
 
 ## Install
@@ -30,7 +29,13 @@ codex-swap add personal    # then log in to each: CODEX_HOME=~/.codex-accounts/w
 codex-swap work             # cold switch: writes auth.json, then restart codex
 ```
 
-Start a **new** Codex CLI session (hooks and AGENTS.md load at session start) and confirm the statusline shows the context/limit meters. Run `/prompts:handoff` inside Codex to hand off before you hit auto-compact.
+Start a **new** Codex CLI session (hooks and AGENTS.md load at session start) and confirm its native footer shows the configured fields; Codex may omit unavailable usage-limit fields. Run `/prompts:handoff` inside Codex to hand off before you hit auto-compact.
+
+The same routing policy is packaged as a portable skill for OpenClaw. Install it from a packaged overcodex build with `openclaw skills install "$(overcodex skill-path)" --global`, then configure the four role agent IDs described in `skill/overcodex-ultracode/references/openclaw-adapter.md`.
+
+For agent-assisted setup, tell OpenClaw:
+
+> Install and activate Overcodex UltraCode. Run `curl -fsSL https://raw.githubusercontent.com/arthur-bump-pm/overcodex/main/install-openclaw.sh | bash`, verify it with `openclaw skills list` and `openclaw agents list`, then configure the scout, worker, reviewer, and judge roles. Do not change credentials or existing agent settings without showing me the proposed diff first.
 
 <details>
 <summary>Other install methods, requirements, upgrading</summary>
@@ -66,7 +71,7 @@ Each account gets its own isolated `CODEX_HOME` (a separate `auth.json`, never a
 
 ```mermaid
 flowchart LR
-    A[Context fills up] --> B[get_context_remaining / statusline flags it]
+    A[Context fills up] --> B[Native footer shows context remaining]
     B --> C[You run /prompts:handoff]
     C --> D[Codex packages goals, state, next steps]
     D --> E[Session ends]
@@ -78,13 +83,29 @@ flowchart LR
 You lose the token bloat, not the thread. Combine with a `codex-swap` restart when you're also switching accounts.
 
 ### Statusline
-Codex's native statusline already covers the meters — run `/statusline` inside Codex and enable the context, five-hour, and weekly items (or set `tui.status_line` in config.toml yourself). The kit deliberately ships no statusline config: the native picker is authoritative, and the exact config-key vocabulary is undocumented — nothing to clobber, nothing to break.
+The kit ships conservative defaults for Codex's native footer, in this order: `model-with-reasoning`, `current-dir`, `project-name`, `context-remaining`, `five-hour-limit`, and `weekly-limit`, with colors enabled. Codex renders these native fields and may omit usage-limit fields that are unavailable. Installation adds the defaults only when you do not already have `tui.status_line`; an existing user setting is preserved. Start a new Codex CLI session after installation for the footer to reload.
+
+OverCodex hooks use rollout data separately to issue handoff warnings as context fills. They cannot inject a custom statusline command or replace Codex's native footer.
+
+### AGENTS.md routing policy + custom agents
+A policy block appended to `$CODEX_HOME/AGENTS.md` (loaded globally, then project `AGENTS.md` files concatenate root-down) tells Codex when to delegate and enforces read-parallel/write-serial coordination, verification floors, escalation, and final synthesis. Four custom-agent definitions under `$CODEX_HOME/agents/`, registered in `[agents]`, pin bulk scouting to Luna, implementation to Terra, review to Sol/high, and adjudication to Sol/xhigh. Routed dispatches use an explicit `agent_type` and `fork_turns = "none"`; a task name alone does not route models.
+
+For an explicit trigger inside Codex, run `/prompts:ultracode` and include the objective. For qualifying complex tasks, the global policy also defaults to delegation and requires the parent to explain any decision to stay serial.
+
+When Codex opens this GitHub checkout, the root `AGENTS.md` supplies the repository-local instruction layer. Prompt it with `Activate Overcodex UltraCode in this repository` to have it inspect the global marker and run `./install.sh` when activation is requested. For OpenClaw, prompt it to run `./install-openclaw.sh`; the portable `SKILL.md` then supplies the same orchestration policy.
 
-### AGENTS.md routing policy
-A policy block appended to `$CODEX_HOME/AGENTS.md` (loaded globally, then project `AGENTS.md` files concatenate root-down): bulk work rides cheap models/effort, verification rides a stronger reasoning tier, only final judgment spends the top tier. Routing table, hard floors, escalation rules included.
+The detailed agent-facing activation contract is in [`AGENT-SETUP.md`](AGENT-SETUP.md). Short prompts are enough because the repository's `AGENTS.md` directs the agent to read that contract:
+
+**Codex:** `Activate Overcodex UltraCode for Codex from https://github.com/arthur-bump-pm/overcodex. Clone it if needed, follow AGENT-SETUP.md, preserve unrelated settings, verify the roles and smoke test, then report the restart step.`
+
+**OpenClaw:** `Activate Overcodex UltraCode for OpenClaw from https://github.com/arthur-bump-pm/overcodex. Clone it if needed, follow AGENT-SETUP.md, show configuration diffs before applying them, verify the skill and agents, then run a harmless scout check.`
+
+The complete copy-paste versions are in [`overcodex-instructions.md`](overcodex-instructions.md).
+
+For full proactive orchestration, select a supported Codex reasoning effort in the model controls. GPT-5.5 supports `none`, `low`, `medium`, `high`, and `xhigh`; GPT-5.6 Sol/Terra/Luna also support `max`. The bundled judge uses portable `xhigh`; use `max` only for a GPT-5.6 quality-critical adjudication. `ultra` is not a Codex effort value. Installing Overcodex does not silently replace your existing model or effort preference.
 
 ### Hooks + prompts
-`PreToolUse`/`PostToolUse`/`SessionStart`/`Stop` hooks wired via an inline `[hooks]` table in `config.toml`, plus `/prompts:*` markdown prompts under `$CODEX_HOME/prompts/` (YAML frontmatter, `$1`-`$9` placeholders) for the handoff flow and other repeatable operations.
+`SessionStart`/`UserPromptSubmit`/`Stop`/`PreCompact` hooks wired via an inline `[hooks]` table in `config.toml`, plus `/prompts:*` markdown prompts under `$CODEX_HOME/prompts/` (YAML frontmatter, `$1`-`$9` placeholders) for the handoff flow and other repeatable operations.
 
 ## Cheat sheet
 
@@ -97,6 +118,8 @@ A policy block appended to `$CODEX_HOME/AGENTS.md` (loaded globally, then projec
 | `overcodex install` | (Re)install/refresh the kit — idempotent |
 | `overcodex uninstall` | Remove exactly what install added |
 | `overcodex path` | Print the bundled payload directory |
+| `overcodex skill-path` | Print the portable OpenClaw/Codex skill directory |
+| `install-openclaw.sh` | Install the packaged skill into OpenClaw |
 
 Or skip memorizing and **paste a prompt**:
 
@@ -115,7 +138,9 @@ flowchart TD
     HK --> PR[/prompts:handoff and friends]
     PR --> CS[codex-swap: isolated CODEX_HOME per account]
     CS --> RS[Cold restart adopts the new account]
-    SL[Statusline: get_context_remaining + native limit items] --> HK
+    SL[Native footer: context-remaining + available usage limits] --> PR
+    HK --> RW[Hooks read rollout data for handoff warnings]
+    RW --> PR
 ```
 
 <details>
@@ -137,8 +162,11 @@ flowchart TD
 | `bin/codex-swap` | `~/.local/bin/` | Cold account switcher: register, list, point `$CODEX_HOME` at an account |
 | `hooks/*.sh` | `$CODEX_HOME/hooks/` | SessionStart / UserPromptSubmit / Stop handlers |
 | `config/hooks-block.toml.tpl` | inline `[hooks]` table appended to `config.toml` (markers) | Hook wiring — only if no `hooks` key exists |
+| `config/agents-block.toml.tpl` | `[agents]` block appended to `config.toml` (markers) | Registers the four routed roles |
 | `codex/AGENTS-ULTRACODE.md` | appended to `$CODEX_HOME/AGENTS.md` (markers) | Model/effort routing policy |
 | `prompts/*.md` | `$CODEX_HOME/prompts/` | `/prompts:*` custom prompts (handoff, etc.) |
+| `agents/*.toml` | `$CODEX_HOME/agents/` | Pinned Luna/Terra/Sol custom subagent roles |
+| `skill/overcodex-ultracode/` | OpenClaw skill root (or packaged payload) | Portable policy, role prompts, and platform adapters |
 
 | `shell/zshrc-snippet.sh` | `~/.zshrc` (markers) | `codex-swap` PATH/alias wiring |
 
@@ -148,6 +176,7 @@ flowchart TD
 <summary>Maintainer workflow</summary>
 
 ```bash
+./tests/smoke.sh     # isolated install/hooks/reinstall/uninstall verification
 ./sync.sh            # live setup -> repo: scrub-gated diff, commit, push
 ./sync.sh --release  # + version bump + GitHub release -> PyPI (trusted publishing)
 ./sync.sh --dry-run  # preview either
@@ -161,6 +190,10 @@ A plain `git push` updates git installs only — **PyPI users get changes only v
 
 overcodex is the Codex CLI sibling of **[overclaude](https://github.com/arthur-bump-pm/overclaude)** (same author, same packaging shape) — overclaude does hot account swapping for Claude Code; Codex CLI's credential model only allows a cold switch, so this kit is built around that constraint instead of hiding it.
 
+### Hot-swap and the codext fork
+
+True hot account switching exists on Codex only via [codext](https://github.com/Loongphy/codext) — an Apache-2.0 hard fork of the Codex CLI that polls `auth.json` and reloads it in-process at idle turn boundaries (verified in its source: `tui/src/auth_watch.rs`, `login/src/auth/manager.rs`). It works, with two trade-offs `codex-swap` deliberately doesn't make: it requires running a single-maintainer fork that rebases onto each upstream release, and it still doesn't solve cross-copy refresh-token rotation — switching back to an account whose token rotated elsewhere can force a re-login (codext issue #1 confirms). `codex-swap` stays cold-but-bulletproof by isolating accounts in separate `CODEX_HOME`s where tokens never move. If OpenAI ships auth live-reload upstream, `codex-swap` grows hot for free.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

overcodex-0.2.0/agents/judge-sol-xhigh.toml

@@ -0,0 +1,11 @@
+name = "judge-sol-xhigh"
+description = "Read-only adjudicator for contradictory reviews and subtle high-risk correctness decisions."
+developer_instructions = """
+Adjudicate only the stated dispute using primary evidence and objective checks.
+Do not edit files. Re-read the relevant artifact instead of inheriting another agent's conclusion.
+Return verdict, confidence from 0 to 1, decisive evidence, rejected alternatives, and residual risk.
+Use this role only when a cheaper reviewer cannot resolve a consequential ambiguity.
+"""
+model = "gpt-5.6-sol"
+model_reasoning_effort = "xhigh"
+sandbox_mode = "read-only"

overcodex-0.2.0/agents/reviewer-sol-high.toml

@@ -0,0 +1,11 @@
+name = "reviewer-sol-high"
+description = "Independent read-only reviewer for correctness, security, regressions, and missing tests."
+developer_instructions = """
+Review the assigned artifact independently. Do not edit files and do not trust the generator's conclusion.
+Prioritize behavioral bugs, security issues, regressions, and missing validation over style.
+Run objective read-only checks when available. Return verdict, confidence from 0 to 1, and evidence with file references.
+State remaining test gaps even when the verdict is PASS.
+"""
+model = "gpt-5.6-sol"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"

overcodex-0.2.0/agents/scout-luna-low.toml

@@ -0,0 +1,11 @@
+name = "scout-luna-low"
+description = "Fast read-only scout for file discovery, inventories, and fixed-schema extraction."
+developer_instructions = """
+Explore only the assigned scope. Do not edit files.
+Return concise findings with exact file paths or other concrete evidence.
+Separate verified facts from inference and identify anything you could not inspect.
+Follow the output contract from the parent prompt exactly.
+"""
+model = "gpt-5.6-luna"
+model_reasoning_effort = "low"
+sandbox_mode = "read-only"

overcodex-0.2.0/agents/worker-terra-medium.toml

@@ -0,0 +1,11 @@
+name = "worker-terra-medium"
+description = "Implementation worker for a bounded change with explicit, non-overlapping file ownership."
+developer_instructions = """
+Implement only the assigned objective and paths. Do not broaden scope.
+Inspect existing conventions before editing, preserve unrelated user changes, and run the requested focused checks.
+Report files changed, checks run, results, and any residual risk.
+If ownership overlaps another worker or the contract is ambiguous, stop and report the conflict before editing.
+"""
+model = "gpt-5.6-terra"
+model_reasoning_effort = "medium"
+sandbox_mode = "workspace-write"

overcodex-0.2.0/codex/AGENTS-ULTRACODE.md

@@ -0,0 +1,66 @@
+# --- overcodex ultracode (begin) ---
+# ULTRACODE - Codex multi-agent routing policy
+
+## When to delegate
+For a complex task with at least two independent, useful work streams, use subagents proactively by default. Good candidates are read-heavy exploration, independent verification, test/log analysis, and clearly partitioned implementation. A qualifying task should not remain entirely in the parent unless the parent records a concrete reason: no independent stream, unsafe shared writes, unavailable role/model, or coordination cost greater than the expected benefit. Do not spawn agents for a small task or work that is inherently sequential.
+
+At the start of every qualifying task, silently perform the UltraCode planning gate below, then tell the user the selected workstreams and roles before dispatching. The parent must either dispatch at least one useful subagent or state the exception that kept the work serial.
+
+Keep the main thread focused on requirements, decisions, and final synthesis. Give each subagent a bounded objective, scope, expected output, and verification standard. Wait for all required results before synthesizing.
+
+## Ultra planning gate
+Before spawning, write a short routing plan in the parent context:
+
+1. Decompose the request into atomic workstreams and identify dependencies.
+2. Classify each stream as `inventory`, `mechanical`, `implementation`, `debugging`, `security`, `architecture`, or `adjudication`.
+3. Score each stream for ambiguity, blast radius, reversibility, and verification difficulty (low/medium/high).
+4. Select the lowest-cost model that meets the task's verification floor. Model choice must be justified by task fit, not by a generic preference for the strongest model.
+5. State ownership, allowed paths, expected artifact, test command, and escalation trigger for every dispatch.
+
+Routing guidance:
+
+| Task shape | Default model | Upgrade when |
+|---|---|---|
+| Inventory, search, schema extraction | `scout-luna-low` | the result is ambiguous or security-relevant |
+| Mechanical, bounded implementation | `worker-terra-medium` | the change crosses shared contracts or tests are weak |
+| Debugging with a reproducible failure | `worker-terra-medium` then `reviewer-sol-high` | the cause is nondeterministic or high blast radius |
+| Security, auth, concurrency, migrations, destructive operations | `reviewer-sol-high` | evidence conflicts or the decision is subtle |
+| Architecture tradeoff or disputed review | `judge-sol-xhigh` | only after independent evidence exists |
+
+Do not use `judge-sol-xhigh` as a default worker. Do not send implementation to a read-only role. If no role meets the floor, stop and say what capability or model is missing rather than silently downgrading.
+
+## Installed roles
+Use these exact Codex custom-agent types when their role fits:
+
+| Agent | Model / effort | Use for |
+|---|---|---|
+| `scout-luna-low` | Luna / low | File discovery, mechanical inventory, fixed-schema extraction |
+| `worker-terra-medium` | Terra / medium | Well-scoped implementation with explicit ownership |
+| `reviewer-sol-high` | Sol / high | Independent correctness, security, regression, and test review |
+| `judge-sol-xhigh` | Sol / xhigh | Contradiction resolution and subtle terminal verdicts |
+
+Codex effort compatibility is model-specific. GPT-5.5 supports `none`, `low`, `medium`, `high`, and `xhigh`. GPT-5.6 Sol/Terra/Luna additionally support `max`. Keep `xhigh` as the portable judge default; select `max` only for a GPT-5.6 task whose quality requirement justifies extra cost and latency. Never write `ultra` as a Codex `model_reasoning_effort` value.
+
+Use the parent Sol session for final synthesis. A high or xhigh parent effort may orchestrate proactively, but it does not remove the need for explicit role and scope selection.
+
+When dispatching one of these roles, the `spawn_agent` call MUST set `agent_type` to the exact name above and `fork_turns` to `"none"`. Put all required task context in the child message. `task_name` is only a label and does not select a model; omitting `agent_type` silently inherits the parent model, while a full-history fork rejects role/model overrides.
+
+## Coordination rules
+- Read-heavy work may run in parallel. Write-heavy work is serial by default.
+- Never let two agents edit the same files concurrently. If parallel writes are justified, partition ownership by non-overlapping paths and say so in every worker prompt.
+- Run objective checks such as tests, typecheck, lint, or numeric validation before spending a reviewer agent. A passing deterministic check outranks an LLM opinion.
+- Verification must be independent: give the reviewer the artifact, requirements, and evidence, not the generator's conclusion.
+- Every reviewer returns `verdict`, `confidence`, and `evidence`. Missing fields, confidence below 0.7, `UNSURE`, or contradictory results trigger one escalation to the next stronger role.
+- Use panels only for high-risk fuzzy judgments. Give 2-3 reviewers distinct lenses; unanimous results may pass, while a split goes to `judge-sol-xhigh` rather than majority vote.
+- Stop escalating when more than one quarter of downgraded stages require escalation. Re-plan the routing instead of silently moving every task to Sol.
+- Reduce fan-out before lowering verification quality. The default `agents.max_depth = 1` is appropriate unless the user explicitly requests recursive delegation.
+
+## Floors
+- User-visible final synthesis with no downstream check: parent Sol session.
+- Security, auth, concurrency, money math, destructive operations, and migrations: `reviewer-sol-high` minimum.
+- A subtle disputed verdict: `judge-sol-xhigh`.
+- Bulk or repetitive work stays on Luna or Terra even when the parent runs at high or xhigh effort.
+
+## Dispatch lint
+Before spawning, confirm that each agent adds new information or independent verification; has an objective, path or topic boundary, and output contract; uses the lowest role that meets its floor; and cannot race another writer. If those conditions are not met, keep the work in the main thread.
+# --- overcodex ultracode (end) ---

overcodex-0.2.0/config/agents-block.toml.tpl

@@ -0,0 +1,22 @@
+# overcodex custom-agent registration. install.sh substitutes @AGENTS_DIR@.
+# `task_name` only labels a child; routing requires agent_type plus a non-full
+# history fork. AGENTS-ULTRACODE.md carries that dispatch contract.
+[agents]
+max_threads = 4
+max_depth = 1
+
+[agents.scout-luna-low]
+description = "Fast read-only scout for discovery, inventory, and extraction."
+config_file = "@AGENTS_DIR@/scout-luna-low.toml"
+
+[agents.worker-terra-medium]
+description = "Bounded implementation worker with explicit file ownership."
+config_file = "@AGENTS_DIR@/worker-terra-medium.toml"
+
+[agents.reviewer-sol-high]
+description = "Independent correctness, security, regression, and test reviewer."
+config_file = "@AGENTS_DIR@/reviewer-sol-high.toml"
+
+[agents.judge-sol-xhigh]
+description = "Adjudicator for contradictory or subtle high-risk verdicts."
+config_file = "@AGENTS_DIR@/judge-sol-xhigh.toml"

overcodex-0.2.0/config/statusline.toml

@@ -0,0 +1,3 @@
+[tui]
+status_line = ["model-with-reasoning", "current-dir", "project-name", "context-remaining", "five-hour-limit", "weekly-limit"]
+status_line_use_colors = true

{overcodex-0.1.0 → overcodex-0.2.0}/hooks/overcodex-ctx-lib.sh

@@ -24,12 +24,10 @@
 #              "last_token_usage":{...},
 #              "model_context_window":W},
 #      "rate_limits":{...}}}
-# total_tokens / model_context_window * 100, taken from the LAST such line, is
-# used as the context-usage percentage everywhere below. This is a real
-# measurement (not a heuristic) but its recency depends on how often Codex
-# emits token_count events — needs live-session validation (see hooks-test
-# notes) to confirm the cadence is tight enough for the 60/75/85 thresholds to
-# feel timely rather than lagging.
+# last_token_usage.total_tokens / model_context_window * 100, taken from the
+# LAST such line, is used as the context-usage percentage everywhere below.
+# `total_token_usage` is cumulative billing usage across turns and can exceed
+# the context window many times over, so it must never drive these thresholds.
 #
 # Contract: ctx_pct_from_transcript prints an integer 0-100 on stdout and
 # returns 0 on success; on ANY failure (no file, no jq, malformed, division by
@@ -55,7 +53,7 @@ ctx_pct_from_transcript() {
     fi
     [ -n "$line" ] || return 1
 
-    total="$(printf '%s' "$line" | jq -r '.payload.info.total_token_usage.total_tokens // empty' 2>/dev/null)"
+    total="$(printf '%s' "$line" | jq -r '.payload.info.last_token_usage.total_tokens // empty' 2>/dev/null)"
     window="$(printf '%s' "$line" | jq -r '.payload.info.model_context_window // empty' 2>/dev/null)"
     [ -n "$total" ] && [ -n "$window" ] || return 1
     case "$total" in ''|*[!0-9]*) return 1 ;; esac

overcodex-0.2.0/install-openclaw.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_url="https://github.com/arthur-bump-pm/overcodex.git"
+
+if ! command -v openclaw >/dev/null 2>&1; then
+  echo "install-openclaw: openclaw is required and was not found" >&2
+  exit 1
+fi
+
+if ! command -v overcodex >/dev/null 2>&1; then
+  if ! command -v pipx >/dev/null 2>&1; then
+    echo "install-openclaw: install pipx or overcodex first" >&2
+    exit 1
+  fi
+  pipx install "git+${repo_url}"
+fi
+
+skill_path="$(overcodex skill-path)"
+openclaw skills install "$skill_path" --global
+
+echo "Overcodex UltraCode is installed in OpenClaw."
+echo "Next: ask OpenClaw to run 'openclaw skills list' and 'openclaw agents list',"
+echo "then configure scout, worker, reviewer, and judge agent IDs."

{overcodex-0.1.0 → overcodex-0.2.0}/install.sh

@@ -25,6 +25,7 @@ AGENTS_MD="$CODEX_HOME/AGENTS.md"
 # Kit sources.
 SRC_SWAP="$SCRIPT_DIR/bin/codex-swap"
 SRC_HOOKS_TPL="$SCRIPT_DIR/config/hooks-block.toml.tpl"
+SRC_AGENT_ROLES_TPL="$SCRIPT_DIR/config/agents-block.toml.tpl"
 SRC_AGENTS="$SCRIPT_DIR/codex/AGENTS-ULTRACODE.md"
 SRC_ZSNIPPET="$SCRIPT_DIR/shell/zshrc-snippet.sh"
 
@@ -41,6 +42,8 @@ ZSH_BEGIN='# --- overcodex integration (begin) ---'
 ZSH_END='# --- overcodex integration (end) ---'
 HOOKS_BEGIN='# --- overcodex hooks (begin) ---'
 HOOKS_END='# --- overcodex hooks (end) ---'
+AGENT_ROLES_BEGIN='# --- overcodex agent roles (begin) ---'
+AGENT_ROLES_END='# --- overcodex agent roles (end) ---'
 SL_BEGIN='# --- overcodex statusline (begin) ---'
 SL_END='# --- overcodex statusline (end) ---'
 
@@ -64,7 +67,7 @@ echo
 # ---------------------------------------------------------------------------
 # 0. Sanity: required kit files present.
 # ---------------------------------------------------------------------------
-for f in "$SRC_SWAP" "$SRC_HOOKS_TPL" "$SRC_AGENTS" "$SRC_ZSNIPPET"; do
+for f in "$SRC_SWAP" "$SRC_HOOKS_TPL" "$SRC_AGENT_ROLES_TPL" "$SRC_AGENTS" "$SRC_ZSNIPPET"; do
   [ -f "$f" ] || die "kit file missing: $f (run from the repo root)"
 done
 # At least one hook script.
@@ -176,17 +179,29 @@ if [ -n "$PROMPTS" ]; then
 else
   note_skip "no prompts/*.md in kit (nothing to install)"
 fi
+
+# agents/*.toml -> $CODEX_HOME/agents/ (optional custom subagent roles)
+AGENT_FILES=$(ls "$SCRIPT_DIR"/agents/*.toml 2>/dev/null)
+if [ -n "$AGENT_FILES" ]; then
+  mkdir -p "$CODEX_HOME/agents" || die "mkdir failed: $CODEX_HOME/agents"
+  for a in "$SCRIPT_DIR"/agents/*.toml; do
+    [ -f "$a" ] || continue
+    install_file "$a" "$CODEX_HOME/agents/$(basename "$a")" -
+  done
+else
+  note_warn "no agents/*.toml in kit — routing policy will be advisory only"
+fi
 echo
 
 # ---------------------------------------------------------------------------
-# 3. config.toml — add the inline [hooks] table and [tui].status_line IF ABSENT.
-#    Never rewrites the file: python3+tomllib decides presence; the hooks block
-#    is APPENDED at EOF between markers (a [hooks] table prepended at the top
-#    would capture every top-level key after it); status_line is a [tui] insert.
+# 3. config.toml — add [hooks], [agents], and [tui].status_line IF ABSENT.
+#    Never rewrites unrelated settings: python3+tomllib decides presence; new
+#    table blocks are appended at EOF between markers and status_line is a
+#    targeted [tui] insert.
 # ---------------------------------------------------------------------------
 echo "-- config.toml --"
 
-# toml_present <config> -> prints "hooks=present|absent" and "sl=present|absent"
+# toml_present <config> -> prints hooks/agents/status_line/status_line_use_colors presence
 # on stdout. Exits 3 on a parse error (caller then leaves the file untouched).
 toml_present() {
   tp_cfg="$1"
@@ -205,18 +220,24 @@ except Exception as e:
 tui = d.get("tui")
 tui = tui if isinstance(tui, dict) else {}
 print("hooks=%s" % ("present" if "hooks" in d else "absent"))
+print("agents=%s" % ("present" if "agents" in d else "absent"))
 print("sl=%s" % ("present" if "status_line" in tui else "absent"))
+print("sl_colors=%s" % ("present" if "status_line_use_colors" in tui else "absent"))
 PY
     return $?
   fi
   # grep fallback (heuristic: matches a top-level-looking key line).
   if [ -f "$tp_cfg" ]; then
-    if grep -Eq '^[[:space:]]*hooks[[:space:]]*=' "$tp_cfg"; then
+    if grep -Eq '^[[:space:]]*(hooks[[:space:]]*=|\[hooks\])' "$tp_cfg"; then
       echo "hooks=present"; else echo "hooks=absent"; fi
+    if grep -Eq '^[[:space:]]*(agents[[:space:]]*=|\[agents\])' "$tp_cfg"; then
+      echo "agents=present"; else echo "agents=absent"; fi
     if grep -Eq '^[[:space:]]*status_line[[:space:]]*=' "$tp_cfg"; then
       echo "sl=present"; else echo "sl=absent"; fi
+    if grep -Eq '^[[:space:]]*status_line_use_colors[[:space:]]*=' "$tp_cfg"; then
+      echo "sl_colors=present"; else echo "sl_colors=absent"; fi
   else
-    echo "hooks=absent"; echo "sl=absent"
+    echo "hooks=absent"; echo "agents=absent"; echo "sl=absent"; echo "sl_colors=absent"
   fi
   return 0
 }
@@ -226,16 +247,21 @@ DET=$(toml_present "$CONFIG_TOML")
 if [ $? -eq 3 ]; then
   CFG_OK=0
   note_warn "config.toml is not valid TOML; leaving it completely untouched."
-  note_warn "  Fix $CONFIG_TOML, then re-run ./install.sh to wire hooks/status_line."
+  note_warn "  Fix $CONFIG_TOML, then re-run ./install.sh to wire hooks/agents/status_line."
 fi
 
 if [ "$CFG_OK" = 1 ]; then
   HOOKS_STATE=$(printf '%s\n' "$DET" | sed -n 's/^hooks=//p')
+  AGENTS_STATE=$(printf '%s\n' "$DET" | sed -n 's/^agents=//p')
   SL_STATE=$(printf '%s\n' "$DET" | sed -n 's/^sl=//p')
+  SL_COLORS_STATE=$(printf '%s\n' "$DET" | sed -n 's/^sl_colors=//p')
 
   NEED_HOOKS=0
   [ "$HOOKS_STATE" = absent ] && NEED_HOOKS=1
 
+  NEED_AGENT_ROLES=0
+  [ "$AGENTS_STATE" = absent ] && NEED_AGENT_ROLES=1
+
   NEED_SL=0
   if [ "$SL_STATE" = absent ]; then
     if [ -n "$SRC_STATUSLINE" ]; then
@@ -255,6 +281,15 @@ if [ "$CFG_OK" = 1 ]; then
       note_warn "  manually (substitute @HOOKS_DIR@ with $CODEX_HOME/hooks)."
     fi
   fi
+  if [ "$AGENTS_STATE" = present ]; then
+    if [ -f "$CONFIG_TOML" ] && grep -qF "$AGENT_ROLES_BEGIN" "$CONFIG_TOML"; then
+      note_skip "config.toml custom agent roles already wired by overcodex"
+    else
+      note_warn "config.toml already defines an 'agents' key — leaving it untouched."
+      note_warn "  Merge the roles from config/agents-block.toml.tpl into your [agents] table"
+      note_warn "  manually (substitute @AGENTS_DIR@ with $CODEX_HOME/agents)."
+    fi
+  fi
   if [ "$SL_STATE" = present ]; then
     if [ -f "$CONFIG_TOML" ] && grep -qF "$SL_BEGIN" "$CONFIG_TOML"; then
       note_skip "config.toml [tui].status_line already set by overcodex"
@@ -263,7 +298,7 @@ if [ "$CFG_OK" = 1 ]; then
     fi
   fi
 
-  if [ "$NEED_HOOKS" = 1 ] || [ "$NEED_SL" = 1 ]; then
+  if [ "$NEED_HOOKS" = 1 ] || [ "$NEED_AGENT_ROLES" = 1 ] || [ "$NEED_SL" = 1 ]; then
     b=""
     [ -f "$CONFIG_TOML" ] && b=$(backup_file "$CONFIG_TOML")
     TMP="$CONFIG_TOML.tmp-$EPOCH"
@@ -287,16 +322,31 @@ if [ "$CFG_OK" = 1 ]; then
       } >> "$TMP"
     fi
 
+    # agents: register each installed role. A file under agents/ alone is not
+    # enough for reliable spawn_agent(agent_type=...) routing on all surfaces.
+    if [ "$NEED_AGENT_ROLES" = 1 ]; then
+      if [ -s "$TMP" ]; then
+        [ -n "$(tail -c1 "$TMP")" ] && printf '\n' >> "$TMP"
+        printf '\n' >> "$TMP"
+      fi
+      {
+        printf '%s\n' "$AGENT_ROLES_BEGIN"
+        sed "s|@AGENTS_DIR@|$CODEX_HOME/agents|g" "$SRC_AGENT_ROLES_TPL"
+        printf '%s\n' "$AGENT_ROLES_END"
+      } >> "$TMP"
+    fi
+
     # status_line: insert our keys just after an existing [tui] header, else
     # append a fresh [tui] table at EOF. Fragment header/comment/blank lines are
-    # dropped so only the key lines land inside our markers.
+    # dropped so only missing key lines land inside our markers.
     if [ "$NEED_SL" = 1 ]; then
       TMP2="$CONFIG_TOML.tmp2-$EPOCH"
-      awk -v sb="$SL_BEGIN" -v se="$SL_END" -v kf="$SRC_STATUSLINE" '
+      awk -v sb="$SL_BEGIN" -v se="$SL_END" -v kf="$SRC_STATUSLINE" -v skip_colors="$SL_COLORS_STATE" '
         function emitkeys(   line) {
           while ((getline line < kf) > 0) {
             if (line == "" || line == "[tui]") continue
             if (line ~ /^[ \t]*#/) continue
+            if (skip_colors == "present" && line ~ /^[ \t]*status_line_use_colors[ \t]*=/) continue
             print line
           }
           close(kf)
@@ -325,6 +375,7 @@ PY
     _bmsg=""
     [ -n "$b" ] && _bmsg=" (backup: $b)"
     [ "$NEED_HOOKS" = 1 ] && note_did "wired the inline [hooks] table into config.toml$_bmsg"
+    [ "$NEED_AGENT_ROLES" = 1 ] && note_did "registered custom [agents] roles in config.toml$_bmsg"
     [ "$NEED_SL" = 1 ]    && note_did "set [tui].status_line in config.toml$_bmsg"
   else
     [ "$HOOKS_STATE" = absent ] || [ "$NEED_HOOKS" = 1 ] || true
@@ -335,16 +386,46 @@ echo
 
 # ---------------------------------------------------------------------------
 # append_marked <target> <begin> <end> <src> <label>
-#   Append a marker-wrapped block only if the begin marker is absent. Any
-#   pre-existing overcodex marker lines in <src> are stripped so we never nest.
+#   Install or refresh a marker-wrapped block. Any pre-existing overcodex
+#   marker lines in <src> are stripped so we never nest. Existing blocks are
+#   replaced on change, which makes upgrades refresh policy text safely.
 # ---------------------------------------------------------------------------
 append_marked() {
   am_target="$1"; am_begin="$2"; am_end="$3"; am_src="$4"; am_label="$5"
+  mkdir -p "$(dirname "$am_target")" || die "mkdir failed for $am_target"
+  am_block="$am_target.block-$EPOCH-$$"
+  {
+    printf '%s\n' "$am_begin"
+    grep -vxF "$am_begin" "$am_src" | grep -vxF "$am_end"
+    printf '%s\n' "$am_end"
+  } > "$am_block" || die "could not stage $am_label"
+
   if [ -f "$am_target" ] && grep -qF "$am_begin" "$am_target"; then
-    note_skip "$am_label already present in $am_target"
+    grep -qF "$am_end" "$am_target" || { rm -f "$am_block"; die "$am_label begin marker exists without end marker in $am_target"; }
+    am_tmp="$am_target.tmp-$EPOCH-$$"
+    awk -v b="$am_begin" -v e="$am_end" -v repl="$am_block" '
+      $0 == b {
+        while ((getline line < repl) > 0) print line
+        close(repl); replacing = 1; next
+      }
+      replacing == 1 { if ($0 == e) replacing = 0; next }
+      { print }
+    ' "$am_target" > "$am_tmp" || { rm -f "$am_block" "$am_tmp"; die "could not refresh $am_label"; }
+    rm -f "$am_block"
+    if cmp -s "$am_target" "$am_tmp"; then
+      rm -f "$am_tmp"
+      note_skip "$am_label already up-to-date in $am_target"
+      return 0
+    fi
+    b=$(backup_file "$am_target")
+    mv "$am_tmp" "$am_target" || die "could not refresh $am_label in $am_target"
+    note_did "refreshed $am_label in $am_target (backup: $b)"
     return 0
   fi
-  mkdir -p "$(dirname "$am_target")" || die "mkdir failed for $am_target"
+  if [ -f "$am_target" ] && grep -qF "$am_end" "$am_target"; then
+    rm -f "$am_block"
+    die "$am_label end marker exists without begin marker in $am_target"
+  fi
   b=""
   [ -f "$am_target" ] && b=$(backup_file "$am_target")
   # Separator blank line before our block when the file has content.
@@ -352,12 +433,8 @@ append_marked() {
     [ -n "$(tail -c1 "$am_target")" ] && printf '\n' >> "$am_target"
     printf '\n' >> "$am_target"
   fi
-  {
-    printf '%s\n' "$am_begin"
-    # Drop any stray marker lines already in the source to avoid nesting.
-    grep -vxF "$am_begin" "$am_src" | grep -vxF "$am_end"
-    printf '%s\n' "$am_end"
-  } >> "$am_target" || die "could not append to $am_target"
+  cat "$am_block" >> "$am_target" || { rm -f "$am_block"; die "could not append to $am_target"; }
+  rm -f "$am_block"
   if [ -n "$b" ]; then
     note_did "appended $am_label to $am_target (backup: $b)"
   else
@@ -366,7 +443,7 @@ append_marked() {
 }
 
 # ---------------------------------------------------------------------------
-# 4. AGENTS.md — append the ultracode block between markers (if absent).
+# 4. AGENTS.md — install or refresh the ultracode block between markers.
 # ---------------------------------------------------------------------------
 echo "-- AGENTS.md --"
 append_marked "$AGENTS_MD" "$AGENTS_BEGIN" "$AGENTS_END" "$SRC_AGENTS" "overcodex ultracode block"
@@ -411,9 +488,28 @@ with open(sys.argv[1], "rb") as f:
 sys.exit(0 if "hooks" in d else 1)
 PY
   then HOOKS_WIRED=yes; fi
-elif [ -f "$CONFIG_TOML" ] && grep -Eq '^[[:space:]]*hooks[[:space:]]*=' "$CONFIG_TOML"; then
+elif [ -f "$CONFIG_TOML" ] && grep -Eq '^[[:space:]]*(hooks[[:space:]]*=|\[hooks\])' "$CONFIG_TOML"; then
   HOOKS_WIRED=yes
 fi
+
+# custom agent roles registered.
+AGENT_ROLES_WIRED=no
+if [ -n "$PYTHON" ] && [ -f "$CONFIG_TOML" ]; then
+  if "$PYTHON" - "$CONFIG_TOML" <<'PY' >/dev/null 2>&1
+import sys, tomllib
+with open(sys.argv[1], "rb") as f:
+    d = tomllib.load(f)
+agents = d.get("agents", {})
+required = {"scout-luna-low", "worker-terra-medium", "reviewer-sol-high", "judge-sol-xhigh"}
+sys.exit(0 if required.issubset(agents) else 1)
+PY
+  then AGENT_ROLES_WIRED=yes; fi
+fi
+if [ "$AGENT_ROLES_WIRED" = yes ]; then
+  echo "  [ok] config.toml custom agent roles registered"
+else
+  note_warn "config.toml does not register every overcodex agent role — model routing will be advisory."
+fi
 if [ "$HOOKS_WIRED" = yes ]; then
   echo "  [ok] config.toml hooks key wired"
 else

overcodex-0.2.0/prompts/ultracode.md

@@ -0,0 +1,17 @@
+---
+description: "Plan and execute a complex task with Codex subagents, model-aware routing, and independent verification."
+argument-hint: "[task or objective]"
+---
+
+# /prompts:ultracode — explicit Codex multi-agent execution
+
+Use the Codex-native UltraCode policy in `$CODEX_HOME/AGENTS.md`.
+
+1. Restate the requested objective and split it into independent workstreams.
+2. Classify each stream and choose the best registered Codex role/model/effort for it. Use the exact `agent_type` and `fork_turns = "none"` fields when spawning.
+3. Before writing, announce the plan: workstream, owner, allowed paths, expected output, verification command, and escalation trigger.
+4. Dispatch read-only scouts in parallel. Serialize workers that could touch overlapping paths.
+5. Run objective checks before review. Use `reviewer-sol-high` for independent review and `judge-sol-xhigh` only for unresolved or high-risk disputes.
+6. Synthesize the results in the parent session. Report which agents ran, what they contributed, model/effort selected, checks run, and residual risk.
+
+If the task is too small or inherently sequential, do it in the parent and explicitly state why delegation would not add value.

{overcodex-0.1.0 → overcodex-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "overcodex"
-version = "0.1.0"
+version = "0.2.0"
 description = "Codex CLI, overclocked — cold multi-account switching, context-threshold handoff, instrumented statusline, and AGENTS.md routing policy for multi-agent workflows"
 readme = "README.md"
 license = { text = "MIT" }
@@ -40,9 +40,12 @@ packages = ["src/overcodex"]
 "config" = "overcodex/payload/config"
 "codex" = "overcodex/payload/codex"
 "prompts" = "overcodex/payload/prompts"
+"agents" = "overcodex/payload/agents"
 "shell" = "overcodex/payload/shell"
+"skill" = "overcodex/payload/skill"
 "install.sh" = "overcodex/payload/install.sh"
 "uninstall.sh" = "overcodex/payload/uninstall.sh"
+"install-openclaw.sh" = "overcodex/payload/install-openclaw.sh"
 
 # hatchling's default sdist build respects VCS-ignore files and otherwise
 # only guarantees the `src/` package tree; it does NOT guarantee the payload
@@ -60,9 +63,12 @@ include = [
     "/config",
     "/codex",
     "/prompts",
+    "/agents",
     "/shell",
+    "/skill",
     "/install.sh",
     "/uninstall.sh",
+    "/install-openclaw.sh",
     "/README.md",
     "/LICENSE",
     "/pyproject.toml",

overcodex-0.2.0/skill/overcodex-ultracode/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: overcodex-ultracode
+description: Coordinate complex engineering work with explicit scout, worker, reviewer, and judge roles, portable across Codex and OpenClaw.
+---
+
+# Overcodex UltraCode
+
+Use this skill for complex, cross-file, risky, or explicitly multi-agent work. Keep small, local edits in the current session. The main session owns requirements, decisions, integration, and the final answer.
+
+## Roles
+
+- **scout-luna-low**: fast, read-only reconnaissance; map relevant files, constraints, and likely risks.
+- **worker-terra-medium**: bounded implementation; write only within an explicit ownership boundary and report changed files and tests.
+- **reviewer-sol-high**: independent review; inspect the diff and behavior, then return `PASS`, `FAIL`, or `UNSURE` with evidence and confidence.
+- **judge-sol-xhigh**: adjudicate contradictory findings, choose the safest supported interpretation, and identify unresolved risk.
+
+## Dispatch contract
+
+1. Select a role explicitly. A task name or friendly label alone does not select a model or policy.
+2. Use the platform's exact role/agent identifier and request its configured model and reasoning level when supported.
+3. Default to isolated context and one delegation level. Do not let a child recursively spawn more workers unless the task explicitly requires it.
+4. If the platform cannot enforce role or model routing, preserve the role prompt but report that routing is advisory.
+
+Codex naming is model-specific: GPT-5.5 uses `none`, `low`, `medium`, `high`, and `xhigh`; GPT-5.6 Sol/Terra/Luna also use `max`. Use `xhigh` for portable high-assurance review and reserve `max` for a GPT-5.6-only quality-critical adjudication. `ultra` is not a Codex effort value.
+
+## Task-aware planning
+
+Before dispatching, create a compact plan in the parent session. Decompose the request into independent workstreams, classify each as `inventory`, `mechanical`, `implementation`, `debugging`, `security`, `architecture`, or `adjudication`, and rate ambiguity, blast radius, reversibility, and verification difficulty. Choose the lowest-cost configured model that satisfies the task's verification floor:
+
+| Task shape | Default role | Upgrade trigger |
+|---|---|---|
+| Inventory or fixed-schema extraction | `scout-luna-low` | ambiguity or security relevance |
+| Bounded implementation | `worker-terra-medium` | shared contracts, broad blast radius, or weak tests |
+| Reproducible debugging | worker, then `reviewer-sol-high` | nondeterminism or high impact |
+| Security, auth, concurrency, migrations, destructive work | `reviewer-sol-high` | conflicting evidence or subtle judgment |
+| Architecture tradeoffs or disputed findings | `judge-sol-xhigh` | only after independent evidence |
+
+Every dispatch must state its objective, ownership paths, expected artifact, verification command, and escalation trigger. Stronger models are a targeted upgrade, not the default. If no configured role meets the floor, stop and report the capability gap instead of silently downgrading.
+
+Platform mechanics are in [codex-adapter.md](references/codex-adapter.md) and [openclaw-adapter.md](references/openclaw-adapter.md).
+
+## Coordination rules
+
+- Read-only scouting may run in parallel. Writes to the same worktree run serially with explicit ownership.
+- Before review, run the narrowest relevant tests and state the verification floor.
+- Escalate `UNSURE`, confidence below 0.70, contradictory findings, security-sensitive changes, or a failed verification floor to the judge.
+- Keep reviewer lenses independent: correctness, regressions, security, and operability are separate concerns.
+- If more than 25% of delegated tasks escalate, stop scaling out and re-profile the work.
+- When context is near its limit, package goals, decisions, changed files, tests, and exact next steps into a fresh-session handoff.
+
+Reusable role prompts and output contracts are in [role-prompts.md](references/role-prompts.md).
+
+## Safety
+
+This skill provides coordination instructions, not permissions. Review hooks, scripts, and external tool calls before trusting them. Never bypass platform trust or sandbox controls as part of normal operation.

overcodex-0.2.0/skill/overcodex-ultracode/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Overcodex UltraCode"
+  short_description: "Portable multi-agent engineering orchestration"
+  default_prompt: "Use $overcodex-ultracode to coordinate this complex engineering task with explicit scout, worker, reviewer, and judge roles."
+policy:
+  allow_implicit_invocation: true

overcodex-0.2.0/skill/overcodex-ultracode/references/codex-adapter.md

@@ -0,0 +1,18 @@
+# Codex Adapter
+
+Install the Codex kit with:
+
+```bash
+pipx install overcodex
+overcodex install
+```
+
+The installer adds the routing policy to `$CODEX_HOME/AGENTS.md`, installs four role definitions under `$CODEX_HOME/agents/`, and registers them in `config.toml`. The portable skill itself is available from a packaged install with `overcodex skill-path`.
+
+For delegation, use the exact registered Codex `agent_type` and `fork_turns = "none"`; a task name does not route a model. Restart Codex after installation, then review and trust the hooks with `/hooks`. GPT-5.5 Codex uses `none`, `low`, `medium`, `high`, or `xhigh`; GPT-5.6 Sol/Terra/Luna additionally support `max`. Keep `xhigh` for cross-model compatibility and request `max` only when the selected model is GPT-5.6 and the task is quality-critical. Never use Claude Code effort names or `ultra` in Codex configuration.
+
+Run the repository smoke test before changing live configuration:
+
+```bash
+./tests/smoke.sh
+```

overcodex-0.2.0/skill/overcodex-ultracode/references/openclaw-adapter.md

@@ -0,0 +1,16 @@
+# OpenClaw Adapter
+
+OpenClaw loads a skill directory containing `SKILL.md`. Install this package from a checkout or extracted wheel with:
+
+```bash
+openclaw skills install ./skill/overcodex-ultracode --global
+openclaw skills list
+```
+
+For a one-message bootstrap, ask the OpenClaw agent to run the repository's `install-openclaw.sh`. It installs the Python package only when needed, installs the skill globally, and prints the remaining verification steps. The agent should show proposed changes before editing existing OpenClaw agent configuration.
+
+The global destination is normally `~/.openclaw/skills`; workspace-local skills are also supported. Configure four OpenClaw agent IDs in the current `agents.list` schema, for example `ultracode-scout`, `ultracode-worker`, `ultracode-reviewer`, and `ultracode-judge`, each with its intended model and default thinking level. Restrict delegation with the agent allowlist and set a maximum spawn depth of 1 and concurrency of 4.
+
+When dispatching, call `sessions_spawn` with the mapped `agentId`, `context: "isolated"`, a descriptive `taskName`, and the role prompt. Use `model` and `thinking` overrides only when the configured OpenClaw version permits them. Wait with `sessions_yield`; do not assume Codex's `agent_type` field exists in OpenClaw.
+
+If separate role IDs are not configured, dispatch remains advisory: include the role prompt and requested model/thinking in the task, then disclose that the runtime could not enforce routing. Verify with `openclaw agents list` and a harmless scout task before relying on the workflow.

overcodex-0.2.0/skill/overcodex-ultracode/references/role-prompts.md

@@ -0,0 +1,21 @@
+# Role Prompts
+
+Use these as short prefixes for delegated tasks. Include the concrete objective, allowed paths, and expected evidence.
+
+Every task prefix should also include: `class`, `risk`, `ownership`, `verification`, and `escalate_when`. The parent must choose the role from the task shape, not from agent availability alone.
+
+## Scout
+
+You are `scout-luna-low`. Do not edit files. Trace the relevant implementation and tests, identify constraints and risks, and return: findings, file paths, recommended next step, and confidence.
+
+## Worker
+
+You are `worker-terra-medium`. Implement only the stated objective inside the allowed ownership boundary. Preserve existing conventions. Run focused tests, report changed files, commands, results, and any unresolved concern.
+
+## Reviewer
+
+You are `reviewer-sol-high`. Independently inspect the proposed diff and its tests. Look for correctness bugs, regressions, unsafe assumptions, and missing verification. Return exactly: verdict (`PASS`, `FAIL`, or `UNSURE`), confidence from 0 to 1, evidence with file paths, and the smallest corrective action.
+
+## Judge
+
+You are `judge-sol-xhigh`. Reconcile the supplied evidence and competing findings. Prefer demonstrated behavior over speculation, decide whether the verification floor is met, and return: decision, rationale, residual risk, and next action.

{overcodex-0.1.0 → overcodex-0.2.0}/src/overcodex/__init__.py

@@ -1,4 +1,4 @@
 """overcodex — Codex CLI, overclocked: cold account switching, handoff prompts,
-statusline config, and AGENTS.md routing policy for multi-agent workflows."""
+context hooks, and pinned custom agents for multi-agent workflows."""
 
 __all__ = []

{overcodex-0.1.0 → overcodex-0.2.0}/src/overcodex/cli.py

@@ -1,7 +1,7 @@
 """overcodex CLI — runs the bundled kit installer/uninstaller.
 
 The package wheel carries the same payload a git clone has (bin/, hooks/,
-config/, codex/, prompts/, shell/, and the install/uninstall scripts). This
+config/, codex/, prompts/, agents/, shell/, and the install/uninstall scripts). This
 CLI just locates that payload and runs the battle-tested bash scripts
 against it.
 """
@@ -35,6 +35,7 @@ def main():
     sub.add_parser("install", help="install/refresh the kit into $CODEX_HOME (idempotent, backs everything up)")
     sub.add_parser("uninstall", help="remove exactly what install added")
     sub.add_parser("path", help="print the bundled payload directory")
+    sub.add_parser("skill-path", help="print the portable OpenClaw/Codex skill directory")
     sub.add_parser("version", help="print the overcodex version")
     args = ap.parse_args()
 
@@ -45,6 +46,12 @@ def main():
     if args.cmd == "path":
         print(_payload_dir())
         return
+    if args.cmd == "skill-path":
+        path = os.path.join(_payload_dir(), "skill", "overcodex-ultracode")
+        if not os.path.isfile(os.path.join(path, "SKILL.md")):
+            sys.exit("overcodex: bundled portable skill is missing — reinstall the package")
+        print(path)
+        return
     if args.cmd == "version":
         print(pkg_version("overcodex"))
 

{overcodex-0.1.0 → overcodex-0.2.0}/uninstall.sh

@@ -25,6 +25,8 @@ ZSH_BEGIN='# --- overcodex integration (begin) ---'
 ZSH_END='# --- overcodex integration (end) ---'
 HOOKS_BEGIN='# --- overcodex hooks (begin) ---'
 HOOKS_END='# --- overcodex hooks (end) ---'
+AGENT_ROLES_BEGIN='# --- overcodex agent roles (begin) ---'
+AGENT_ROLES_END='# --- overcodex agent roles (end) ---'
 SL_BEGIN='# --- overcodex statusline (begin) ---'
 SL_END='# --- overcodex statusline (end) ---'
 
@@ -107,23 +109,35 @@ for p in "$SCRIPT_DIR"/prompts/*.md; do
   fi
 done
 
+# Custom agent definitions (by the names shipped in the kit).
+for a in "$SCRIPT_DIR"/agents/*.toml; do
+  [ -f "$a" ] || continue
+  dest="$CODEX_HOME/agents/$(basename "$a")"
+  if [ -f "$dest" ]; then
+    rm -f "$dest" && note_did "removed $dest" || note_warn "could not remove $dest"
+  else
+    note_skip "not present: $dest"
+  fi
+done
+
 # Prune now-empty kit dirs (never touch anything non-empty).
-for d in "$CODEX_HOME/hooks" "$CODEX_HOME/prompts"; do
+for d in "$CODEX_HOME/hooks" "$CODEX_HOME/prompts" "$CODEX_HOME/agents"; do
   [ -d "$d" ] && rmdir "$d" 2>/dev/null && note_did "removed empty dir $d"
 done
 echo
 
 # ---------------------------------------------------------------------------
-# 2. config.toml — remove ONLY our marker blocks (hooks + status_line).
+# 2. config.toml — remove ONLY our marker blocks (hooks + agent roles + status_line).
 # ---------------------------------------------------------------------------
 echo "-- config.toml --"
 if [ ! -f "$CONFIG_TOML" ]; then
   note_skip "no config.toml"
 else
-  HAS_HOOKS=no; HAS_SL=no
+  HAS_HOOKS=no; HAS_AGENT_ROLES=no; HAS_SL=no
   grep -qF "$HOOKS_BEGIN" "$CONFIG_TOML" && HAS_HOOKS=yes
+  grep -qF "$AGENT_ROLES_BEGIN" "$CONFIG_TOML" && HAS_AGENT_ROLES=yes
   grep -qF "$SL_BEGIN"    "$CONFIG_TOML" && HAS_SL=yes
-  if [ "$HAS_HOOKS" = no ] && [ "$HAS_SL" = no ]; then
+  if [ "$HAS_HOOKS" = no ] && [ "$HAS_AGENT_ROLES" = no ] && [ "$HAS_SL" = no ]; then
     note_skip "config.toml has no overcodex blocks (no change)"
   else
     b=$(backup_file "$CONFIG_TOML")
@@ -133,12 +147,17 @@ else
       strip_block "$tmp" "$HOOKS_BEGIN" "$HOOKS_END" > "$tmp.2" && mv "$tmp.2" "$tmp" \
         || die "could not strip hooks block"
     fi
+    if [ "$HAS_AGENT_ROLES" = yes ]; then
+      strip_block "$tmp" "$AGENT_ROLES_BEGIN" "$AGENT_ROLES_END" > "$tmp.2" && mv "$tmp.2" "$tmp" \
+        || die "could not strip agent roles block"
+    fi
     if [ "$HAS_SL" = yes ]; then
       strip_block "$tmp" "$SL_BEGIN" "$SL_END" > "$tmp.2" && mv "$tmp.2" "$tmp" \
         || die "could not strip status_line block"
     fi
     mv "$tmp" "$CONFIG_TOML" || die "could not write $CONFIG_TOML"
     [ "$HAS_HOOKS" = yes ] && note_did "removed hooks block from config.toml (backup: $b)"
+    [ "$HAS_AGENT_ROLES" = yes ] && note_did "removed custom agent roles block from config.toml (backup: $b)"
     [ "$HAS_SL" = yes ]    && note_did "removed [tui].status_line block from config.toml (backup: $b)"
   fi
 fi

overcodex-0.1.0/codex/AGENTS-ULTRACODE.md

@@ -1,54 +0,0 @@
-# --- overcodex ultracode (begin) ---
-# ULTRACODE.md — Model & Effort Routing for Codex (v2-codex, ported 2026-07 from the Claude Code ULTRACODE v2)
-
-## 1. Core principle
-Spend the flagship tier only where judgment is the bottleneck, never where volume is. `model_reasoning_effort` and any per-role `model` override that you omit silently inherits the top-level `model` (currently `gpt-5.6-sol` — the flagship). Explicit down-routing is your default posture, not an optimization.
-Route each subagent/role by one question: "if this is quietly wrong, who catches it?" — a downstream check means you may downgrade; nobody means top tier.
-
-## 2. Tier map (GPT-5.6 family, mid-2026)
-Codex's current lineup is three permanent price/capability tiers, not a Claude-style haiku/sonnet/opus/apex ladder — treat them as the equivalent rungs:
-
-| Rung | Codex tier | Claude-side equivalent | Use for |
-|---|---|---|---|
-| 1 (cheap/fast) | **Luna** | haiku | scouting, file listing, mechanical transforms, fixed-schema extraction |
-| 2 (mid) | **Terra** | sonnet | finder sweeps, well-scoped implementation edits, bulk reading of dense code |
-| 3 (flagship) | **Sol** | opus | security sweeps, cross-cutting edits, adversarial verification, judge panels, completeness critics |
-| 3 + effort ceiling | **Sol @ high** (or the Max reasoning-effort / Ultra sub-agent mode where the deployment exposes it) | fable/apex | terminal judge, final synthesis, subtle-correctness verdicts |
-
-Effort is the second axis: `model_reasoning_effort = low \| medium \| high` (config.toml or `--config`). Pair rung × effort the same way ULTRACODE always has:
-- Rung 1 → low. Rung 2 → medium. Rung 3 → high. Terminal/apex → Sol @ high, plus Max/Ultra if the account has it — never below Sol.
-- Effort amplifies capability, it never substitutes: Luna@high loses to Terra@medium on judgment work. Never pair a high-effort setting with a fan-out stage.
-
-## 3. Routing surface (how to actually pin a tier per subagent)
-Codex's per-subagent override surface is younger than Claude Code's Task-tool `model` param — there is no first-class "one dispatch call, one model" primitive yet. Use what exists, and state the gap honestly where it doesn't:
-- **`[agents]` table (`AgentRoleToml` per role)** in config.toml — the closest analog to Claude's per-agent `model`. Give each role you define (scout, finder, verifier, judge) its own `model` + `model_reasoning_effort` entry. This is the primary lever; use it whenever the orchestrator supports role-scoped agents.
-- **`profiles`** (`codex --profile <name>`) — a named bundle of `model` + `model_reasoning_effort` (+ sandbox/approval settings). Define one profile per rung (e.g. `scout`, `implement`, `verify`, `apex`) and invoke the right profile per stage instead of editing global config mid-session.
-- **`orchestrator.max_threads` / `max_depth`** — the fan-out width and recursion-depth knobs. Set `max_threads` to match the routing-lint width rule below (wide stages get width, not tier); use `max_depth` to cap runaway recursive sub-agent spawning, which is the Codex-side proxy for "never two agents editing the same files."
-- **Where enforcement is weak** (no live per-call model override mid-session, no schema-typed subagent handoff): the orchestrating model itself must apply the routing table by discipline — choosing the right profile/role before dispatch — because the harness will not silently downgrade or refuse an unrouted call the way a stricter per-call API might. Say so in-session rather than assuming the harness caught it.
-
-## 4. Hard guardrails (unchanged from v2, ported verbatim)
-Never downgrade below floor:
-- Final synthesis and any output the user sees with no downstream check: Sol, never below. Terminal stage = apex profile, or Sol@high with Max/Ultra if available.
-- Adversarial verification, judge panels, security verdicts, completeness critics: Sol floor. A false CONFIRM ends scrutiny.
-- Subtle-correctness verdicts (concurrency, auth/crypto, money math, migrations): apex — "looks correct" and "is correct" diverge most here.
-
-Verification order: where an OBJECTIVE check exists (tests, typecheck, lint, a numeric answer), gate on it via `codex exec` + shell BEFORE spending an LLM verifier. A passing test outranks an LLM CONFIRM. For fuzzy deliverables with no automatic check, buy a stronger generator, not a weak-generator-plus-judge pipeline.
-
-Escalation rule: every finder/verifier role emits `verdict`/`confidence`/`evidence` (approximate via prompt contract — Codex has no first-class typed `schema` param yet, so state the required shape in the prompt and treat a response missing any field as low confidence). Re-run once at the next rung up on confidence < 0.7, UNSURE, empty/malformed output, or contradiction between parallel roles. Escalation target must be ≥ generator's rung. Escalation has a ceiling too: >1-in-4 downgraded stages escalating means the routing was miscalibrated — stop and re-profile, don't silently run everything on Sol.
-
-Panels: 2–3 voters with distinct lenses (correctness / security / reproduces-it), never N identical-role repeats. Unanimous → accept; split → one apex adjudicator; never majority-vote or average.
-
-Budget pressure: cut `max_threads` / batch more files per role first; floors are the last thing to fall. Treat the apex rung as a read-only reserve (usually synthesis only). If budget can't cover the apex/Sol terminal stages, say so and propose the cut — never silently ship a downgraded final answer.
-
-## 5. Routing lint (pre-flight, fix before dispatch)
-1. Every role/profile has an explicit `model` + `model_reasoning_effort`, or the omission is a deliberate apex spend (inherits top-level `model`). More than 2 omissions = under-routing.
-2. No wide/parallel role runs on Sol@high or inherits the apex profile; bulk roles sit at Luna/Terra regardless of the rest of the routing.
-3. Verifiers, judges, synthesis are at their floors even under budget pressure; `max_depth` prevents two roles editing the same files concurrently.
-4. Every downgraded trusted-adjacent stage has a stated escalation trigger, and an objective check (test/lint/typecheck via shell) gates before any LLM verifier where one exists.
-5. Every role's prompt states an objective + expected output shape + scope boundary vs sibling roles — Codex has no schema enforcement, so the prompt IS the contract.
-6. A stage is justified only if it accesses information the prior stage couldn't (new tool call, test run, independent read). A stage that reformats an upstream conclusion is overhead — collapse it into one higher-effort call.
-7. Profile/role names embed the tier (e.g. `verify-sol-high`), so a session log shows the routing without opening config.toml.
-
-## 6. Scope
-This table binds any one-off `codex exec` dispatch too, not just multi-agent orchestrator runs: a lone bulk-reading call is still a Luna/Terra job; a lone terminal judgment still earns Sol@high or a deliberate apex inheritance. Absence of `[agents]`/`orchestrator` config does not relax the discipline — apply it by hand via `--profile` and `--config model_reasoning_effort=`.
-# --- overcodex ultracode (end) ---