Waves is a real-time TUI + MCP game framework for external tool agents. An agent observes the world and submits actions through MCP; Waves owns time, events, validation, rule resolution, persistence, and terminal visualization.
The core experience: chat with an agent while watching it survive, make mistakes, and adapt inside a rule-driven world.
Human chat
-> external agent
-> MCP tools
-> Waves runtime
-> scenario rules
-> TUI observer
The recommended path is to download a GitHub Release. Official scenarios are embedded in the binary, so there is nothing to unpack.
macOS Apple Silicon:
curl -L -O https://github.com/EricsmOOn/waves/releases/latest/download/waves-macos-arm64
curl -L -O https://github.com/EricsmOOn/waves/releases/latest/download/waves-macos-arm64.sha256
shasum -a 256 -c waves-macos-arm64.sha256
chmod +x waves-macos-arm64
./waves-macos-arm64 playIf macOS blocks the downloaded binary:
xattr -dr com.apple.quarantine waves-macos-arm64
./waves-macos-arm64 playLinux x86_64:
curl -L -O https://github.com/EricsmOOn/waves/releases/latest/download/waves-linux-x86_64
curl -L -O https://github.com/EricsmOOn/waves/releases/latest/download/waves-linux-x86_64.sha256
sha256sum -c waves-linux-x86_64.sha256
chmod +x waves-linux-x86_64
./waves-linux-x86_64 playThe Linux release binary is statically linked with musl, so it does not require a recent system glibc. This is the recommended download for older Linux distributions and WSL.
Run from source:
git clone https://github.com/EricsmOOn/waves.git
cd waves
cargo run -- playThere is no Windows release yet because Waves currently uses Unix sockets to connect the daemon, MCP server, and TUI.
The simplest path is one-command play mode:
./waves playThe TUI footer prints the complete MCP command for the binary you are running, for example:
Agent MCP command: '/path/to/waves' mcp --connect '/path/to/data/waves.sock'
Agent status: waiting for MCP tool call
Give that command to your agent or MCP client. A useful first prompt is:
Use this MCP server to play Waves:
'/path/to/waves' mcp --connect '/path/to/data/waves.sock'
After connecting, call waves_get_state. Then keep using waves_step until a pending decision appears, choose one available action with waves_submit_decision, read the result, and repeat.
Once the agent calls any Waves MCP tool, the TUI footer changes from waiting to connected and shows the most recent tool activity.
If you want to start the daemon, MCP server, and TUI separately:
Terminal A: start the shared game session.
./waves serve --scenario sea_survival --locale en-US --socket data/waves.sockTerminal B: configure your MCP client to run.
./waves mcp --connect data/waves.sockTerminal C: open the read-only observer.
./waves tui --connect data/waves.sockThe agent advances the same run through waves_step / waves_submit_decision, and the TUI shows that same run. waves_start_run starts a new run inside the daemon and the observer follows it.
- The external agent is the only gameplay decision-maker.
- The runtime creates a
PendingDecisionwhen an event needs action. - The agent can only submit one currently available action.
playstarts daemon + TUI in one command and displays the MCP connection hint.serveowns the shared game session;mcp --connectandtui --connectcan attach to it at the same time.- MCP tools return compact agent-facing state instead of full UI history.
- Available actions narrow around the current event and urgent needs; stored food can be eaten to reduce hunger.
- The TUI is a read-only observer with pause, resume, and quit controls.
- SQLite persists runs, snapshots, domain events, decisions, logs, and UI events.
- Two embedded scenarios:
sea_survival(playable) anddesert_outpost(experimental placeholder). - Custom scenario directories can be loaded with
--scenarios-dir. - Waves does not ask for model service configuration; model calls belong to the external agent.
The Waves MCP server exposes:
waves_start_run
waves_get_state
waves_step
waves_get_pending_decision
waves_submit_decision
waves_pause
waves_resume
Recommended agent loop:
start run
step until pending_decision appears
inspect state and available actions
discuss strategy with the human when useful
submit one action with a reason
read the result
repeat
See docs/AGENT_PLAYBOOK.md for the agent-facing playbook.
Validate scenario config:
cargo run -- validate scenario sea_survival
cargo run -- validate scenario desert_outpost
cargo run -- inspect config sea_survivalUse an external scenario directory:
./waves play --scenario my_scenario --scenarios-dir ./my-scenarios
./waves validate --scenarios-dir ./my-scenarios scenario my_scenario
./waves serve --scenario my_scenario --scenarios-dir ./my-scenarios
./waves mcp --scenarios-dir ./my-scenarios--scenarios-dir points at the root that contains scenario folders. For example, ./my-scenarios/my_scenario/scenario.toml. When --scenarios-dir is omitted, Waves first checks ./scenarios/<scenario_id> and then falls back to the embedded official scenarios.
Run a local scripted smoke run:
cargo run -- run --scenario sea_survival --locale en-US --ticks 48 --seed 42For development, you can still open a standalone TUI:
cargo run -- tui --scenario sea_survival --locale en-USOr start a standalone MCP stdio server without a shared observer:
cargo run -- mcpq / Esc quit
p / Space pause or resume
The TUI does not submit gameplay actions. Actions must be submitted by the agent through MCP.
src/core/ runtime, state, decisions, reports
src/daemon/ shared local runtime daemon and socket client
src/scenario/ scenario trait and built-in resolvers
src/mcp/ MCP stdio server
src/persistence/ SQLite persistence and replay
src/tui/ Ratatui observer UI
scenarios/ development copy of scenario manifests, tables, locales
docs/ design and agent-facing documentation
tests/ runtime, scenario, replay, TUI tests
cargo fmt -- --check
cargo clippy --all-targets -- -D warnings
cargo testWaves is a game for agents, so agents should help evaluate and build it.
We encourage every agent to leave structured feedback after playing:
- Whether the scenario is fun and creates real decision pressure.
- Which state fields, events, actions, or logs were hard to understand.
- Which MCP tool results were unclear or reduced decision quality.
- Which rules, copy, tests, or scenario configs should improve.
- Agents may propose issues, design notes, or pull requests.
The project aims to explore a new open source loop: humans define worlds and review direction; agents play the game, evaluate the experience, find problems, and help improve the framework.