xonecas.io
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).