claudehop-cli 1.4.0__tar.gz

claudehop_cli-1.4.0/CHANGELOG.md

@@ -0,0 +1,174 @@
+# Changelog
+
+All notable changes to this project are documented here.
+This project follows [semantic versioning](https://semver.org/).
+
+## [1.4.0] — 2026-08-11
+
+### Added
+
+- **On PyPI.** `claudehop` installs from the index and puts both `claudehop` and
+  `hop` on your PATH:
+
+  ```bash
+  pipx install claudehop
+  ```
+
+  Still no dependencies, still one file you can read in a sitting. `install.sh`
+  is unchanged and remains the way to get the shell glue with it.
+- **Tagged releases build and publish themselves.** `.github/workflows/release.yml`
+  checks the tag against `VERSION`, builds the wheel and the sdist, publishes to
+  PyPI with trusted publishing (no API token anywhere), and attaches both files
+  to the GitHub release.
+- **`claudehop shell-init`** prints the shell glue a packaged install needs —
+  the `hop` alias and tab-completion, without the PATH line the repo installer
+  writes. `eval "$(claudehop shell-init)"` in your rc file.
+
+### Changed
+
+- The tool moved from `bin/claudehop` to `claudehop.py` at the top of the repo,
+  so it can be both the installed script and the packaged module. `install.sh`,
+  `~/.claude/bin/claudehop` and every command name are unaffected.
+- Tab-completion now offers `shell-init` and `version`, and the completion list
+  is generated from the command table — a test fails if the sourced glue and the
+  packaged one drift apart.
+
+## [1.3.0] — 2026-08-06
+
+### Added
+
+- **`doctor` now works out when you next have to log in for real, and the
+  cheapest day to do it.** A refresh token lasts about 30 days from the `/login`
+  that issued it and using the account does not extend it — measured across four
+  accounts, one of which had its access token reissued that morning and still
+  expired 30 days after its first login. So it is a hard monthly expiry per
+  account, and with several accounts the dates drift apart into a browser
+  round-trip per account per month. Logging in early resets the full window, so
+  `doctor` names the account that goes first and says to do them all that day,
+  which collapses them onto one date:
+
+  ```
+  re-login     by 2026-08-30 (work); the other 3 by 2026-09-04
+               windows are ~30d from login and do not slide, so re-login all 4 on
+               2026-08-30 and they collapse to one date
+  ```
+
+  `doctor --json` carries the same thing under `reloginPlan`, and an account whose
+  refresh token has already died is called out separately — that one needs
+  `claudehop add` rather than planning.
+
+### Changed
+
+- **The expiry warning starts 14 days out instead of 7.** With several accounts on
+  staggered dates, one week is not enough notice to plan a single sitting.
+
+## [1.2.1] — 2026-08-06
+
+### Changed
+
+- **`hop` on its own now asks which account you want.** It prints the list
+  numbered and switches to the one you pick; Enter leaves you where you are. You
+  no longer have to read a table and then retype a name out of it. Piped output,
+  `--json` and a single saved account all still get the plain listing, so
+  statuslines and scripts are unaffected.
+- **The default listing is name, email and plan.** Token expiry and save dates
+  moved behind `--long`. `expired (auto-renews)` under `TOKEN` needed a paragraph
+  of README to be readable and was the most-misread thing the tool printed; it is
+  not something you need in order to choose an account.
+- **`add` stops if other `claude` sessions are running** instead of warning and
+  carrying on into a corrupted result. `--yes` overrides it.
+- **`add` tells you to use a private browser window** before it hands you to
+  `/login`, rather than leaving it in the README's gotchas.
+- `help` leads with the three commands you actually use and lists the rest below.
+
+### Fixed
+
+- **`add` could lose a login it had already completed.** The new credential was
+  read inside the cleanup path but written to disk after it, with an API call for
+  the account's email in between. Anything that ended the process in that window
+  — Ctrl-C, closing the terminal, the identity lookup being cut short — left you
+  logged in as an account with no profile saved for it. The token is now written
+  first and the email filled in afterwards, so an interrupted `add` still leaves
+  a usable profile. Recover one from an older version with `claudehop save <name>`
+  while that login is still live.
+- **`add` no longer unwinds on the first Ctrl-C.** In Claude Code, Ctrl-C cancels
+  the current turn rather than quitting, so `add` used to start cleaning up while
+  `claude` was still running and still writing to the credential store. It now
+  ignores SIGINT while the child runs, the way a shell does, and lets `claude`
+  decide when to exit. SIGHUP and SIGTERM are turned into a clean unwind instead
+  of killing the process outright.
+- **`add` no longer files one account's credential under another account's
+  name.** A `claude` session that was already running writes its own refreshed
+  token into the credential store, and `add` would save that as the new account.
+  It now checks the account UUID before keeping the profile, and puts a refreshed
+  token back where it belongs instead.
+- **Replacing an existing account no longer keeps the old email and plan** next
+  to the new account's token.
+
+## [1.2.0] — 2026-08-05
+
+### Changed
+
+- **Renamed to `claudehop`.** The command is `claudehop`, with `hop` as a shell
+  alias. `claude-acct` and `cacct` keep working as shell functions, so nothing
+  you have typed before breaks.
+- Environment variables are now `CLAUDE_HOP_BACKEND`, `CLAUDE_HOP_OFFLINE` and
+  `CLAUDE_HOP_TIMEOUT`. The old `CLAUDE_ACCT_*` names are still honoured.
+  `CLAUDE_CONFIG_DIR` and `CLAUDE_ACCOUNTS_DIR` are unchanged.
+
+Your saved accounts do not move: they stay in `~/.claude/accounts/`, and
+`install.sh` removes the old `claude-acct` binary and glue so you never end up
+with two copies on your PATH.
+
+## [1.1.0] — 2026-08-05
+
+First public release, under the name `claude-acct`.
+
+### Added
+
+- **macOS keychain backend.** Reads and writes the `Claude Code-credentials`
+  item the same way Claude Code does, and falls back to `.credentials.json`
+  when the keychain holds no login. Override with `CLAUDE_ACCT_BACKEND`.
+- **`doctor`** — checks permissions, stale files, dangling pointers, expiring
+  refresh tokens, environment overrides and running sessions. `--fix` repairs
+  what it safely can.
+- **`active`** — prints just the active account name with no network call, for
+  statuslines and scripts.
+- **`--json`** on `list`, `whoami`, `active` and `doctor`. No secrets in it.
+- **A lock** (`accounts/.lock`) around every mutating command, so two switches
+  at once can't interleave and lose an account.
+- Warning when an account's *refresh* token is within a week of expiring —
+  that's the one whose death means a real re-login.
+- `--version`, `--no-color`, `NO_COLOR` and `CLICOLOR_FORCE` support.
+- zsh tab-completion (via `bashcompinit`), and `--no-rc` for `install.sh`.
+
+### Fixed
+
+- **`add` could leave you logged out of everything.** If `claude` was missing,
+  exited without a login, or you hit Ctrl-C, the credentials it had cleared were
+  never put back. They are now restored in a `finally` block.
+- **Crash on macOS.** The running-session check read `/proc` unconditionally;
+  it now falls back to `pgrep` and never raises.
+- **Misaligned table.** Colour escapes inside a cell were counted as visible
+  width, so one expired token knocked every later column out of line.
+- **`list --verify` reported healthy accounts as `invalid`.** An access token
+  that has simply aged out now reads `stale (renews)`, which is what actually
+  happens to it.
+- `rename` leaked a file descriptor and could leave the active pointer behind.
+- `rm` left the active pointer naming a deleted account.
+- Unknown options (`--typo`) were silently treated as an account name; they now
+  exit 2 with a usage error.
+- Account names are validated, so a name can't escape the accounts directory,
+  and an auto-generated name can no longer shadow a command.
+- `list --verify` only rewrites a profile when something actually changed.
+- `claude-acct list | head` no longer prints a `BrokenPipeError` traceback.
+
+### Changed
+
+- `list` no longer calls the API on the default path — the bare command is now
+  local-only and instant. `--verify` still asks, and now asks for every account
+  in parallel.
+- Profile writes no longer leave `<name>.json.bak` files lying around; they were
+  extra copies of a live credential. `doctor --fix` removes old ones.
+- The `STATE` column only appears with `--verify`, where it means something.
+- `whoami` exits 1 when nothing is logged in.

claudehop_cli-1.4.0/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for looking. This is a small tool and it intends to stay small.
+
+## The rules that keep it small
+
+1. **Python 3.9+, standard library only.** No dependencies, no build step.
+   `claudehop.py` must stay a single file you can read in one sitting and run
+   straight from a clone — `pyproject.toml` packages that one module and
+   nothing else.
+2. **Never lose a login.** Any code path that replaces the live credential must
+   first write what was there into a profile. If you can't identify it, stash it
+   under a generated name. Losing a token costs a browser round-trip and,
+   sometimes, a device-approval email.
+3. **Tests use fake credentials and no network.** `test/test-switch.sh` runs
+   against a temp `CLAUDE_CONFIG_DIR` with `CLAUDE_ACCT_OFFLINE=1`. A test that
+   needs a real account is not a test we can run.
+4. **Secrets never get printed.** Not in `--json`, not in errors, not in debug
+   output.
+
+## Working on it
+
+```bash
+git clone https://github.com/psychofict/claudehop.git
+cd claudehop
+./install.sh              # symlinks, so your edits are live immediately
+./test/test-switch.sh     # 99 checks, about two seconds
+```
+
+Before opening a pull request:
+
+```bash
+./test/test-switch.sh
+ruff check claudehop.py         # if you have it; CI runs it either way
+shellcheck install.sh shell/*.sh test/*.sh
+```
+
+Add a check to `test/test-switch.sh` for anything you fix or add. If the
+behaviour is user-visible, update `README.md` and `CHANGELOG.md` in the same
+pull request.
+
+## Things worth doing
+
+- Verification of the macOS keychain backend against a real Mac. It is written
+  against Claude Code's own `security` calls and tested through a stand-in, but
+  nobody has run it on real hardware yet.
+- fish shell completion (`shell/claudehop.sh` is POSIX/bash + zsh today).
+- A `--verify` cache so `list --verify` doesn't re-ask the API every time.
+
+## Style
+
+Match what's there: plain names, comments that explain *why*, error messages
+that tell the user what to do next. Keep line length near 100.

claudehop_cli-1.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ebenworks
+
+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.

claudehop_cli-1.4.0/MANIFEST.in

@@ -0,0 +1,6 @@
+# The wheel is one module. The sdist also carries the repo installer, the shell
+# glue it wires up, the statusline extra and the test suite.
+include LICENSE CHANGELOG.md CONTRIBUTING.md SECURITY.md install.sh
+include shell/claudehop.sh
+include extras/statusline-snippet.sh
+include test/test-switch.sh

claudehop_cli-1.4.0/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: claudehop-cli
+Version: 1.4.0
+Summary: Hop Claude Code between several Claude accounts without logging in again — swap the saved OAuth login in one keystroke, keep every account's usage pool separate.
+Author-email: Ebenworks <hello@ebenworks.co>
+License: MIT
+Project-URL: Homepage, https://github.com/psychofict/claudehop
+Project-URL: Repository, https://github.com/psychofict/claudehop
+Project-URL: Changelog, https://github.com/psychofict/claudehop/blob/master/CHANGELOG.md
+Project-URL: Issues, https://github.com/psychofict/claudehop/issues
+Project-URL: Author, https://ebenworks.co/
+Keywords: claude,claude-code,anthropic,account-switcher,multi-account,oauth,credentials,keychain,cli,developer-tools,productivity,shell,terminal,ai,llm
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Version Control
+Classifier: Topic :: Utilities
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/psychofict/claudehop/master/assets/cover.png" alt="claudehop — hop Claude Code between accounts" width="560">
+</p>
+
+<h1 align="center">claudehop</h1>
+
+<p align="center">
+  <b>Hop Claude Code between several Claude accounts without logging in again.</b><br>
+  Personal Max account in one terminal, work Team seat in another —
+  <i>two separate usage pools, one machine, no browser round-trip.</i>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/claudehop/"><img src="https://img.shields.io/pypi/v/claudehop.svg?color=FC5F00&label=pypi" alt="PyPI"></a>
+  <a href="https://github.com/psychofict/claudehop/actions/workflows/ci.yml"><img src="https://github.com/psychofict/claudehop/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/psychofict/claudehop/blob/master/LICENSE"><img src="https://img.shields.io/badge/licence-MIT-FC5F00.svg" alt="Licence: MIT"></a>
+  <img src="https://img.shields.io/badge/python-3.9%2B-1D1009.svg" alt="Python 3.9+">
+  <img src="https://img.shields.io/badge/dependencies-none-1D1009.svg" alt="No dependencies">
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="https://github.com/psychofict/claudehop/blob/master/CHANGELOG.md">Changelog</a> ·
+  <a href="https://github.com/psychofict/claudehop/blob/master/SECURITY.md">Security</a>
+</p>
+
+---
+
+## Switching accounts
+
+Run `hop`, press a number.
+
+```
+$ hop
+      NAME  EMAIL           PLAN
+1.    home  me@gmail.com    max
+2. *  work  me@company.com  team
+
+hop to which? [1-2, Enter to stay] 1
+switched to home (me@gmail.com, max)
+```
+
+Then start a new `claude`. That's it — that's the whole tool.
+
+If you'd rather not read a menu, `hop home` goes straight there. Sessions you
+already have open keep the account they started with; only new ones pick up the
+change.
+
+## Install
+
+```bash
+pipx install claudehop              # or: pip install --user claudehop
+eval "$(claudehop shell-init)"      # the `hop` alias + tab-completion
+```
+
+Put that `eval` line in your `~/.bashrc` or `~/.zshrc` and open a new terminal.
+`hop` and `claudehop` are the same command.
+
+Or from a clone, if you'd rather have it symlinked into `~/.claude` with the
+shell glue written for you:
+
+```bash
+git clone https://github.com/psychofict/claudehop.git
+cd claudehop
+./install.sh          # symlinks into ~/.claude, adds one line to your rc file
+```
+
+`./install.sh --copy` installs copies instead of symlinks, `--no-rc` skips the
+shell wiring, `--uninstall` reverses it. None of them ever touch
+`~/.claude/accounts/`, where the credentials live.
+
+Requires Python 3.9+ and Claude Code. Linux and macOS. One module, no
+dependencies.
+
+## Adding an account
+
+```bash
+hop add work
+```
+
+Quit your other `claude` sessions first — `add` will stop and tell you if you
+haven't, because a session left running can write its own token back into the
+credential store mid-login and you'd end up with the wrong account saved under
+that name.
+
+`add` then starts `claude` with no login so you can `/login`, and saves whatever
+that produces when you exit with `/exit`. **Paste the login URL into a private
+browser window.** Your normal browser is already signed in as one of your other
+accounts and will authorise that one without asking.
+
+If the login produces nothing — you changed your mind, you hit Ctrl-C — your
+previous credentials come back. If it does produce a login, that login is saved
+even if the terminal dies on the way out.
+
+Already logged in by hand? `hop save work` names whatever is live right now.
+
+## Everything else
+
+```bash
+hop whoami           # who am I right now (asks the API)
+hop --long           # add token expiry and save dates to the listing
+hop list --verify    # check every saved token against the API
+hop rm <name>        # delete a saved account (does not log you out)
+hop rename <a> <b>
+hop doctor           # check the setup; --fix repairs what it can
+hop shell-init       # shell glue for a pip install: alias + tab-completion
+```
+
+`--json` on `list`, `whoami`, `active` and `doctor` gives machine-readable
+output with no secrets in it, for scripts and statuslines. `hop active` prints
+just the active name with no network call. `hop use <name>` is the long spelling
+of `hop <name>`, and `hop sync` writes the live login back to its own file.
+
+## How it works
+
+Claude Code keeps the live login under the `claudeAiOauth` key of its credential
+store. This tool keeps one saved copy of that block per account in
+`~/.claude/accounts/<name>.json` and swaps the active one in and out. The
+`mcpOAuth` key in the same store — your Vercel/Neon/etc. MCP logins — is left
+alone, so switching accounts doesn't sign you out of anything else.
+
+| | credential store |
+|---|---|
+| Linux | `~/.claude/.credentials.json` |
+| macOS | login keychain item `Claude Code-credentials`, falling back to the file |
+
+The backend is detected from whichever one currently holds a login. Force it
+with `CLAUDE_HOP_BACKEND=file` or `=keychain` if you need to.
+
+Nothing else needs patching. Account identity in `~/.claude.json`
+(`oauthAccount`) is re-fetched from the API by Claude Code at startup: put a
+bogus email in there, start a session, and it comes back corrected. So swapping
+the credential is the whole job.
+
+Identity, plan and token checks come from `GET /api/oauth/profile` with the
+account's own bearer token. Set `CLAUDE_HOP_OFFLINE=1` to skip every API call.
+
+### Two details that make or break it
+
+**Access tokens rotate.** Claude Code refreshes them every few hours and writes
+the new one straight into the credential store. A switcher that identifies the
+active profile by comparing token values therefore stops recognising it after
+the first refresh — and then loses the refreshed token when you switch away. So
+the active profile is tracked in `accounts/active` and confirmed against the
+account UUID from the API, and every switch writes the live block back to its
+profile before loading the next one.
+
+**A login you can't identify is stashed, never dropped.** If the live
+credentials match no saved profile (you ran `/login` by hand, say), switching
+saves them under a name derived from the account's email first. You can always
+get back to a session you'd otherwise have to re-authenticate.
+
+## Gotchas
+
+- Switching affects **new** `claude` processes. Sessions already running keep the
+  account they started with, and will rewrite the credential store when their
+  token refreshes — which can silently undo a switch. `claudehop` prints the
+  PIDs it finds; quit them for a clean switch.
+- `/login` opens your default browser, which is already signed in as somebody.
+  Paste the URL into an incognito window to authenticate as a different account.
+- `ANTHROPIC_API_KEY` and `CLAUDE_CODE_OAUTH_TOKEN` in the environment override
+  the saved login entirely. `whoami` and `doctor` warn when either is set.
+- `--long` showing `expired (auto-renews)` under `TOKEN` is normal — the access
+  token is short lived and Claude Code renews it from the refresh token.
+  `list --verify` prints `stale (renews)` for the same reason. What actually
+  matters is the refresh token; see below. This is why the default listing
+  doesn't show either of them.
+- Each account still has its own rate limits and its own terms. This moves your
+  own logins between your own terminals; it is not a way to pool quota.
+
+## Every account needs a real login about once a month
+
+The refresh token is good for roughly 30 days from the `/login` that issued it,
+and **using the account does not extend it.** Measured 2026-08-06 across four
+accounts: one had its access token reissued that morning and its refresh window
+still ended 30 days after its first login, not 30 days after the refresh. So this
+is a hard monthly expiry per account, and nothing on this side can lengthen it —
+it's set by the OAuth server. `claude setup-token` is not a way around it either;
+those tokens expire too, and carry inference scope only.
+
+With several accounts the dates drift apart and you get a browser round-trip per
+account per month. Logging in early resets the whole 30 days, so the cheap move is
+to do them all on the day the earliest one comes due — after that they share one
+date and it's one sitting a month. `doctor` works this out for you:
+
+```
+$ hop doctor
+  accounts     /home/you/.claude/accounts (4 saved)
+  active       work
+  re-login     by 2026-08-30 (work); the other 3 by 2026-09-04
+               windows are ~30d from login and do not slide, so re-login all 4 on
+               2026-08-30 and they collapse to one date
+```
+
+You also get a per-account warning starting 14 days out, and `doctor --json`
+carries the same thing under `reloginPlan` if you want to hang a reminder off it.
+
+## Why not `claude setup-token`
+
+The obvious approach is a long-lived token per account exported as
+`CLAUDE_CODE_OAUTH_TOKEN`. It doesn't hold up:
+
+- those tokens carry inference scope only — `/api/oauth/profile` answers `403 OAuth
+  token does not meet scope requirement`, so you can't tell whose token you're
+  holding or whether it's still good;
+- they expire, and a dead one looks exactly like a live one until a request fails;
+- it's per-shell, so every terminal has to be primed before `claude` starts.
+
+Swapping the real credential block avoids all three and matches what Claude Code
+already does to itself.
+
+## Security
+
+Saved credentials are real, live Claude logins. `accounts/` is `700`, every
+profile is `600`, and writes are atomic. Nothing is ever sent anywhere except
+`api.anthropic.com` to resolve an email and plan. See
+[SECURITY.md](https://github.com/psychofict/claudehop/blob/master/SECURITY.md)
+for the threat model and how to report a problem.
+
+## Files
+
+```
+claudehop.py                 the tool (python3, stdlib only)
+shell/claudehop.sh           PATH, tab-completion, back-compat aliases
+extras/statusline-snippet.sh show the active account in the Claude Code statusline
+install.sh                   symlink/copy into ~/.claude, wire up the rc file
+pyproject.toml               packaging: one module, no dependencies, two commands
+test/test-switch.sh          99 checks against a throwaway config dir, no network
+assets/                      logo, icon, cover and social preview (svg sources + png)
+```
+
+## Tests
+
+```bash
+./test/test-switch.sh
+```
+
+Runs entirely inside a temp dir with fake credentials — it never reads or writes
+a real account, and never touches the network. Covers the swap, mcpOAuth
+preservation, token rotation, the stash path, concurrent switches, the macOS
+keychain backend (through a stand-in `security`), `add` rolling back a failed
+login, `add` surviving a teardown after a successful one, the refresh race, JSON
+output, table layout, housekeeping and file permissions.
+
+## Contributing
+
+Issues and pull requests welcome — see
+[CONTRIBUTING.md](https://github.com/psychofict/claudehop/blob/master/CONTRIBUTING.md).
+If `claudehop` saved you a browser round-trip this morning, a ⭐ on
+[GitHub](https://github.com/psychofict/claudehop) helps others find it.
+
+## Licence
+
+MIT. Not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" and
+"Claude Code" are trademarks of Anthropic, PBC, used here only to say what this
+works with.
+
+---
+
+<p align="center">
+  Made by <a href="https://ebenworks.co/">Ebenworks</a>
+</p>