overcodex

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

codex-swap work         # register/list accounts, then switch — restart required
/prompts:handoff        # package this session's state, 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
codex-swap add personal    # then log in to each: CODEX_HOME=~/.codex-accounts/work codex login
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 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.

# 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 <account> points the shell at that directory and tells you to restart. 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.

/prompts:handoff — escape context bloat, keep the thread

flowchart LR
    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]
    E --> F[SessionStart hook injects the package on next launch]
    F --> G[Fresh session, ctx near zero]
    G --> A

You lose the token bloat, not the thread. Combine with a codex-swap restart 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. 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.

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 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.

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

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

Or skip memorizing and paste a prompt:

How it fits together

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

./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

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.