overclaude

Claude Code, overclocked. Hot-swap between Claude accounts without leaving your session, hand off to a fresh session before context fills up, and watch every usage meter live:

Fable 5 (high) | myproject (master*) | 3 sessions | 👤 work [1/2] ↻ Thu Oct 9 23:59 (1d 6h)
└ model+effort   └ folder+branch*      └ live count └ account     └ when its weekly limit resets

ctx [████░░░░░░] 42% | 5h [███████░░░] 71% | week [██░░░░░░░░] 18% | Fable [███████░░░] 73%
└ context window       └ 5-hour limit         └ weekly limit           └ model-scoped bucket

↳ personal [2] 5h 10% · week 85% · Fable 100% ↻ Thu Oct 9 17:59 (1d 1h)
└ every OTHER account: its limits + weekly reset, so you know where to swap next

bars and percentages turn yellow at 50% · red at 80%

Versions

Install or upgrade: pipx install overclaude && overclaude install (upgrade: overclaude update, or pipx upgrade overclaude && overclaude install from versions before 1.3).

What's new in 1.5

Plan and status: docs/plan-1.5.md. The multi-Mac features (fleet, sessions on another Mac, /handoff <mac>) are experimental: they are tested against simulated Macs only, not yet on real ones, and do nothing until you run overclaude fleet add.

• Logins that stay alive — a small background job (swap-guard keepalive, on by default) fetches every account's usage every 2 hours, which is what makes cswap refresh a login. Each refresh hands back a fresh refresh token, so an account you don't touch for weeks no longer loses its login. It never switches accounts and never writes a credential itself. When a login does die (revoked, or used on two machines), you get one notification a day with the fix (swap-guard login N). Off: swap-guard keepalive off (remembered across reinstalls).
• Long-lived tokens for headless jobs (experimental) — swap-guard token add <account> runs claude setup-token with its output hidden (you see only the sign-in link), checks that the one-year token works with one tiny claude -p, and stores it in the keychain. The token never appears on screen, in a file or in a process list. swap-guard token run <account> -- claude -p "…" runs one command with it. These tokens only make model requests (no Remote Control, no usage figures), so they are for scripts and worker Macs; interactive sessions keep their normal logins. overclaude doctor warns 30 days before one expires.
• Your other Macs, from this one (experimental) — overclaude fleet add <mac> registers a Mac on your Tailscale network (SSH with a key, never a password prompt). overclaude fleet then shows every Mac: sessions (and how many are busy), which accounts are logged in and which is active, dead logins, load and memory, overclaude version. The statusline gets a ↳ fleet 3/3 macs · 7 sessions line (refreshed in the background every 10 minutes; SWAP_HIDE_FLEET=1 hides it), and overclaude doctor flags offline Macs, outdated kits and dead logins there. When an account hits its limit, the instant swap now also moves your other Macs off it, each to the account with the most room among those logged in there (/swap fleet swap does it by hand, after showing the plan). Logins are never copied between Macs: each Mac logs in to its own accounts.
• A session on another Mac (experimental) — /swap remote <mac> <goal> (or overclaude remote start <mac> <goal>) starts Claude on that Mac in the background with Remote Control, named after the Mac and the goal, so you drive it from claude.ai/code or the Claude app. remote list|logs|stop|attach <mac> manage it. It uses that Mac's own login (a normal /login; setup-tokens can't do Remote Control) and starts in a folder you have trusted there: pass --dir <project>, because the home folder usually isn't trusted for this. The goal is passed as Task: <goal>, so it can never be taken as a command-line option. /handoff <mac> continues the current conversation there instead: the handoff package travels in the same SSH call that starts the session, lands where that Mac's startup hook loads it (with a lasting copy the session is pointed at, in case the hook isn't installed there), and starts in the same folder relative to home.
• Resume after server errors (opt-in) — /swap auto retry on: when a turn dies on a temporary server error (server_error / overloaded), the session waits (30 s, 2 min, 5 min) and continues by itself, at most 3 times per session per hour. Off by default.
• Loop guard (opt-in, experimental) — /swap auto loop on: when the same tool call fails the same way 3 times in a row (timings and line numbers don't hide a repeat; successful calls in between don't reset it, a different failure does; repeats more than 30 min apart don't count), Claude is told to stop repeating it and try a different approach; at 6, to stop and tell you. Silent otherwise. Off by default; SWAP_LOOP_MAX changes the 3.
• Instruction-size check — overclaude doctor reports how big your global instructions are (CLAUDE.md plus its @ imports, loaded into every session), warns past ~40 KB, and flags imports that point at missing files.

What's new in 1.4

• Codex as the next place to work — /handoff codex (or /swap codex) writes the handoff where overcodex's Codex hook loads it, so work continues in the Codex CLI when every Claude account is out; typing $handoff-claude in Codex (overcodex 0.3) hands it back. The usage note and the instant-swap notification suggest it when no Claude account has room.
• Codex limits on the statusline — ↳ codex 5h 12% · week 18% ↻ … (every window that Codex account has), read from Codex's own session logs, one line per Codex account. SWAP_HIDE_CODEX=1 hides them.
• Codex as an independent reviewer — swap-guard codex-review runs a read-only, ephemeral codex exec with a timeout (optional JSON verdict schema, --stdin for a diff). ULTRACODE now recommends one cross-family voter on verdicts that matter.
• Routing guard — on a Fable session, a subagent launched without a model (or a Workflow agent() call without one) is blocked with the fix, so the scarce tier is only spent on purpose. /swap guard off (or OVERCLAUDE_ROUTE_GUARD=off) disables it; the installer says when it turns on.
• Spend report — /swap spend: what your usage would cost at API list prices, by model, account, day and session, against what your plans cost; the statusline shows 💵 $1.8k/7d · 19.2× plan (refreshed in the background every 15 minutes; SWAP_HIDE_SPEND=1 hides it). The plan cost counts every registered account; plan prices come from each account's tier and can be overridden in ~/.claude-swap-backup/plans.json.
• Smarter instant swap and leaner snapshots — ties go to the account with more of the capped model left; artifact snapshots are copy-on-write clones on APFS (identical content shares disk space, every copy stays independently editable).
• Fixes — uninstall refuses (instead of deleting everything below it) when the .zshrc block's end marker was edited or is missing, and keeps a symlinked .zshrc/CLAUDE.md and its file mode; the update badge re-checks PyPI right after an upgrade instead of showing a day-old "latest". Maintainers: sync.sh --dry-run no longer writes live copies into the repo.

What's new in 1.3.1

QA fixes for 1.3, found by an audit of the released package:

• /swap can now be started by plain requests ("my work account says relogin — fix it"): the skill is model-invocable behind the same explicit-consent gate as /handoff, so the paste-a-prompt rows below actually run the safe flows.
• swap-guard artifacts link <old-url> <new-url> now connects republished copies (tool responses carry UUID ids while URLs end in a short code; both are matched, and find shows the linked URL).
• A cswap y/N confirmation during /swap relogin or /swap add (an organization change) now reaches you when you run swap-guard login in a terminal; /swap add reports the slot it registered.
• An expired-but-refreshing token (token_expired) is no longer reported as dead; accounts without an alias show their real status in doctor.
• The installer says when it turns instant swap on, and the update badge suggests git pull && ./install.sh for git-checkout installs.

What's new in 1.3

• Instant swap on a usage cap — the moment "You've reached your Fable limit" stops a session, a hook switches to the account with the most room on that limit and wakes the session to carry on. Sessions that hit the cap together share one swap; a short-lived 429 slowdown never swaps; dead, disabled and API-key accounts are never targets. On by default (/swap auto instant off to disable), independent of the opt-in background auto-swap.
• Re-login that doesn't kill your other account — refresh tokens are single-use, so a plain /login over the live account overwrote its newest token and that account died next: re-logging one account killed the other, in turn. /swap relogin <account> (or swap-guard login <account> in a terminal) saves the live account's token first and signs in inside a throwaway profile, so the live login is never touched. /swap add uses the same flow and no longer needs /logout.
• The model sees your usage — when the active account crosses 75/90/100% of a model limit (or 85/95/100% weekly, 90/100% 5-hour), one line tells Claude, so ULTRACODE's budget rules (cut fan-out, keep the top tier for the final synthesis) actually kick in — with a pointer to an account that has room. One more line when the pressure clears; silent otherwise.
• One list of every artifact — every publish is recorded with the account that owns it and a durable copy of its source. /swap artifacts villa finds it from any account; swap-guard artifacts index backfills artifacts published before 1.3 (owner inferred from cswap's switch history).
• Same link across accounts — handoffs now say which account owns each artifact and suggest sharing it to the next account with edit access, so the new session updates it in place instead of republishing a copy at a new URL.
• overclaude update — upgrades however you installed it (pipx, uv or pip) and reinstalls the kit. The statusline shows ⬆ overclaude X available when a release is out (checked in the background once a day; OVERCLAUDE_NO_UPDATE_CHECK=1 hides it).
• overclaude doctor --fix (or /swap doctor fix) — reinstalls drifted or missing files and hooks, offers to restart a stopped auto-swap agent and to run the safe re-login for dead tokens (both only when run in a terminal), then checks again.
• Safer releases — the release script runs shellcheck and the full test suite before anything is committed or tagged, and the publish job reuses the push's test run instead of queueing a second macOS job.

What's new in 1.2

• Busy-aware auto-swap (opt-in) — /swap auto on installs a background agent that switches accounts before you hit a wall. It never flips credentials while a session is mid-task (proactive switches wait); at-limit switches go through, dead tokens are skipped, bad settings are refused at install, and a macOS notification tells you what happened.
• overclaude doctor — one read-only command that checks dependencies, installed files, hooks, statusline, account tokens, sessions running stale hooks, and the auto-swap agent, with the exact fix for each problem. Also /swap doctor.
• Recover expired handoffs — /handoff history lists past packages; /handoff restore [n] re-arms one (packages expire 10 minutes after you leave a session). A package it replaces is archived, never discarded.
• Handoffs never get truncated — Claude Code caps hook output at 10,000 characters; oversized packages now inject section by section with a pointer to the full file, and the skill writes to a size budget.
• cswap 0.26 bundled (was 0.21), and overclaude install upgrades an older copy.
• Tests + CI — a plain-bash suite (statusline, handoff budget, history/restore, auto-swap decisions, artifact snapshots) runs on macOS for every push, and releases only publish when it passes.

What's new in 1.1

• Weekly reset on the statusline — ↻ Thu Oct 9 23:59 (1d 6h) next to the account, in local time.
• See every account's limits — one compact line per other account (5h / week / Fable + reset), with ⚠ relogin when a token has died.
• Artifacts survive a handoff — claude.ai artifacts the session made are snapshotted (sources + URLs + owner) before an account switch and handed to the next session, which keeps editing them or re-homes them on the new account.
• Handoff packages before it switches — so nothing that needs the old account (artifacts, artifact data) is lost to the credential flip.

Install

pipx install overclaude && overclaude install

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

Then register your accounts (once):

cswap add             # registers the account you're logged in as
cswap alias 1 work    # name your slots
cswap alias 2 personal
exec zsh              # reload shell

Start a new Claude Code session (hooks load at session start) and check the statusline shows 👤 work [1/2]. Adding a second account is guided — run /swap add inside Claude Code. Anything look wrong? overclaude doctor checks the whole setup and prints the fix for each problem.

# uv
uv tool install overclaude && overclaude install

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

# track unreleased main
pipx install git+https://github.com/arthur-bump-pm/overclaude.git

What you get

/swap — hot account switching

Every live Claude Code session on the machine adopts the new account's credential within ~30 s — mid-conversation, no restart, context preserved. Hit a rate limit? /swap work and keep typing. A preflight blocks the swap while another session is mid-task (force overrides).

/handoff — escape context bloat, keep the thread

flowchart LR
    A[Context fills up] --> B[Hook offers handoff at 60/75/85%]
    B --> C[You accept]
    C --> D[Claude packages goals, state, next steps, artifacts]
    D --> E[Session exits, shell wrapper relaunches]
    E --> F[SessionStart hook auto-injects the package]
    F --> G[Fresh session, ctx near zero]
    G --> A

You lose the token bloat, not the thread. Works same-account (/handoff) or combined with a switch (/swap work handoff).

Artifacts travel too. Before switching accounts, handoff runs swap-guard artifacts: it reads the session transcript (subagents and workflows included), finds every claude.ai artifact the session published or touched, copies each source out of the session's temporary scratchpad into ~/.claude-swap-backup/handoff-artifacts/<session>/, and lists them in the package with their URLs and owner account. Artifacts belong server-side to the account that published them, so the next session updates them in place on the same account, and on a different account republishes from the saved source as a new artifact (or updates in place if you shared the original with edit access). Artifact database rows can be exported before the switch on request.

Statusline

The display at the top. Line 1 ends with the active account and when its weekly limit resets (local time + countdown). Line 2 is the live meters. Below that, each other account gets a compact line with its 5h / week / Fable usage and weekly reset, so you can see where to swap before you hit a wall — ⚠ relogin flags a dead token, a dim (2h old) flags stale numbers, and SWAP_HIDE_OTHERS=1 hides these lines.

Usage numbers come from cswap's per-account cache, kept ≤ ~5 min fresh by a debounced background refresh (the render itself never waits on the network). It is also the kit's data spine: it publishes each session's context % to a relay the threshold hooks read. Skip the kit's statusline and handoff offers never fire.

ULTRACODE.md — model routing for multi-agent workflows

A policy loaded into every session: bulk work rides cheap models, verification rides opus, only final judgment spends the top tier. Routing table, hard floors, escalation rules included.

Cheat sheet

Or skip memorizing and paste a prompt:

How it fits together

flowchart TD
    SL[Statusline publishes ctx relay] --> HK[ctx-watch and ctx-notify hooks]
    HK --> SK[swap and handoff skills]
    SK --> GD[swap-guard busy preflight]
    GD --> CS[cswap vendored engine]
    CS --> KC[macOS keychain credential]
    KC --> AS[All live sessions adopt within 30s]

The heavy lifting — credential storage, keychain switching, OAuth refresh, usage polling — is claude-swap by Onur Cetinkol (MIT), vendored unmodified in vendor/claude-swap/ and installed automatically. Go star it.

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

Roadmap

1.6: re-login on another Mac and a job queue (from docs/plan-1.5.md), once the multi-Mac features have been tried on real Macs. Also on the list:

1. Weekly pace forecast on the statusline — cswap 0.26 already computes the projection (expectedPct, projectedExhaustionAt).
2. Titled relaunch after handoff — claude -n "↪ <goal>" "Continue from the handoff".
3. Compaction awareness — re-inject handoff state and artifact links after /compact.
4. Per-directory accounts via cswap map/run (needs every component to honor CLAUDE_CONFIG_DIR).

License

MIT — see LICENSE. Vendored claude-swap retains its own MIT license and copyright (Onur Cetinkol).