claude-sessions

claude-sessions

Consulting for several clients means several Claude Code accounts, and Claude Code keeps one login per config dir. Start a session in the wrong terminal and the work, the memory and the bill land on the wrong account. A long task that hits the 5-hour rate limit stops until someone notices.

claude-sessions runs several Claude Code accounts on one machine, each isolated and labelled. It is open source under the MIT licence: github.com/macleodlabs-ai/claude-sessions.

One command per client

./claude-session --create acme clientA clientB
cc-acme

For each client, --create makes:

• its own config dir under ~/.claude-clients/<client>, so credentials and history stay apart
• a client CLAUDE.md that imports one shared global.md, so common rules are written once
• a statusline that names the client in every session footer
• a cc-<client> launcher, started in auto permission mode unless you pass another mode

A bare claude is refused on purpose, with the list of launchers, so no session starts unlabelled against the default account. command claude bypasses the guard when you mean it. Every subcommand is idempotent, and --revert removes the tooling while keeping the account dirs.

The footer

● acme │ Opus 5.5 │ 📁 growthOS │ 🧠 18% │ ⏳ 5h 42% · 7d 11% │ ↻ acme-2 — │ $3.12 +212/-9

Each footer shows the client, model, folder, context used, the 5-hour and 7-day rate-limit windows (green, yellow, red, with the reset time once the 5-hour window is hot), the other pool accounts' last-seen usage, and the session cost. It also shows whether the session bills a subscription or an API key: the launchers drop an exported ANTHROPIC_API_KEY for a dir logged in with a subscription.

Rate-limit rotation

claude-session --pool-add acme adds a second account, acme-2, with its own subscription. When the active account hits its limit, a StopFailure hook fires, the supervisor relaunches Claude Code under the next account and resumes the same conversation with --resume, about two seconds later, and submits a continuation prompt so the task picks straight back up. A Remote Control session re-pairs. When every account in the pool is limited it stops with a red message and the soonest reset, never a silent fallback.

• Shared tools. Session history, skills, plugins, agents and commands are shared across the pool by symlink. MCP server definitions and the enabled-plugins setting are synced on every rotation and when a session ends.
• Accounts stay put. Each dir is pinned to the account it first logged in with, and Claude Code itself then rejects a login into any other account. A drifted dir is skipped and flagged in red in the footer.
• Manual control. /rotate inside a session, or claude-session --rotate, switches now; --usage lists each account's usage and reset times.

It is a restart-and-resume supervisor, not a proxy: every request is made by the real claude binary with that account's own login. No tokens are extracted, shared or proxied. The README is plain about the terms of service: rotating accounts to extend usage is a gray area, so keep it to your own subscriptions at a human pace.

How it stays current

It is also a Claude Code plugin, sessions, which carries the skill and a session-start hook. Launchers and footers check for a new version at most once an hour and refresh every client from the tool's own clone; CCB_NO_AUTOUPDATE=1 turns that off. bash tests/run.sh runs the regression tests in a throwaway sandbox with a fake claude, and each test names the incident it guards.