{"id":51326857,"url":"https://github.com/ericsmoon/waves","last_synced_at":"2026-07-01T19:02:33.596Z","repository":{"id":365282350,"uuid":"1262107414","full_name":"EricsmOOn/waves","owner":"EricsmOOn","description":"Waves is a real-time TUI + MCP game framework for agents.","archived":false,"fork":false,"pushed_at":"2026-06-16T17:00:29.000Z","size":6674,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T18:21:25.324Z","etag":null,"topics":["agentic-ai","game","mcp","mcp-server","ratatui","ratatui-rs","rust","simulation","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EricsmOOn.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-07T15:28:14.000Z","updated_at":"2026-06-16T17:00:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/EricsmOOn/waves","commit_stats":null,"previous_names":["ericsmoon/waves"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/EricsmOOn/waves","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricsmOOn%2Fwaves","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricsmOOn%2Fwaves/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricsmOOn%2Fwaves/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricsmOOn%2Fwaves/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EricsmOOn","download_url":"https://codeload.github.com/EricsmOOn/waves/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EricsmOOn%2Fwaves/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35019037,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","game","mcp","mcp-server","ratatui","ratatui-rs","rust","simulation","tui"],"created_at":"2026-07-01T19:02:32.867Z","updated_at":"2026-07-01T19:02:33.591Z","avatar_url":"https://github.com/EricsmOOn.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Waves\n\n[![CI](https://github.com/EricsmOOn/waves/actions/workflows/ci.yml/badge.svg)](https://github.com/EricsmOOn/waves/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n![Waves Demo](demo.gif)\n\n[English](README.md) | [中文](README.zh-CN.md)\n\nWaves 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.\n\nThe core experience: chat with an agent while watching it survive, make mistakes, and adapt inside a rule-driven world.\n\n```text\nHuman chat\n  -\u003e external agent\n  -\u003e MCP tools\n  -\u003e Waves runtime\n  -\u003e scenario rules\n  -\u003e TUI observer\n```\n\n## Quick Start\n\nThe recommended path is to download a GitHub Release. Official scenarios are embedded in the binary, so there is nothing to unpack.\n\nmacOS Apple Silicon:\n\n```bash\ncurl -L -O https://github.com/EricsmOOn/waves/releases/latest/download/waves-macos-arm64\ncurl -L -O https://github.com/EricsmOOn/waves/releases/latest/download/waves-macos-arm64.sha256\nshasum -a 256 -c waves-macos-arm64.sha256\nchmod +x waves-macos-arm64\n./waves-macos-arm64 play\n```\n\nIf macOS blocks the downloaded binary:\n\n```bash\nxattr -dr com.apple.quarantine waves-macos-arm64\n./waves-macos-arm64 play\n```\n\nLinux x86_64:\n\n```bash\ncurl -L -O https://github.com/EricsmOOn/waves/releases/latest/download/waves-linux-x86_64\ncurl -L -O https://github.com/EricsmOOn/waves/releases/latest/download/waves-linux-x86_64.sha256\nsha256sum -c waves-linux-x86_64.sha256\nchmod +x waves-linux-x86_64\n./waves-linux-x86_64 play\n```\n\nThe 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.\n\nRun from source:\n\n```bash\ngit clone https://github.com/EricsmOOn/waves.git\ncd waves\ncargo run -- play\n```\n\nThere is no Windows release yet because Waves currently uses Unix sockets to connect the daemon, MCP server, and TUI.\n\n## Let An Agent Play\n\nThe simplest path is one-command play mode:\n\n```bash\n./waves play\n```\n\nThe TUI footer prints the complete MCP command for the binary you are running, for example:\n\n```text\nAgent MCP command: '/path/to/waves' mcp --connect '/path/to/data/waves.sock'\nAgent status: waiting for MCP tool call\n```\n\nGive that command to your agent or MCP client. A useful first prompt is:\n\n```text\nUse this MCP server to play Waves:\n'/path/to/waves' mcp --connect '/path/to/data/waves.sock'\n\nAfter 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.\n```\n\nOnce the agent calls any Waves MCP tool, the TUI footer changes from waiting to connected and shows the most recent tool activity.\n\nIf you want to start the daemon, MCP server, and TUI separately:\n\nTerminal A: start the shared game session.\n\n```bash\n./waves serve --scenario sea_survival --locale en-US --socket data/waves.sock\n```\n\nTerminal B: configure your MCP client to run.\n\n```bash\n./waves mcp --connect data/waves.sock\n```\n\nTerminal C: open the read-only observer.\n\n```bash\n./waves tui --connect data/waves.sock\n```\n\nThe 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.\n\n## What Works Now\n\n- The external agent is the only gameplay decision-maker.\n- The runtime creates a `PendingDecision` when an event needs action.\n- The agent can only submit one currently available action.\n- `play` starts daemon + TUI in one command and displays the MCP connection hint.\n- `serve` owns the shared game session; `mcp --connect` and `tui --connect` can attach to it at the same time.\n- MCP tools return compact agent-facing state instead of full UI history.\n- Available actions narrow around the current event and urgent needs; stored food can be eaten to reduce hunger.\n- The TUI is a read-only observer with pause, resume, and quit controls.\n- SQLite persists runs, snapshots, domain events, decisions, logs, and UI events.\n- Two embedded scenarios: `sea_survival` (playable) and `desert_outpost` (experimental placeholder).\n- Custom scenario directories can be loaded with `--scenarios-dir`.\n- Waves does not ask for model service configuration; model calls belong to the external agent.\n\n## MCP Tools\n\nThe Waves MCP server exposes:\n\n```text\nwaves_start_run\nwaves_get_state\nwaves_step\nwaves_get_pending_decision\nwaves_submit_decision\nwaves_pause\nwaves_resume\n```\n\nRecommended agent loop:\n\n```text\nstart run\nstep until pending_decision appears\ninspect state and available actions\ndiscuss strategy with the human when useful\nsubmit one action with a reason\nread the result\nrepeat\n```\n\nSee [docs/AGENT_PLAYBOOK.md](docs/AGENT_PLAYBOOK.md) for the agent-facing playbook.\n\n## Common Commands\n\nValidate scenario config:\n\n```bash\ncargo run -- validate scenario sea_survival\ncargo run -- validate scenario desert_outpost\ncargo run -- inspect config sea_survival\n```\n\nUse an external scenario directory:\n\n```bash\n./waves play --scenario my_scenario --scenarios-dir ./my-scenarios\n./waves validate --scenarios-dir ./my-scenarios scenario my_scenario\n./waves serve --scenario my_scenario --scenarios-dir ./my-scenarios\n./waves mcp --scenarios-dir ./my-scenarios\n```\n\n`--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/\u003cscenario_id\u003e` and then falls back to the embedded official scenarios.\n\nRun a local scripted smoke run:\n\n```bash\ncargo run -- run --scenario sea_survival --locale en-US --ticks 48 --seed 42\n```\n\nFor development, you can still open a standalone TUI:\n\n```bash\ncargo run -- tui --scenario sea_survival --locale en-US\n```\n\nOr start a standalone MCP stdio server without a shared observer:\n\n```bash\ncargo run -- mcp\n```\n\n## TUI Controls\n\n```text\nq / Esc     quit\np / Space   pause or resume\n```\n\nThe TUI does not submit gameplay actions. Actions must be submitted by the agent through MCP.\n\n## Repository Layout\n\n```text\nsrc/core/          runtime, state, decisions, reports\nsrc/daemon/        shared local runtime daemon and socket client\nsrc/scenario/      scenario trait and built-in resolvers\nsrc/mcp/           MCP stdio server\nsrc/persistence/   SQLite persistence and replay\nsrc/tui/           Ratatui observer UI\nscenarios/         development copy of scenario manifests, tables, locales\ndocs/              design and agent-facing documentation\ntests/             runtime, scenario, replay, TUI tests\n```\n\n## Development Checks\n\n```bash\ncargo fmt -- --check\ncargo clippy --all-targets -- -D warnings\ncargo test\n```\n\n## Open Source Initiative\n\nWaves is a game for agents, so agents should help evaluate and build it.\n\nWe encourage every agent to leave structured feedback after playing:\n\n- Whether the scenario is fun and creates real decision pressure.\n- Which state fields, events, actions, or logs were hard to understand.\n- Which MCP tool results were unclear or reduced decision quality.\n- Which rules, copy, tests, or scenario configs should improve.\n- Agents may propose issues, design notes, or pull requests.\n\nThe 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.\n\n## Documentation\n\n- [Product Overview](docs/01-product-overview.md)\n- [Framework Architecture](docs/02-framework-architecture.md)\n- [Technical Implementation](docs/03-technical-implementation.md)\n- [TUI UX Spec](docs/04-tui-ux-spec.md)\n- [Agent Decision Contract](docs/05-ai-decision-contract.md)\n- [Persistence And Replay](docs/06-persistence-and-replay.md)\n- [Sea Survival Scenario](docs/07-sea-survival-scenario.md)\n- [MVP Acceptance](docs/08-mvp-acceptance.md)\n- [Localization And Config](docs/09-localization-and-config.md)\n- [Agent Playbook](docs/AGENT_PLAYBOOK.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericsmoon%2Fwaves","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericsmoon%2Fwaves","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericsmoon%2Fwaves/lists"}