fairshare-cli 0.1.1__py3-none-any.whl
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.
- fairshare/__init__.py +2 -0
- fairshare/browser.py +91 -0
- fairshare/cli.py +3266 -0
- fairshare/hub.py +272 -0
- fairshare/model.py +411 -0
- fairshare/plans/__init__.py +0 -0
- fairshare/plans/claude-max.toml +15 -0
- fairshare/plans/claude-pro.toml +13 -0
- fairshare/plans/claude-ultra.toml +17 -0
- fairshare/policy.py +73 -0
- fairshare/providers/__init__.py +12 -0
- fairshare/providers/base.py +193 -0
- fairshare/providers/claude.py +1176 -0
- fairshare/providers/claude_skill/SKILL.md +55 -0
- fairshare/session.py +113 -0
- fairshare/store.py +648 -0
- fairshare_cli-0.1.1.dist-info/METADATA +152 -0
- fairshare_cli-0.1.1.dist-info/RECORD +21 -0
- fairshare_cli-0.1.1.dist-info/WHEEL +4 -0
- fairshare_cli-0.1.1.dist-info/entry_points.txt +2 -0
- fairshare_cli-0.1.1.dist-info/licenses/LICENSE +21 -0
|
@@ -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,21 @@
|
|
|
1
|
+
fairshare/__init__.py,sha256=yM4GdnT-nYuDLoG_JmKPhEQo21di1u24v_7iv8kVhv0,98
|
|
2
|
+
fairshare/browser.py,sha256=eDFXkJ68y4-sMZ_KVerQ_NgcLZ1SYRWe2FhCkNc1rEg,3955
|
|
3
|
+
fairshare/cli.py,sha256=TYXug5dQZho9QeByLZiCGerrbGqm3fJZUCgKhT4G5oo,154765
|
|
4
|
+
fairshare/hub.py,sha256=hkQIEcac3--WwNlXH-gyWKbp1rWHgV4vqyRHs8t0kuA,12898
|
|
5
|
+
fairshare/model.py,sha256=BbVy87R-phnLgczVG9K6fS7bP-vaRVJ4EznknxjWa-8,17943
|
|
6
|
+
fairshare/policy.py,sha256=9MF0tVX4RE4GF4aHijz9Y1r6j59PXHS04EVGBG48hzU,3329
|
|
7
|
+
fairshare/session.py,sha256=wNEkVZ2HPfMm8pK-OPu5rULHgAP_h4rg_XBYx1FWNtY,4629
|
|
8
|
+
fairshare/store.py,sha256=hqDKCyvdFdbGfza3KRlkay6gwAm_knwrbhc0TTng10c,28852
|
|
9
|
+
fairshare/plans/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
10
|
+
fairshare/plans/claude-max.toml,sha256=zAqiPiPP86IY-bsyZJEEs0pkJYS9sgrmsRmaqXhIcr8,456
|
|
11
|
+
fairshare/plans/claude-pro.toml,sha256=YsJYSSHkgW4K2m6Z-jneFEJTirw1sYf4ErECAjOWaag,309
|
|
12
|
+
fairshare/plans/claude-ultra.toml,sha256=ul3NcC-B0LOrh40xOgVR0zS15RlE0tfSsNJV_1jnudg,639
|
|
13
|
+
fairshare/providers/__init__.py,sha256=jeqeg6hjTrQ60OYocbkiaqxokUj8WX-dyhg9rXO_28o,270
|
|
14
|
+
fairshare/providers/base.py,sha256=QUUZRk7PHfEPROOMO5Ru93-bN0JdHPjpv_zoigDOJEY,11043
|
|
15
|
+
fairshare/providers/claude.py,sha256=FFvaYuFtGN-gxbsda1XvjjJbdheG-wf-M89hNfssBYQ,59476
|
|
16
|
+
fairshare/providers/claude_skill/SKILL.md,sha256=fH9jdA3frzpBDgw1XvygUfIvmcI-7qOBSkMKKCrpWFA,3550
|
|
17
|
+
fairshare_cli-0.1.1.dist-info/METADATA,sha256=XgP9TuGiCAh48LKh51vCIz0DK-ObE59fIMWqP3wK9AI,7260
|
|
18
|
+
fairshare_cli-0.1.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
19
|
+
fairshare_cli-0.1.1.dist-info/entry_points.txt,sha256=l6tpucVwz8krM_bNu4AcpcurSYwAPYeD7fTDRaTKQd8,49
|
|
20
|
+
fairshare_cli-0.1.1.dist-info/licenses/LICENSE,sha256=IJVuG23EfH77TM3QXz7OZIc9bviGECgbRCFOKm3Ca40,1067
|
|
21
|
+
fairshare_cli-0.1.1.dist-info/RECORD,,
|
|
@@ -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.
|