termquarium

A living aquarium in your terminal. Zero dependencies, one crab.

~≈~~~~~~≈~~~~~~≈~~~~~~≈~~~~~~≈~~~~~~≈~~~~~~≈~~~~~~≈~~
                                      O
                                          ·>         o
                        .                        .  .
                      <*)))><        ><>       <°))><
                                                      
         ><((°> ><((°>                         ><>
                                                      
                                              n
       n
                                         )           (
       (             (                   (           )
       )             )                   ((\/)       (
:·,,·..:·,,·..:·,,·..:·,,·..:·,,·..:·,,·..:·,,·..:·,,·

Four species of fish wander, bounce, and blow bubbles. Jellyfish drift up and respawn. A crab patrols the sand. Seaweed sways. And every 15–40 seconds… dun dun… dun dun… — a shark crosses the tank and everyone politely panics.

Usage

npx termquarium

npx termquarium --fish 40 --fps 30
npx termquarium --seed "my tank"      # the same tank, every time
npx termquarium --duration 60         # a 60-second screensaver

# or keep it around:
npm install -g termquarium

Keys

| Key | Action | | --- | ------------------------------------------ | | f | drop food — the fish will race each other | | p | pause / resume | | q | drain the tank |

How it works

The whole aquarium is a pure simulation:

tick(world, dt, rng)  →  renderCells(world)  →  ANSI frame

• world.ts — all behavior: fish wander and bounce off glass, seek the nearest food flake, flee the shark at 1.8× speed; bubbles rise and pop; jellyfish drift; the crab scuttles; the shark spawns on a timer, crosses, and leaves.
• render.ts — painter's-order projection to a character grid, then a thin ANSI compositor. renderText exists purely so tests can assert on frames.
• cli.ts — a dumb loop: tick, render, write. Alt-screen, raw keys, resize handling, and guaranteed terminal restore on exit.

Everything interesting is deterministic under a seeded RNG, which is why the fish physics, feeding frenzy, shark lifecycle, and frame geometry all have unit tests. Yes, there are unit tests for a fish tank. pnpm test.

Development

pnpm install
pnpm test
pnpm typecheck
pnpm build

License

MIT © Gyan Prakash Karn