Usage

Once tetris is installed and wired into an assistant, there is nothing to start, nothing to keep open, nothing to remember. This page covers the small set of commands you actually use day to day.

1. The five commands you’ll use

Command	When
`tetris doctor`	First thing if anything looks wrong. Inspects binary, license, heartbeat, every assistant’s hook wiring. One-pass diagnostic.
`tetris stats`	Lifetime + month-to-date savings, top strategies, per-assistant breakdown. Reads the local ledger; no network.
`tetris dashboard`	Same data, but live in your browser at `http://localhost:8787`. Updates in real time as your assistant fires tool calls.
`tetris login`	One-time after install (the onboarding wizard runs this for you). Re-run if your license expires or after 72h offline.
`tetris install <assistant>`	Add a hook to a new assistant. Idempotent — safe to re-run after the assistant updates and clobbers its config.

2. What happens when your assistant calls a tool

Your assistant (Claude Code, Codex, Gemini, …) is about to send a tool call to the model.
The pre-tool hook fires, piping the tool call (JSON) into tetris compress.
Tetris extracts the large prose / file-body fields, runs them through the compression pipeline (eight stages, picks what helps), reassembles the JSON, and prints the compressed version on stdout.
The assistant sends the compressed version to the model. The model sees less context. You pay for fewer tokens.
Tetris records the savings to the ledger at ~/.tetris/ledger.jsonl.

Total wall-clock overhead: tens of milliseconds for typical inputs. Large file pastes (10 KB+) might add up to ~150 ms; everything else is dominated by the network round-trip you were already paying.

3. Verify compression is firing

The simplest test — ask your assistant to read a long file. Then:

tetris stats --json

You should see "compressions": N increase by 1 after each tool call. If "available": false persists after invoking a tool, the hook isn’t firing — see troubleshooting.

4. Read your stats

tetris stats

Default human view. Three sections:

Lifetime — total compressions, tokens saved, dollars saved (priced against the destination model’s public rate at the time of the call).
Month-to-date — same metrics for the current calendar month. The Free plan’s $150/mo cap is read against this row.
Top strategies — which compression stages contributed the most savings. Useful when reasoning about what kind of context your assistant produces most.

For machine-readable output: tetris stats --json.

5. Live dashboard

tetris dashboard

Spawns a local web server at http://localhost:8787 that streams live ledger updates. Useful for watching a long agent run in real time. Ctrl+C to stop. Nothing leaves your machine; the server binds to 127.0.0.1 only.

6. Update tetris

curl -fsSL https://get.tetris.codes | sh

The same one-liner that installed tetris also updates it. The installer downloads the latest release, verifies the SHA-256 against releases.tetris.codes/latest.json, replaces the binary, and re-runs the hook installer for every assistant whose config it can find. Safe to re-run on the same machine repeatedly.

To pin a specific version (avoid auto-updating in CI): TETRIS_VERSION=v0.0.27 curl -fsSL https://get.tetris.codes | sh.

7. Add a new assistant after the fact

You installed Codex last month, then added Cursor. Wire it in:

tetris install cursor

Or wire every assistant on the machine in one pass:

tetris install

This is also the right command after an assistant updates and silently rewrites its config — if tetris doctor shows a yellow line for an assistant that used to be green, run the install command for that assistant to re-add the hook.

8. Manage the license

tetris license

Shows plan, device count, monthly cap, renewal date, status. To switch accounts:

tetris logout
tetris login

To list devices currently consuming a slot under your license (Pro / Team / Enterprise):

tetris devices

9. Where things live on disk

Path	What
`~/.local/bin/tetris`	The binary (Unix). Windows: `%LOCALAPPDATA%\tetris\tetris.exe`.
`~/.tetris/ledger.jsonl`	Append-only session log. One JSON line per compression. `tetris stats` reads this.
`~/.tetris/license`	Your signed JWT. Contains plan, device limit, expiry. Generated by `tetris login`.
`~/.tetris/heartbeat`	Timestamp of the last successful contact with our license server. Used by the 72h offline grace gate.
`~/.tetris/last_heartbeat.txt`	The 6h rate limiter for outbound heartbeats. Distinct file from the grace timestamp; same stamp is written to both on success.
`~/.tetris/install_id`	A pseudonymous UUID we use to count distinct devices for the community stats and your license’s device cap. Never tied to your email.
`~/.tetris/backups/<assistant>/`	Timestamped backups of each assistant’s settings file before the hook was added. Used by `tetris uninstall` to restore.

To use a different data directory entirely (CI runners, isolated profiles), set TETRIS_DATA_DIR before running anything.

10. Patterns that catch people out

Restart the assistant after a fresh install. Claude Code, Codex, and Cursor read hook config at startup — the hook you just added isn’t live until you reopen the app.
Hook entries are fully replaceable. If you nuke ~/.claude/settings.json, run tetris install claude-code to put the hook back. No state is lost.
Compression is allowed to no-op. Short tool calls, dense code, or non-text payloads pass through unchanged — that’s correct, not a bug.
The license check is cached per process. If you upgrade your plan, restart the assistant once so the cached cap re-reads.
The ledger is append-only and idempotent. Safe to copy between machines for backup — but the per-machine install_id stays unique, so “active devices” will count both.

11. Going deeper

Supported assistants — full matrix with config-file paths and known limitations.
Troubleshooting — common failures and the exact commands to fix them.
Privacy — precisely what the heartbeat contains and what never leaves your machine.
Methodology — the math behind the “tokens saved” and “dollars saved” numbers.