A terminal pet fed by real Claude Code and Codex token usage.
It lives in your shell, hatches from a local seed, and grows from the work you actually do. No manual feeding, no fake metrics — when you ship more code, your pet evolves.
Glorp is local-only. No telemetry, no upload, no transcripts. The pet never stores prompt text, response text, tool-call payloads, or source files — only normalized numeric usage metadata that the renderer needs.
npm install -g @arittr/glorp
glorp init
glorp watchThe npm package bundles the native binary for your platform plus the ccusage helpers.
cargo install --path .
glorp doctorWhen installing from source, make sure ccusage and ccusage-codex are on PATH. glorp doctor will tell you what's missing.
glorp init # hatch your first pet
glorp watch # open the live terminal pet
glorp status # one-shot summary, pipe-friendlyinit derives traits from a seed. The same seed always grows the same pet — pass --seed mochi-7f3a for reproducibility, or let glorp generate one.
| Command | What it does |
|---|---|
glorp init [--seed S] [--name N] [--yes] |
Create local state and hatch the first pet. |
glorp watch |
Run the live terminal pet beside your coding session. |
glorp status |
Print a compact summary: stage progress, usage confidence, helper health. |
glorp rename <name> |
Rename the pet without changing seed-derived traits. |
glorp reset --yes |
Clear pet state after confirmation. Usage DB is preserved. |
glorp doctor |
Check config paths, helper availability, parser health, recent diagnostics. |
For local design review, Glorp has a hidden preview lab command:
cargo run -- dev-preview --scenario all --out target/glorp-preview
open target/glorp-preview/index.htmlUse --scenario watch for the wide/compact watch layouts, --scenario pets
for the all-species/all-stage pet matrix, or --scenario all for both. The
bundle also writes manifest.json, review.md, local assets, and
frames/*.txt / frames/*.cells.json captures for agent review.
qquitrrefresh usage and pet state?toggle help overlay
Glorp polls ccusage and ccusage-codex every ten seconds, diffs the running totals against a saved cursor, and turns positive deltas into pet food. Each delta is smeared across 6–12 ten-minute buckets so a heavy hour of coding doesn't crush a single tick.
Stages are gated by calibrated XP: roughly "one active day at your typical pace." A 500M-token/day user and a 50k-token/day user evolve at the same wall-clock cadence.
S0 fluff → S1 fuzzling → S2 kit → S3 pup → S4 fuzz → S5 archfuzz → S6 mythic-fuzz
~1 hour ~6 hours ~1 day ~4 days ~2 weeks ~2 months (sage)
(That's the fuzz species arc — each of the six species — fuzz, blob, ghost, glitch, crystal, mech — has its own stage names and silhouettes.)
Config lives at ~/.config/glorp/config.toml (or $GLORP_CONFIG_DIR/config.toml).
# How much to weight cache_read tokens when computing effective tokens.
# Default 0.03 reflects that cache reads are real work but cheap.
cache_read_weight = 0.03| Var | Purpose |
|---|---|
GLORP_CONFIG_DIR |
Override ~/.config/glorp/ (handy for sandboxing). |
GLORP_CCUSAGE_BIN |
Pin a specific ccusage binary. |
GLORP_CCUSAGE_CODEX_BIN |
Pin a specific ccusage-codex binary. |
GLORP_NODE_BIN |
Pin a specific node binary for JS helpers. |
Glorp surfaces cost figures from helper output as display-only metadata. Your provider's billing dashboard remains the source of truth for invoices, credits, discounts, and final billing totals. Cost never affects food, XP, mood, or stage progression.
Glorp publishes through GitHub Actions, not from a local npm publish at the
repo root. The root package.json is only workspace glue; the publish workflow
builds the five native platform packages first, publishes those, then publishes
@arittr/glorp after its optional dependencies can resolve.
Before tagging a release:
node scripts/bump-npm-version.mjs X.Y.Z
node scripts/assert-release-version.mjs --tag vX.Y.Z
cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
npm testThen commit the version bump, create an annotated vX.Y.Z tag, and push the
commit and tag. Pushing the tag runs .github/workflows/publish.yml, which
re-runs the release-version assertion against the tag, tests Rust on
Ubuntu/macOS/Windows, builds the native release binaries, smoke-tests the npm
launcher, and publishes with npm trusted publishing/provenance.
For a no-publish rehearsal, run the publish workflow manually with the default
dry_run input. That exercises the test/build/smoke matrix but skips the npm
publish jobs.
Visual design ported from the Tokenpet mockup. Inspired by Tamagotchis, dotfiles, and the perpetual question of whether your tools are alive.
MIT