sidequest

Ever wondered what to do while waiting for an ansible playbook to finish, a build to complete, or a long-running script to finish? Ever tried to look busy while you just wait for Codex to do your stuff ?

Look no further!

Sidequest runs your command in one tmux pane and focuses a small Snake game in another. The command stays visible, so you can follow what's happening while you play. Now with Boss-Key(F9). You also get noticed when the command finishes. By default, command-pane output is stored for later review, so we could say you're doing some documentation along the way.

Contents

• Installation
• Quick Start
• Gameplay
• FAQ / Known Issues

Installation

Sidequest currently supports Linux amd64 and arm64. Windows users should run Sidequest inside WSL 2.

Install the latest release:

curl -fsSL https://github.com/WBT112/sidequest/releases/latest/download/install.sh | sh -s -- --update-path

Open a new terminal after installation, then verify:

sidequest --version

Sidequest requires tmux at runtime (sudo apt install tmux or sudo dnf install tmux). Release assets also include .deb and .rpm packages for manual installation.

Quick Start

sidequest -- ssh deploy@example.com
sidequest -- sh -c 'sudo du -xh /var /usr /home 2>/dev/null | sort -h'
sidequest --no-history -- ssh production.example.com
sidequest --no-color -- make test
sidequest --graphics ascii -- ssh legacy-host.example.com
sidequest --aug -- make test
sidequest --mode quest -- make test
sidequest -- codex
sidequest -- claude "Run the test suite, fix any failures, and summarize the changes."

Try it with a harmless demo workload:

sidequest --aug -- bash -c 'for i in {1..60}; do printf "working step %02d/60\n" "$i"; sleep 1; done'

Gameplay

• WASD or arrow keys move Snake.
• F9 hides or restores Sidequest while the command keeps running.
• F12 switches between Snake and the command pane.
• Snake focus-pauses while the command pane is active and resumes when the game pane is active again, unless you paused manually.
• In the command pane, Page Up and Page Down scroll pages; arrow up and arrow down scroll line by line. Scrolling back to the bottom resumes live command output.
• F10 detaches back to your shell. If the command is still running, Sidequest prints the sidequest attach <id> command.
• R restarts Snake after a round over while the command keeps running.
• After the command finishes, C continues the current round. Use F10 to return to your shell.

Classic mode keeps Snake simple and adds Command Heat: the longer you actively play, the faster Snake gets and the more food is worth. Time spent in the command pane, on pause, or in the command-finished choice does not raise Heat. If you press C after the command finishes, the same round continues and Heat resumes increasing only during active gameplay.

Quest mode adds combo scoring, one mission per command, Golden Bytes that grow Snake by two cells, random arena pickups and other stuff.

Use --aug to show the latest command output line centered in the game pane while the original command pane stays unchanged.

Use --no-color or a non-empty NO_COLOR environment variable for monochrome Sidequest game/UI rendering. Wrapped command output is left untouched.

For complete controls and behavior details, use:

man sidequest

FAQ / Known Issues

Snake graphics look wrong in MobaXterm or older SSH terminals

Some terminals render block characters differently. Sidequest keeps rich block graphics by default, but can use a safer ASCII fallback:

sidequest --graphics ascii -- <command>

If Sidequest detects a fallback but your terminal renders rich graphics correctly, force the default style:

sidequest --graphics rich -- <command>

Sessions and History

Runtime sessions:

sidequest list
sidequest attach <session-id>

Stored run history:

sidequest runs
sidequest show last
sidequest output last
sidequest purge <run-id>

By default, finished runs keep visible command-pane output under ${XDG_STATE_HOME:-$HOME/.local/state}/sidequest/runs/. Sidequest stores result metadata and pane output, not the command or argument list. Terminal output may still contain sensitive data.

For sensitive workloads, disable run history:

sidequest --no-history -- <command> [arguments...]

In no-history mode, Sidequest does not capture the command pane, does not write an output file, and does not create stored run metadata. The live tmux pane scrollback remains visible until the Sidequest session is closed.

Game statistics and separate Classic/Quest TOP 5 lists are stored locally in ${XDG_STATE_HOME:-$HOME/.local/state}/sidequest/game-stats.json.

Development

Sidequest is built and released with Go 1.26.5.

Run the normal local quality suite before committing:

./scripts/qa.sh

If Go is not available as go in PATH, point the script at the Go binary:

GO=/usr/local/go/bin/go ./scripts/qa.sh

Extended checks:

./scripts/qa.sh --race
./scripts/qa.sh --cover
./scripts/qa.sh --vuln
./scripts/qa.sh --race --cover

Scope

Sidequest is meant for builds, upgrades, deployments and scripts that should stay visible but do not need constant attention. It does not modify the wrapped command, replace tmux, hide interactive prompts or act as a full terminal emulator. Do not use this on production servers of course. I try to make Sidequest as safe as possible, but it is still a game and may have bugs. Use at your own risk.