overcodex 0.1.0__py3-none-any.whl

overcodex/__init__.py

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

overcodex/cli.py

@@ -0,0 +1,53 @@
+"""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
+CLI just locates that payload and runs the battle-tested bash scripts
+against it.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+from importlib.metadata import version as pkg_version
+from importlib.resources import files
+
+
+def _payload_dir():
+    p = files("overcodex").joinpath("payload")
+    path = str(p)
+    if not os.path.isdir(path) or not os.path.isfile(os.path.join(path, "install.sh")):
+        sys.exit("overcodex: bundled payload is missing — broken install; reinstall the package")
+    return path
+
+
+def _run_script(name):
+    return subprocess.call(["bash", os.path.join(_payload_dir(), name)])
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        prog="overcodex",
+        description="Codex CLI, overclocked — codex-swap, hooks, statusline, AGENTS.md routing.",
+    )
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    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("version", help="print the overcodex version")
+    args = ap.parse_args()
+
+    if args.cmd == "install":
+        sys.exit(_run_script("install.sh"))
+    if args.cmd == "uninstall":
+        sys.exit(_run_script("uninstall.sh"))
+    if args.cmd == "path":
+        print(_payload_dir())
+        return
+    if args.cmd == "version":
+        print(pkg_version("overcodex"))
+
+
+if __name__ == "__main__":
+    main()

overcodex/payload/bin/codex-swap

@@ -0,0 +1,320 @@
+#!/usr/bin/env bash
+# codex-swap — cold multi-account manager for the Codex CLI.
+#
+# Design: CODEX_HOME-per-account isolation. Codex refresh tokens can be
+# single-use across COPIES of auth.json, so accounts are never created by
+# copying credentials — each account gets its own real $CODEX_HOME directory
+# under ~/.codex-accounts/<name>/ and logs in there directly. This is a COLD
+# switch by design: a running `codex` process reads its credentials once at
+# startup, so switching the active account never affects sessions already
+# running — only new `codex` invocations (via the codex() shell wrapper) pick
+# it up. There is no hot-swap here; that's a different kit's trick.
+#
+# Layout:
+#   ~/.codex                    the PRIMARY account (name: "primary", implicit,
+#                                never created/removed by this tool)
+#   ~/.codex-accounts/<name>/   one directory per additional account
+#   ~/.codex-accounts/.active   one line: the active account name (or absent /
+#                                "primary" for the default)
+#
+# Per account, "add" symlinks the SHARED config in from the primary home
+# (AGENTS.md, prompts/, hooks/, hooks.json, config.toml) so every account
+# runs the same routing/hooks setup. auth.json and all session/thread state
+# are always per-account: real files, never symlinked, never copied.
+#
+# Subcommands:
+#   add <name>              create (or repair) an account, linking shared config
+#   list [--json]           accounts, which is active, login state
+#   use <name|primary>      set the active-account marker (cold switch)
+#   which                   print the active account name + its CODEX_HOME
+#   remove <name> [--yes]   delete an account (never removes primary)
+set -u
+
+HOME_DIR="${HOME:?codex-swap: \$HOME is not set}"
+PRIMARY_HOME="$HOME_DIR/.codex"
+ACCOUNTS_ROOT="$HOME_DIR/.codex-accounts"
+ACTIVE_FILE="$ACCOUNTS_ROOT/.active"
+PRIMARY_LABEL="primary"
+
+# Shared across every account (symlinked from the primary home by `add`).
+SHARED_ITEMS="AGENTS.md prompts hooks hooks.json config.toml"
+
+usage() {
+  cat >&2 <<'EOF'
+usage: codex-swap <subcommand> [args]
+  add <name>              create/repair an account under ~/.codex-accounts/<name>
+                          (symlinks shared config from primary; prints login steps)
+  list [--json]           accounts + active marker + login state
+  use <name|primary>      set the active account marker (cold switch — restart
+                          running codex sessions to adopt it)
+  which                   print the active account name and its CODEX_HOME
+  remove <name> [--yes]   delete an account's directory (never removes primary)
+
+"primary" always refers to the default $HOME/.codex and is never created,
+listed as a file, or removable — it's the account you get with no marker set.
+EOF
+  exit 2
+}
+
+die() { echo "codex-swap: $1" >&2; exit 1; }
+
+charset_ok() {
+  case "$1" in
+    '') return 1 ;;
+    *[!A-Za-z0-9_-]*) return 1 ;;
+    *) return 0 ;;
+  esac
+}
+
+home_for() {
+  if [ "$1" = "$PRIMARY_LABEL" ]; then
+    printf '%s\n' "$PRIMARY_HOME"
+  else
+    printf '%s\n' "$ACCOUNTS_ROOT/$1"
+  fi
+}
+
+active_name() {
+  local n=""
+  if [ -f "$ACTIVE_FILE" ]; then
+    n="$(tr -d '[:space:]' <"$ACTIVE_FILE" 2>/dev/null)"
+  fi
+  [ -n "$n" ] || n="$PRIMARY_LABEL"
+  printf '%s\n' "$n"
+}
+
+# human_age <epoch-seconds> — coarse relative-time string.
+human_age() {
+  local mtime="$1" now diff
+  case "$mtime" in ''|*[!0-9]*) printf 'unknown age\n'; return 0 ;; esac
+  now="$(date +%s)"
+  diff=$(( now - mtime ))
+  [ "$diff" -ge 0 ] || diff=0
+  if   [ "$diff" -lt 60 ];    then printf '%ss ago\n'  "$diff"
+  elif [ "$diff" -lt 3600 ];  then printf '%sm ago\n'  $(( diff / 60 ))
+  elif [ "$diff" -lt 86400 ]; then printf '%sh ago\n'  $(( diff / 3600 ))
+  else                             printf '%sd ago\n'  $(( diff / 86400 ))
+  fi
+}
+
+# auth_status <codex_home> — one-line login state for the account.
+auth_status() {
+  local ch="$1" f mtime
+  f="$ch/auth.json"
+  if [ -f "$f" ]; then
+    mtime="$(stat -f %m "$f" 2>/dev/null)" || mtime=""
+    printf 'logged in (auth.json %s)\n' "$(human_age "$mtime")"
+  else
+    printf 'not logged in (no auth.json)\n'
+  fi
+}
+
+# all_account_names — "primary" then every dir under ACCOUNTS_ROOT, one per line.
+all_account_names() {
+  printf '%s\n' "$PRIMARY_LABEL"
+  [ -d "$ACCOUNTS_ROOT" ] || return 0
+  local d n
+  for d in "$ACCOUNTS_ROOT"/*/; do
+    [ -d "$d" ] || continue
+    n="$(basename "$d")"
+    printf '%s\n' "$n"
+  done
+}
+
+cmd_add() {
+  local name="${1:-}" acc_dir is_new item src dst
+  [ -n "$name" ] || { echo "usage: codex-swap add <name>" >&2; exit 2; }
+  charset_ok "$name" || die "invalid name '$name' — use letters, digits, - and _ only"
+  [ "$name" != "$PRIMARY_LABEL" ] || die "'$PRIMARY_LABEL' is reserved for \$CODEX_HOME ($PRIMARY_HOME) — pick another name"
+
+  [ -d "$PRIMARY_HOME" ] || echo "codex-swap: warning: primary CODEX_HOME ($PRIMARY_HOME) does not exist yet — shared items will be skipped" >&2
+
+  acc_dir="$ACCOUNTS_ROOT/$name"
+  is_new=1
+  [ -d "$acc_dir" ] && is_new=0
+  mkdir -p "$acc_dir" || die "could not create $acc_dir"
+
+  echo "== codex-swap add $name =="
+  echo "  account home: $acc_dir"
+  for item in $SHARED_ITEMS; do
+    src="$PRIMARY_HOME/$item"
+    dst="$acc_dir/$item"
+    if [ -e "$dst" ] || [ -L "$dst" ]; then
+      if [ -L "$dst" ] && [ "$(readlink "$dst")" = "$src" ]; then
+        echo "  [=] already linked: $item"
+      else
+        echo "  [!] leaving as-is (exists, not our symlink): $item" >&2
+      fi
+      continue
+    fi
+    if [ -e "$src" ]; then
+      if ln -s "$src" "$dst" 2>/dev/null; then
+        echo "  [+] linked: $item -> $src"
+      else
+        echo "  [!] failed to link: $item" >&2
+      fi
+    else
+      echo "  [-] skip (not present in primary yet): $item"
+    fi
+  done
+
+  echo
+  if [ "$is_new" -eq 1 ]; then
+    echo "Created account '$name'. auth.json and session state are per-account (never shared, never copied)."
+  else
+    echo "Account '$name' already existed — repaired missing shared symlinks only (auth.json/session state untouched)."
+  fi
+  echo
+  echo "Next steps:"
+  echo "  1. One-off login for this account (does not touch primary or the active marker):"
+  echo "       CODEX_HOME=\"$acc_dir\" codex login"
+  echo "  2. Make it the active account for the codex() shell wrapper:"
+  echo "       codex-swap use $name"
+  echo "     Then open a NEW terminal/tab (or: exec zsh) — this is a cold switch, running"
+  echo "     codex sessions keep whatever account they started with."
+  echo
+  echo "Caveat: config.toml is shared by symlink. If it sets an ABSOLUTE sqlite_home or"
+  echo "log path, that storage would be shared too — keep such paths relative (the"
+  echo "default) so each account's session state actually stays separate."
+  exit 0
+}
+
+cmd_list() {
+  local as_json=no n ch mark login
+  case "${1:-}" in
+    --json) as_json=yes ;;
+    "") ;;
+    *) echo "usage: codex-swap list [--json]" >&2; exit 2 ;;
+  esac
+
+  local active; active="$(active_name)"
+
+  if [ "$as_json" = yes ]; then
+    printf '['
+    local first=1
+    while IFS= read -r n; do
+      [ -n "$n" ] || continue
+      ch="$(home_for "$n")"
+      login=false
+      [ -f "$ch/auth.json" ] && login=true
+      [ "$first" -eq 1 ] || printf ','
+      printf '{"name":"%s","codexHome":"%s","active":%s,"loggedIn":%s}' \
+        "$n" "$ch" "$([ "$n" = "$active" ] && echo true || echo false)" "$login"
+      first=0
+    done <<EOF
+$(all_account_names)
+EOF
+    printf ']\n'
+    exit 0
+  fi
+
+  printf '%-2s %-20s %-10s\n' "" "NAME" "STATE"
+  while IFS= read -r n; do
+    [ -n "$n" ] || continue
+    ch="$(home_for "$n")"
+    mark=" "
+    [ "$n" = "$active" ] && mark="*"
+    printf '%-2s %-20s %s\n' "$mark" "$n" "$(auth_status "$ch")"
+    printf '   %-20s %s\n' "" "$ch"
+  done <<EOF
+$(all_account_names)
+EOF
+  echo
+  echo "* = active for the codex() shell wrapper (cold switch — see 'codex-swap which')"
+  exit 0
+}
+
+cmd_use() {
+  local name="${1:-}"
+  [ -n "$name" ] || { echo "usage: codex-swap use <name|primary>" >&2; exit 2; }
+  if [ "$name" != "$PRIMARY_LABEL" ]; then
+    charset_ok "$name" || die "invalid name '$name'"
+    [ -d "$ACCOUNTS_ROOT/$name" ] || die "no such account '$name' (see: codex-swap list)"
+  fi
+
+  mkdir -p "$ACCOUNTS_ROOT" || die "could not create $ACCOUNTS_ROOT"
+  local tmp="$ACTIVE_FILE.tmp.$$"
+  if printf '%s\n' "$name" >"$tmp" 2>/dev/null && mv "$tmp" "$ACTIVE_FILE" 2>/dev/null; then
+    echo "Active account set to '$name' ($(home_for "$name"))."
+    echo "Cold switch: any ALREADY-RUNNING codex session keeps its old account until"
+    echo "restarted. Open a new terminal/tab (or: exec zsh) and start a fresh 'codex'."
+    exit 0
+  fi
+  rm -f "$tmp" 2>/dev/null
+  die "failed to write active marker $ACTIVE_FILE"
+}
+
+cmd_which() {
+  local n ch
+  n="$(active_name)"
+  ch="$(home_for "$n")"
+  echo "$n"
+  echo "  CODEX_HOME: $ch"
+  echo "  $(auth_status "$ch")"
+  exit 0
+}
+
+cmd_remove() {
+  local name="${1:-}" confirm_yes=no acc_dir reply
+  [ -n "$name" ] || { echo "usage: codex-swap remove <name> [--yes]" >&2; exit 2; }
+  shift 2>/dev/null || true
+  while [ $# -gt 0 ]; do
+    case "$1" in --yes|-y) confirm_yes=yes ;; esac
+    shift
+  done
+
+  [ "$name" != "$PRIMARY_LABEL" ] || die "refusing to remove '$PRIMARY_LABEL' (\$CODEX_HOME, $PRIMARY_HOME)"
+  charset_ok "$name" || die "invalid name '$name'"
+  acc_dir="$ACCOUNTS_ROOT/$name"
+  [ -d "$acc_dir" ] || die "no such account '$name' (see: codex-swap list)"
+  # Defense in depth: never rm -rf outside ACCOUNTS_ROOT even though the
+  # charset check above already makes escaping the directory impossible.
+  case "$acc_dir" in
+    "$ACCOUNTS_ROOT"/*) : ;;
+    *) die "refusing to remove path outside $ACCOUNTS_ROOT: $acc_dir" ;;
+  esac
+
+  if [ "$confirm_yes" != yes ]; then
+    if [ -t 0 ]; then
+      printf "This deletes %s — including its auth.json and session state. Type the account name to confirm: " "$acc_dir"
+      read -r reply
+      [ "$reply" = "$name" ] || die "confirmation did not match — aborted, nothing removed"
+    else
+      die "remove requires --yes when not run interactively"
+    fi
+  fi
+
+  rm -rf "$acc_dir" || die "failed to remove $acc_dir"
+  echo "Removed account '$name' ($acc_dir)."
+
+  if [ "$(active_name)" = "$name" ]; then
+    rm -f "$ACTIVE_FILE" 2>/dev/null
+    echo "It was the active account — active account reset to '$PRIMARY_LABEL'."
+    echo "Cold switch: restart running codex sessions to adopt this."
+  fi
+  exit 0
+}
+
+main() {
+  local sub="${1:-}"
+  [ $# -gt 0 ] && shift
+  case "$sub" in
+    add)    cmd_add "$@" ;;
+    list)   cmd_list "$@" ;;
+    use)    cmd_use "$@" ;;
+    which)  cmd_which "$@" ;;
+    remove) cmd_remove "$@" ;;
+    -h|--help|help|"") usage ;;
+    *)
+      # Bare account name convenience: `codex-swap work` == `codex-swap use work`.
+      if [ -d "$ACCOUNTS_ROOT/$sub" ]; then
+        cmd_use "$sub"
+      else
+        echo "codex-swap: unknown subcommand or account '$sub'" >&2; usage
+      fi ;;
+  esac
+}
+
+if [ "${BASH_SOURCE[0]:-}" = "$0" ]; then
+  main "$@"
+fi

overcodex/payload/codex/AGENTS-ULTRACODE.md

@@ -0,0 +1,54 @@
+# --- 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) ---

overcodex/payload/config/hooks-block.toml.tpl

@@ -0,0 +1,42 @@
+# overcodex hook wiring — TOML fragment. install.sh substitutes @HOOKS_DIR@
+# with the resolved absolute $CODEX_HOME/hooks and appends the result between
+# marker comments at the END of config.toml (a [hooks] table cannot be
+# prepended: it would capture every top-level key that follows it).
+#
+# Shape provenance (codex-cli 0.144.5, reconstructed from the binary's
+# embedded types — no public docs exist for this surface as of this writing):
+#   HookEventsToml: PascalCase event keys (PreToolUse, PermissionRequest,
+#   PostToolUse, PreCompact, PostCompact, SessionStart, UserPromptSubmit,
+#   SubagentStart, SubagentStop, Stop); each event holds an ARRAY of matcher
+#   groups (ConfiguredHookMatcherGroup: matcher?, hooks[]).
+#   Handlers: internally tagged HookHandlerConfig::Command with fields
+#   type / command / commandWindows / timeout / async / statusMessage
+#   (`timeout`, NOT the app-server wire name `timeoutSec`).
+#   `matcher` semantics for non-tool events are unconfirmed — omitted here;
+#   each script filters on its own payload fields instead.
+# FLAG FOR LIVE VALIDATION: if codex warns on config load, check its
+# configWarning output first — the shape above is inferred, not documented.
+
+[[hooks.SessionStart]]
+[[hooks.SessionStart.hooks]]
+type = "command"
+command = "bash @HOOKS_DIR@/overcodex-handoff-inject.sh"
+timeout = 10
+
+[[hooks.UserPromptSubmit]]
+[[hooks.UserPromptSubmit.hooks]]
+type = "command"
+command = "bash @HOOKS_DIR@/overcodex-ctx-watch.sh"
+timeout = 5
+
+[[hooks.Stop]]
+[[hooks.Stop.hooks]]
+type = "command"
+command = "bash @HOOKS_DIR@/overcodex-notify.sh"
+timeout = 5
+
+[[hooks.PreCompact]]
+[[hooks.PreCompact.hooks]]
+type = "command"
+command = "bash @HOOKS_DIR@/overcodex-precompact-offer.sh"
+timeout = 5

overcodex/payload/hooks/overcodex-ctx-lib.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# overcodex-ctx-lib.sh — shared helper, sourced by overcodex-ctx-watch.sh,
+# overcodex-notify.sh and overcodex-precompact-offer.sh. Not a hook itself
+# (no shebang execution expected; hooks.json never references this file).
+#
+# Codex hook stdin carries NO context-usage percentage (verified: none of the
+# ten hook input JSON Schemas embedded in the codex-cli 0.144.5 binary —
+# PreToolUse/PermissionRequest/PostToolUse/PreCompact/PostCompact/SessionStart/
+# UserPromptSubmit/SubagentStart/SubagentStop/Stop — carry a token or context
+# field). There is also no custom-command statusline relay available: Codex's
+# `tui.status_line` only lists built-in item names (run state, ctx/limits
+# meters) — unlike Claude Code's statusline, it is not an external command fed
+# rich JSON, so there is nothing analogous to overclaude's
+# statusline-command.sh relay-file trick to piggyback on.
+#
+# What IS available: every hook payload with a `transcript_path` field points
+# at the session's rollout JSONL file
+# ($CODEX_HOME/sessions/YYYY/MM/DD/rollout-<ts>-<thread-id>.jsonl, confirmed by
+# direct inspection of a real rollout in this sandbox — never modified, only
+# read). Codex periodically appends a line shaped like:
+#   {"timestamp":"...","type":"event_msg",
+#    "payload":{"type":"token_count",
+#      "info":{"total_token_usage":{"...","total_tokens":N},
+#              "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.
+#
+# 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
+# zero) it prints nothing and returns 1. Callers must treat a non-zero return
+# as "context usage unknown right now" and silently skip, never error.
+exec 2>/dev/null
+
+# Only scan the last N bytes of the rollout for performance/safety on very
+# long sessions (rollouts can grow to many MB; a full-file grep on every
+# UserPromptSubmit would add up). Falls back to a full-file scan on the rare
+# chance the last token_count line is further back than the tail window (e.g.
+# immediately followed by a very large function_call_output).
+OVERCODEX_CTX_TAIL_BYTES=${OVERCODEX_CTX_TAIL_BYTES:-2000000}
+
+ctx_pct_from_transcript() {
+    tp="${1:-}"
+    [ -n "$tp" ] && [ "$tp" != "null" ] && [ -f "$tp" ] || return 1
+    command -v jq >/dev/null 2>&1 || return 1
+
+    line="$(tail -c "$OVERCODEX_CTX_TAIL_BYTES" "$tp" 2>/dev/null | grep -a '"type":"token_count"' | tail -n 1)"
+    if [ -z "$line" ]; then
+        line="$(grep -a '"type":"token_count"' "$tp" 2>/dev/null | tail -n 1)"
+    fi
+    [ -n "$line" ] || return 1
+
+    total="$(printf '%s' "$line" | jq -r '.payload.info.total_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
+    case "$window" in ''|*[!0-9]*) return 1 ;; esac
+    [ "$window" -gt 0 ] || return 1
+
+    awk -v t="$total" -v w="$window" 'BEGIN { printf "%d", (t / w) * 100 }'
+}

overcodex/payload/hooks/overcodex-ctx-watch.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# overcodex-ctx-watch.sh — Codex UserPromptSubmit hook.
+# Ported from overclaude's hooks/ctx-watch.sh. Computes context usage from the
+# session's rollout transcript (see overcodex-ctx-lib.sh for why: Codex hook
+# stdin carries no context percentage and there is no statusline relay to
+# piggyback on) and, when usage crosses a new threshold, injects a
+# handoff-offer note into the turn via hookSpecificOutput.additionalContext.
+# Contract: always exit 0, silent on every error path, defensive jq parsing,
+# no state writes on the /handoff skip path.
+exec 2>/dev/null
+set -u
+
+HOOKS_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)" || exit 0
+# shellcheck source=./overcodex-ctx-lib.sh
+. "$HOOKS_DIR/overcodex-ctx-lib.sh" 2>/dev/null || exit 0
+
+# Thresholds (contract: variables at top).
+T1=60
+T2=75
+T3=85
+
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+CTX_DIR="$CODEX_HOME/overcodex/ctx"
+
+INPUT="$(cat)" || INPUT=""
+command -v jq >/dev/null 2>&1 || exit 0
+
+# Skip path FIRST — before any state read/write. Matches the /prompts:handoff
+# custom-prompt convention this kit's prompts/ builder uses (see repo
+# README), plus /handoff and /swap as generic aliases in case those also end
+# up wired.
+prompt="$(printf '%s' "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)"
+case "$prompt" in
+    "/handoff"*|"/swap"*|"/prompts:handoff"*) exit 0 ;;
+esac
+
+session_id="$(printf '%s' "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)"
+[ -n "$session_id" ] || exit 0
+
+transcript_path="$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)"
+
+# pct unavailable (missing transcript, no token_count line yet, no jq) ->
+# silent exit. This is expected/common early in a session before the first
+# token_count event has been written.
+pct="$(ctx_pct_from_transcript "$transcript_path")" || exit 0
+case "$pct" in ''|*[!0-9]*) exit 0 ;; esac
+
+# State (missing/corrupt -> fired=0 bannered=0). Shared state file with
+# overcodex-notify.sh: each script only actively manages its own field but
+# preserves the other's across writes, exactly as overclaude's ctx-watch.sh /
+# ctx-notify.sh pair do.
+state="$CTX_DIR/$session_id.state"
+fired=0
+bannered=0
+if [ -f "$state" ]; then
+    f="$(jq -r '.fired // 0' "$state" 2>/dev/null)"
+    b="$(jq -r '.bannered // 0' "$state" 2>/dev/null)"
+    case "$f" in 0|60|75|85) fired=$f ;; esac
+    case "$b" in 0|60|75|85) bannered=$b ;; esac
+fi
+
+changed=0
+
+# Re-arm rule: if pct < fired-10 -> fired = highest threshold <= pct
+# (else 0), and bannered = min(bannered, fired).
+if [ "$pct" -lt $(( fired - 10 )) ]; then
+    new_fired=0
+    for t in "$T1" "$T2" "$T3"; do
+        [ "$pct" -ge "$t" ] && new_fired=$t
+    done
+    fired=$new_fired
+    [ "$bannered" -gt "$fired" ] && bannered=$fired
+    changed=1
+fi
+
+# Fire: highest threshold T with pct >= T and T > fired.
+T=0
+for t in "$T1" "$T2" "$T3"; do
+    [ "$pct" -ge "$t" ] && T=$t
+done
+if [ "$T" -gt "$fired" ]; then
+    jq -n --arg ctx "[context-watch] Context is at ${pct}%. After fully completing the user's current request, tell them context is filling up and OFFER /prompts:handoff to continue in a fresh session. Do NOT invoke the handoff flow yourself unless the user explicitly accepts in their own message — an offer you made is not acceptance. If they decline or ignore the offer, drop the subject; this notice will re-appear at the next threshold." \
+        '{hookSpecificOutput: {hookEventName: "UserPromptSubmit", additionalContext: $ctx}}'
+    fired=$T
+    changed=1
+fi
+
+# Persist only when something changed (atomic write).
+if [ "$changed" -eq 1 ]; then
+    mkdir -p "$CTX_DIR" 2>/dev/null || exit 0
+    tmp="$state.tmp.$$"
+    printf '{"fired":%d,"bannered":%d}\n' "$fired" "$bannered" > "$tmp" 2>/dev/null && mv -f "$tmp" "$state" 2>/dev/null
+fi
+exit 0