terminalcreature 2.0.0__tar.gz

terminalcreature-2.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.DS_Store
+*.bak
+dist/
+*.egg-info/

terminalcreature-2.0.0/CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+Notable changes, newest first. Versions follow semver; the version lives in
+`terminalcreature/__init__.py` and each release is the matching `v*` tag.
+
+## 2.0.0
+
+- Renamed: brainbuddy is now **terminalcreature**. New package, module, CLI
+  (`terminalcreature`), slash commands (`/creature`, `/creature-hatch`,
+  `/creature-new`, `/creature-hide`, `/creature-show`), state dir
+  (`~/.claude/terminalcreature/`), shim, and `TERMINALCREATURE_TARBALL`.
+- The installer migrates an existing brainbuddy install in place: state, XP
+  cache, and settings move over, the old command files are removed, and a
+  stub is left at the old shim path so project-level statuslines keep
+  drawing. Re-run the bootstrap you installed with; the old URL redirects.
+- Creatures are unchanged. The seed salt keeps its original value on
+  purpose, so every buddy hatched under the old name is the same creature.
+- New wordmark on the site and README; site at terminalcreature.com.
+
+## 1.3.0
+
+- brainbuddy is now **terminalcreature**. This is the last release under the
+  old name and it changes nothing else. To move over, re-run the bootstrap you
+  installed with (the old URL redirects), or `pipx install terminalcreature`.
+  Your creature, roster, and settings migrate in place. New home:
+  <https://github.com/smejkaldesign/terminalcreature>.
+
+## 1.2.0
+
+- Opt-in update alert: `config update_check true` lets the background refresh
+  ask pypi once a day for the latest version number, and a yellow `⬆ update`
+  chip appears at the end of the statusline when a release is out, leaving on
+  its own after you upgrade. Off by default, asked once after the hatch, and
+  the render path still never touches the network in either setting; the
+  socket test now proves both. Existing installs get a one-time offer from
+  `/brainbuddy`, and `doctor` reports the check's state and last run.
+
+## 1.1.0
+
+- An egg renders as Unhatched everywhere, never as a name. The name is chosen
+  at the hatch: two ideas from the new `brainbuddy names`, your own via
+  `hatch --name <n>`, or let it name itself and find out at the reveal.
+- The session counter (`+N XP`) moved to the right of the progress bar, so the
+  caption reads level, bar, then what this session added.
+
+## 1.0.0
+
+The first public release: install it with one command, and the owner's costs
+stay at zero because everything lives on your machine.
+
+- Fixed: a background refresh no longer writes back the roster it loaded before
+  the scan, which could silently revert an egg laid or hatched while it ran.
+- Fixed: the leak guard no longer skips files whose names contain spaces, and it
+  now catches capitalized and `/home/` paths too.
+- Fixed: `--uninstall` recognizes a statusline that names the shim through `~`
+  instead of deleting the shim and leaving the statusline pointing at it.
+- Fixed: a non-numeric `config xp_max`/`columns`/`sprite_height` or `simulate`
+  argument gets a one-line answer instead of a traceback carrying a home path.
+- Upgrades keep your buddy. `state.json` carries a schema version, and a file
+  written by any earlier version is brought forward on load: nothing is dropped,
+  missing fields are filled, and a focus pointing at a creature that isn't there
+  falls back to the roster rather than rendering as no buddy at all.
+- `brainbuddy update` and `brainbuddy doctor --check` ask PyPI whether there's a
+  newer version. They're the only two commands that go online, and only when you
+  run them; the statusline never does, and a test asserts it. No network is not
+  an error, it's one line and exit 0.
+- `doctor` names a project-level statusline. If a repo's own
+  `.claude/settings.json` sets `statusLine`, that wins inside the repo and the
+  creature never draws there. Doctor says so and prints the two-step fix with
+  your own command already in it. It only ever reads that file.
+- Windows: `install.sh` and `bootstrap.sh` name WSL and Git Bash when they're
+  run by something that isn't bash. There's no PowerShell version.
+- Hatching with no memory system is a moment rather than a silent Lv0. The
+  reveal is unchanged; the level is followed by what it means and what to feed.
+- One-line install: `bootstrap.sh` fetches the latest tagged release, unpacks it
+  to a temp dir and runs its `install.sh` with whatever flags you passed, so the
+  usual path is one command instead of a clone. It falls back to the default
+  branch until a release exists.
+- PyPI packaging: `pipx install brainbuddy` / `uvx brainbuddy` now work; the
+  installed entry point is the same `brainbuddy` command the shim calls.
+- Release workflow: tagging `vX.Y.Z` tests, builds, and publishes to PyPI via
+  trusted publishing.
+- `brainbuddy doctor` reports the installed version.
+- Installable as a Claude Code plugin: a `SessionStart` hook notices an unwired
+  install and offers `install.sh --no-commands`, which ends on the same egg.
+
+## 0.1.0
+
+Everything before packaging: the creature, the egg-and-hatch flow, three XP
+providers, the statusline wrap installer, five slash commands, the leak guard,
+and the test suite.

terminalcreature-2.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eric Smejkal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

terminalcreature-2.0.0/PKG-INFO

@@ -0,0 +1,502 @@
+Metadata-Version: 2.5
+Name: terminalcreature
+Version: 2.0.0
+Summary: a terminal pet for your Claude Code statusline that evolves as your memory grows
+Project-URL: Homepage, https://github.com/smejkaldesign/terminalcreature
+Project-URL: Changelog, https://github.com/smejkaldesign/terminalcreature/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/smejkaldesign/terminalcreature/issues
+Author-email: Smejkal Design <eric@smejkal.design>
+License: MIT License
+        
+        Copyright (c) 2026 Eric Smejkal
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: claude-code,pet,statusline,tamagotchi,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Terminals
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="site/assets/terminalcreature-logo.png" width="247" alt="TERMINAL CREATURE" />
+</p>
+
+<h3 align="center">A terminal pet that levels off your second brain.</h3>
+
+<p align="center">
+  A creature that lives in your Claude Code statusline, hatches from an egg,<br />
+  and grows on a diet of your own memories. It counts your notes and never reads them.
+</p>
+
+<br />
+
+<p align="center">
+  <a href="https://terminalcreature.com"><strong>Website</strong></a> &nbsp;&middot;&nbsp;
+  <a href="https://pypi.org/project/terminalcreature/"><strong>PyPI</strong></a> &nbsp;&middot;&nbsp;
+  <a href="CHANGELOG.md"><strong>Changelog</strong></a> &nbsp;&middot;&nbsp;
+  <a href="https://github.com/smejkaldesign/terminalcreature/issues"><strong>Report a bug</strong></a> &nbsp;&middot;&nbsp;
+  <a href="CONTRIBUTING.md"><strong>Contribute</strong></a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/terminalcreature/"><img src="https://img.shields.io/pypi/v/terminalcreature?color=ffb627&label=pypi" alt="PyPI" /></a>
+  <img src="https://img.shields.io/badge/python-3.9%E2%80%933.13-3776AB?logo=python&logoColor=white" alt="Python 3.9 to 3.13" />
+  <a href="https://github.com/smejkaldesign/terminalcreature/actions/workflows/ci.yml"><img src="https://github.com/smejkaldesign/terminalcreature/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <img src="https://img.shields.io/badge/dependencies-0-4ade80" alt="Zero dependencies" />
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT" /></a>
+</p>
+
+<pre align="center">
+day one                                  a few hundred notes later
+┌───────────┐                            ┌───────────┐
+│    ___    │  ████░░░░░░  my-brain      │   .\|/.   │  ████░░░░░░  my-brain
+│   /   \   │  🥚 Unhatched              │  ( o o )  │  🥚 Drain · Sage Lv65 █████░ +16 XP
+│  ( ooo )  │                            │  /|ooo|\  │
+│   \___/   │                            │   |___|   │
+└───────────┘                            │  /     \  │
+                                         └───────────┘
+</pre>
+
+---
+
+## Why terminalcreature exists
+
+A second brain only pays off if you keep writing to it, and nothing in a terminal rewards that. Streaks punish weekends. Timers reward sitting still. terminalcreature rewards the one thing that matters: a durable note landed on disk.
+
+Every note you write is XP. The creature evolves through five forms as your vault grows, and it never loses a level when you tidy up. Not a streak you can drop, not a timer. Feed it or it sits there. That's the whole loop.
+
+## How It Works
+
+```
+your notes                 terminalcreature                       statusline
+──────────────── ──►  ──────────────────────  ──►  ───────────────────────────
+~/.claude/projects/*/     glob + stat only           ┌───────────┐
+  memory/*.md             (never open())             │   ( ' ' ) │  🥚 Zask · Adept Lv44
+~/notes/**/*.md                │                     │  <|+++|>  │  ███░░░ +12 XP
+a structured vault        weighted count = xp        │   /|_|\   │
+                               │                     └───────────┘
+                     level = 100·√(xp / xp_max)
+                               │
+                     sprite = f(level, seed)
+```
+
+The egg banks XP from the moment it exists, including everything you'd written before you installed anything. So the first hatch isn't a blank slate, it's a reveal:
+
+```
+$ terminalcreature hatch
+
+  the egg cracks
+
+       _^_
+     ( ' ' )
+      /$$$\
+       ^ ^
+
+  Zask, a Legendary Nim (shiny)
+  Lv41 Adept
+```
+
+---
+
+## Quick Start
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/smejkaldesign/terminalcreature/main/bootstrap.sh | bash
+```
+
+Then, in Claude Code:
+
+```
+/creature-hatch
+```
+
+That's it. The installer wraps whatever statusline you already have rather than replacing it, lays your first egg, and tells you how to open it. The hatch is a short guided setup the first time: it looks for your notes, offers what it found with a file count each, and opens the egg at whatever level your writing has already earned.
+
+Point it at your notes in the same breath; the bootstrap passes flags straight through to the installer:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/smejkaldesign/terminalcreature/main/bootstrap.sh | bash -s -- --folder ~/notes
+```
+
+### Requirements
+
+| | |
+| :--- | :--- |
+| **Runtime** | Python 3.9 or newer, stdlib only. No dependencies, ever. |
+| **Installer** | bash, tar, and either curl or wget. Pipe to `bash`, not `sh`. |
+| **macOS / Linux** | Supported, including the stock macOS bash 3.2. |
+| **Windows** | Under **WSL** or **Git Bash**. PowerShell and cmd are not, because the statusline shim is a shell script. |
+
+### The first hatch asks three questions
+
+`/creature-hatch` guides the first egg, because the things it can't guess are the ones that decide everything afterwards:
+
+1. **Where do your memories live?** It looks for an Obsidian vault, a notes folder, and Claude Code's own memory, then offers what it found with a file count each. That sets `provider` and `vault_root`.
+2. **Score what's already written, or start from 0?** Scoring is the default and opens the egg several forms in. `--from-zero` baselines what's there so only new notes count, for people who'd rather have the climb.
+3. **What's it called?** Two fresh ideas from `terminalcreature names`, your own, or let the egg name itself at the reveal. Until it hatches the statusline just says Unhatched.
+
+Later eggs inherit the first two answers. The name is asked for every egg.
+
+### Other ways to install
+
+| Route | What you get |
+| :--- | :--- |
+| **Clone and run `./install.sh`** | The same installer the bootstrap runs, if you want to read the code first. |
+| **`pipx install terminalcreature`** | The CLI on your PATH and nothing else. It does not wire your statusline, which is most of what terminalcreature is. |
+| **Claude Code plugin** | Coming soon. The manifest and marketplace listing ship in this repo. |
+| **Offline or behind a mirror** | Set `TERMINALCREATURE_TARBALL` to a URL or a tarball on disk and the bootstrap installs from that. |
+
+### Installer flags
+
+| Flag | What it does |
+| :--- | :--- |
+| `--folder <path>` | count a folder of markdown notes (the usual case for an existing notes dir) |
+| `--vault <path>` | count a structured vault layout |
+| `--statusline <cmd>` | wrap this command instead of the one in `settings.json` |
+| `--inline` | one-line segment after your statusline instead of the boxed column |
+| `--no-wire` | install the library and commands only, wire it yourself |
+| `--no-commands` | skip the slash commands, when something else already ships them |
+| `--uninstall` | unwire, restore your old statusline, remove the commands |
+
+Re-running is safe and is how you pick up new commands. It won't wrap itself twice and it leaves an existing buddy alone.
+
+### How the wiring works
+
+The installer **wraps** your existing statusline rather than editing it. It points `statusLine.command` at a small generated shim; the shim runs whatever command was there before, on the same stdin Claude Code hands it, then draws the creature to the left of that output. Your own script is never modified. It keeps a `settings.json.pre-terminalcreature.bak`, and `--uninstall` puts the original command back.
+
+**Project-level statuslines need one manual step.** The installer only touches `~/.claude/settings.json`. If a repo sets its own `statusLine` in `<repo>/.claude/settings.json`, wrap it explicitly, then point the project at the shim:
+
+```bash
+./install.sh --statusline "/path/to/repo/.claude/statusline.sh"
+# then in <repo>/.claude/settings.json:
+#   "statusLine": { "type": "command", "command": "~/.claude/terminalcreature/statusline-terminalcreature.sh" }
+```
+
+---
+
+## The Creature
+
+### Species and rarity
+
+Eight species. The eyes and the body motif come from the species, so a Bramble is recognisable at a glance.
+
+```
+     _^_            _^_            _^_            _^_
+   ( o o )        ( - - )        ( ^ ^ )        ( . . )
+   <|ooo|>        <|~~~|>        <|***|>        <|...|>
+    /   \          /   \          /   \          /   \
+    ^   ^          ^   ^          ^   ^          ^   ^
+     Mote           Wisp          Ember           Pip
+
+     _^_            _^_            _^_            _^_
+   ( o o )        ( v v )        ( ' ' )        ( > < )
+   <|===|>        <|###|>        <|+++|>        <|///|>
+    /   \          /   \          /   \          /   \
+    ^   ^          ^   ^          ^   ^          ^   ^
+     Fen          Bramble          Nim           Quill
+```
+
+| Rarity | Odds | Mark |
+| :--- | :--- | :--- |
+| Common | 60% | |
+| Uncommon | 25% | `+` |
+| Rare | 10% | `*` |
+| Epic | 4% | `**` |
+| Legendary | 1% | `***` |
+
+The mark carries the tier without relying on colour, so it reads on a mono terminal or to a colour-blind user. On top of that, a **1% shiny** roll remakes the body motif: symbols become `$` (`<|+++|>` becomes `<|$$$|>`) and letters go uppercase (`<|ooo|>` becomes `<|OOO|>`).
+
+All of it is a pure function of the seed. Hand-editing `state.json` can't promote a Common into a shiny Legendary; derived values are recomputed on every load and win.
+
+### The evolution ladder
+
+Six sprites: the egg, then five forms gaining detail at every step.
+
+```
+    ___        _^_        _^_        \|/       .\|/.     *.\|/.*
+   /   \     ( ' ' )    ( ' ' )    ( ' ' )    ( ' ' )   \( ' ' )/
+  ( ooo )     /+++\     <|+++|>    <|+++|>    /|+++|\    /|+++|\
+   \___/       ^ ^       /   \      /|_|\      |___|     =|___|=
+                         ^   ^      ^   ^     /     \    ^     ^
+
+    egg     Hatchling  Fledgling    Adept       Sage    Ascendant
+ unhatched     0-19      20-39      40-59      60-79     80-100
+```
+
+### The egg is a state, not a level
+
+A buddy is an **egg** until you hatch it, whatever level it is. Level 0 is a Hatchling, a baby with a face, not an egg. Species, rarity, shiny, and stats are fixed the moment the egg exists, so an unhatched egg shows none of it:
+
+```
+$ terminalcreature card
+
+       ___
+      /   \
+     ( ooo )
+      \___/
+
+  Unhatched
+  0 xp eaten and counting
+  /creature-hatch to find out what it is
+```
+
+**Eggs bank XP while closed**, so waiting costs nothing. A buddy added later with `--add` starts at 0 and hatches as a Hatchling, because XP banks per creature.
+
+---
+
+## XP and Levelling
+
+### Where XP comes from
+
+XP is a weighted count of markdown files in a memory system, so terminalcreature needs one to point at. Three providers, set with `/creature config provider <name>`:
+
+| Provider | Counts | Point it somewhere |
+| :--- | :--- | :--- |
+| `claude` | stock Claude Code memory, `~/.claude/projects/*/memory/*.md` | default, nothing to set |
+| `folder` | every `.md` under a directory, recursively | `config vault_root ~/notes` |
+| `vault` | a structured vault, weighted per directory | `config vault_root ~/brain` |
+
+`terminalcreature doctor` says which one is live, whether the root is there, what it counted, and what your buddy banked of that:
+
+```
+$ terminalcreature doctor
+provider: folder (folder of notes)
+root: ~/notes (found)
+  notes      9
+source xp 18 -> level 10
+Zask banked 18 -> level 10 (Hatchling)
+```
+
+A zero reading has three causes, and `doctor` names the one you've got:
+
+- **the root isn't there**: wrong path, or Claude Code hasn't written memory yet
+- **the root is real but empty**: nothing to do but write things down
+- **the root has markdown the provider's layout doesn't match**: pointing `vault` at a plain notes folder does this, and the fix is `provider folder`
+
+**No memory system at all?** Then your buddy sits at level 0, which is a fair reading rather than a bug. The installer and `doctor` both hand you a prompt for it:
+
+> "Set up a persistent memory system for this project: one markdown file per durable fact in your memory directory, an index listing them, and write to it as we work."
+
+### How levelling works
+
+Durable facts are worth more than session logs because they cost more to produce, and generated index files are excluded so they can't inflate the count for free. `claude` counts one source at ×3, `folder` counts every note at ×2, and `vault` weights per directory:
+
+| Source | Glob | Weight | Excluded |
+| :--- | :--- | :--- | :--- |
+| memories | `auto-memory/*.md` | ×3 | `MEMORY.md`, `index.md` |
+| knowledge | `05-knowledge/*.md` | ×2 | `index.md` |
+| projects | `04-projects/*.md` | ×2 | `index.md` |
+| decisions | `memory/decisions/*.md` | ×2 | |
+| sessions | `memory/sessions/*.md` | ×1 | |
+
+```
+level = min(100, floor(100 * sqrt(xp / xp_max)))
+```
+
+A square root curve, so early memories move the needle hard and later ones don't. **Level 100 is fully grown** and the curve stops there. `xp_max` is the XP at level 100 and the one dial that controls pace; the default of **1500** puts a well-established vault around 65.
+
+| Level | XP needed | Roughly |
+| :--- | :--- | :--- |
+| 5 | 4 | a couple of notes |
+| 10 | 16 | ~5 durable memories |
+| 20 | 61 | ~20 durable memories |
+| 40 | 241 | ~80 durable memories |
+| 65 | 634 | ~211 durable memories |
+| 100 | 1,500 | ~500 durable memories |
+
+Want it slower? `terminalcreature config xp_max 5000` triples the distance. Deleting memories never de-levels anyone: the high-water mark only rises, because tidying up shouldn't be punished.
+
+### The session counter
+
+Right of the level bar, the caption shows what your buddy has eaten **in this session**:
+
+```
+🥚 Neux · Sage Lv66 ██░░░░ +16 XP
+```
+
+It baselines the first time a session draws itself and is tracked per session id, since several are usually open at once. It stays hidden until there's something to show.
+
+---
+
+## The Statusline
+
+`density` picks how much room the **inline** segment takes (`render`, or an `--inline` install):
+
+| Mode | Looks like | Notes |
+| :--- | :--- | :--- |
+| `minimal` | `◔` | one glyph, filling as you evolve (`◌ ○ ◔ ◑ ◕ ●`, or `. o c C O @` in ascii) |
+| `compact` | `<><> Lv65` | default, ~10 columns inline |
+| `full` | `<><> Drain Lv65` | adds the name |
+| `sprite` | the 5-row creature | its own rows, right-aligned to `columns` |
+| `ruler` | a column ruler | a measuring aid, not a creature |
+
+`compose "<text>"` is what the installed shim uses by default: your own text with the creature as a **left column**, sharing row one. The column is boxed in dark grey; `config border false` drops the box and gets two rows of height back. `sprite_height 3` cuts the creature to three rows and keeps the evolution beats:
+
+```
+┌───────────┐
+│   .\|/.   │  ████░░░░░░  my-brain ⎇ main          .\|/.    ████░░░░░░  my-brain ⎇ main
+│  ( o o )  │  🥚 Drain · Sage Lv65 █████░         ( o o )   🥚 Drain · Sage Lv65 █████░
+│  /|ooo|\  │                                      /|ooo|\
+│   |___|   │                                       |___|
+│  /     \  │                                      /     \
+└───────────┘
+   border true                                        border false
+```
+
+Either way the column is pinned to the creature's **widest** form, so your text doesn't shift the day it evolves into an Ascendant. `sprite` needs a width and a statusline script is handed no terminal, so `density ruler` prints a ruler: read the last digit you can see and pass it to `config columns <n>`.
+
+`/creature-hide` takes the creature out without uninstalling anything. XP keeps banking while it's hidden.
+
+### The roster
+
+Keep several creatures. Only the **focused** one gains XP; the others hold their level and wait.
+
+```
+$ terminalcreature list
+  ◕ Drain      Lv65   Sage       Common
+* ○ Zask       Lv0    Hatchling  Legendary shiny
+
+* = focused (the one gaining xp)
+```
+
+`/creature-new` asks before it acts: `--replace` retires the current buddy and focuses a new egg, `--add` keeps it active and focuses a new egg. **Neither deletes anything.** A retired buddy keeps its banked XP and `focus <name>` brings it back. There's no level requirement, since the tradeoff is identical at level 12 and level 99.
+
+---
+
+## Commands and Settings
+
+```
+terminalcreature new               lay an egg (--replace or --add, --yes to confirm)
+terminalcreature hatch [--name <n>] [--from-zero]  open the egg, naming it as it opens
+terminalcreature names             two fresh name ideas for the egg
+terminalcreature card              the full creature card
+terminalcreature list              the roster
+terminalcreature focus <name>      choose who banks new xp, un-retires
+terminalcreature rename <old> <new>
+terminalcreature retire <name>     retires, keeps the record and its xp
+terminalcreature hide / show       drop it from the statusline, or bring it back
+terminalcreature config [key val]  see settings, or set one
+terminalcreature simulate <xp>     preview any level without touching real state
+terminalcreature sources           what it can count, and what to do if that's nothing
+terminalcreature doctor            what can it see, and why is it zero
+terminalcreature doctor --check    the same, plus a version check against pypi
+terminalcreature update            ask pypi whether there's a newer terminalcreature
+terminalcreature render            the one-line statusline segment
+terminalcreature compose "<text>"  your statusline text, creature as a left column
+terminalcreature refresh           recompute the xp cache
+```
+
+Five are slash commands in Claude Code, so plain language reaches them without the CLI: `/creature`, `/creature-new`, `/creature-hatch`, `/creature-hide`, `/creature-show`.
+
+After an `install.sh` or bootstrap install there's no `terminalcreature` on your PATH: the library is imported by the statusline, not installed as a binary. The slash commands reach everything you'd normally want. For the rest, alias it, or `pipx install terminalcreature`:
+
+```bash
+alias terminalcreature='PYTHONPATH="$HOME/.claude/terminalcreature/lib" python3 -m terminalcreature.cli'
+```
+
+| Setting | Values | Default |
+| :--- | :--- | :--- |
+| `provider` | `claude`, `folder` or `vault` | `claude` |
+| `vault_root` | path, for `folder` and `vault` | |
+| `xp_max` | XP at level 100, the pace dial | `1500` |
+| `density` | `minimal` `compact` `full` `sprite` `ruler` | `compact` |
+| `sprite_height` | `3` or `5` | `5` |
+| `border` | box the `compose` column, costs 2 rows | `true` |
+| `columns` | right-align width for `sprite` | `0` |
+| `unicode` | `true` or `false` | `true` |
+| `hidden` | `true` or `false` | `false` |
+| `update_check` | `true` or `false`, the once-a-day check behind the `⬆ update` chip | `false` |
+
+---
+
+## Privacy Promise
+
+Short enough to check yourself.
+
+- **It counts your files without ever opening them.** The only filesystem calls in `metric.py` are `glob` and `stat`. It never calls `open()` on a note, never reads a byte of content, never parses frontmatter. That isn't a promise about what it does with your data; it's a statement that it never has your data.
+- **It never prints a path it matched**, in any mode including `doctor`, which reports a home-relative root and counts rather than filenames.
+- **All state is local**, at `~/.claude/terminalcreature/`: the roster, your settings, and the XP cache. Nothing else, nowhere else.
+- **The render never opens a socket, and by default neither does anything it starts.** No telemetry, no analytics, no phone-home.
+- **The only network calls are the ones you allowed.** The installer downloading a release tarball from `api.github.com`; `terminalcreature update` and `doctor --check` reading pypi's public package metadata; and, if you opt in with `config update_check true`, that same version request once a day from the background refresh so the yellow `⬆ update` chip can appear. It's off by default and asked as a question. Every one is an unauthenticated GET that sends nothing about you or your memory.
+
+Three tests enforce this. A runtime trap patches every file-reading builtin and asserts none fire during a measurement. A static pass tokenizes `metric.py` and fails if a reader appears in the code at all. A third guards every socket call, including in the background processes a render spawns: opted out, an aged cache plus a render produces zero network from any process; opted in, exactly one attempt per day, never from the render itself. A leak guard runs in CI and as a `pre-push` hook, failing the build if an absolute home path or a vault-shaped filename ever reaches the repo.
+
+---
+
+## Under the Hood
+
+| | |
+| :--- | :--- |
+| **The shim wraps, it doesn't edit** | `statusLine.command` points at a generated shim; your original command is saved next to it and run by it. A script that already calls terminalcreature is detected and left alone. |
+| **A cache on the hot path** | `render` reads a cached XP value and spawns the recount in the background, blocking only on a cold start. |
+| **High-water mark** | New XP is the delta above the highest total ever seen, so deleting notes can't take a level away, and a render before your first hatch can't burn the XP waiting for it. |
+| **Derived beats persisted** | Species, rarity, shiny, and accent are recomputed from the seed on every load and overwrite whatever is on disk. Only id, seed, name, hatch time, and banked XP persist. |
+| **Counting is all it does** | The measurement path is `glob` and `stat` only, enforced by a runtime trap and a static check. |
+
+## Repository Structure
+
+```
+terminalcreature/
+├── terminalcreature/            # the package, stdlib only
+│   ├── cli.py             #   commands
+│   ├── render.py          #   statusline segment, compose, card
+│   ├── state.py           #   roster, settings, xp cache
+│   ├── metric.py          #   providers: glob + stat, nothing else
+│   ├── creature.py        #   seed → species, rarity, shiny
+│   └── sprites.py         #   stage templates × species motifs
+├── commands/              # the five Claude Code slash commands
+├── site/                  # the website, deployed by pages.yml
+├── install.sh             # wraps your statusline, lays the egg
+├── bootstrap.sh           # curl | bash entry: fetches a release, runs install.sh
+├── scripts/leak-guard.sh  # fails on machine paths and vault-shaped filenames
+├── tests/                 # stdlib test suite, incl. the privacy traps
+├── .claude-plugin/        # plugin manifest
+└── marketplace/           # marketplace listing
+```
+
+## Development
+
+```bash
+git clone https://github.com/smejkaldesign/terminalcreature && cd terminalcreature
+python3 tests/test_terminalcreature.py     # synthetic fixtures in a temp dir; no real memory touched
+./scripts/leak-guard.sh              # the same check CI runs
+git config core.hooksPath .githooks  # optional pre-push copy of the guard
+```
+
+No virtualenv, nothing to install, no build step. Run the CLI from the clone with `python3 -m terminalcreature.cli card`. CI runs the suite on Python 3.9 through 3.13, builds the wheel, and installs under the stock macOS bash 3.2.
+
+## Contributing
+
+Small project, short rules: stdlib only, Python 3.9 floor, one change per PR, new behavior gets a test, and the privacy tests must keep passing. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Provenance
+
+Anthropic shipped a terminal pet in Claude Code (`/buddy`, April 2026). Nice idea, no progression: species and stats are recomputed from your user ID every session and never change. terminalcreature is a clean-room rebuild of the *concept* with the missing half added, growth you actually earn. No code, species names, sprite art, stat names, or hashing details were taken from it. Not affiliated with or endorsed by Anthropic.
+
+## License
+
+MIT. See [LICENSE](LICENSE). &copy; 2026 Smejkal Design.