Skip to content

Releases

fairshare 0.3.0

Choose a tag to compare

@Dongli99 Dongli99 released this 21 Nov 19:06

pickup now always continues the same session, and the new fork makes a copy on purpose. fairshare can also take over your per-account aliases.

After upgrading, run fairshare doctor --fix to put the updated skill in the hub.

Changed: pickup never copies (decision 32)

fairshare pickup used to continue a session that might still be running as a copy under a new id, without being asked. Tooling that tracks a session by its id then treated the session's own work as someone else's. Now:

  • A session that isn't running resumes in place, under its own id. This includes one you stopped by hand.
  • A worker, picked up by its main session, is stopped and resumed in place, without asking. fairshare started it, and its main session manages it.
  • Another session running in the background: from a terminal, fairshare asks Stop it and continue it here? [Y/n] and says so first if a turn is in progress. Without a terminal it refuses and names the stop command and fork.
  • A session open in a terminal is never stopped. Exit it there, then pick it up.
  • Bare pickup in a session not started by fairshare refuses, since nothing can stop that session. Use fairshare handoff or fairshare fork.

New

  • fairshare fork [SESSION]: a copy under a new id, on the best account (or -a). The original goes on, with its workers. Forks are named <name>-f2, -f3, and so on. The copy is told it is the copy and waits for instructions.
  • A session list. Bare fairshare pickup or fairshare fork from a terminal lists up to 8 recent main sessions to choose from: this folder's first, with their state (at its limit, running, stopped) and the last thing you typed in each. Workers are left out; their main session manages them, and pickup <id> still reaches one.
  • fairshare aliases [--remove]: replaces per-account CLAUDE_CONFIG_DIR aliases that still point at pre-hub folders with one marked block (alias X='fairshare run -a X'). It shows the diff and asks first, and makes a backup. setup and join offer it, and doctor warns while the old aliases are still in effect. fairshare run -a X <subcommand> (such as daemon status, agents --json, rm <id> or stop <id>) goes straight to Claude Code on that account's folder.
  • A usage log (~/.local/state/fairshare/usage/<account>.jsonl) records each change in the usage percentages and the dollars drawn since the previous one. It's groundwork for showing room left in dollars.

Fixed

  • A background session picked up on its own account always became a copy. Claude Code copies a background session resumed with any flag, and fairshare always added --name, --model and --effort. A known background session now resumes with none, keeping its saved name, model and effort. An explicit --model or --effort there is refused, with the matching fork command.
  • A launcher whose terminal closed while it was suspended (Ctrl-Z) stayed stopped forever, unable to clean up its child. It now stops itself the way Ctrl-Z does (SIGTSTP), which the kernel drops when no shell is left to resume it.
  • When a full reset is planned and due, every usage warning on that account now says to work to the limit rather than move.
  • Docs: how to recover when Claude Code's shared background process on an account breaks every worker started from it.

v0.2.1

Choose a tag to compare

@Dongli99 Dongli99 released this 20 Nov 17:52

fairshare's choice of account now says why, and a planned full reset no longer ends by mistake.

After upgrading, run fairshare doctor --fix to put the updated skill in the hub.

New

  • A choice of account says why. fairshare status ends with why A: A before B (score … vs …: room left per hour until it resets, so room that would expire unused is spent first); A: <reason>; B: <reason>. The warning's best other account and fairshare worker say the same. Percentages alone can point the other way: room that resets sooner is spent first, and a planned full reset counts as room. When fewer running sessions or your preference put a lower score first, it says so.
  • A planned full reset's reason now says what is there before the reset is used: +100% planned (26% left until it is used).
  • The skill tells the agent to follow the choice and override it (--account) only when the job needs more room than the chosen account has left now.

Fixed

  • A planned full reset could be marked used when the 5-hour window rolled over: the new window can show up just before the stored reset (given to the minute) passes, and its lower value read as a reset. A window within an hour of its own reset is no longer taken as evidence; a real reset still shows in the other window. If your plan ended this way, plan it again: fairshare full-reset ACCOUNT.

v0.2.0

Choose a tag to compare

@Dongli99 Dongli99 released this 19 Nov 23:29

Handoff by default, named sessions, a planned full reset, and more reliable workers.

After upgrading, run fairshare doctor --fix. It installs a new hook (Stop) and the updated skill in the hub. Until then, an agent following the old skill may call fairshare worker without --name, which is now required.

Changed

  • A usage warning (90% / 95%) now hands off by default: the agent writes a note and a fresh session continues on the best account, reading it first. [policy] warning_move = "pickup" keeps the old move (the same session, resumed with its whole context).
  • fairshare worker --name is required. The old default (w-<id>-<n>) said nothing in watch lines; the skill has the agent name the task (fs-watch-stops).
  • Your own handoff comes first. When a project's instructions say how to write a handoff (a file, where it goes), the skill has the agent follow them and pass that file's path as the note.

New

  • Session names that follow the work. A handoff's fresh session is named after the old one with the next number (fairshare-6a → fairshare-6a-h2 → -h3). A pickup keeps the session's name; when the old session still runs (Claude Code gives no two running sessions one name), it takes the next number instead.
  • fairshare full-reset ACCOUNT: plan a full reset your provider granted (Claude: refills the 5-hour and weekly limits, keeps your weekly reset day) for this week. That account ranks with +100% of its week until the reset is seen used or the week resets; the status bar shows +reset, then use reset from 90%, and the agent's warning reminds you to use it. fairshare cannot see held resets, so you plan; it never uses one for you. --cancel drops the plan.
  • A worker hears its main session's new id after a handoff or a pickup under a new id, with its name, so it can still reach it.

Fixed

  • watch looked for every worker in one account's session list; a background session is listed only through its own account, so workers on another account read "ended" too early. Now each worker is looked for in its own account's list.
  • watch could miss a worker's turn end for hours (Claude Code's list kept calling it busy). A worker's own Stop hook now reports it: worker X ended its turn and is waiting, with the count of background tasks it left running.
  • A handoff left the fresh session unlinked from the old one (its workers invisible to watch), and a session's recorded folder followed its shell's cd. The fresh session now takes the old one's place, in the old one's start folder.
pipx upgrade fairshare-cli
fairshare doctor --fix

v0.1.4

Choose a tag to compare

@Dongli99 Dongli99 released this 18 Nov 04:48

Remote Control from setup, a clearer message when a session moves near a limit, and a demo.

  • Setup asks once whether to turn on Remote Control for every session (Enter: yes), so you can follow and steer sessions from claude.ai or the Claude app. It asks only when your shared settings don't already say, and n writes nothing.
  • When a session moves off an account that is at 90% or more of a window (the move fairshare's warning asks the agent to make), the resumed session now starts with "because is near its usage limit" instead of "because a move was asked for".
  • The README opens with a 30-second demo: accounts ranked by real usage, a session starting on the best one, and the agent moving itself to another account near a limit, with its context.
pipx upgrade fairshare-cli

v0.1.3

Choose a tag to compare

@Dongli99 Dongli99 released this 17 Nov 23:48

Smarter choice of account at launch, and a launch bug fixed.

  • Sessions started close together spread out: when the accounts that can take work score within 10% of each other, a new session goes to the one with fewer sessions running. Outside 10%, the score decides as before.
  • A nearly full 5-hour window that resets within the hour now takes a new session only when no other account can work. What is left of such a window lasts minutes, so a session started there soon stopped and waited at its limit.
  • Fixed: when a nearly full account outscored one that could work, fairshare said "no account is eligible" and asked to wait instead of starting on the account that could. Launches now start on the best account that can take work, and fairshare status marks that one with >.
  • New: fairshare -v / --version prints the installed version.
pipx upgrade fairshare-cli

fairshare 0.1.2

Choose a tag to compare

@Dongli99 Dongli99 released this 17 Nov 21:47

Fixes a loop at a usage limit: when an account hit its 5-hour limit with the reset under an hour away, fairshare could restart the session on that same account again and again.

  • At a limit, fairshare now waits for Claude Code's own resume and says so once: the limit, when it resets, the best usable account, and that ! fairshare pickup moves the session now. To get automatic moves back, set resume_wait_minutes = 30 under [policy].
  • An account whose 5-hour window is spent takes no work until it resets, however soon.
  • A manual pickup never lands on an account that cannot work; with none, it says so and does nothing.
  • The launcher never resumes a session on the account that just stopped it before that account resets.
pipx upgrade fairshare-cli

fairshare 0.1.1 (alpha)

Choose a tag to compare

@Dongli99 Dongli99 released this 17 Nov 20:52

First public release.

pipx install fairshare-cli    # the command is `fairshare`
fairshare setup
fairshare
  • One assistant across several Claude Code subscriptions: shared history, memory, settings and skills in one hub; your own folders are only read.
  • Each session starts on the account whose budget is best used now, by real usage (Claude Code's own /usage and status line; no tokens, no undocumented endpoints).
  • When an account runs out mid-session: pickup (same session, another account), handoff (fresh session from a note), switch; background workers that checkpoint.
  • macOS and Linux, Python 3.11+. Early: expect rough edges, and please open issues.

On PyPI as fairshare-cli: the name fairshare belonged to an unrelated, removed project whose file names PyPI does not reuse. Read terms and limits before you start.