ccherd

Run Claude Code subagents across several Claude accounts.

If you have more than one Claude subscription, each lives in its own CLAUDE_CONFIG_DIR (~/.claude, ~/.claude-work, ...). Claude Code only sees the sessions of the account it runs under, and a subagent always spends the quota of its parent. ccherd fixes both:

• it lists and messages sessions across all your accounts, and
• it starts background subagents on the account whose weekly quota is most likely to expire unused, so you use what you pay for before paying extra.

macOS and Linux. Needs Python 3.10+ and the claude CLI.

Install

uv tool install ccherd
# or
pipx install ccherd

Setup

Run this inside the repo where you want to use ccherd:

ccherd setup

It asks:

0. Whether each subscription already has its own config dir. If not, it asks how many subscriptions you have, creates numbered dirs next to your current one (~/.claude, ~/.claude-2, ...), prints the command to log in to each, and stops. Log in, then run ccherd setup again.
1. Which organizations. Every login belongs to an organization: a company team, or for a private plan "'s Organization". If your dirs span more than one, you tick the ones ccherd may use - typically your company team, or all your private plans. Subagents should run with the same skills and memories as their caller, so a private plan next to a company team usually stays out. Dirs of other organizations are left out, even if a pattern matches them.
2. Which config dirs are your accounts. It lists every ~/.claude* dir. A numbered family like ~/.claude-work, ~/.claude-work2, ~/.claude-work3 gets one extra line: tick it to save the pattern, so ~/.claude-work4 is picked up later without running setup again. Or tick single dirs. Anything elsewhere goes into the "Other" line.
3. Where to put the Claude skill: in this repo (.claude/skills/ccherd) or in every account's config dir.
4. Whether to add a short note to CLAUDE.local.md. Creates the file if needed and adds it to .gitignore.

At the end it runs ccherd doctor.

Shared skills and memories

A subagent should behave like the session that started it. So all accounts should share skills, projects (memories and conversations), agents, plugins, settings.json and CLAUDE.md: one account holds them, the others symlink to it. This is optional: ccherd doctor only warns about what is not linked, and ccherd doctor --fix links it when you want that. An account's own copy is merged into the shared one first; files that differ stay in a *.ccherd-backup-* dir next to it. Nothing is deleted.

Every question has a flag, so setup also runs without a terminal: ccherd setup --list shows what there is, then for example ccherd setup --organization "Acme" --schema ~/.claude-work --skill repo --claude-local (--organization can be given several times). ccherd setup --help lists all flags.

Let your agent do it

Point your agent at this repo and tell it:

Set up ccherd for me, following https://raw.githubusercontent.com/bocode-labs/ccherd/main/docs/agent-setup.md

It installs ccherd, shows you what it found, asks you the few questions that are yours to answer, and checks the result with ccherd doctor. Logging in to a new account opens a browser, so that part stays with you.

Config is stored in ~/.config/ccherd/config.json.

Commands

ccherd --help explains every command and all its arguments.

spawn, agents, send, result, log and kill are meant to be run by Claude from inside a session; the skill tells it how. A finished subagent reports back to the session that started it as a message.

How auto picks an account

Score = weekly % left ÷ hours until the weekly reset × free share of the 5-hour window. The highest score wins. Accounts at ≥ 90 % of their 5-hour window or ≥ 98 % of their week are skipped.

When every account is past its limits, spawn refuses by default. ccherd config when-saturated use makes it spawn anyway, on an account that has extra usage enabled. The limits themselves are settings too (five-hour-limit, weekly-limit). Change them any time.

ccherd never refreshes an OAuth token itself - the refresh token rotates, so that would log out the Claude Code instance that owns the account. When an access token has expired and no session runs on that account, it lets Claude Code renew it (claude auth status).

Contributing

If you are using this and have trouble during setup: we welcome PRs that improve it for everyone. If you ran the setup through an agent and something did not go smoothly, please open a PR too.

Development

PYTHONPATH=src python3 -m unittest discover -s tests

License

MIT