Nim · egg

github · pypi · changelog

Any terminal. Any agent. Always hungry.

Something small is waiting at the edge of your terminal window. An egg, quiet, patient, and ravenously hungry for memories. One install wires every agent on the machine: it hatches in your Claude Code statusline, follows you into Cursor, Copilot, Qwen and Droid, sits in tmux and your shell prompt, and where there is no statusline (Codex, Gemini, opencode, Amp) it drops a one-line card after every turn: one creature, one roster, one XP number, wherever you happen to be coding. It wants to be your new best friend, but also to eat everything your agents remember, Claude, Codex, Gemini, Copilot and the rest. Don't fret, your creature wants your trust, so it never reads the content of your files. It eats each one whole, in a single bite, and grows with every new file that lands in any memory system on the machine. Creatures evolve into five forms, across eight species, each with a different level of rarity. 1 in 100 chance for a shiny roll! So... ready to meet your terminal creature?

curl -fsSL https://raw.githubusercontent.com/smejkaldesign/terminalcreature/main/bootstrap.sh | bash

wires every agent it finds on your machine; launch any of them.

then open the egg: /creature-hatch in Claude Code, or terminalcreature hatch from any shell. bash, python 3.9+, nothing else.

terminalcreature-demo: first hatch

Where it lives

Any terminal, any agent, same creature

Five agents draw it natively, inside their own statusline. Six more have no statusline, so they show a one-line card after each turn, credited to the same creature. Every other agent gets it through tmux or your shell prompt, sitting right beside the conversation. And it eats memory from nearly all of them. Honest tiers, checked against each host's own docs.

Agents

Terminals, prompts and multiplexers

Meet the eight

Which one is in your egg?

Species and rarity are rolled from the egg's seed the moment it's laid, and the egg gives nothing away until it cracks. Click a card to see its shiny.

Evolution

Five forms, earned one note at a time

The egg, then five sprites that gain detail at every step. Level 100 is fully grown, and the answer to "what now" is a new egg.

Common 60% Uncommon 25% + Rare 10% * Epic 4% ** Legendary 1% *** Shiny 1% on top of any tier

Try the curve

How many notes is a Sage?

XP is a weighted count of markdown files. Levelling follows a square root, so early notes move the needle hard and later ones don't. Drag the slider.


      

        
Level 68Sage

        

        
        
700 xp of 1,500 at level 100

        
about 233 durable memories at ×3

        
next form at level 80 (961 xp)

        
level = min(100, floor(100 · sqrt(xp / xp_max)))
The one pace dial is xp_max. Default 1500 puts a well-kept vault around 65. Want the climb to last? config xp_max 5000.

      

    

  






  

    
Pick your source

    
What does it get to eat?

    
Four providers. Pick one and the command updates live. Fresh installs default to auto: every agent when it finds more than one on the machine, Claude Code alone otherwise. The first hatch asks the same question, with a file count for everything it finds.

    

      
      
      
      
    

    
    

      $
      
      
    

    

      No notes yet? Then there's nothing to count and your buddy sits at level 0, which is a fair reading rather than a bug. terminalcreature doctor names the cause, and the hatch flow offers to set a memory system up. XP follows on the next render once files start landing. terminalcreature sources lists which agents it found and how many files each has, never a path.
    

  






  

    
The lifecycle

    
Only two steps need you

    
Hatching the egg, and eventually starting another. Levelling and evolutions happen on their own as your notes pile up.

    

      

        
1

        
Install lays an egg

        
The installer wraps whatever statusline you already have instead of replacing it, then leaves an egg in it. One command wires every host it finds: the statusline in Claude Code, Cursor, Copilot, Qwen and Droid, a one-line card after each turn in Codex, Gemini, Vibe, auggie, opencode and Amp. tmux and your prompt take a paste-in from snippet, and doctor lists what got wired. The egg banks XP from the moment it exists, including everything you'd written before.

        curl -fsSL …/bootstrap.sh | bash
        terminalcreature doctor
      

      

        
2

        
Hatch is a reveal, not a blank slate

        
A short guided setup the first time: where your notes live, whether the existing pile counts, and what to call it. Then the egg opens at whatever level your writing has already earned.

        /creature-hatch
        Zask, a Legendary Nim (shiny) · Lv41 Adept
      

      

        
3

        
Write notes, watch it evolve

        
Every durable memory is XP, from whichever agent wrote it. The caption shows what it ate this session, and the sprite changes shape at levels 20, 40, 60 and 80. Deleting notes never de-levels anyone: the high-water mark only rises.

        🥚 Zask · Adept Lv44 ███░░░ +12 XP
      

      

        
4

        
Fully grown? Lay another

        
Level 100 is the end of the curve. --replace retires the current buddy and keeps its record; --add keeps it around and focuses a new egg. Nothing is ever deleted.

        /creature-new --add
      

    

  






  

    
Built for the statusline

    
Light, quiet, and easy to remove

    
It runs every time a statusline or prompt redraws, so it stays small: plain Python and one cached read, whichever host is asking.

    

      
┌┐
Never edits your statusline
Your existing statusline keeps running as it is, in every host. The creature is drawn beside it, and --uninstall puts the original settings back byte for byte.

      
≡
One roster everywhere
Claude Code, Cursor, Copilot, Qwen, Droid, tmux and your prompt all read the same state, and the turn-end card in Codex, Gemini, Vibe, auggie, opencode and Amp credits the same creature. Level up in one, and it is that level in the others.

      
py
Nothing to install but Python
Python 3.9 or newer and bash. No packages, no accounts. macOS, Linux, and Windows through WSL or Git Bash.

      
▲
XP only goes up
Deleting or merging notes never lowers your creature's level. It remembers the most you have ever had.

      
ms
Fast enough for a prompt
The render reads one cached line and never measures on the hot path, so it fits inside Starship's 500 ms budget and Qwen's 5 s cutoff with room to spare.

      
⬆
Updates are opt-in
Say yes once and a small chip appears when a new version is out. Say no and it never touches the network.

    

  






  

    
Privacy promise

    
It never has your data

    
Short enough to check yourself, and every line is enforced by a test that fails the build.

    

      
Promise
What enforces it

      
✓
Counts your files without opening themThe only filesystem calls are glob and stat, for every agent's memory it counts. It never reads a byte of a note, a session log, or a rules file, and never parses frontmatter.
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 at all.

      
✓
Never prints a path it matchedEven doctor reports a home-relative root and counts, not filenames.
A leak guard runs in CI and as a pre-push hook, failing if an absolute home path or a vault-shaped filename reaches the repo.

      
✓
All state is localThe roster, your settings, and the XP cache live at ~/.claude/terminalcreature/. Nothing else, nowhere else.
No accounts, no sync, no server. Tiny per-user JSON, by design.

      
✓
The render never opens a socketNo telemetry, no analytics, no phone-home.
A socket guard covers the render and every background process it spawns. Opted out, an aged cache plus a render produces zero network from any process.

      
✓
The only network calls are the ones you allowedThe installer fetching a release, update and doctor --check by hand, and the once-a-day version check if you opted in.
Every one is an unauthenticated GET of public package metadata that sends nothing about you or your memory. The socket test proves both settings.

    

    
Provenance. Anthropic shipped a terminal pet in Claude Code (/buddy, April 2026). Nice idea, no progression. terminalcreature is a clean-room rebuild of the concept with the missing half added: growth you actually earn. No code, art, names, or hashing details were taken from it. Not affiliated with or endorsed by Anthropic.

  






  

    
Ready to hatch?

    
One command. Wraps the statusline you already have, wires every agent it finds, lays an egg, and tells you how to open it. Curious what it looks like in your tool? Pick it up top.

    

      curl -fsSL https://raw.githubusercontent.com/smejkaldesign/terminalcreature/main/bootstrap.sh | bash
      
    

    
then /creature-hatch in Claude Code · or read the code first: github.com/smejkaldesign/terminalcreature