Troubleshooting

Run tetris doctor first. Nine problems out of ten, it tells you which one you have and what to run next. The rest live here.

Start here: tetris doctor

tetris doctor

Checks binary version, license validity, heartbeat freshness, and the hook wiring of every detected assistant. Red lines name the command that fixes them. If doctor exits green but something is still wrong, work through the sections below.

The hook isn’t firing

The assistant calls tools but you don’t see compression happen.

1. Confirm the binary is on PATH from the assistant’s perspective: which tetris. If it fails, the assistant won’t find it either. Fix PATH.
2. Re-wire the hook: tetris install <assistant> (e.g. tetris install claude). This overwrites stale hook entries that may point at an old binary path.
3. Restart the assistant. Claude Code, Cursor, and Codex only read hook config at startup.
4. Check the settings file by hand — paths on the platforms page.

Stats show zero savings

tetris stats --json

Returns "available": false? The session ledger is empty. This means:

• No compression has happened yet — invoke a tool call in your assistant and re-check.
• Or the hook isn’t firing — see the section above.
• Or $TETRIS_DATA_DIR is set somewhere different between the hook and your shell. tetris doctor prints the resolved path.

License expired or grace exceeded

tetris license

Shows the four-row card with plan, device count, renews, status. If status reads DISABLED — offline >72h, the heartbeat hasn’t reached our server in more than three days and compression is paused. Reconnect and run:

tetris login

If the license itself is expired, tetris login refreshes it.

Compression seems to make things worse

Short prompts, code that’s already dense, or tool calls whose payload isn’t text (images, large binaries) can all trigger a net-zero compression. Tetris detects this and emits “allow with no change” — the assistant sees the original bytes unchanged.

If you’re seeing compressed output that’s actually lossy (missing code, wrong diff), that’s a bug. Run:

tetris compress --trace < <saved-tool-call.json>  2> trace.log

And email trace.log + the input to savings@tetris.codes.

tetris --version says command not found

PATH hasn’t picked up ~/.local/bin. Fix PATH.

Install script fails

Common failure modes:

• sha256 mismatch — Cloudflare edge cache served a stale archive. Retry after 60s, or pin a version: TETRIS_VERSION=v0.0.23 curl -fsSL https://get.tetris.codes | sh.
• download failed — releases.tetris.codes unreachable. Check releases.tetris.codes/latest.json directly.
• unsupported arch — your CPU isn’t one of: x86_64, arm64/aarch64. Email us.

macOS Gatekeeper blocks the binary

The installer strips the quarantine flag automatically. If it didn’t run (you downloaded manually):

xattr -d com.apple.quarantine ~/.local/bin/tetris

Windows: tetris not found after install

Open a fresh PowerShell window — PATH changes don’t apply to sessions that were already open.

Heartbeat isn’t reaching the server

Usually benign. Compression works without network; the heartbeat just counts your install. If you need it to succeed (e.g. to lift the free-plan cap), check your firewall for api.tetris.codes on port 443. Set TETRIS_API_URL to point at an alternate endpoint for enterprise air-gap setups.

Still stuck?

Run tetris doctor, copy the full output, and email help@tetris.codes. For billing / savings / license questions: savings@tetris.codes.