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 organization. If your dirs are logged in to more than one (say a private plan and a company team), ccherd uses one of them: subagents should run with the same skills and memories as their caller. 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. ccherd doctor shows what is linked; ccherd doctor --fix links the rest. 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. 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://github.com/bocode-labs/ccherd/blob/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.

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