Quick Start

Quick Start🔗

A world in the window, an agent in a terminal beside it, in a few minutes. To previs a screenplay with nothing installed, drop it on localgpt.md instead.

1. Open a world🔗

# from a checkout (see Installation for the macOS bundle)
cargo run -p localgpt-app -- --doc notes.md         # a Markdown document as a world
cargo run -p localgpt-app -- --song track.mp3      # a song as a world that performs it
cargo run -p localgpt-app -- --world harbour.world # a .world package, opened as a live canvas
cargo run -p localgpt-app                          # reopens what was opened last; a starter song the first time

A document rebuilds as you type; a song plays its world; a package opens live, with its history in the left panel.

2. Open a terminal, run your agent🔗

The + on the right opens a terminal: your login shell, started in the folder of what is open. Run whatever agent you have in it:

claude      # or codex, gemini, opencode, …

Nothing is configured in LocalGPT: no model, no key. In a live package’s folder the agent finds AGENTS.md, which tells it how to change the world, and the world’s API address in .live/endpoint.json. Ask it to hang a lamp by the crate, and the lamp lands in the window as one entry in the history, attributed to the agent, undoable, with a branch if it built on an earlier entry.

A phone or a tablet on the same network can show the same terminals and the world: the Phone button pairs it with a QR code.

3. Or give the agent the shim🔗

An MCP client gets the open world’s tools from localgpt world mcp, registered once:

npm install -g localgpt                           # prebuilt; or, with Rust, cargo install localgpt
claude mcp add world -- localgpt world mcp        # Claude Code; Codex and Gemini CLI take the same command in their MCP config

The shim finds the world the terminal is in (or $LOCALGPT_WORLD_DIR, which the app’s terminals set), and serves submit, undo, log, tips, goto, verify, screenshot and selection over stdio.

4. The world’s command line🔗

The same commands, from any shell, whether or not the app has the world open:

localgpt world log harbour.world --last 5
localgpt world submit harbour.world -m "a lamp by the crate" <<'EOF'
[{"SpawnEntity": {"entity": {"name": "lamp", "transform": {"position": [2, 0.5, 1]}}}}]
EOF
localgpt world undo harbour.world
localgpt world verify harbour.world

With the app open, each command is a call to its API and the window follows; with nothing open, the command is the authority itself. See CLI Commands.

5. Gen on its own🔗

cargo install localgpt-gen
localgpt-gen --mcp-relay                  # the window; an MCP client drives it through `mcp-server --connect`
localgpt-gen mcp-server                   # the window as an MCP client's own process (Claude Desktop, editors)
localgpt-gen --live harbour.world --review   # the live canvas, each agent batch accepted or rejected by you
localgpt-gen --host --web                 # a collaborative session; browsers join with the invite link

See LocalGPT Gen, the MCP relay and the MCP server.

Next Steps🔗