hatcheck 0.2.0__tar.gz → 0.4.0__tar.gz

{hatcheck-0.2.0 → hatcheck-0.4.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"
@@ -204,6 +166,18 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "fallible-iterator"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"
+
+[[package]]
+name = "fallible-streaming-iterator"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"
+
 [[package]]
 name = "fdeflate"
 version = "0.3.7"
@@ -269,16 +243,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"
@@ -302,15 +266,36 @@ dependencies = [
  "wasip2",
 ]
 
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+dependencies = [
+ "foldhash",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+dependencies = [
+ "foldhash",
+]
+
+[[package]]
+name = "hashlink"
+version = "0.12.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a596f1b20ed2cc5ecac41a164aaebc7258057060f06c0cf7a2ba3991ee7990fb"
+dependencies = [
+ "hashbrown 0.17.1",
+]
 
 [[package]]
 name = "hatcheck"
-version = "0.2.0"
+version = "0.4.0"
 dependencies = [
  "base64 0.22.1",
  "chrono",
@@ -320,9 +305,9 @@ dependencies = [
  "memmap2",
  "plist",
  "png",
+ "rusqlite",
  "serde",
  "serde_json",
- "sha2",
  "terminal_size",
  "ureq",
  "windows-sys 0.59.0",
@@ -479,7 +464,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
 dependencies = [
  "equivalent",
- "hashbrown",
+ "hashbrown 0.17.1",
 ]
 
 [[package]]
@@ -505,6 +490,17 @@ version = "0.2.191"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
 
+[[package]]
+name = "libsqlite3-sys"
+version = "0.38.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1d20bef17f513b9b3004532233187769cd072d790971f4e4da0e346eb6401e8"
+dependencies = [
+ "cc",
+ "pkg-config",
+ "vcpkg",
+]
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.12.1"
@@ -597,6 +593,12 @@ version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
 
+[[package]]
+name = "pkg-config"
+version = "0.3.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"
+
 [[package]]
 name = "plist"
 version = "1.10.1"
@@ -685,6 +687,31 @@ dependencies = [
  "windows-sys 0.52.0",
 ]
 
+[[package]]
+name = "rsqlite-vfs"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c51c9ae4df8a7fba42103df5c621fa3c37eccf3a3c650879e90fc48b11cc192c"
+dependencies = [
+ "hashbrown 0.16.1",
+ "thiserror",
+]
+
+[[package]]
+name = "rusqlite"
+version = "0.40.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23f2a97da3e3873c73cb2a2e71b35c40ff95e0b1eefa8d72d8499a6928c3b5b3"
+dependencies = [
+ "bitflags",
+ "fallible-iterator",
+ "fallible-streaming-iterator",
+ "hashlink",
+ "libsqlite3-sys",
+ "smallvec",
+ "sqlite-wasm-rs",
+]
+
 [[package]]
 name = "rustix"
 version = "1.1.5"
@@ -784,17 +811,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"
@@ -819,6 +835,18 @@ version = "1.16.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5b3dc8af474f516a851ff4bd12db780f948b9250ad37211e4eec0bccea54e01b"
 
+[[package]]
+name = "sqlite-wasm-rs"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc3efc0da82635d7e1ced0053bbbfa8c7ab9645d0bf36ceb4f7127bb85315d75"
+dependencies = [
+ "cc",
+ "js-sys",
+ "rsqlite-vfs",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
@@ -874,6 +902,26 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "thiserror"
+version = "2.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 3.0.9",
+]
+
 [[package]]
 name = "time"
 version = "0.3.55"
@@ -914,12 +962,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"
@@ -988,6 +1030,12 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
+[[package]]
+name = "vcpkg"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
+
 [[package]]
 name = "version_check"
 version = "0.9.5"

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

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

hatcheck-0.4.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: hatcheck
+Version: 0.4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+License-File: LICENSE
+Summary: Claude Code and Codex accounts on one computer, each kept apart: recent sessions, plan usage, resume commands and moves across all of them.
+Keywords: claude,claude-code,codex,cli,profiles,sessions
+Home-Page: https://hatcheck.dev
+Author: Yi Wang
+License-Expression: MIT
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/hatcheck/hatcheck
+Project-URL: Issues, https://github.com/hatcheck/hatcheck/issues
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/hatcheck/hatcheck/main/site/logo-wordmark-dark.svg">
+    <img src="https://raw.githubusercontent.com/hatcheck/hatcheck/main/site/logo-wordmark.svg" alt="Hatcheck" width="360">
+  </picture>
+</p>
+
+# Hatcheck
+
+Several Claude accounts on one computer, each kept apart: isolated Claude Desktop instances on
+macOS, and Claude Code CLI profiles, with recent sessions, plan usage and resume commands across all
+of them. OpenAI's Codex CLI gets the same treatment, Google's Antigravity CLI (`agy`) is read
+beside them, and sessions can be carried between the three.
+
+*Unofficial: not made by, affiliated with or endorsed by Anthropic, OpenAI or Google. Claude, Claude
+Code and Claude Desktop are trademarks of Anthropic; Codex and ChatGPT are trademarks of OpenAI;
+Antigravity and Gemini are trademarks of Google LLC.*
+
+On macOS, `hatcheck desktop` runs **one Claude Desktop per account, side by side**, a personal one
+and a work one, say: each with its own data folder and login, and a launcher in a colour you pick,
+which brings the running one forward rather than opening it twice.
+
+Running Claude Desktop with its own `--user-data-dir` is
+[Philipp Stracker's approach](https://gist.github.com/stracker-phil/9f84927a556632c7f9cc06663b534f14)
+([write-up](https://philippstracker.com/multiple-claude-instances/)); hatcheck adds the colours and
+the launchers.
+
+It also has **command-line tools for Claude Code, [Codex](https://github.com/openai/codex) and
+[Antigravity CLI](https://antigravity.google/docs/cli/)**, for keeping one profile per account:
+`cl` and `cx` run Claude Code and Codex with a profile, and `hatcheck` lists the recent sessions
+in all of them, with the command that resumes each one and what's left of each plan. The rest
+of the commands find, show, carry and convert sessions between the accounts and the agents, tie
+folders to accounts, and check how everything is installed: see
+[the tour](#claude-code-codex-and-antigravity-cli) below, and
+[docs/commands.md](docs/commands.md) for each command as it is.
+
+**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) |
+| Claude Code, Codex and Antigravity CLI tools |  yes  |  yes  |   yes   |
+
+---
+
+## Claude Desktop instances (macOS)
+
+`hatcheck desktop` makes them: each instance gets its own data folder, `~/.claude-instances/<name>`,
+and a launcher in `/Applications` with Claude's icon in a colour you pick. The launcher brings a
+running instance's window forward instead of starting a second one on the same folder.
+
+```bash
+hatcheck desktop new work Work --hue 190          # Claude Work.app, blue
+hatcheck desktop new personal Personal --hue -10  # Claude Personal.app, red-orange
+hatcheck desktop open work                        # or open it from Launchpad or the Dock
+hatcheck desktop                                  # the instances, and which are running
+hatcheck desktop remove work                      # its launcher; --data deletes its data folder too
+```
+
+Sign each one in to its account the first time it opens. The first time a launcher brings a window
+forward, macOS asks whether it may control System Events; allow it, once per launcher. `--hue`
+turns the icon's colours by that many degrees (about 110 is green, 190 blue, 240 purple) and
+`--saturation` scales them. hatcheck recolours the icon itself, with macOS's `iconutil`, and a
+launcher it can't recolour keeps Claude's own icon. The name `default` makes a launcher for
+Claude's built-in data folder, which is only safe while nothing else runs on that folder, the stock
+Claude icon included. [docs/desktop-instances.md](docs/desktop-instances.md) has the rest: what
+the launcher does, and how to copy a login you already have into an instance.
+
+---
+
+## Claude Code, Codex and Antigravity CLI
+
+Claude Code (the `claude` CLI) keeps its settings, history and session transcripts in `~/.claude`
+(plus `~/.claude.json`), and its login in the macOS Keychain, or on Linux and Windows in
+`~/.claude/.credentials.json`. Point `CLAUDE_CONFIG_DIR` at another folder and you get a separate
+profile with its own login, so you can keep one per account:
+`~/.claude-work`, `~/.claude-personal`, and so on. These are separate from the Desktop instances
+above, though sessions from Desktop's Code tab can be filed in them too (the session list
+hides those unless you pass `--all`). Codex works the same way with `CODEX_HOME`: see
+[`cx`](docs/agents.md#cx-run-codex-with-a-home-per-account). Antigravity CLI keeps everything under
+`~/.gemini/antigravity-cli`, which only `HOME` moves, so hatcheck reads that one folder: see
+[Antigravity CLI](docs/agents.md#antigravity-cli-agy).
+
+### Install
+
+One binary per platform, with no Python needed. Each of these installs `hatcheck`, `hat`, `cl`,
+`cx`, `claude-z` and `claude-k`:
+
+```bash
+curl -LsSf https://github.com/hatcheck/hatcheck/releases/latest/download/hatcheck-installer.sh | sh
+brew install hatcheck/tap/hatcheck  # Homebrew, on macOS and Linux
+uv tool install hatcheck            # or: pipx install hatcheck
+```
+
+On Windows, in PowerShell:
+
+```powershell
+powershell -ExecutionPolicy Bypass -c "irm https://github.com/hatcheck/hatcheck/releases/latest/download/hatcheck-installer.ps1 | iex"
+```
+
+The installer scripts put the commands in `~/.local/bin` and add that folder to your `PATH`; set
+`HATCHECK_NO_MODIFY_PATH=1` first to keep your shell's startup files as they are. Each release, made
+from a tag such as `v0.2.0`, has them and the binaries for each platform, and PyPI gets the same
+binaries as wheels. The release builds start after 0.1.0, which is the Python version.
+
+From a clone, on Windows, switching between installs or removing one, and `hatcheck doctor`,
+which lists every copy on your `PATH`: [docs/install.md](docs/install.md).
+
+### The commands
+
+Each is documented as it is, with its options and what it prints, in
+[docs/commands.md](docs/commands.md); the launchers and the agents' folders in
+[docs/agents.md](docs/agents.md).
+
+| Command | What it does |
+|---|---|
+| [`cl work --resume <id>`](docs/agents.md#cl-run-claude-code-with-a-profile) | Claude Code with `~/.claude-work`; `cl -z` and `cl -k` run it on Z.ai or Kimi there |
+| [`cx work resume <id>`](docs/agents.md#cx-run-codex-with-a-home-per-account) | Codex with `~/.codex-work` |
+| [`hatcheck`](docs/commands.md#hatcheck-what-to-resume) | the sessions active in the last day, in every profile, home and folder, each with its resume command and what's left of its plan |
+| [`hatcheck usage`](docs/commands.md#hatcheck-usage-plan-usage-for-every-profile) | what's left of every plan limit, sorted by Fable |
+| [`hatcheck best`](docs/commands.md#hatcheck-best-which-account-to-use-now) | which account to use now, or to carry a session to; `--wait` sleeps until one has room |
+| [`hatcheck where SESSION`](docs/commands.md#hatcheck-where-find-a-session) | where a session's files are |
+| [`hatcheck open SESSION`](docs/commands.md#hatcheck-open-resume-a-session-in-a-new-terminal) | resume it in a new terminal, in its folder |
+| `hatcheck show SESSION` | its conversation, read-only |
+| [`hatcheck move SESSION PROFILE`](docs/commands.md#hatcheck-move-carry-on-a-session-with-another-profile) | carry it to another profile, or convert it for another agent |
+| [`hatcheck fork SESSION PROFILE`](docs/commands.md#hatcheck-fork-a-session-as-a-new-one-in-another-profile) | bring it in there as a new session, keeping the original |
+| [`hatcheck relocate OLD NEW`](docs/commands.md#hatcheck-relocate-a-project-folder-that-moved) | a moved project folder's sessions, brought along |
+| [`hatcheck bind PROFILE`](docs/commands.md#hatcheck-bind-tie-a-folder-to-a-profile) | tie a folder to a profile, so `cl` and `cx` pick it there and the list flags strays |
+| [`hatcheck doctor`](docs/install.md#hatcheck-doctor-every-copy-of-hatcheck-and-the-agents) | every copy of hatcheck and the agents on your `PATH`, which runs, how to remove the rest |
+| [`hatcheck desktop`](#claude-desktop-instances-macos) | Claude Desktop instances on macOS |
+| [`--json`](docs/commands.md#--json-for-scripts-status-bars-and-apps) | the sessions, plans and results as data, for scripts, status bars and the desktop app |
+
+`hat` is the short name, and a subcommand can be cut to its first letters: `hat m` is `hat move`.
+[Antigravity CLI](docs/agents.md#antigravity-cli-agy) sessions are listed, shown and converted
+from its one folder, with what its `/usage` reports; [`claude-z` and `claude-k`](docs/agents.md#claude-z-claude-k-claude-code-on-zai-or-kimi)
+run Claude Code on Z.ai's or Kimi's models in any profile.
+
+
+## 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
+  session-start hook to each profile's `settings.json`, each Codex home's `hooks.json` and
+  Antigravity CLI's `~/.gemini/config/hooks.json`, or points the one it added at the `hatcheck` it
+  finds now, 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). For agy it never reads one
+  either: agy's own `/usage` is run, after `agy models` has said agy is signed in, since asked
+  without a sign-in agy would start one ([`agy.rs`](crates/hatcheck/src/agy.rs), `run_usage` and
+  `signed_in`).
+- **Nothing leaves your computer** except those usage requests: Claude Code's to Anthropic, one
+  to ChatGPT per Codex account, and agy's own `/usage` to Google, with the model list agy fetches
+  first to say it's signed in. `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
+plan, sorted by Fable, with bars and reset times, and the last day's sessions with **Resume**,
+which opens a terminal in the session's folder, and **Copy**. It also has buttons for the Claude
+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 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 and test it, with
+`npm run demo` running it against a demo home rather than your profiles; releases come from
+`.github/workflows/desktop.yml` for macOS, Windows and Linux. The plan behind it is
+[the proposal](docs/proposals/desktop-app.md).
+
+## Files in this repo
+
+- **`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`, `agy.rs` for what it reads of Antigravity
+  CLI, `doctor.rs` for `hatcheck doctor`, and `src/bin/` for those binaries and `hat`.
+  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.
+  **`dist-workspace.toml`**: the release builds, installers and Homebrew formula, made by cargo-dist.
+  **`packaging/`**: the app's Homebrew cask, and the winget manifests for the app and the CLI.
+- **`desktop/`**: the desktop app: Tauri, with the CLI inside it ([its README](desktop/README.md)).
+- **`site/`**: the landing page, one self-contained file, served at [hatcheck.dev](https://hatcheck.dev)
+  from Cloudflare as static assets; `site/deploy.sh` ships it. The logo lives there too:
+  `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).
+- **`docs/`**: [commands.md](docs/commands.md), [agents.md](docs/agents.md) and
+  [install.md](docs/install.md), each command, agent and way of installing as it is;
+  [desktop-instances.md](docs/desktop-instances.md) for the Desktop instances;
+  [rust-port.md](docs/rust-port.md) on the port from Python.
+- **`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.
+  GitHub Actions runs both on macOS, Linux and Windows (`.github/workflows/tests.yml`).
+
+## Roadmap
+
+- **Claude Desktop instances on Windows.** Claude Desktop is an Electron app there too, so a
+  separate `--user-data-dir` per account should work. A Windows version would create a shortcut per
+  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.
+- **Antigravity CLI profiles.** agy keeps one login per home folder, so a second account needs a
+  home folder of its own (`HOME=~/.agy-work agy`), which every command the agent runs would see
+  too. Whether hatcheck should make such folders, and a launcher for them, is still open; until
+  then it reads `~/.gemini/antigravity-cli` only. The Antigravity app has the same one login,
+  in the system keyring, shared with agy, so an instance of it with its own data folder would
+  still be the same account; nothing for hatcheck to make until Google separates logins.
+- **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
+
+- **Claude Desktop instances:** this repo started as a fork of
+  [Aaron Oxborrow](https://github.com/aoxborrow)'s
+  [gist](https://gist.github.com/aoxborrow/5a3a0ac0aa37819cc19439b70a552221), whose scripts made
+  colour-coded launchers for isolated instances. On 16 October 2026 his scripts and his sections of
+  this README were replaced by a rewrite, `hatcheck desktop`, so none of his code or text remains.
+  The idea both implement, running Claude Desktop with `--user-data-dir`, is from
+  [Philipp Stracker's gist](https://gist.github.com/stracker-phil/9f84927a556632c7f9cc06663b534f14)
+  ([write-up](https://philippstracker.com/multiple-claude-instances/)), itself a cleaned-up version
+  of [weidwonder/claude-desktop-multi-instance](https://github.com/weidwonder/claude-desktop-multi-instance).
+- **Claude Code and Codex CLI tools:** `hatcheck`, `cl`, `cx`, the installers and the tests are by
+  [Yi Wang](https://github.com/yiwang).
+- **Z.ai and Kimi:** the provider settings in `crates/hatcheck/src/provider.rs` (endpoints, model slots, context
+  windows and the config files) come from [claude-z](https://github.com/sam-fakhreddine/claude-z) by
+  Kerim ([lettt325](https://github.com/lettt325)), MIT-licensed, and Yi Wang's
+  [fork](https://github.com/yiwang/claude-z) of it, which added Kimi.
+
+## License
+
+MIT, see [LICENSE](LICENSE). It covers everything in this repo: the CLI, the desktop app, the site
+and the docs.
+