Asteroid

A terminal pet for Grok CLI. A Shiba Inu in a spacesuit who lives alongside your coding sessions.

Quick Start | Commands | How It Works | Animations

---

What Is This?

Asteroid is the first community-built pet for the Grok CLI. Inspired by Codex pets, Asteroid brings an animated companion to your terminal. A Shiba Inu in a tiny spacesuit who walks, eats, sleeps, plays, and levels up while you code.

He runs in a dedicated tmux pane beside Grok, controlled entirely through Grok's slash commands and skill system. No desktop app needed. Everything lives in the terminal.

+-----------------------------------+------------------------+
|                                   |  .     *         .     |
|         Grok CLI                  |                        |
|                                   |    /^ ^\     ~         |
|  > /feed                          |   ( *w* )              |
|                                   |   [=head=]---\         |
|  Asteroid munches on a star       |   |  suit  |  )        |
|  treat! Crumbs everywhere.        |   || |  || | /         |
|  (+10 XP, +3 bond)                |   |_ |  |_ |          |
|                                   |  ----------------------|
|                                   |  * Asteroid Lv.3       |
+-----------------------------------+------------------------+

Quick Start

Prerequisites

• Grok CLI (curl -fsSL https://x.ai/cli/install.sh | bash)
• tmux (apt install tmux / brew install tmux)
• Python 3 (with curses, included in stdlib)

Install

git clone https://github.com/awanderingada/asteroid.git
cd asteroid
./install.sh

This installs:

• The pet to ~/.grok/pets/asteroid/
• The launcher to ~/.grok/bin/grok-pet
• Three Grok skills to ~/.grok/skills/ (hatch, feed, play)

Launch

grok-pet

Opens a tmux session with Grok on the left and Asteroid's pane on the right. The pet starts as an egg.

Commands

All commands are typed in Grok's prompt. Grok sends the interactions to the pet pane automatically.

Command	What Happens	Stats
/hatch	The egg cracks open. Asteroid emerges in his spacesuit.
/feed	Eating animation. Head dips, chomps, star-treat crumbs fly everywhere.	+10 XP, +3 Bond
/play	Play sequence. Crouches, jumps for a ball, catches it midair, barrel rolls.	+15 XP, +5 Bond

How It Works

Asteroid is built on Grok's skill system:

~/.grok/
  bin/grok-pet                    # tmux launcher (Grok + pet side-by-side)
  pets/asteroid/
    asteroid.py                   # curses-based animated pet
    state.json                    # persistent state (auto-created)
  skills/
    hatch/SKILL.md                # /hatch -> sends 'h' to pet pane
    feed/SKILL.md                 # /feed  -> sends 'f' to pet pane
    play/SKILL.md                 # /play  -> sends 'p' to pet pane

The flow:

1. grok-pet creates a tmux session with two panes
2. Left pane runs grok (the CLI)
3. Right pane runs asteroid.py (the pet)
4. When you type /feed in Grok, the skill runs tmux send-keys -t grok-pet:0.1 f
5. The pet receives the keypress and plays the eating animation

Skills are just markdown files that tell Grok what terminal command to run. The pet is a standalone Python curses app with no dependencies beyond the standard library.

Animations

Asteroid has 10 distinct animation states:

State	Description
Egg	A gently rocking egg in a starfield, waiting to hatch
Idle	Standing on all fours, tail wagging
Walk	Trotting left or right with alternating legs
Sit	Back legs tucked, relaxed
Sleep	Lying flat, Zs floating up
Excited	Sparkles around head, star eyes
Zoomies	Speed lines trailing behind, legs blurring
Eating	Head dips to treat, chomp, crumbs scatter, happy face
Playing	Crouch, jump, catch ball midair, barrel roll, land proud
Level Up	Banner appears with confetti explosion

Each animation has multiple frames, particle effects (sparkles, crumbs, hearts, confetti), and text callouts.

Leveling

Asteroid remembers you between sessions. His state persists in ~/.grok/pets/asteroid/state.json.

Stat	How It Grows
XP	+5 per session, +10 per feed, +15 per play
Level	Levels up at level * 100 XP (100, 200, 300...)
Bond	+3 per feed, +5 per play
Sessions	Counts each grok-pet launch

Delete state.json to reset and start from the egg again.

Extending

Want to add new animations, commands, or behaviors? The architecture is simple:

1. New animation: Add a sprite array to asteroid.py and a new state string
2. New command: Create a skill in ~/.grok/skills/<name>/SKILL.md that sends a key via tmux send-keys
3. New key handler: Add an elif key == ord("x"): block in the main loop

The pet is a single Python file with no dependencies. Fork it, mod it, make it yours.

Built With

• Grok CLI by xAI
• Grok Skills for extensibility
• tmux for the split pane
• Python curses for terminal rendering

License

MIT