Metadata-Version: 2.2
Name: tokiepet
Version: 0.1.0
Summary: A pixel desktop pet that feeds on Claude Code tokens, walks on top of your windows, and falls when you move them.
Author: Tokie contributors
License: MIT
Project-URL: Homepage, https://github.com/Andersonscat/tokiepet
Project-URL: Repository, https://github.com/Andersonscat/tokiepet
Project-URL: Issues, https://github.com/Andersonscat/tokiepet/issues
Keywords: desktop,pet,pixel,claude,tokens,macos,shimeji
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: MacOS X :: Cocoa
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Desktop Environment
Classifier: Topic :: Games/Entertainment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyobjc-core>=12.0
Requires-Dist: pyobjc-framework-Cocoa>=12.0
Requires-Dist: pyobjc-framework-Quartz>=12.0

# tokie

A pixel desktop pet that lives on top of your windows, walks across the edges of your terminal / browser / IDE, and slowly grows fatter on the tokens you've spent in [Claude Code](https://claude.com/claude-code).

macOS only (uses Cocoa + Quartz for the click-through overlay).

## Install (one-liner)

```bash
pip install git+https://github.com/Andersonscat/tokiepet.git
```

Then:

```bash
tokie start
```

That's it — the pet will start walking on top of your windows. Requires macOS 11+ and Python 3.9+. Dependencies (PyObjC) are installed automatically.

> A PyPI release under the name `tokiepet` is planned (the bare `tokie`
> name is squatted by an unrelated tokenizer). Once published, the
> one-liner will simplify to `pip install tokiepet`. The CLI command and
> Python import are both `tokie` either way.

### From source (for development)

```bash
git clone https://github.com/Andersonscat/tokiepet
cd tokiepet
pip install -e .
```

### Uninstall

```bash
tokie stop
pip uninstall tokiepet
rm -rf ~/.tokie
```

## Run

```bash
tokie            # foreground — Ctrl-C to quit
tokie start      # detach into the background
tokie stop       # kill any running instance
tokie status     # show pid + uptime
```

You can also run as a module:

```bash
python -m tokie
```

## What he does

- **Walks** along the top edges of any window on screen — terminal, browser, finder, IDE — and falls with gravity when you move that window out from under him.
- **Eats** whenever Claude spends tokens in `~/.claude/projects/**/*.jsonl`. Different food (berries / cookies / sushi / cake) per token type (input / output / cache read / cache write). Fatter when you've been coding a lot.
- **Sleeps** in a curl when he hasn't been fed in a while. Place a doghouse near him for a nicer nap.
- **Lounges** spontaneously when idle — lies down on his side, eyes open, tail flicking.
- **Roasts marshmallows** if you put a placed campfire next to him. Six-second roast cycle with browning marshmallow, then he eats it.
- **Plays Pixel Smash** — there's a built-in catapult + block-tower mini-game (toolkit in inventory → Games).
- **Falls with a parachute** if you drop him from a serious height.

## Interactions

- **Hover over him** with the cursor — eyes track, you can pet him by waving over his body, hearts spawn.
- **Drag** him anywhere with the mouse.
- **Click** him to toggle the stats dashboard (Health, Hunger, Joy, Energy, XP, token totals).
- **Inventory** lives in a small chest button — drag out a stick (he fetches), catapult, doghouse, fan, campfire, build pieces, or pet-card.
- **Pet card** opens his profile — click the name to rename him, toggle behaviour settings, see stats.

## State & data

All state is stored in `~/.tokie/state.json`. Token data is read from `~/.claude/projects/**/*.jsonl` — Tokie never sends anything anywhere.

If you previously had `~/claude-pet/state.json` from an older install, it's auto-migrated on first run.

## Requirements

- macOS 11+ (relies on `pyobjc-framework-Cocoa` 12+; older PyObjC 10.x segfaults when rendering borderless overlays).
- Python 3.9+
- A copy of Claude Code is optional — Tokie still works without any tokens to eat, he just won't grow.

## Status

Single-author hobby project. macOS only for now; Windows/Linux would need a different overlay backend (Qt/Tauri). Contributions welcome.

## License

MIT
