60255
Zn
Zoea-Nova / files
Zoea-Nova / README.md
4.2 KB
1<p align="center"> 2 <img src="assets/logos/logo-brand.svg" width="300" alt="Zoea-Nova Logo"> 3</p> 4 5# Zoea-Nova 6 7Zoea-Nova is a high-performance command center designed to orchestrate massive swarms of Myses within the SpaceMolt universe. It synchronizes individual larval clients into a singular, explosive force capable of dominating the Crustacean Cosmos through unified tactical maneuvers. By bridging the gap between micro-unit control and cosmic-scale strategy, it allows you to pilot an entire fleet as a single, unstoppable organism. 8 9> **It's actually just a fancy TUI App to control several mcp clients for the game: [SpaceMolt](https://www.spacemolt.com/)** 10 11## Preview 12 13<br /> 14<p align="center"> 15 <img src="assets/preview.gif" width="800" alt="Zoea-Nova Preview"> 16</p> 17 18## Features 19 20- **Swarm Control**: Create and manage multiple AI Myses, each with independent memory and LLM provider 21- **Broadcast Messaging**: Send commands to all Myses simultaneously with tracked history 22- **Direct Messaging**: Target individual Myses for specific tasks 23- **Tool Calling**: Myses use MCP to interact with SpaceMolt (mine, trade, navigate, etc.) 24- **Focus Mode**: View detailed conversation logs for any Mysis 25- **Provider Flexibility**: Use local Ollama or remote OpenCode Zen models per-Mysis 26- **Context Compression**: Sliding window keeps LLM context small for fast inference while full history remains searchable (see [documentation](documentation/architecture/CONTEXT_COMPRESSION.md)) 27- **Memory Search**: Myses can search past messages and broadcasts to recall older information 28 29## Terminology 30 31Zoea Nova uses a small set of in-app terms (Mysis, Commander, Swarm, Provider, MCP). The canonical glossary lives in `AGENTS.md` under the Terminology section. 32 33## Requirements 34 35**Terminal:** 36- Minimum size: 80 columns × 20 lines 37- TrueColor support recommended (24-bit RGB) 38- Unicode font (Nerd Font or Unicode-compatible font) 39 40**Recommended Terminals:** 41- Alacritty, Kitty, WezTerm, Ghostty (best compatibility) 42- iTerm2 (macOS), Windows Terminal (with Nerd Font) 43 44See `documentation/guides/TERMINAL_COMPATIBILITY.md` for detailed compatibility information. 45 46## Try it 47 48```sh 49make run # Build and start 50make install # Install to ~/.zoea-nova/bin/zoea 51./bin/zoea # Run directly 52 53or 54 55./bin/zoea -debug # With debug logging 56./bin/zoea -offline # Run in offline mode (mock game server) 57``` 58 59## CLI Flags 60 61- `--config <path>` - Path to config file (default: `./config.toml` or `~/.zoea-nova/config.toml`) 62- `--debug` - Enable debug logging 63- `--offline` - Run in offline mode (stub MCP server) 64- `--start-swarm` - Auto-start all idle myses on launch (excludes errored myses; default: disabled) 65 66## Creating a Mysis 67 68Press `n` to create a new mysis. You'll be prompted for: 69 701. **Name** (required) - Unique identifier for the mysis 712. **Provider** (optional) - Leave empty to use default from config, or specify: 72 - `ollama` - Local Ollama with qwen3:8b 73 - `ollama-qwen` - Local Ollama with qwen3:8b 74 - `ollama-qwen-small` - Local Ollama with qwen3:4b 75 - `ollama-llama` - Local Ollama with llama3.1:8b 76 - `opencode_zen` - OpenCode Zen with gpt-5-nano (default) 77 - `zen-nano` - OpenCode Zen with gpt-5-nano 78 - `zen-pickle` - OpenCode Zen with big-pickle 79 80The model is determined by the provider's configuration in `config.toml`. 81 82## Keyboard Shortcuts 83 84| Key | Action | 85| --------- | --------------------------- | 86| `n` | Create new Mysis | 87| `b` | Broadcast message to all | 88| `m` | Message selected Mysis | 89| `r` | Relaunch Mysis | 90| `s` | Stop Mysis | 91| `d` | Delete Mysis | 92| `c` | Configure Mysis | 93| `Enter` | Focus on selected Mysis | 94| `Esc` | Return to dashboard | 95| `v` | Toggle verbose JSON (focus) | 96| `k / ↑` | Navigate up / Scroll up | 97| `j / ↓` | Navigate down / Scroll down | 98| `PgUp` | Page up (fast scroll) | 99| `PgDn` | Page down (fast scroll) | 100| `?` | Show help | 101| `q` | Quit | 102 103## Known Issues 104 105For a list of current bugs, technical debt, and planned improvements, see [KNOWN_ISSUES.md](documentation/current/KNOWN_ISSUES.md).