hatcheck 0.2.0__tar.gz → 0.3.0__tar.gz

{hatcheck-0.2.0 → hatcheck-0.3.0}/Cargo.lock

@@ -41,15 +41,6 @@ version = "2.13.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
 
-[[package]]
-name = "block-buffer"
-version = "0.10.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
-dependencies = [
- "generic-array",
-]
-
 [[package]]
 name = "bumpalo"
 version = "3.20.3"
@@ -124,15 +115,6 @@ version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
-[[package]]
-name = "cpufeatures"
-version = "0.2.17"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
-dependencies = [
- "libc",
-]
-
 [[package]]
 name = "crc32fast"
 version = "1.5.2"
@@ -142,32 +124,12 @@ dependencies = [
  "cfg-if",
 ]
 
-[[package]]
-name = "crypto-common"
-version = "0.1.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
-dependencies = [
- "generic-array",
- "typenum",
-]
-
 [[package]]
 name = "deranged"
 version = "0.5.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9e9de72ce2ad1f90dc62fa25f0f430ef85eb4b0d8fa0be4f30373bc40a21d28e"
 
-[[package]]
-name = "digest"
-version = "0.10.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
-dependencies = [
- "block-buffer",
- "crypto-common",
-]
-
 [[package]]
 name = "displaydoc"
 version = "0.2.7"
@@ -269,16 +231,6 @@ dependencies = [
  "slab",
 ]
 
-[[package]]
-name = "generic-array"
-version = "0.14.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
-dependencies = [
- "typenum",
- "version_check",
-]
-
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -310,7 +262,7 @@ checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 
 [[package]]
 name = "hatcheck"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "base64 0.22.1",
  "chrono",
@@ -322,7 +274,6 @@ dependencies = [
  "png",
  "serde",
  "serde_json",
- "sha2",
  "terminal_size",
  "ureq",
  "windows-sys 0.59.0",
@@ -784,17 +735,6 @@ dependencies = [
  "zmij",
 ]
 
-[[package]]
-name = "sha2"
-version = "0.10.9"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
-dependencies = [
- "cfg-if",
- "cpufeatures",
- "digest",
-]
-
 [[package]]
 name = "shlex"
 version = "2.0.1"
@@ -914,12 +854,6 @@ dependencies = [
  "zerovec",
 ]
 
-[[package]]
-name = "typenum"
-version = "1.20.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
-
 [[package]]
 name = "unicode-ident"
 version = "1.0.27"

{hatcheck-0.2.0 → hatcheck-0.3.0}/Cargo.toml

@@ -6,7 +6,7 @@ exclude = ["desktop/src-tauri"]
 resolver = "2"
 
 [workspace.package]
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 license = "MIT"
 rust-version = "1.90"

{hatcheck-0.2.0 → hatcheck-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hatcheck
-Version: 0.2.0
+Version: 0.3.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -52,12 +52,21 @@ keeping one profile per account: `cl` and `cx` run Claude Code and Codex with a
 `hatcheck` lists the recent sessions in all of them, with the command that resumes each one and
 what's left of each plan. `hatcheck usage` shows the plans, `hatcheck best` says which account to use
 now, `hatcheck where` finds a session, `hatcheck open` resumes one in a new terminal, and
-`hatcheck move` carries one over to another profile, or converts it between Claude Code and Codex.
-`hatcheck bind` ties a folder to a profile, so `cl` and `cx` pick it there, and `--json` gives the
-sessions and plans to scripts and status bars. `claude-z` and `claude-k` run Claude Code on Z.ai's
+`hatcheck move` carries one over to another profile, or converts it between Claude Code and Codex,
+and `hatcheck fork` brings one in there as a new session, keeping the original.
+`hatcheck relocate` brings a moved project folder's sessions along, `hatcheck bind` ties a folder
+to a profile, so `cl` and `cx` pick it there, and `--json` gives the sessions and plans to scripts
+and status bars. `claude-z` and `claude-k` run Claude Code on Z.ai's
 GLM or Kimi's models instead, in any profile. See
 [Claude Code and Codex CLI profiles](#claude-code-and-codex-cli-profiles).
 
+**Not a gateway.** Hatcheck is never between an agent and its model. It rewrites no agent's
+config, holds no login, and runs nothing in the background. Tools such as
+[magpie](https://github.com/yetone/magpie) put a local gateway in that path so any agent can use
+any model and accounts can take over from each other when a quota runs out. If that is what you
+want, use one of those. Hatcheck is for the opposite case: keeping a work account and a personal
+account apart, and knowing which one each session ran on. See [Rules it keeps](#rules-it-keeps).
+
 |                                 | macOS | Linux | Windows |
 |---------------------------------|:-----:|:-----:|:-------:|
 | Claude Desktop instances        |  yes  | no official Desktop app | [planned](#roadmap) |
@@ -350,6 +359,11 @@ which is listed too. Codex files its sessions by the date they started, archived
 `hat` is the short name: `hat`, `hat usage`, `hat move …` and so on work the same. `hat check` is the name
 in two words, so it's `hat` again: `hat check` lists sessions and `hat check usage` is `hat usage`.
 
+A subcommand can be cut to its first letters, after `hat` or `hatcheck`: `hat m …` is `hat move …`
+and `hat f …` is `hat fork …`. Where two share a letter, it goes to the one used more: `b` is
+`best`, `s` is `show` and `u` is `usage`, so `bind` and `unbind` take two letters, `bi` and `un`.
+What it prints, and the commands it suggests, use the whole name.
+
 Lists the Claude Code sessions from every `~/.claude*` profile, and the Codex sessions from every
 `~/.codex*` home, that were active in the last 24 hours or are still open, grouped by folder and
 newest first. Run from a folder that has sessions, it lists
@@ -377,7 +391,7 @@ cd ~/notes
     9h  Write release notes · main
         cl work --resume 7e8f9a0b-1c2d-4e3f-8a4b-5c6d7e8f9a0b
 Profiles: ~/.claude (1), ~/.claude-personal (1), ~/.claude-work (4)
-Usage from Claude Code's last snapshot (token expired; run claude in this profile to renew it): ~/.claude-personal 9h ago
+Usage from Claude Code's last snapshot (Claude Code's /usage couldn't fetch new numbers; offline, or rate limited?): ~/.claude-personal 9h ago
 ```
 
 - Run the folder's `cd` line, then the session's command. Sessions still open in a terminal are
@@ -403,8 +417,11 @@ Usage from Claude Code's last snapshot (token expired; run claude in this profil
   like Desktop ones, and Codex's own approval reviews aren't listed.
 - Since the usage is a shell comment, pasting the whole line runs just the command (zsh needs
   `setopt interactivecomments`).
-- Usage is fetched live, one request per account. When that fails (expired token, rate limit), Claude
-  Code's last saved snapshot is used instead and named at the bottom with its age.
+- Usage is fetched live: Claude Code's `/usage` is run once per account, in its profile, and the
+  snapshot it saves is read (see [`hatcheck usage`](#hatcheck-usage-plan-usage-for-every-profile)
+  below); ChatGPT's usage endpoint is asked once per Codex account. When that gives nothing new
+  (offline, not signed in, rate limited), the last saved snapshot is used instead and named at the
+  bottom with its age.
 - A session that ran in a folder [bound](#hatcheck-bind-tie-a-folder-to-a-profile) to another
   profile is marked `⚠ folder bound to ~/.claude-work`, so it's easy to spot and `hatcheck move`.
 - What it reads from each session file is cached, in `sessions.json` in `~/Library/Caches/hatcheck`
@@ -436,7 +453,7 @@ Sorted by Fable: those with some left first, the soonest reset on top; then thos
 ~/.claude  pro · live
   session (5h)       62% ██████▎░░░  █████▍░░░░ resets 5:01pm (in 2h41m)
   week (all models)  91% █████████▏  ████▍░░░░░ resets Sat 4:20pm (in 3d2h)
-~/.claude-personal  pro · cached 9h00m ago (token expired; run claude in this profile to renew it)
+~/.claude-personal  pro · cached 9h00m ago (Claude Code's /usage couldn't fetch new numbers; offline, or rate limited?)
   session (5h)         ? ··········             reset 10:20am, after this snapshot
   week (all models)  97% █████████▊  ███████▎░░ resets Mon 4:20pm (in 5d2h)
 ~/.codex-work  ChatGPT plus · live
@@ -446,19 +463,26 @@ Sorted by Fable: those with some left first, the soonest reset on top; then thos
 
 - Accounts are sorted by their Fable limit. First come those with some Fable left, the soonest
   Fable reset on top: what's left there goes unused once it resets, so that's the one to use first.
-  Next come those out of Fable, or out of the weekly limit for all models, which Fable counts against
-  too, the soonest back on top. Then come accounts without a Fable limit, such as Pro plans, and
-  Codex homes. A snapshot saved before its Fable limit reset counts as full until the reset after.
+  An account past 90% of its Fable limit goes behind the fresher ones, and past 98% behind those
+  too: nearly out, it's the one to use last. Next come those out of Fable, or out of the weekly
+  limit for all models, which Fable counts against too, the soonest back on top. Then come accounts
+  without a Fable limit, such as Pro plans, and Codex homes. A snapshot saved before its Fable limit
+  reset counts as full until the reset after.
 - Each limit has two bars: what's left of it, then how much of its window, 5 hours or a week, is
   left before it resets. In a terminal the second goes from blue with most of the window to go,
   through gold and orange, to red as the reset nears. When the first bar is shorter than the
   second, as for `Fable` here, the limit is being used up faster than its window runs out. A limit
   without a reset time, like an unused 5-hour session, has no time bar.
-- It reads each profile's OAuth token from the macOS Keychain, or from the profile's
-  `.credentials.json` on Linux and Windows, and asks the same endpoint as Claude Code's `/usage`. The token is only read, never refreshed: a refresh rotates it and would sign Claude Code
-  out of that profile.
-- When a token has expired or the endpoint rate-limits the account, Claude Code's last saved snapshot
-  is shown with its age. Run `claude` (or `cl <name>`) in that profile to renew the token.
+- A Claude Code account's numbers come from Claude Code itself: `claude -p /usage` is run in the
+  profile, with no tools, MCP servers, settings or transcript, which asks Anthropic with the
+  profile's own login and saves the answer in the profile's `.claude.json`; that snapshot is what's
+  shown. hatcheck never reads a login: the plan's name comes from the account details Claude Code
+  keeps beside the snapshot. The runs take about a second each, in parallel, from a folder of
+  hatcheck's own (`claude-usage` in its cache folder), so the one empty project folder Claude Code
+  makes for the folder it runs in is the same every time.
+- When that gives nothing new (`claude` not on the `PATH`, the profile not signed in, offline, or
+  Anthropic rate-limiting the account), Claude Code's last saved snapshot is shown with its age and
+  the reason.
 - Profiles signed in to the same account are shown together. Per-model limits such as
   `week (Fable)` are named in violet, with their bar drawn in it, to tell them from `week (all
   models)`; the % keeps the severity's colour. Quota fields the server
@@ -476,18 +500,19 @@ Sorted by Fable: those with some left first, the soonest reset on top; then thos
 
 ### `hatcheck move`: carry on a session with another profile
 
-When one account runs low, continue a session on another profile, or in the other agent. It copies
-the session by default; `--no-keep` deletes the original once the copy is checked, which moves it.
+When one account runs low, continue a session on another profile, or in the other agent. It moves
+the session: the original is deleted once every copied file is checked against it, and an older
+copy never replaces a newer one. `--keep` keeps the original, which copies it instead.
 
 ```
 $ hatcheck move 9a8b7c6d work
-Copied session 9a8b7c6d "Add rate limiting to the login endpoint" from ~/.claude to ~/.claude-work:
+Moved session 9a8b7c6d "Add rate limiting to the login endpoint" from ~/.claude to ~/.claude-work:
   transcript                 53.0 KB
   subagents and tool output  3 files
   /rewind file snapshots     4 files
   plan                       quiet-river-plan.md
 Paths in the conversation to these files now point to the copies.
-Kept the original in ~/.claude; --no-keep deletes it once the copy is checked.
+Deleted the original from ~/.claude; the plan file stays, since sessions can share one.
 Resume it with:
   cd ~/code/api
   cl work --resume 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
@@ -495,9 +520,9 @@ Resume it now in ~/.claude-work? [y/N]
 ```
 
 - It copies the transcript, the folder of subagent transcripts and saved tool output, the `/rewind`
-  file snapshots and the plan file, keeping their timestamps, and checks every copied file. Paths in
-  the conversation that point at those files are changed to point at the copies, except inside
-  Claude's thinking, whose signatures would stop matching.
+  file snapshots and the plan file, keeping their timestamps, and checks every copied file before it
+  deletes anything. Paths in the conversation that point at those files are changed to point at the
+  copies, except inside Claude's thinking, whose signatures would stop matching.
 - A session that's open in a terminal is refused: quit it first, so it stops changing.
   `hatcheck` marks those `● open`.
 - Resume it with the printed command, from the directory it ran in, or answer `y` when it asks and
@@ -506,38 +531,51 @@ Resume it now in ~/.claude-work? [y/N]
   permissions, MCP servers, plugins and project memory are the new profile's. If the new account
   rejects the signatures on earlier thinking, Claude Code drops those thinking blocks and carries
   on.
-- Plan files stay in the old profile even with `--no-keep`, since sessions can share one.
+- The plan file stays in the old profile, since sessions can share one.
 - If the session's last reply came from Z.ai or Kimi, it also prints the `cl -z` or `cl -k` command
   that carries on there instead of on the new profile's Claude plan.
 
 #### When the profile already has a copy
 
-A session copied to another profile and carried on there can be moved back: the copy it left
-behind is an older version of it. The two copies are compared line by line:
+A session copied to another profile with `--keep` and carried on there can be moved back: the copy
+it left behind is an older version of it. The two copies are compared line by line:
 
 - **The copy there is older**, because the session went on from it: it's brought up to date, and
   each item shows `(updated an older copy)`. Nothing is lost, since the copy being moved starts with
   all of it.
-- **The copy there is newer**, because the session went on there: nothing is copied. With
-  `--no-keep`, the older copy here is deleted.
-- **Both went on** after the copy was made: nothing is copied, since that would lose the prompts
+- **The copy there is newer**, because the session went on there: it stops and changes nothing,
+  since putting this copy there would lose what came after. It prints the command that resumes the
+  session there, and the files of the older copy here, to delete if you don't want them.
+- **Both went on** after the copy was made: nothing is moved, since that would lose the prompts
   only the copy there has. It says when they split and how many prompts each has had since.
-  `--fork` brings this one in as a new session with its own ID and keeps both, as Claude Code's
-  `claude --resume <id> --fork-session` and `codex fork` do. Or delete the copy there first.
+  [`hatcheck fork`](#hatcheck-fork-a-session-as-a-new-one-in-another-profile) brings this one in
+  as a new session with its own ID and keeps both. Or delete the copy there first.
+
+```
+$ hatcheck move 9a8b7c6d work
+~/.claude-work already has session 9a8b7c6d "Add rate limiting to the login endpoint", with everything in this copy and more: the session went on there. This copy is older, so nothing was moved.
+Resume it there with:
+  cd ~/code/api
+  cl work --resume 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
+To drop the older copy in ~/.claude, delete:
+  ~/.claude/projects/-Users-me-code-api/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d.jsonl
+  ~/.claude/projects/-Users-me-code-api/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
+  ~/.claude/file-history/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
+```
 
 ```
 $ hatcheck move 9a8b7c6d default
-Session 9a8b7c6d went on in both ~/.claude-work and ~/.claude after Oct 15 01:40: 3 new prompts in ~/.claude-work, 1 in ~/.claude. Copying this one over would lose what's only in ~/.claude, so nothing was copied.
+Session 9a8b7c6d went on in both ~/.claude-work and ~/.claude after Oct 15 01:40: 3 new prompts in ~/.claude-work, 1 in ~/.claude. Moving this one over would lose what's only in ~/.claude, so nothing was moved.
 To keep both, bring this one in as a new session with its own ID:
-  hatcheck move 9a8b7c6d default --fork
+  hatcheck fork 9a8b7c6d default
 Or delete the copy in ~/.claude first, to replace it:
   ~/.claude/projects/-Users-me-code-api/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d.jsonl
+  ~/.claude/projects/-Users-me-code-api/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
+  ~/.claude/file-history/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
 ```
 
-A fork changes the session's ID in its records and gives it its own folders for subagents, saved
-tool output and `/rewind` snapshots. Its message IDs stay the same, as in Claude Code's own fork.
-Resuming a fork, a round trip and a copy that went on in both profiles were tested with the real
-`claude` (2.1.301).
+A round trip and a copy that went on in both profiles were tested with the real `claude`
+(2.1.301).
 
 When more than one profile has the session, you're asked which copy to take. The one used last
 comes first and is the default, and each other one says how it stands to it:
@@ -565,7 +603,7 @@ Converted Codex session 019a8c1e "Add retries to the uploader" from ~/.codex-wor
   tool calls                 191, as text with their output shortened
   left out                   Codex's reasoning, images, goals and subagent sessions
   new session                6f6749d7-0f59-4683-997c-a3595421b93f (241.9 KB)
-The original stays in ~/.codex-work.
+The original stays in ~/.codex-work, since a conversion leaves things out.
 Resume it with:
   cd ~/code/api
   cl work --resume 6f6749d7-0f59-4683-997c-a3595421b93f
@@ -573,9 +611,8 @@ Resume it now in ~/.claude-work? [y/N]
 ```
 
 - Between Codex homes signed in to the same ChatGPT account, the session file is copied as it is,
-  with its ID and its name, and `--no-keep` works as for Claude Code. A copy already there is
-  compared the same way, and `--fork` gives the copy a new ID in its file name, its
-  `session_meta` and its events.
+  with its ID and its name, and the original is deleted once the copy is checked, as for Claude
+  Code. A copy already there is compared the same way.
 - Between Claude Code and Codex (`hatcheck move 3f1c2a9e codex:work` goes the other way), and
   between Codex homes on different accounts, the session is converted into a new one with a new ID,
   and the original is always kept. Codex encrypts its reasoning and its summaries of compacted
@@ -599,9 +636,87 @@ Resume it now in ~/.claude-work? [y/N]
 | `SESSION`        | the session ID, or the start of it                                           |
 | `PROFILE`        | where it goes: `NAME` for `~/.claude-NAME`, `default` for `~/.claude`, `codex` for `~/.codex`, `codex:NAME` for `~/.codex-NAME`, or a path |
 | `--from PROFILE` | the profile or home to take it from, when more than one has it; without it you're asked, with the one used last as the default, and a script or `--json` gets that one |
-| `--no-keep`      | delete the original once the copy is checked, which moves it (not when converting) |
-| `--fork`         | copy it in as a new session with its own ID, leaving a copy already there as it is (a converted session always gets one) |
-| `--dry-run`      | show what would be copied, converted and deleted, and change nothing         |
+| `--keep`         | keep the original, which copies the session rather than moving it (a converted session's original is always kept) |
+| `--dry-run`      | show what would be moved, copied, converted and deleted, and change nothing  |
+
+`--no-keep`, which a move needed before it was the default, is still accepted, and so is `--fork`,
+which does what [`hatcheck fork`](#hatcheck-fork-a-session-as-a-new-one-in-another-profile) does.
+
+### `hatcheck fork`: a session as a new one in another profile
+
+Bring a session into another profile as a new one with its own ID, and keep the original, as
+Claude Code's `claude --resume <id> --fork-session` and `codex fork` do within one profile. It's
+how to keep both when a move stops because the session went on in both profiles.
+
+```
+$ hatcheck fork 9a8b7c6d default
+Forked session 9a8b7c6d "Add rate limiting to the login endpoint" from ~/.claude-work to ~/.claude as a new session:
+  transcript                 61.2 KB
+  subagents and tool output  3 files
+  /rewind file snapshots     5 files
+  plan                       quiet-river-plan.md  (already there)
+  new session                5b1e0c4a-7d2f-4e6b-9a3c-8f1d2e3c4b5a
+Paths in the conversation to these files now point to the copies.
+The copy of session 9a8b7c6d that was already in ~/.claude stays as it was.
+The original stays in ~/.claude-work.
+Resume it with:
+  cd ~/code/api
+  claude --resume 5b1e0c4a-7d2f-4e6b-9a3c-8f1d2e3c4b5a
+Resume it now in ~/.claude? [y/N]
+```
+
+- It copies what `move` copies and checks it the same way, and the copy gets the new ID in its
+  records, and its own folders for subagents, saved tool output and `/rewind` snapshots. Its
+  message IDs stay the same, as in Claude Code's own fork. A Codex session gets the new ID in its
+  file name, its `session_meta` and its events.
+- A copy already in the profile stays as it is, so a fork never stops for one, and the original
+  always stays where it was. A plan file already there stays too, since the copy there uses it.
+- To the other agent, or to a Codex home on another account, it converts the session, as `move`
+  does: a converted session is always a new one.
+- Resuming a fork was tested with the real `claude` (2.1.301).
+
+| Option           | What it does                                                                 |
+|------------------|------------------------------------------------------------------------------|
+| `SESSION`        | the session ID, or the start of it                                           |
+| `PROFILE`        | where it goes, as for [`move`](#hatcheck-move-carry-on-a-session-with-another-profile) |
+| `--from PROFILE` | the profile or home to take it from, when more than one has it, as for `move` |
+| `--dry-run`      | show what would be copied or converted, and change nothing                   |
+
+### `hatcheck relocate`: a project folder that moved
+
+Claude Code files a session under `projects/<the folder's name>` and records the folder in every
+line, so once a project folder is renamed or moved, `claude --resume` from the new folder doesn't
+list its sessions, and the commands `hatcheck` prints `cd` to a folder that's gone. `hatcheck
+relocate` brings the sessions along, in every profile and home:
+
+```console
+$ mv ~/code/api ~/code/api2
+$ hatcheck relocate ~/code/api ~/code/api2
+Relocated 4 sessions from ~/code/api to ~/code/api2:
+  ~/.claude-work  2 sessions: projects/-Users-me-code-api renamed projects/-Users-me-code-api2, with its memory and index
+  ~/.claude  1 session: projects/-Users-me-code-api renamed projects/-Users-me-code-api2
+  ~/.codex  1 session: the folder in the file rewritten
+The folder binding of ~/code/api moved to ~/code/api2.
+Resume them from ~/code/api2. To undo: hatcheck relocate ~/code/api2 ~/code/api
+```
+
+- Sessions that ran in the folder, or in a folder under it, come along. Each profile's project
+  folder is renamed to the new name when every session in it moves, so its `memory/` and
+  `sessions-index.json` come with it, the index's paths updated; when some stay, the sessions are
+  moved into the new project folder one by one, with their subagent and tool-output folders. In
+  each transcript the lines' top-level `cwd` is rewritten to the new folder, and nothing else:
+  what was said about the old path stays as it was. A Codex session, filed by date, stays where
+  it is, with the folder in its `session_meta` and `turn_context` lines rewritten, so `codex
+  resume` lists it from the new folder. Timestamps are kept, and a folder binding
+  ([`hatcheck bind`](#hatcheck-bind-tie-a-folder-to-a-profile)) of the old folder moves to the new.
+- A project folder whose name matches but whose sessions ran elsewhere (Claude Code names
+  `~/code/api-old` and `~/code/api/old` alike) is left alone and listed.
+- It refuses, and changes nothing, when a session is open, was written in the last minute, is a
+  link rather than a file, is already filed under the new folder, or has a line naming the folder
+  that isn't JSON; and when NEW doesn't exist, is OLD, or is inside OLD. `--dry-run` shows what
+  would move. Running it the other way round, `hatcheck relocate NEW OLD`, undoes it, byte for
+  byte.
+- `--json` prints the sessions moved and skipped, the binding and the undo command.
 
 ### `hatcheck open`: resume a session in a new terminal
 
@@ -635,27 +750,39 @@ cl work --resume 3f1c2a9e-8b7d-4c1e-9f2a-6d5e4c3b2a10
 ```console
 $ hatcheck best
 Claude Code, best first (sorted by Fable, as hatcheck usage sorts)
-   1. ~/.claude-work      Fable 31% left, resets Tue 12:00pm · 5h 80%   → cl work
-   2. ~/.claude-team      Fable 100% left, resets Thu 1:00am · 5h 100%  → cl team
-   3. ~/.claude-personal  Fable 0% left, back Sat 4:59pm · 5h 100%      → cl personal
-   4. ~/.claude           week 64% · 5h 100%                            → claude
+   1. ~/.claude-work      Fable 31% left, resets Tue 12:00pm, 0.5%/h · 5h 80%   → cl work
+   2. ~/.claude-team      Fable 100% left, resets Thu 1:00am, 0.9%/h · 5h 100%  → cl team
+   3. ~/.claude-personal  Fable 0% left, back Sat 4:59pm · 5h 100%              → cl personal
+   4. ~/.claude           week 64%, 1.3%/h · 5h 100%                            → claude
 Codex, best first
-   1. ~/.codex  month 100%  → codex
+   1. ~/.codex  month 100%, 0.2%/h  → codex
 Advice only: nothing is started, moved or switched. hatcheck best --for <session> says where to carry a session.
 $ hatcheck best --for 9a8b7c6d
 Session 9a8b7c6d "Add rate limiting to the login endpoint" is in ~/.claude-personal: Fable 0% left, back Sat 4:59pm · 5h 100%.
-Carry it to ~/.claude-work: Fable 31% left, resets Tue 12:00pm · 5h 80%.
+Carry it to ~/.claude-work: Fable 31% left, resets Tue 12:00pm, 0.5%/h · 5h 80%.
   hatcheck move 9a8b7c6d work --from personal
 It prints the command that resumes it there, and offers to run it.
+$ hatcheck best --wait work && cl work
+No room yet; waiting for ~/.claude-work until Tue 12:00pm (in 2d14h)…
 ```
 
 - Claude Code accounts come in the order `hatcheck usage` sorts them: those with Fable left first,
-  the soonest Fable reset on top; then those out of Fable, or out of the weekly limit for all models,
-  the soonest back on top; then accounts without a Fable limit, by the limit with the least left.
-  Codex homes are ranked by the limit with the least left.
+  the soonest Fable reset on top, with those past 90% used behind the fresher ones and those past
+  98% behind those; then those out of Fable, or out of the weekly limit for all models, the soonest
+  back on top; then accounts without a Fable limit, by the limit with the least left. Codex homes
+  are ranked by the limit with the least left.
+- The Fable part ends with the account's pace: what's left, divided by the hours until it resets,
+  so what the account can spend per hour without running out before the reset. `0.5%/h` with 31%
+  left means about 62 hours to go. An account without a Fable limit shows the pace of its tightest
+  limit instead.
 - `--for <session>` picks the best other account of the session's agent that has room now, and
   prints the [`hatcheck move`](#hatcheck-move-carry-on-a-session-with-another-profile) command. If
   the session's own account is the best, it says so and prints the resume command.
+- `--wait` sleeps until an account has room, then answers as above: any Claude Code account;
+  `--wait NAME` (or `default`, `codex`, `codex:NAME`) that one profile or home; with `--for`, an
+  account of the session's agent. It sleeps until the soonest reset the numbers name, says so on
+  stderr, then looks again; when nothing says when an account will have room, it stops with an
+  error instead of polling. For a script: `hatcheck best --wait work && cl work`.
 - The numbers are the ones `hatcheck usage` shows, live when it can be, with a snapshot's age
   otherwise; `--cached` skips the APIs.
 - **Advice only.** It runs when you ask, prints commands, and never starts, moves or switches
@@ -741,10 +868,11 @@ $ hatcheck --json
       "why": null,
       "limits": [
         {"name": "session (5h)", "short": "5h", "kind": "session", "used_percent": 20, "left_percent": 80,
-         "resets_at": "2026-10-16T01:30:00Z", "window_seconds": 18000, "severity": "normal", "per_model": false}
+         "resets_at": "2026-10-16T01:30:00Z", "window_seconds": 18000, "severity": "normal", "per_model": false,
+         "pace": 28.42}
       ],
       "extra": null,
-      "fable": {"left": true, "resets_at": "2026-10-20T16:00:00Z"}
+      "fable": {"left": true, "resets_at": "2026-10-20T16:00:00Z", "band": "fresh"}
     }
   ],
   "hidden": {"Desktop": 3},
@@ -759,12 +887,52 @@ $ hatcheck --json
   `--no-usage`). `hatcheck usage --json` gives every account, in its Fable order, with `sorted_by`.
 - **Stable:** absolute paths rather than `~`, times in UTC (ISO 8601), no colours. `version` goes up
   only when a field changes meaning or goes away; new fields can appear at any time.
-- `left_percent` is `null` for a snapshot's limit that has reset since it was saved. `fable` is
-  `{"left": true, "resets_at": …}`, `{"left": false, "back_at": …}`, or `null` without a Fable limit.
-  `source` is `live`, `cached` or `none`, with `why` when it isn't live.
+- `left_percent` is `null` for a snapshot's limit that has reset since it was saved. `pace` is what's
+  left per hour until the reset (`left_percent` over the hours to go, at least one), `null` without
+  a reset ahead. `fable` is `{"left": true, "resets_at": …}`, `{"left": false, "back_at": …}`, or
+  `null` without a Fable limit; its `band` is `fresh`, `low` (past 90% used), `nearly out` (past 98%)
+  or `out`, the order `hatcheck usage` sorts by. `source` is `live`, `cached` or `none`, with `why`
+  when it isn't live.
 - Errors go to stderr with a non-zero exit, so stdout is always valid JSON. Email addresses only with
   `--email`.
 
+## Rules it keeps
+
+Each rule names the code that keeps it, so it can be checked rather than taken on trust.
+
+- **Not in the path.** Nothing of Hatcheck sits between an agent and its model. `cl` and `cx`
+  set `CLAUDE_CONFIG_DIR` or `CODEX_HOME` (and, for `cl -z` and `cl -k`, the provider variables
+  you set up) and run the agent in their place; nothing stays running
+  ([`launch.rs`](crates/hatcheck/src/launch.rs), `run`).
+- **No agent's config is rewritten**, except when you ask: `hatcheck bind --hook` adds one
+  `SessionStart` hook to each profile's `settings.json` and each Codex home's `hooks.json`, and
+  `unbind --hook` removes only what it added ([`bind.rs`](crates/hatcheck/src/bind.rs),
+  `add_hooks` and `remove_hooks`).
+- **No credentials.** It never asks for, stores, refreshes or moves a login. For Claude it
+  never reads one: Claude Code's own `/usage` is run in the profile and the snapshot it saves is
+  read ([`usage.rs`](crates/hatcheck/src/usage.rs), `run_claude_usage` and `claude_live`). For
+  Codex, the home's `auth.json` token is sent only to ChatGPT's usage endpoint, as it is, and
+  never refreshed (`read_codex_login` and `fetch_codex_usage` there).
+- **Nothing leaves your computer** except those usage requests: Claude Code's to Anthropic, and
+  one to ChatGPT per Codex account. `CODEX_USAGE_URL` in `usage.rs` is the one address the
+  binary itself calls; `--cached` and `--no-usage` make none. The Z.ai and Kimi endpoints in
+  [`provider.rs`](crates/hatcheck/src/provider.rs) are handed to Claude Code, which calls them
+  only when you run `cl -z` or `cl -k`.
+- **No automatic switching** between accounts. `hatcheck best` ranks and prints commands, and
+  nothing in the binary starts, moves or switches a session on its own
+  ([`best.rs`](crates/hatcheck/src/best.rs): advice only, `--wait` sleeps and then prints).
+- **Nothing runs in the background.** There's no daemon. `hatcheck serve` is the desktop app's
+  engine and lives only while the app does, one command per line
+  ([`serve.rs`](crates/hatcheck/src/serve.rs)).
+- **Sessions are only ever moved, copied or rewritten in ways you can undo.** `move` deletes the
+  original only once every copied file is checked against it, never puts an older copy over a
+  newer one, and is undone by moving the session back; `fork` keeps the original; `relocate`
+  prints the command that undoes it; and all three have `--dry-run`, which runs every check and
+  writes nothing ([`move_cmd.rs`](crates/hatcheck/src/move_cmd.rs),
+  [`relocate.rs`](crates/hatcheck/src/relocate.rs)).
+
+Function names rather than line numbers, since lines move; `git grep` finds them.
+
 ## The desktop app
 
 A menu-bar app (system tray on Windows and Linux) built on the CLI. It shows what's left of every
@@ -773,9 +941,9 @@ which opens a terminal in the session's folder, and **Copy**. It also has button
 Desktop instances and notifies you when a limit runs low or resets.
 
 Its main window browses every session, with search, filters and a read-only preview of the
-conversation. From there you can resume a session, copy its command, or move it to another
-profile after a dry run. The window also lists profiles and homes, signs in to a new one in a
-terminal, and makes Desktop instances.
+conversation. From there you can resume a session, copy its command, or move or fork it to
+another profile after a dry run. The window also lists profiles and homes, signs in to a new one
+in a terminal, and makes Desktop instances.
 
 It ships the CLI inside itself, so it needs no Python. It never handles a login, and live usage is
 off until you turn it on. See [desktop/README.md](desktop/README.md) to build it; releases come
@@ -787,7 +955,10 @@ from `.github/workflows/desktop.yml` for macOS, Windows and Linux. The plan behi
 - **`crates/hatcheck/`**: hatcheck in Rust, the commands and the launchers. Its `src/` has a file per
   subcommand (`sessions.rs`, `usage.rs`, `move_cmd.rs`, `open_cmd.rs`, `desktop.rs` and the rest),
   `launch.rs` for `cl`, `cx`, `claude-z` and `claude-k`, and `src/bin/` for those binaries and `hat`.
-  It was ported from a Python version with the same output; see [docs/rust-port.md](docs/rust-port.md).
+  Its own README is the crate's page on crates.io. It was ported from a Python version with the
+  same output; see [docs/rust-port.md](docs/rust-port.md).
+- **`CHANGELOG.md`**: what changed in each release of the CLI; a release's notes on GitHub are its
+  section there.
 - **`install.sh`** / **`install.ps1`**: build the commands from a clone and put them on your `PATH`
   (`~/.local/bin` by default).
 - **`pyproject.toml`**: the PyPI package, the binaries as wheels built with maturin.
@@ -799,6 +970,9 @@ from `.github/workflows/desktop.yml` for macOS, Windows and Linux. The plan behi
   `logo.svg` and `logo-dark.svg` (the mark), `logo-wordmark.svg` and `logo-wordmark-dark.svg`, `favicon.svg`.
 - **`docs/proposals/`**: the plans these came from: [the CLI features](docs/proposals/cli-features.md)
   and [the desktop app](docs/proposals/desktop-app.md).
+- **`AGENTS.md`** and **`docs/lessons.md`**: notes for coding agents (`CLAUDE.md` imports them): how
+  to build and check, the rules the code keeps, and what earlier work got wrong, with the rule that
+  would have caught it.
 - **`tests/`**: the command tests, which run the binary against throwaway home folders:
   `python3 -m unittest discover -s tests`, which builds it with cargo first, and the crate's own
   tests with `cargo test -p hatcheck`. They never read your real profiles, Keychain or the network.
@@ -811,9 +985,9 @@ from `.github/workflows/desktop.yml` for macOS, Windows and Linux. The plan behi
   instance with its own icon, and a launcher that brings a running instance forward instead of
   opening a duplicate. It needs testing on a Windows machine first.
 - **Linux.** There's no official Claude Desktop for Linux, so only the CLI tools apply there.
-- **Releases:** the CLI's 0.1.0 is on PyPI, as Python; the next release ships the Rust binaries to
-  PyPI, GitHub, the Homebrew tap and winget, then the app's installers, once the release workflows
-  have their accounts and secrets (the workflows list them).
+- **Releases:** the CLI is on GitHub, the Homebrew tap, PyPI and crates.io from 0.2.0
+  ([CHANGELOG.md](CHANGELOG.md)). Next are winget, then the app's installers, once its release
+  workflow has its signing and updater secrets (`desktop.yml` lists them).
 - **Signing:** a Developer ID for the macOS app, and a certificate for the Windows one.
 
 ## Credits