Build with an assistant (draft)
An AI assistant can build in Hyprune for you: “a cosy rooftop garden at sunset with three
screens and a CPU tower that glows” becomes a world you can walk, keep, change and release.
It works through hyprune mcp, a Model Context Protocol
server in the Hyprune SDK. Any MCP client can use it; Hyprune runs no model and sends nothing
anywhere itself. The design is RFC-0016.
Connecting a client
Section titled “Connecting a client”Add a local (stdio) MCP server to your assistant with the command hyprune mcp. The exact
place differs per client: a settings page for MCP servers, or a JSON entry like
{"mcpServers": {"hyprune": {"command": "hyprune", "args": ["mcp"]}}}The assistant should run inside your Hyprland session (so the server finds Hyprune’s control
socket); HYPRUNE_SOCKET names it otherwise. Clients that load agent skills can also take the
hyprune-world-builder skill: hyprune mcp --install-skill <your skills folder>. Every client
also gets it as the MCP prompt build_a_world.
Approving it
Section titled “Approving it”When the server starts, Hyprune asks: the HUD shows “$XDG_STATE_HOME/hyprune/approvals.json; Director → Builder → Connected assistants lists
remembered ones with Revoke.
What it can and can’t do
Section titled “What it can and can’t do”| It can | It can’t |
|---|---|
| Make and open world folders, set the sky, the floor and the spawn | See or use your windows, workspaces, input, camera or focus |
| Place shapes, catalog objects and workspace screens; move, resize and remove them | Change your settings, keymap or Hyprune’s own files |
| Make materials, import model files you name (with their licence, author and source) | Download files itself from anywhere but the libraries below |
| Set HTTP data sources and data-driven behaviours | Read secrets (it can name one you set) |
| Propose a command data source | Run it: Objects → Data sources shows the command with Allow |
| Choose, name and set your companion; make quests | Import new characters (that stays yours) |
| Search and install official or community packages | Add or refresh package sources |
| Fetch CC0 textures, skies and models from Poly Haven, ambientCG or Kenney | Fetch from other sites (you or your assistant app can download files and name them) |
| Fill in a release (version and notes) for you | Press Release |
| Look at what it built (rendered previews), read the checklist | Release, push or publish anything |
| Save (a local commit labelled “Assistant: “) and undo its own steps | Act after you disconnect it |
While it is connected, the HUD shows the Assistant chip: its name, how many changes it made and its last action. Connected assistants has Pause (its changes are refused until you resume) and Disconnect (it ends; the assistant has to be restarted to ask again).
Undoing its work
Section titled “Undoing its work”Everything it changes in a world folder stays unsaved until it or you save, so Director →
Builder shows the unsaved changes and the checklist as it works. The assistant’s undo reverses
its own steps, newest first; undoing everything since the last save leaves the folder exactly
as saved. Saves are ordinary commits: the Builder page’s history shows which ones an assistant
made.
Previews
Section titled “Previews”look renders the world from a pose. With Hyprune running and the folder open, Hyprune draws it
in a separate process (hyprune-preview, never in the compositor’s render pass and never by
moving your camera); screens show empty, never your windows. Without Hyprune, the SDK draws a
simple CPU preview of the folder.