overcodex

Codex CLI, overclocked. Cold-switch between Codex accounts, hand off to a fresh session with the $handoff skill before context fills up, watch usage on the native footer, and route multi-agent work with an AGENTS.md policy:

codex-swap use work     # register/list accounts, then switch — restart required
$handoff                # (inside Codex) package this session, resume fresh next launch

native footer: model with reasoning | current directory | project name | context remaining | 5h limit | weekly limit

Install

pipx install overcodex && overcodex install

Fresh machine? If you get command not found: overcodex, pipx's bin folder isn't on your PATH yet — run pipx ensurepath && source ~/.zshrc, then overcodex install. (Use source, not exec zsh: replacing the shell swallows any commands you pasted after it.)

Then register your accounts (once, per account):

codex-swap add work        # creates an isolated account home + links shared config, skills, hooks
codex-swap add personal    # then log in to each: CODEX_HOME=~/.codex-accounts/work codex login
codex-swap use work        # cold switch: only writes the ~/.codex-accounts/.active marker
                           # (shorthand: codex-swap work) — then start a new codex

One manual step: trust the hooks (once per account)

Codex runs a hook only after you trust it. Start a new Codex session; when Codex shows "Hooks need review", choose "Trust all and continue" (or inspect them first with /hooks). Codex keys that trust by config path (<config path>:<event>:<group>:<handler>, path not canonicalized), so every codex-swap account — ~/.codex-accounts/<name>/config.toml is a different path even though it is a symlink to the shared file — asks once on its own. Any change to a hook's definition (an upgrade that changes the hooks block says so) asks again. overcodex doctor lists each account's hook trust status.

Then confirm the native footer shows the configured fields (Codex may omit unavailable usage-limit fields), and type $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.

# uv
uv tool install overcodex && overcodex install

# from source
git clone https://github.com/arthur-bump-pm/overcodex && cd overcodex && ./install.sh

What you get

codex-swap — cold account switching

Each account gets its own isolated CODEX_HOME (a separate auth.json, never a copied/overwritten one — refresh tokens can be single-use across copies, so isolation is the only safe design). codex-swap use <account> only records which account is active (~/.codex-accounts/.active); the codex() shell wrapper passes that account's home to each new codex process (CODEX_HOME=… command codex, never exported into your shell, and your own CODEX_HOME is left alone when no account is active). This is a cold switch: any Codex session already running keeps its old credentials until you quit and relaunch it. There is no hot mid-session swap here — if you need that, it's overclaude's /swap for Claude Code, not this.

$handoff — escape context bloat, keep the thread

Codex 0.158 removed /prompts:* custom prompts, so the handoff flow ships as Codex skills in $CODEX_HOME/skills/ (shared into every codex-swap account). Invoke one by typing its $ mention anywhere in your message — $handoff, or $handoff now please — or browse them with /skills.

flowchart LR
    A[Context fills up] --> B[Hook offers a handoff at 60/75/85%]
    B --> C[You type $handoff]
    C --> D[Codex packages goals, state, next steps]
    D --> E[You exit and relaunch codex in the same directory]
    E --> F[SessionStart hook injects the package]
    F --> G[Fresh session, ctx near zero]
    G --> A

You lose the token bloat, not the thread. The package format (header line, 12-hex sha256-of-cwd file name, 10-minute window) is byte-compatible with overclaude: $handoff-claude hands the work to Claude Code, and overclaude's /handoff codex hands it back. Combine with codex-swap use <name> before relaunching when you're also switching accounts.

Statusline

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 (an inline tui = { … } table is left alone with a warning). 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, type $ultracode followed by 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.

The detailed agent-facing activation contract is in 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 the test suite, then report the restart and hook-trust steps.

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.

Models and reasoning effort. Codex's model catalog (as of Codex 0.158) defaults to gpt-6-astra. Every listed model accepts low, medium, high, and xhigh; max is also available on GPT-6 Astra/Sol/Luna and GPT-5.6 Sol/Terra/Luna; ultra only on gpt-6-astra, gpt-6-sol, gpt-5.6-sol, and gpt-5.6-terra (not on Luna models; the legacy gpt-5.5 stops at xhigh). No model accepts none as an effort. The bundled judge uses the portable xhigh; reserve max/ultra for a quality-critical adjudication on a model that lists it. Installing overcodex does not replace your existing model or effort preference.

Hooks + skills

SessionStart (matcher = "startup", additionalContextLimit = 8000 so a handoff package is not spilled/middle-truncated) / UserPromptSubmit / Stop / PreCompact hooks, wired via a marker-wrapped [hooks] block at the end of config.toml, plus five skills under $CODEX_HOME/skills/<name>/SKILL.md for the handoff flow and explicit multi-agent runs.

Cheat sheet

Or skip memorizing and paste a prompt:

How it fits together

flowchart TD
    AH[AGENTS.md routing policy] --> HK[config.toml hooks block: SessionStart/UserPromptSubmit/Stop/PreCompact]
    HK --> TR[Trusted once per account]
    TR --> SK[$handoff and friends: skills in CODEX_HOME/skills]
    SK --> CS[codex-swap: isolated CODEX_HOME per account]
    CS --> RS[Cold restart adopts the new account]
    SL[Native footer: context-remaining + available usage limits] --> SK
    HK --> RW[Hooks read rollout data for handoff warnings]
    RW --> SK

./tests/run.sh       # full suite in throwaway $HOMEs (also drives `codex app-server` when codex is installed)
./sync.sh            # live setup -> repo: scrub-gated diff, commit, push
./sync.sh --release  # + release gate (shellcheck + tests), version bump unless already ahead, GitHub release -> PyPI
./sync.sh --dry-run  # preview either

Versions

Credits

overcodex is the Codex CLI sibling of 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 — 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_HOMEs where tokens never move. If OpenAI ships auth live-reload upstream, codex-swap grows hot for free.

License

MIT — see LICENSE.