Skip to main content

fairshare

Use multiple AI subscriptions like one.

Per-session, token-free, agent-aware.

fairshare runs Claude Code as one assistant across the subscriptions you already have: every account shares the same history, memory, settings and skills.

  • Per-session. Each session starts on the account whose budget is best used right now, judged by its real usage, its plan's size and the time to its weekly reset. Sessions running side by side spread across accounts, and moving one never moves the others.
  • Token-free. fairshare never reads, stores or swaps a login. Each account signs in through Claude Code itself, and usage comes from Claude Code's own /usage command and status line, so reading it spends nothing.
  • Agent-aware. Near a limit, fairshare tells the agent in the session. The agent hands off to a fresh session on another account with a note, or moves the session with its whole context, and decides what its background workers do.

The aim is to use every account fully before its weekly reset. It is a heuristic, not a guarantee.

A 30-second demo with three made-up accounts: fairshare status ranks them by real usage; fairshare starts a session on the best one; when that account reaches 95% of its 5-hour window, fairshare tells the agent, which writes a checkpoint and runs fairshare pickup, and the same session continues on another account

Status: early (0.x). Claude Code on Pro, Max and Ultra plans is the first supported provider. Runs on macOS and Linux; Windows is not supported.

Terms. Whether spreading work across several subscriptions fits a provider's terms is for you to check. docs/terms-and-limits.md says what fairshare deliberately never does and what is left for you to decide.

Quick start

pipx install fairshare-cli      # the command is `fairshare`
fairshare setup
fairshare

From source: git clone https://github.com/Dongli99/fairshare && pipx install ./fairshare. Installing needs network access once, to fetch the build tool; fairshare itself has no dependencies.

What setup does

fairshare setup builds the hub: one folder (default ~/.local/share/fairshare/hub) that holds a Claude Code config folder per account, all linked to one shared set of history, transcripts, memory, settings, CLAUDE.md and skills. Before you run it, know that:

  • it lists the Claude Code folders it finds, asks which to join and, for each, a name (Enter keeps the folder's own);
  • each account you join gets a new folder in the hub and one browser sign-in there, through Claude Code's own sign-in (fairshare never sees a token);
  • it copies your history, settings and skills into the hub. Your own folders are not changed: fairshare never writes them, and to label them it runs Claude Code's own sign-in check there;
  • the first folder joined decides the shared settings, CLAUDE.md and keybindings. Later folders' differences are shown, not applied. all joins signed-in folders first, your default ~/.claude first among them; type numbers to choose the order yourself;
  • it asks once whether to turn on Remote Control for every session (Enter: yes), unless your settings already say;
  • when an alias of yours still starts Claude Code on a folder you joined, it offers one block at the end of that shell file that overrides it (alias work='fairshare run -a work'), shown as a diff and asked first; your own lines stay, and fairshare aliases --remove undoes it. Plain claude still uses ~/.claude, outside the hub. Start sessions with fairshare.

Everyday use

  • fairshare starts a session on the best account. fairshare run <args> passes the arguments to Claude Code unchanged; fairshare run -a ID starts that account instead.
  • fairshare status lists the accounts, best first, with their usage and live sessions.
  • Near a limit (90% and 95% of a window), fairshare tells the agent in the session, naming the best account now. A skill fairshare installs in the hub teaches it to run fairshare handoff with a note at its next stopping point, unless little work is left: a fresh session continues on that account before the limit, reading the note first. (warning_move = "pickup" moves the same session instead, with its whole context.) It is the agent's call, so it usually happens, not always.
  • When an account hits its limit mid-session, fairshare checks it really is out, then leaves the session for Claude Code to resume by itself at the reset, with its whole context. A line and the status bar say which limit, when it resets, and the best account that can take work; ! fairshare pickup moves the session there now. resume_wait_minutes makes that move automatic. A session is never resumed on an account that is out.
  • Inside a session, ! fairshare pickup moves it now, ! fairshare handoff starts a fresh session from a written note, and ! fairshare starts a fresh session with nothing carried over (a switch).
  • From a terminal, fairshare pickup lists your recent sessions and continues the one you pick, the same session under its own id; fairshare fork continues a copy instead, and the original goes on.
  • A worker is a background session the main session starts for big work; near a limit, the main session decides what its workers do.
  • fairshare full-reset ID plans a full reset claude.ai granted that account for this week: it ranks with twice its week's room until the reset is used, and the status bar says when to use it. fairshare cannot see which resets you hold, so you plan them.
  • fairshare doctor checks the setup; fairshare doctor --fix repairs what it can. fairshare -v prints the installed version.

Every command, message and setting is in docs/usage.md.

How it decides

For each account:

score = capacity × (100 − weekly used %) ÷ hours until the weekly reset

The score is the share of the week's budget it must burn per hour to use it all; the highest score wins. That sends work to the account whose reset is nearest and whose budget is least used. Capacity is the plan's size (Pro = 1).

  • If the short (5-hour) window is nearly full, the score is scaled by what is left of that window, and new sessions go to an account that can work now. One resetting within the hour is still used when no other account can.
  • Between accounts within 10% of each other, a new session goes to the one with fewer sessions running.
  • An account whose week or short window is spent ranks below every usable account, however soon it resets: it cannot take work until then.
  • A planned full reset (fairshare full-reset) counts as 100% more weekly room until fairshare sees it used or the week resets.

Usage comes from Claude Code's own local /usage command, asked for every account at each launch (no model call, nothing spent), and from its status line during a session. The rule is one pure function in src/fairshare/policy.py.

Removal

fairshare uninstall        # changes nothing; says where everything is
pipx uninstall fairshare-cli

uninstall lists the config, the state folder (usage snapshots, session records, checkpoint notes) and the hub, and gives you a prompt for your own agent to merge the hub's history back into your own folders. They all stay until you delete them. The hub's accounts stay signed in; fairshare leave --logout ID signs one out before you delete the hub.

Requirements

  • macOS or Linux, Python 3.11+.
  • Claude Code, signed in with a Pro, Max or Ultra subscription on each account.

More

Prior art

ccm shares state between Claude Code accounts in a similar way. fairshare borrowed several of its ideas, reimplemented in its own code: ignoring stale statusLine redraws, reading claude auth status, warning about login-override variables, and merging a stray folder into the shared one with the clashing file renamed.

Contributing

See CONTRIBUTING.md. New providers and plans are welcome; the policy never changes for them.

License

MIT

Metadata

Release files for fairshare-cli 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fairshare-cli 0.3.0
File Size Uploaded Provenance Actions
fairshare_cli-0.3.0.tar.gz 311.7 kB With provenance Details for fairshare_cli-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fairshare-cli 0.3.0
File Interpreter ABI Platform Actions
fairshare_cli-0.3.0-py3-none-any.whl Python 3 none any Details for fairshare_cli-0.3.0-py3-none-any.whl

Total release size: 437.1 kB

Release files / fairshare_cli-0.3.0.tar.gz

Download URL fairshare_cli-0.3.0.tar.gz
Size 311.7 kB
Tags Source
SHA-256 checksum
How to use checksums
9675eb9e8e1441037d7c7118d3ef771b08dbfc23008b524a274d44cc266c8c92
BLAKE2b-256 checksum
How to use checksums
afab745ccd239116a8077a1fd802b092f25ac661bac6db4275ce7651f9ee1230
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / fairshare_cli-0.3.0-py3-none-any.whl

Download URL fairshare_cli-0.3.0-py3-none-any.whl
Size 125.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8a9b065f642555592a07798fe22c08d0bd8917db20abfb46aa2db7fc8ca8134e
BLAKE2b-256 checksum
How to use checksums
d4be71ad00d9a5e1e519e09bdeebe12a82b7af90519202cbf24e05770650b071
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for fairshare-cli 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fairshare_cli-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page