fairshare-cli 0.1.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. fairshare_cli-0.1.1/.githooks/pre-commit +6 -0
  2. fairshare_cli-0.1.1/.github/workflows/publish.yml +37 -0
  3. fairshare_cli-0.1.1/.github/workflows/tests.yml +35 -0
  4. fairshare_cli-0.1.1/.gitignore +13 -0
  5. fairshare_cli-0.1.1/CLAUDE.md +19 -0
  6. fairshare_cli-0.1.1/CONTRIBUTING.md +42 -0
  7. fairshare_cli-0.1.1/LICENSE +21 -0
  8. fairshare_cli-0.1.1/PKG-INFO +152 -0
  9. fairshare_cli-0.1.1/README.md +128 -0
  10. fairshare_cli-0.1.1/docs/architecture.md +1025 -0
  11. fairshare_cli-0.1.1/docs/terms-and-limits.md +22 -0
  12. fairshare_cli-0.1.1/docs/usage.md +438 -0
  13. fairshare_cli-0.1.1/pyproject.toml +41 -0
  14. fairshare_cli-0.1.1/src/fairshare/__init__.py +2 -0
  15. fairshare_cli-0.1.1/src/fairshare/browser.py +91 -0
  16. fairshare_cli-0.1.1/src/fairshare/cli.py +3266 -0
  17. fairshare_cli-0.1.1/src/fairshare/hub.py +272 -0
  18. fairshare_cli-0.1.1/src/fairshare/model.py +411 -0
  19. fairshare_cli-0.1.1/src/fairshare/plans/__init__.py +0 -0
  20. fairshare_cli-0.1.1/src/fairshare/plans/claude-max.toml +15 -0
  21. fairshare_cli-0.1.1/src/fairshare/plans/claude-pro.toml +13 -0
  22. fairshare_cli-0.1.1/src/fairshare/plans/claude-ultra.toml +17 -0
  23. fairshare_cli-0.1.1/src/fairshare/policy.py +73 -0
  24. fairshare_cli-0.1.1/src/fairshare/providers/__init__.py +12 -0
  25. fairshare_cli-0.1.1/src/fairshare/providers/base.py +193 -0
  26. fairshare_cli-0.1.1/src/fairshare/providers/claude.py +1176 -0
  27. fairshare_cli-0.1.1/src/fairshare/providers/claude_skill/SKILL.md +55 -0
  28. fairshare_cli-0.1.1/src/fairshare/session.py +113 -0
  29. fairshare_cli-0.1.1/src/fairshare/store.py +648 -0
  30. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.321/auth-status-logged-out.json +9 -0
  31. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.321/auth-status-pro.json +15 -0
  32. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/auth-status-logged-out.exit +1 -0
  33. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/auth-status-logged-out.json +9 -0
  34. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/auth-status-pro.json +15 -0
  35. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/note-stream.jsonl +59 -0
  36. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/transcript.jsonl +12 -0
  37. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/usage-logged-out.exit +1 -0
  38. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/usage-logged-out.json +67 -0
  39. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/usage-week-hot.json +68 -0
  40. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/usage-week-hot.txt +17 -0
  41. fairshare_cli-0.1.1/tests/fixtures/claude-2.1.322/usage.txt +17 -0
  42. fairshare_cli-0.1.1/tests/test_canaries.py +250 -0
  43. fairshare_cli-0.1.1/tests/test_checkpoints.py +99 -0
  44. fairshare_cli-0.1.1/tests/test_claude_and_store.py +175 -0
  45. fairshare_cli-0.1.1/tests/test_continuation.py +285 -0
  46. fairshare_cli-0.1.1/tests/test_degrade.py +397 -0
  47. fairshare_cli-0.1.1/tests/test_discovery.py +84 -0
  48. fairshare_cli-0.1.1/tests/test_fix.py +167 -0
  49. fairshare_cli-0.1.1/tests/test_handover.py +641 -0
  50. fairshare_cli-0.1.1/tests/test_honest.py +512 -0
  51. fairshare_cli-0.1.1/tests/test_hooks.py +241 -0
  52. fairshare_cli-0.1.1/tests/test_hub.py +997 -0
  53. fairshare_cli-0.1.1/tests/test_launcher.py +414 -0
  54. fairshare_cli-0.1.1/tests/test_note_progress.py +300 -0
  55. fairshare_cli-0.1.1/tests/test_pause.py +171 -0
  56. fairshare_cli-0.1.1/tests/test_pickup.py +920 -0
  57. fairshare_cli-0.1.1/tests/test_policy.py +154 -0
  58. fairshare_cli-0.1.1/tests/test_prefer.py +80 -0
  59. fairshare_cli-0.1.1/tests/test_session.py +191 -0
  60. fairshare_cli-0.1.1/tests/test_signin.py +225 -0
  61. fairshare_cli-0.1.1/tests/test_skill.py +95 -0
  62. fairshare_cli-0.1.1/tests/test_spend.py +211 -0
  63. fairshare_cli-0.1.1/tests/test_trust.py +311 -0
  64. fairshare_cli-0.1.1/tests/test_usage.py +482 -0
  65. fairshare_cli-0.1.1/tests/test_wait.py +146 -0
  66. fairshare_cli-0.1.1/tests/test_watch.py +148 -0
  67. fairshare_cli-0.1.1/tests/test_workers.py +287 -0
@@ -0,0 +1,6 @@
1
+ #!/bin/sh
2
+ # Blocks a plaintext secret at commit time. Enable once per clone: git config core.hooksPath .githooks
3
+ if command -v gitleaks >/dev/null 2>&1; then
4
+ exec gitleaks protect --staged --redact
5
+ fi
6
+ echo "fairshare pre-commit: gitleaks not installed, secret scan SKIPPED (brew install gitleaks)" >&2
@@ -0,0 +1,37 @@
1
+ name: publish
2
+ on:
3
+ push:
4
+ tags: ["v*"]
5
+ permissions:
6
+ contents: read
7
+ jobs:
8
+ build:
9
+ runs-on: ubuntu-latest
10
+ steps:
11
+ - uses: actions/checkout@v5
12
+ - uses: actions/setup-python@v6
13
+ with:
14
+ python-version: "3.13"
15
+ - name: tests
16
+ run: python -m unittest discover -s tests
17
+ env:
18
+ PYTHONPATH: src
19
+ - name: the tag names the package version
20
+ run: test "${GITHUB_REF_NAME#v}" = "$(PYTHONPATH=src python -c 'import fairshare; print(fairshare.__version__)')"
21
+ - run: python -m pip install build==1.2.2.post1 && python -m build
22
+ - uses: actions/upload-artifact@v4
23
+ with:
24
+ name: dist
25
+ path: dist/
26
+ pypi:
27
+ needs: build
28
+ runs-on: ubuntu-latest
29
+ environment: pypi
30
+ permissions:
31
+ id-token: write # trusted publishing: no token is stored anywhere
32
+ steps:
33
+ - uses: actions/download-artifact@v4
34
+ with:
35
+ name: dist
36
+ path: dist/
37
+ - uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,35 @@
1
+ name: tests
2
+ on:
3
+ push:
4
+ pull_request:
5
+ permissions:
6
+ contents: read
7
+ jobs:
8
+ unittest:
9
+ strategy:
10
+ fail-fast: false
11
+ matrix:
12
+ os: [ubuntu-latest, macos-latest]
13
+ python: ["3.11", "3.14"]
14
+ runs-on: ${{ matrix.os }}
15
+ steps:
16
+ - uses: actions/checkout@v5
17
+ - uses: actions/setup-python@v6
18
+ with:
19
+ python-version: ${{ matrix.python }}
20
+ - run: python -m unittest discover -s tests -v
21
+ env:
22
+ PYTHONPATH: src
23
+ windows-says-unsupported:
24
+ runs-on: windows-latest
25
+ steps:
26
+ - uses: actions/checkout@v5
27
+ - uses: actions/setup-python@v6
28
+ with:
29
+ python-version: "3.13"
30
+ - shell: bash
31
+ run: |
32
+ set +e
33
+ out=$(PYTHONPATH=src python -c "import fairshare.cli" 2>&1); code=$?
34
+ echo "exit $code: $out"
35
+ [ "$code" = 1 ] && echo "$out" | grep -q "macOS and Linux"
@@ -0,0 +1,13 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .venv/
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .DS_Store
9
+ # local state and credentials never belong in the repo
10
+ accounts.toml
11
+ snapshots/
12
+ .env
13
+ *.local.*
@@ -0,0 +1,19 @@
1
+ # fairshare
2
+
3
+ Routes AI-assistant sessions across several subscriptions by real usage. Open-source (MIT). **Nothing in this repo may reference any other project, private host, path, account or person's credentials.** One exception: the README's "Prior art" credit.
4
+
5
+ ## Layout
6
+ `src/fairshare/policy.py` the rule (pure) · `model.py` data + config loading · `providers/` one adapter per provider · `plans/` data files · `store.py` snapshots · `hub.py` the hub: links, start check, seeding · `browser.py` per-account sign-in browser · `session.py` runs the child session (signals, exit code) · `cli.py`. Seams and decisions: `docs/architecture.md`. Stance on terms: `docs/terms-and-limits.md`. User-facing behaviour: `docs/usage.md`. How to contribute: `CONTRIBUTING.md`.
7
+
8
+ ## Run
9
+ `PYTHONPATH=src python3 -m unittest discover -s tests -v` (stdlib only: no pytest, no dependencies, ever, without a reason written in docs/architecture.md).
10
+
11
+ ## Rules
12
+ 1. Restraint: add a field, flag or parameter only when no change to what exists does the job. A fix leaves the code simpler.
13
+ 2. The policy stays pure. I/O goes in `store.py`, `hub.py`, `browser.py`, `providers/` and `cli.py`; `model.py` reads the config and plan files.
14
+ 3. Never read, copy or log a login, token or cookie. Never call an undocumented endpoint. Never edit a user's file without showing the diff and getting a yes for that file; back it up first, and keep the edit reversible.
15
+ 4. A new provider or plan must need no change to `policy.py`. If it does, the abstraction is wrong: stop and say so.
16
+ 5. A wrong ranking is cheap and a lost or wrong *record* is not: snapshots are written atomically and never overwritten with less information.
17
+ 6. Commit after each validated change, and only when asked. Before committing run `git diff --staged --stat`: every file must belong to the task. Build or tests fail twice: stop and report.
18
+ 7. Quote real test output when reporting. A report is a claim until checked against the repo.
19
+
@@ -0,0 +1,42 @@
1
+ # Contributing
2
+
3
+ Thanks for looking. fairshare is small on purpose; these rules keep it that way.
4
+
5
+ ## Run the tests
6
+
7
+ ```
8
+ PYTHONPATH=src python3 -m unittest discover -s tests -v
9
+ ```
10
+
11
+ Python 3.11+, the standard library only: no pytest and no runtime dependencies. A new
12
+ dependency needs a reason written in `docs/architecture.md` first.
13
+
14
+ ## Before you write code
15
+
16
+ - Read `docs/architecture.md` (the seams and the numbered decisions) and
17
+ `docs/terms-and-limits.md` (what fairshare will never do).
18
+ - Open an issue first for anything larger than a fix, so we can agree on the shape.
19
+
20
+ ## Rules a change must keep
21
+
22
+ 1. **Restraint.** Add a field, flag or option only when no change to what exists does the job.
23
+ A fix should leave the code simpler.
24
+ 2. **The policy stays pure.** `policy.py` does no I/O. A new provider or plan must need no
25
+ change to it; if it does, the abstraction is wrong, and that is worth an issue.
26
+ 3. **No credentials.** Never read, copy, store or log a login, token or cookie. Never call an
27
+ undocumented endpoint.
28
+ 4. **The user's files.** Never edit a file outside the hub without showing the diff and getting
29
+ a yes for that file; back it up first.
30
+ 5. **Records are precious.** A wrong ranking is cheap; a lost or wrong record is not. Writes are
31
+ atomic and never replace a record with one that holds less.
32
+ 6. **Vendor facts are constants.** Anything a provider may rename (a command, a flag, a field)
33
+ is one named constant in that provider's file, with a recorded fixture in `tests/fixtures/`.
34
+ Scrub fixtures of every `*_id` value and anything personal.
35
+
36
+ ## Pull requests
37
+
38
+ - One change per pull request, with tests. Quote the test run in the description.
39
+ - Keep to the style of the code around it: short functions, plain names, docstrings that say
40
+ what and why.
41
+ - fairshare is not affiliated with any provider. Do not add anything that implies endorsement,
42
+ and keep provider trademarks out of names.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dongli Liu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,152 @@
1
+ Metadata-Version: 2.5
2
+ Name: fairshare-cli
3
+ Version: 0.1.1
4
+ Summary: One assistant across several AI-assistant subscriptions: shared history and settings, each session started on the account whose budget is best used now.
5
+ Project-URL: Homepage, https://github.com/Dongli99/fairshare
6
+ Project-URL: Issues, https://github.com/Dongli99/fairshare/issues
7
+ Project-URL: Documentation, https://github.com/Dongli99/fairshare/blob/main/docs/usage.md
8
+ Author: Dongli Liu
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: claude-code,cli,routing,subscriptions,usage
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Programming Language :: Python :: 3.13
21
+ Classifier: Programming Language :: Python :: 3.14
22
+ Requires-Python: >=3.11
23
+ Description-Content-Type: text/markdown
24
+
25
+ # fairshare
26
+
27
+ One assistant across the AI-assistant subscriptions you already have. Every account shares the
28
+ same history, memory, settings and skills, and each new session starts on the account whose
29
+ budget is best used right now, judged by its real usage. When an account runs out mid-task, the
30
+ session continues on another one with its context. The aim is to use every account fully before
31
+ its weekly reset. It is a heuristic, not a guarantee.
32
+
33
+ > Status: early (0.x). Claude Code on Pro, Max and Ultra plans is the first supported provider.
34
+ > Runs on macOS and Linux; Windows is not supported.
35
+
36
+ **Terms.** Whether spreading work across several subscriptions fits a provider's terms is for
37
+ you to check. [docs/terms-and-limits.md](https://github.com/Dongli99/fairshare/blob/main/docs/terms-and-limits.md) says what fairshare
38
+ deliberately never does and what is left for you to decide.
39
+
40
+ ```
41
+ $ fairshare status
42
+ > two claude-pro score 2.40 seven_day 40% used, resets in 25h
43
+ one claude-pro score 0.27 seven_day 70% used, resets in 111h
44
+
45
+ $ fairshare # starts a session on the account at the top of that list
46
+ ```
47
+
48
+ ## Quick start
49
+
50
+ ```
51
+ pipx install fairshare-cli # the command is `fairshare`
52
+ fairshare setup
53
+ fairshare
54
+ ```
55
+
56
+ From source: `git clone https://github.com/Dongli99/fairshare && pipx install ./fairshare`.
57
+ Installing needs network access once, to fetch the build tool; fairshare itself has no
58
+ dependencies.
59
+
60
+ ## What setup does
61
+
62
+ `fairshare setup` builds the **hub**: one folder (default `~/.local/share/fairshare/hub`) that
63
+ holds a Claude Code config folder per account, all linked to one shared set of history,
64
+ transcripts, memory, settings, CLAUDE.md and skills. Before you run it, know that:
65
+
66
+ - it lists the Claude Code folders it finds, asks which to join and, for each, a name (Enter
67
+ keeps the folder's own);
68
+ - each account you join gets a new folder in the hub and **one browser sign-in** there, through
69
+ Claude Code's own sign-in (fairshare never sees a token);
70
+ - it copies your history, settings and skills into the hub. Your own folders are not changed:
71
+ fairshare never writes them, and to label them it runs Claude Code's own sign-in check there;
72
+ - **the first folder joined decides the shared settings, CLAUDE.md and keybindings**. Later folders'
73
+ differences are shown, not applied. `all` joins signed-in folders first, your default
74
+ `~/.claude` first among them; type numbers to choose the order yourself;
75
+ - it does not touch your shell files: plain `claude` still uses `~/.claude`, outside the hub.
76
+ Start sessions with `fairshare`.
77
+
78
+ ## Everyday use
79
+
80
+ - `fairshare` starts a session on the best account. `fairshare run <args>` passes the arguments
81
+ to Claude Code unchanged; `fairshare run -a ID` starts that account instead.
82
+ - `fairshare status` lists the accounts, best first, with their usage and live sessions.
83
+ - When an account hits its limit mid-session, fairshare checks it really is out. If the limit
84
+ resets soon (30 minutes by default), Claude Code resumes the session by itself. Otherwise the
85
+ same session continues on the best other account, with its whole context.
86
+ - Inside a session, `! fairshare pickup` moves it now, `! fairshare handoff` starts a fresh
87
+ session from a written note, and `! fairshare` starts a fresh session with nothing carried
88
+ over (a *switch*).
89
+ - A *worker* is a background session the main session starts for big work; fairshare warns the
90
+ main session near a limit and it decides what its workers do. A skill in the hub teaches it.
91
+ - `fairshare doctor` checks the setup; `fairshare doctor --fix` repairs what it can.
92
+
93
+ Every command, message and setting is in [docs/usage.md](https://github.com/Dongli99/fairshare/blob/main/docs/usage.md).
94
+
95
+ ## How it decides
96
+
97
+ For each account:
98
+
99
+ ```
100
+ score = capacity × (100 − weekly used %) ÷ hours until the weekly reset
101
+ ```
102
+
103
+ The score is the share of the week's budget it must burn per hour to use it all; the highest
104
+ score wins. That sends work to the account whose reset is nearest and whose budget is least
105
+ used. Capacity is the plan's size (Pro = 1).
106
+
107
+ - If the short (5-hour) window is nearly full and not resetting within the hour, the score is
108
+ scaled by what is left of that window.
109
+ - An account whose week is spent ranks below every usable account.
110
+
111
+ Usage comes from Claude Code's own local `/usage` command, asked for every account at each
112
+ launch (no model call, nothing spent), and from its status line during a session. The rule is
113
+ one pure function in [`src/fairshare/policy.py`](https://github.com/Dongli99/fairshare/blob/main/src/fairshare/policy.py).
114
+
115
+ ## Removal
116
+
117
+ ```
118
+ fairshare uninstall # changes nothing; says where everything is
119
+ pipx uninstall fairshare-cli
120
+ ```
121
+
122
+ `uninstall` lists the config, the state folder (usage snapshots, session records, checkpoint
123
+ notes) and the hub, and gives you a prompt for your own agent to merge the hub's history back
124
+ into your own folders. They all stay until you delete them. The hub's accounts stay signed in;
125
+ `fairshare leave --logout ID` signs one out before you delete the hub.
126
+
127
+ ## Requirements
128
+
129
+ - macOS or Linux, Python 3.11+.
130
+ - Claude Code, signed in with a Pro, Max or Ultra subscription on each account.
131
+
132
+ ## More
133
+
134
+ - [docs/usage.md](https://github.com/Dongli99/fairshare/blob/main/docs/usage.md): every command, message, setting and exit code.
135
+ - [docs/terms-and-limits.md](https://github.com/Dongli99/fairshare/blob/main/docs/terms-and-limits.md): what fairshare never does.
136
+ - [docs/architecture.md](https://github.com/Dongli99/fairshare/blob/main/docs/architecture.md): the design decisions, seams and known limits.
137
+
138
+ ## Prior art
139
+
140
+ [ccm](https://github.com/revfactory/ccm) shares state between Claude Code accounts in a similar
141
+ way. fairshare borrowed several of its ideas, reimplemented in its own code: ignoring stale
142
+ statusLine redraws, reading `claude auth status`, warning about login-override variables, and
143
+ merging a stray folder into the shared one with the clashing file renamed.
144
+
145
+ ## Contributing
146
+
147
+ See [CONTRIBUTING.md](https://github.com/Dongli99/fairshare/blob/main/CONTRIBUTING.md). New providers and plans are welcome; the policy never
148
+ changes for them.
149
+
150
+ ## License
151
+
152
+ MIT
@@ -0,0 +1,128 @@
1
+ # fairshare
2
+
3
+ One assistant across the AI-assistant subscriptions you already have. Every account shares the
4
+ same history, memory, settings and skills, and each new session starts on the account whose
5
+ budget is best used right now, judged by its real usage. When an account runs out mid-task, the
6
+ session continues on another one with its context. The aim is to use every account fully before
7
+ its weekly reset. It is a heuristic, not a guarantee.
8
+
9
+ > Status: early (0.x). Claude Code on Pro, Max and Ultra plans is the first supported provider.
10
+ > Runs on macOS and Linux; Windows is not supported.
11
+
12
+ **Terms.** Whether spreading work across several subscriptions fits a provider's terms is for
13
+ you to check. [docs/terms-and-limits.md](https://github.com/Dongli99/fairshare/blob/main/docs/terms-and-limits.md) says what fairshare
14
+ deliberately never does and what is left for you to decide.
15
+
16
+ ```
17
+ $ fairshare status
18
+ > two claude-pro score 2.40 seven_day 40% used, resets in 25h
19
+ one claude-pro score 0.27 seven_day 70% used, resets in 111h
20
+
21
+ $ fairshare # starts a session on the account at the top of that list
22
+ ```
23
+
24
+ ## Quick start
25
+
26
+ ```
27
+ pipx install fairshare-cli # the command is `fairshare`
28
+ fairshare setup
29
+ fairshare
30
+ ```
31
+
32
+ From source: `git clone https://github.com/Dongli99/fairshare && pipx install ./fairshare`.
33
+ Installing needs network access once, to fetch the build tool; fairshare itself has no
34
+ dependencies.
35
+
36
+ ## What setup does
37
+
38
+ `fairshare setup` builds the **hub**: one folder (default `~/.local/share/fairshare/hub`) that
39
+ holds a Claude Code config folder per account, all linked to one shared set of history,
40
+ transcripts, memory, settings, CLAUDE.md and skills. Before you run it, know that:
41
+
42
+ - it lists the Claude Code folders it finds, asks which to join and, for each, a name (Enter
43
+ keeps the folder's own);
44
+ - each account you join gets a new folder in the hub and **one browser sign-in** there, through
45
+ Claude Code's own sign-in (fairshare never sees a token);
46
+ - it copies your history, settings and skills into the hub. Your own folders are not changed:
47
+ fairshare never writes them, and to label them it runs Claude Code's own sign-in check there;
48
+ - **the first folder joined decides the shared settings, CLAUDE.md and keybindings**. Later folders'
49
+ differences are shown, not applied. `all` joins signed-in folders first, your default
50
+ `~/.claude` first among them; type numbers to choose the order yourself;
51
+ - it does not touch your shell files: plain `claude` still uses `~/.claude`, outside the hub.
52
+ Start sessions with `fairshare`.
53
+
54
+ ## Everyday use
55
+
56
+ - `fairshare` starts a session on the best account. `fairshare run <args>` passes the arguments
57
+ to Claude Code unchanged; `fairshare run -a ID` starts that account instead.
58
+ - `fairshare status` lists the accounts, best first, with their usage and live sessions.
59
+ - When an account hits its limit mid-session, fairshare checks it really is out. If the limit
60
+ resets soon (30 minutes by default), Claude Code resumes the session by itself. Otherwise the
61
+ same session continues on the best other account, with its whole context.
62
+ - Inside a session, `! fairshare pickup` moves it now, `! fairshare handoff` starts a fresh
63
+ session from a written note, and `! fairshare` starts a fresh session with nothing carried
64
+ over (a *switch*).
65
+ - A *worker* is a background session the main session starts for big work; fairshare warns the
66
+ main session near a limit and it decides what its workers do. A skill in the hub teaches it.
67
+ - `fairshare doctor` checks the setup; `fairshare doctor --fix` repairs what it can.
68
+
69
+ Every command, message and setting is in [docs/usage.md](https://github.com/Dongli99/fairshare/blob/main/docs/usage.md).
70
+
71
+ ## How it decides
72
+
73
+ For each account:
74
+
75
+ ```
76
+ score = capacity × (100 − weekly used %) ÷ hours until the weekly reset
77
+ ```
78
+
79
+ The score is the share of the week's budget it must burn per hour to use it all; the highest
80
+ score wins. That sends work to the account whose reset is nearest and whose budget is least
81
+ used. Capacity is the plan's size (Pro = 1).
82
+
83
+ - If the short (5-hour) window is nearly full and not resetting within the hour, the score is
84
+ scaled by what is left of that window.
85
+ - An account whose week is spent ranks below every usable account.
86
+
87
+ Usage comes from Claude Code's own local `/usage` command, asked for every account at each
88
+ launch (no model call, nothing spent), and from its status line during a session. The rule is
89
+ one pure function in [`src/fairshare/policy.py`](https://github.com/Dongli99/fairshare/blob/main/src/fairshare/policy.py).
90
+
91
+ ## Removal
92
+
93
+ ```
94
+ fairshare uninstall # changes nothing; says where everything is
95
+ pipx uninstall fairshare-cli
96
+ ```
97
+
98
+ `uninstall` lists the config, the state folder (usage snapshots, session records, checkpoint
99
+ notes) and the hub, and gives you a prompt for your own agent to merge the hub's history back
100
+ into your own folders. They all stay until you delete them. The hub's accounts stay signed in;
101
+ `fairshare leave --logout ID` signs one out before you delete the hub.
102
+
103
+ ## Requirements
104
+
105
+ - macOS or Linux, Python 3.11+.
106
+ - Claude Code, signed in with a Pro, Max or Ultra subscription on each account.
107
+
108
+ ## More
109
+
110
+ - [docs/usage.md](https://github.com/Dongli99/fairshare/blob/main/docs/usage.md): every command, message, setting and exit code.
111
+ - [docs/terms-and-limits.md](https://github.com/Dongli99/fairshare/blob/main/docs/terms-and-limits.md): what fairshare never does.
112
+ - [docs/architecture.md](https://github.com/Dongli99/fairshare/blob/main/docs/architecture.md): the design decisions, seams and known limits.
113
+
114
+ ## Prior art
115
+
116
+ [ccm](https://github.com/revfactory/ccm) shares state between Claude Code accounts in a similar
117
+ way. fairshare borrowed several of its ideas, reimplemented in its own code: ignoring stale
118
+ statusLine redraws, reading `claude auth status`, warning about login-override variables, and
119
+ merging a stray folder into the shared one with the clashing file renamed.
120
+
121
+ ## Contributing
122
+
123
+ See [CONTRIBUTING.md](https://github.com/Dongli99/fairshare/blob/main/CONTRIBUTING.md). New providers and plans are welcome; the policy never
124
+ changes for them.
125
+
126
+ ## License
127
+
128
+ MIT