overclaude 1.0.0__tar.gz

overclaude-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.venv/

overclaude-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 arthur-bump-pm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

overclaude-1.0.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: overclaude
+Version: 1.0.0
+Summary: Claude Code, overclocked — multi-account hot-swap, context-threshold handoff, instrumented statusline, and model routing for multi-agent workflows
+Project-URL: Homepage, https://github.com/arthur-bump-pm/overclaude
+Project-URL: Repository, https://github.com/arthur-bump-pm/overclaude
+Project-URL: Issues, https://github.com/arthur-bump-pm/overclaude/issues
+Author: arthur-bump-pm
+License: MIT
+License-File: LICENSE
+Keywords: claude,claude-code,cli,dotfiles
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# overclaude
+
+**Claude Code, overclocked.** A portable kit that turns a stock Claude Code install into a multi-account, context-aware, model-routed setup: hot-swap between Claude accounts without leaving your session, hand off to a fresh session before context fills up, watch every usage meter in the statusline, and route multi-agent workflow subagents to the right model tier automatically.
+
+Clone it, run the installer, register your accounts — same setup on any Mac.
+
+```
+Fable 5 (high) | myproject (master*) | 3 sessions | 👤 work [1/2]
+ctx [████░░░░░░] 42% | 5h [███████░░░] 71% | week [██░░░░░░░░] 18% | Fable [███████░░░] 73%
+```
+
+## Features
+
+### `/swap` — hot account switching
+Switch which Claude account serves your sessions **without restarting anything**. Every live Claude Code session on the machine (CLI, VS Code, background) adopts the new credential within ~30 seconds, mid-conversation, full context preserved. Hit a rate limit on one account? `/swap work` and keep typing.
+
+- `/swap` — dashboard: accounts, aliases, token health, per-account 5h/7d/scoped usage, live-session table
+- `/swap <target>` — hot-swap (guarded: refuses if another session is mid-task, unless you `force`)
+- `/swap <target> handoff` — switch accounts AND continue in a fresh session with packaged context
+- `/swap <target> restart` — rare escape hatch for model-entitlement mismatches or wedged auth
+- `/swap add` — guided registration of a new account
+
+A busy-session preflight protects you from yanking credentials out from under an active session. Sessions too old to report status are judged by transcript activity instead of being assumed busy.
+
+### `/handoff` — context-threshold session handoff
+When a session's context crosses **60% / 75% / 85%**, Claude offers a handoff: it packages goals, state, decisions, files touched, and next steps into a structured document, then a fresh session auto-loads it via a SessionStart hook. You lose the token bloat, not the thread. Works same-account (`/handoff`) or combined with an account switch (`/swap <target> handoff`). Also: `/handoff status`, `/handoff cancel`.
+
+### Instrumented statusline
+Two lines, everything you actually check: model + effort, folder (git branch, dirty marker), live session count, active account `[slot/total]`, then four 10-char meters — **context window, 5-hour limit, weekly limit, and your model-scoped (Fable) bucket** — green/yellow/red at 50/80%. The statusline is also the data spine: it publishes each session's context % to a relay file the threshold hooks read.
+
+### `ULTRACODE.md` — model routing for multi-agent workflows
+A policy document loaded into every session that teaches the orchestrator to route workflow subagents by task: haiku/sonnet for bulk scouting and finding, opus for verification and judging, the top tier reserved for final synthesis and tie-breaks. Core rule: *spend the scarce model only where judgment is the bottleneck, never where volume is.* Includes a routing table, hard floors that never get downgraded, escalation rules, and a pre-dispatch lint.
+
+## Requirements
+
+- macOS (scripts use BSD `stat -f`, `shasum`), zsh
+- `jq`, `git`, `pipx`
+- [Claude Code](https://claude.com/claude-code) — tested on 2.1.212; the session-registry `status` field needs ~2.1.211+
+- Claude subscription accounts (Max-style) — the rate-limit meters read subscription usage buckets
+
+The credential-switching engine, **cswap**, ships with the kit as a full source tree (`vendor/claude-swap/`, v0.21.0) and is installed automatically by `install.sh` via pipx or uv — no separate install step. See [Credits](#credits).
+
+## Install
+
+### One-liner (pipx or uv)
+
+```bash
+pipx install overclaude && overclaude install
+# or
+uv tool install overclaude && overclaude install
+```
+
+The package carries the full kit (including the bundled cswap), so this is everything. The `overclaude` command stays around for later: `overclaude install` (refresh after an upgrade), `overclaude uninstall`, `overclaude path`, `overclaude version`. Upgrade with `pipx upgrade overclaude` / `uv tool upgrade overclaude`.
+
+To track the latest unreleased main instead: `pipx install git+https://github.com/arthur-bump-pm/overclaude.git`.
+
+### From a clone
+
+```bash
+git clone https://github.com/arthur-bump-pm/overclaude.git
+cd overclaude
+./install.sh
+```
+
+Use the clone if you want to hack on the kit — `sync.sh` (live-setup → repo → push) only works from a git clone.
+
+The installer is **idempotent and conservative**: every modified file gets a timestamped backup, your existing `settings.json` content (other hooks, permissions) is preserved by a jq merge, an existing statusLine is never overwritten (you get instructions instead), and re-running is a no-op.
+
+The installer also sets up cswap from the bundled copy if it isn't on the machine yet (needs `pipx`; Python dependencies are resolved from PyPI).
+
+### Or just ask Claude
+
+If Claude Code is already running on the machine, paste this and let it do the work:
+
+> Clone https://github.com/arthur-bump-pm/overclaude, read its README, run ./install.sh, and fix anything the preflight complains about (jq, pipx, PATH). Then tell me what post-install steps I need to do myself.
+
+Claude will run the installer, resolve missing dependencies, and hand you back the two things only you can do: registering accounts (`cswap add` needs you to `/login` as each account) and restarting sessions. After a restart, `/swap add` gives you a guided flow for registering additional accounts from inside Claude Code.
+
+Post-install:
+
+1. Register accounts: `cswap add` (repeat per account), then alias them: `cswap alias 1 work`, `cswap alias 2 personal`
+2. Open a new shell (or `source ~/.zshrc`)
+3. Start a **new** Claude Code session — hooks and statusline load at session start
+4. Verify: `swap-guard whoami` prints your session JSON; the statusline shows `👤 <alias> [n/N]` and four meters
+
+## Components
+
+| File | Installs to | What it does |
+|---|---|---|
+| `bin/swap-guard` | `~/.local/bin/` | State/guard engine: `whoami`, live-session table, busy-preflight for swaps, per-directory handoff state, relay status |
+| `skills/swap/SKILL.md` | `~/.claude/skills/swap/` | The `/swap` skill: dashboard, guarded hot-swap, handoff/restart modes, account registration |
+| `skills/handoff/SKILL.md` | `~/.claude/skills/handoff/` | The `/handoff` skill: context packaging, relaunch flags, status/cancel |
+| `hooks/handoff-inject.sh` | `~/.claude/hooks/` | SessionStart: auto-loads a pending handoff package into the new session (10-min TTL, per-directory) |
+| `hooks/ctx-watch.sh` | `~/.claude/hooks/` | UserPromptSubmit: fires the 60/75/85% handoff offers, with re-arm hysteresis |
+| `hooks/ctx-notify.sh` | `~/.claude/hooks/` | Stop: threshold banner notifications |
+| `statusline/statusline-command.sh` | `~/.claude/statusline-command.sh` | Renders the statusline; publishes the context relay the hooks depend on |
+| `claude/ULTRACODE.md` | `~/.claude/` + import in `CLAUDE.md` | Model/effort routing policy for multi-agent workflows |
+| `settings/settings-fragment.json` | merged into `~/.claude/settings.json` | 3 hook groups, statusLine block, 2 permission allows |
+| `shell/zshrc-snippet.sh` | appended to `~/.zshrc` (markers) | `claude()` wrapper honoring handoff/restart relaunch flags, `swap` alias, PATH guard |
+| `vendor/claude-swap/` | pipx/uv-installed if `cswap` absent | The bundled credential-switching engine, full source (see [Credits](#credits)) |
+
+## Behaviors & caveats — read these
+
+- **A swap flips ALL live Claude Code sessions on the machine** within ~30s. It's the shared keychain credential, not per-terminal.
+- **Hooks load at session start.** Sessions already running at install time won't offer handoffs until restarted; a plain hot-swap works everywhere immediately.
+- **The kit's statusline is a hard dependency for the handoff offers** — it publishes the context relay that `ctx-watch`/`ctx-notify` read. If the installer skipped it because you already had a statusLine, either switch (`.statusLine.command` → `bash ~/.claude/statusline-command.sh`) or merge the relay block into your own script; otherwise threshold prompts silently never fire.
+- The **Fable/scoped meter reads cswap's cache**, refreshed whenever cswap runs (any `/swap` dashboard, switch, or `cswap list`) — it can lag between invocations. The 5h/week meters describe the account that served the last response, so they lag ~1 turn right after a swap; the 👤 segment is always current.
+- Statusless legacy clients (older VS Code extension builds) are judged busy/idle by **transcript mtime** (2-min window) during swap preflight.
+- **claude.ai connectors (Gmail/Drive/…) are per-account server-side** — they don't follow a swap.
+- Context thresholds re-arm if usage drops 10 points below the fired threshold; Claude Code's auto-compact (~92%) remains the backstop.
+- The `swap` shell alias (`cswap switch`) works from any terminal even when sessions are hard rate-limited — the panic path when a session can't complete its own `/swap` turn.
+
+## Keeping the repo in sync with your live setup
+
+Improve your live setup (statusline tweaks, skill edits, ULTRACODE changes), then:
+
+```bash
+./sync.sh            # live files -> repo, scrub-check, show diff, commit, push
+./sync.sh --dry-run  # just show what would change
+```
+
+`sync.sh` copies the live files back into the repo layout, extracts your current zshrc block, **aborts if the diff contains personal data** (usernames, emails, `/Users/...` paths), and only then commits and pushes. On other machines: `git pull && ./install.sh` (no-ops everything unchanged).
+
+`settings/settings-fragment.json` is curated by hand — if you add hooks or permissions the kit should ship, edit the fragment directly.
+
+## Uninstall
+
+```bash
+./uninstall.sh
+```
+
+Removes installed files, deletes the zshrc block, removes the `@ULTRACODE.md` import, and strips exactly the kit's entries from `settings.json` (your other settings survive; everything edited is backed up first). Runtime state in `~/.claude-swap-backup/` (cswap credentials/cache, handoff archives) is deliberately left — delete it manually for a clean slate. cswap itself, if the installer set it up, is removed with `pipx uninstall claude-swap`.
+
+## Credits
+
+The account-switching engine bundled in `vendor/claude-swap/` is **[claude-swap](https://github.com/realiti4/claude-swap)** by [Onur Cetinkol](https://github.com/realiti4) (MIT license) — the complete, unmodified v0.21.0 source as published to [PyPI](https://pypi.org/project/claude-swap/). overclaude's swap/handoff layer, statusline, hooks, and routing policy are built around it — cswap does the hard, careful work of credential storage, keychain switching, OAuth refresh, and usage polling. Go star it.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The vendored claude-swap package retains its own MIT license and copyright (Onur Cetinkol).

overclaude-1.0.0/README.md

@@ -0,0 +1,140 @@
+# overclaude
+
+**Claude Code, overclocked.** A portable kit that turns a stock Claude Code install into a multi-account, context-aware, model-routed setup: hot-swap between Claude accounts without leaving your session, hand off to a fresh session before context fills up, watch every usage meter in the statusline, and route multi-agent workflow subagents to the right model tier automatically.
+
+Clone it, run the installer, register your accounts — same setup on any Mac.
+
+```
+Fable 5 (high) | myproject (master*) | 3 sessions | 👤 work [1/2]
+ctx [████░░░░░░] 42% | 5h [███████░░░] 71% | week [██░░░░░░░░] 18% | Fable [███████░░░] 73%
+```
+
+## Features
+
+### `/swap` — hot account switching
+Switch which Claude account serves your sessions **without restarting anything**. Every live Claude Code session on the machine (CLI, VS Code, background) adopts the new credential within ~30 seconds, mid-conversation, full context preserved. Hit a rate limit on one account? `/swap work` and keep typing.
+
+- `/swap` — dashboard: accounts, aliases, token health, per-account 5h/7d/scoped usage, live-session table
+- `/swap <target>` — hot-swap (guarded: refuses if another session is mid-task, unless you `force`)
+- `/swap <target> handoff` — switch accounts AND continue in a fresh session with packaged context
+- `/swap <target> restart` — rare escape hatch for model-entitlement mismatches or wedged auth
+- `/swap add` — guided registration of a new account
+
+A busy-session preflight protects you from yanking credentials out from under an active session. Sessions too old to report status are judged by transcript activity instead of being assumed busy.
+
+### `/handoff` — context-threshold session handoff
+When a session's context crosses **60% / 75% / 85%**, Claude offers a handoff: it packages goals, state, decisions, files touched, and next steps into a structured document, then a fresh session auto-loads it via a SessionStart hook. You lose the token bloat, not the thread. Works same-account (`/handoff`) or combined with an account switch (`/swap <target> handoff`). Also: `/handoff status`, `/handoff cancel`.
+
+### Instrumented statusline
+Two lines, everything you actually check: model + effort, folder (git branch, dirty marker), live session count, active account `[slot/total]`, then four 10-char meters — **context window, 5-hour limit, weekly limit, and your model-scoped (Fable) bucket** — green/yellow/red at 50/80%. The statusline is also the data spine: it publishes each session's context % to a relay file the threshold hooks read.
+
+### `ULTRACODE.md` — model routing for multi-agent workflows
+A policy document loaded into every session that teaches the orchestrator to route workflow subagents by task: haiku/sonnet for bulk scouting and finding, opus for verification and judging, the top tier reserved for final synthesis and tie-breaks. Core rule: *spend the scarce model only where judgment is the bottleneck, never where volume is.* Includes a routing table, hard floors that never get downgraded, escalation rules, and a pre-dispatch lint.
+
+## Requirements
+
+- macOS (scripts use BSD `stat -f`, `shasum`), zsh
+- `jq`, `git`, `pipx`
+- [Claude Code](https://claude.com/claude-code) — tested on 2.1.212; the session-registry `status` field needs ~2.1.211+
+- Claude subscription accounts (Max-style) — the rate-limit meters read subscription usage buckets
+
+The credential-switching engine, **cswap**, ships with the kit as a full source tree (`vendor/claude-swap/`, v0.21.0) and is installed automatically by `install.sh` via pipx or uv — no separate install step. See [Credits](#credits).
+
+## Install
+
+### One-liner (pipx or uv)
+
+```bash
+pipx install overclaude && overclaude install
+# or
+uv tool install overclaude && overclaude install
+```
+
+The package carries the full kit (including the bundled cswap), so this is everything. The `overclaude` command stays around for later: `overclaude install` (refresh after an upgrade), `overclaude uninstall`, `overclaude path`, `overclaude version`. Upgrade with `pipx upgrade overclaude` / `uv tool upgrade overclaude`.
+
+To track the latest unreleased main instead: `pipx install git+https://github.com/arthur-bump-pm/overclaude.git`.
+
+### From a clone
+
+```bash
+git clone https://github.com/arthur-bump-pm/overclaude.git
+cd overclaude
+./install.sh
+```
+
+Use the clone if you want to hack on the kit — `sync.sh` (live-setup → repo → push) only works from a git clone.
+
+The installer is **idempotent and conservative**: every modified file gets a timestamped backup, your existing `settings.json` content (other hooks, permissions) is preserved by a jq merge, an existing statusLine is never overwritten (you get instructions instead), and re-running is a no-op.
+
+The installer also sets up cswap from the bundled copy if it isn't on the machine yet (needs `pipx`; Python dependencies are resolved from PyPI).
+
+### Or just ask Claude
+
+If Claude Code is already running on the machine, paste this and let it do the work:
+
+> Clone https://github.com/arthur-bump-pm/overclaude, read its README, run ./install.sh, and fix anything the preflight complains about (jq, pipx, PATH). Then tell me what post-install steps I need to do myself.
+
+Claude will run the installer, resolve missing dependencies, and hand you back the two things only you can do: registering accounts (`cswap add` needs you to `/login` as each account) and restarting sessions. After a restart, `/swap add` gives you a guided flow for registering additional accounts from inside Claude Code.
+
+Post-install:
+
+1. Register accounts: `cswap add` (repeat per account), then alias them: `cswap alias 1 work`, `cswap alias 2 personal`
+2. Open a new shell (or `source ~/.zshrc`)
+3. Start a **new** Claude Code session — hooks and statusline load at session start
+4. Verify: `swap-guard whoami` prints your session JSON; the statusline shows `👤 <alias> [n/N]` and four meters
+
+## Components
+
+| File | Installs to | What it does |
+|---|---|---|
+| `bin/swap-guard` | `~/.local/bin/` | State/guard engine: `whoami`, live-session table, busy-preflight for swaps, per-directory handoff state, relay status |
+| `skills/swap/SKILL.md` | `~/.claude/skills/swap/` | The `/swap` skill: dashboard, guarded hot-swap, handoff/restart modes, account registration |
+| `skills/handoff/SKILL.md` | `~/.claude/skills/handoff/` | The `/handoff` skill: context packaging, relaunch flags, status/cancel |
+| `hooks/handoff-inject.sh` | `~/.claude/hooks/` | SessionStart: auto-loads a pending handoff package into the new session (10-min TTL, per-directory) |
+| `hooks/ctx-watch.sh` | `~/.claude/hooks/` | UserPromptSubmit: fires the 60/75/85% handoff offers, with re-arm hysteresis |
+| `hooks/ctx-notify.sh` | `~/.claude/hooks/` | Stop: threshold banner notifications |
+| `statusline/statusline-command.sh` | `~/.claude/statusline-command.sh` | Renders the statusline; publishes the context relay the hooks depend on |
+| `claude/ULTRACODE.md` | `~/.claude/` + import in `CLAUDE.md` | Model/effort routing policy for multi-agent workflows |
+| `settings/settings-fragment.json` | merged into `~/.claude/settings.json` | 3 hook groups, statusLine block, 2 permission allows |
+| `shell/zshrc-snippet.sh` | appended to `~/.zshrc` (markers) | `claude()` wrapper honoring handoff/restart relaunch flags, `swap` alias, PATH guard |
+| `vendor/claude-swap/` | pipx/uv-installed if `cswap` absent | The bundled credential-switching engine, full source (see [Credits](#credits)) |
+
+## Behaviors & caveats — read these
+
+- **A swap flips ALL live Claude Code sessions on the machine** within ~30s. It's the shared keychain credential, not per-terminal.
+- **Hooks load at session start.** Sessions already running at install time won't offer handoffs until restarted; a plain hot-swap works everywhere immediately.
+- **The kit's statusline is a hard dependency for the handoff offers** — it publishes the context relay that `ctx-watch`/`ctx-notify` read. If the installer skipped it because you already had a statusLine, either switch (`.statusLine.command` → `bash ~/.claude/statusline-command.sh`) or merge the relay block into your own script; otherwise threshold prompts silently never fire.
+- The **Fable/scoped meter reads cswap's cache**, refreshed whenever cswap runs (any `/swap` dashboard, switch, or `cswap list`) — it can lag between invocations. The 5h/week meters describe the account that served the last response, so they lag ~1 turn right after a swap; the 👤 segment is always current.
+- Statusless legacy clients (older VS Code extension builds) are judged busy/idle by **transcript mtime** (2-min window) during swap preflight.
+- **claude.ai connectors (Gmail/Drive/…) are per-account server-side** — they don't follow a swap.
+- Context thresholds re-arm if usage drops 10 points below the fired threshold; Claude Code's auto-compact (~92%) remains the backstop.
+- The `swap` shell alias (`cswap switch`) works from any terminal even when sessions are hard rate-limited — the panic path when a session can't complete its own `/swap` turn.
+
+## Keeping the repo in sync with your live setup
+
+Improve your live setup (statusline tweaks, skill edits, ULTRACODE changes), then:
+
+```bash
+./sync.sh            # live files -> repo, scrub-check, show diff, commit, push
+./sync.sh --dry-run  # just show what would change
+```
+
+`sync.sh` copies the live files back into the repo layout, extracts your current zshrc block, **aborts if the diff contains personal data** (usernames, emails, `/Users/...` paths), and only then commits and pushes. On other machines: `git pull && ./install.sh` (no-ops everything unchanged).
+
+`settings/settings-fragment.json` is curated by hand — if you add hooks or permissions the kit should ship, edit the fragment directly.
+
+## Uninstall
+
+```bash
+./uninstall.sh
+```
+
+Removes installed files, deletes the zshrc block, removes the `@ULTRACODE.md` import, and strips exactly the kit's entries from `settings.json` (your other settings survive; everything edited is backed up first). Runtime state in `~/.claude-swap-backup/` (cswap credentials/cache, handoff archives) is deliberately left — delete it manually for a clean slate. cswap itself, if the installer set it up, is removed with `pipx uninstall claude-swap`.
+
+## Credits
+
+The account-switching engine bundled in `vendor/claude-swap/` is **[claude-swap](https://github.com/realiti4/claude-swap)** by [Onur Cetinkol](https://github.com/realiti4) (MIT license) — the complete, unmodified v0.21.0 source as published to [PyPI](https://pypi.org/project/claude-swap/). overclaude's swap/handoff layer, statusline, hooks, and routing policy are built around it — cswap does the hard, careful work of credential storage, keychain switching, OAuth refresh, and usage polling. Go star it.
+
+## License
+
+MIT — see [LICENSE](LICENSE). The vendored claude-swap package retains its own MIT license and copyright (Onur Cetinkol).