Luma World · User guide

Welcome to Luma World.

Luma World is your interactive world of AI agents, a desktop app that gives them a place to work. Each agent sits at a desk in a small 3D office, and you can see at a glance who is busy, who is waiting for you and who has finished. The agents are the real Claude Code and Codex tools, running on the subscription you already have.

Get started Your first ten minutes Watch the videos
Start here

Your first ten minutes.

Follow these steps in order the first time. Each one links to the page that explains it in more detail.

  1. Get Luma World. Sign up on luma.pixelcity.world, verify your email, then download the Mac build and install it. (Windows and Linux exist in the app already but are not published yet.) Getting started
  2. Sign in to Luma World. Use the email you signed up, verified and downloaded with, with Google, GitHub or a password. New users: do that on the website first — the in-app sign-in screen's own create one can refuse an address that has not been through it yet. Signing in
  3. Set up Claude Code or Codex. Your agents run on the real command-line tools, signed in with your own subscription. You need one of the two. If neither is ready, the app shows a setup screen that installs it and signs you in. No subscription? An API key can stand in. How your agents run
  4. Make a city, then a building. On the globe, press ＋ New City. In the city, add a building and give it a Working Directory: the project folder you want your agents to work in. Globe, city, building
  5. Walk in and add an agent. Click the building. In the office, press + Agent, pick a name and a model, and press Confirm. A small character walks to a free desk. Desks and agents
  6. Give it a small first task. The agent's terminal opens on the right. Type something like "read the README and tell me what this project does" and press Enter. The agent panel
  7. Watch the room. The character works at its desk, a short status line floats over its head, and when it is done you hear it and see a ✓ with a one-line recap. What the character is telling you
The guide

Five pages, one idea each.

Start with getting set up. The four pages after it each open with a short narrated video, then walk through the details.

1

Getting started

Create your account, verify your email, download the Mac build, install and sign in. Set up Claude Code or Codex, or use an API key, see which features need which keys, and keep the app up to date.

Read the getting started page → 2

The office

The globe, the city and the building. The 3D room, the desks and floors, what a character's moves and speech bubble mean, the agent panel, and talking to the office by voice.

Read the office page → 3

Screens

Every agent can run up to three conversations at once. How to switch between them, what the screen chips tell you, what to do when one will not start, and who pays for what.

Read the screens page → 4

Sub-agents

When an agent hands part of a job to helpers, they appear as small birds circling its desk. What you can see, and what you cannot.

Read the sub-agents page → 5

The Circle

Call your agents to a round-table meeting. They prepare first while their work carries on, then take turns around a lantern, propose, vote, and leave a written record behind.

Read the Circle page →
Glossary

Words you will see in the app.

Agent
An AI coding assistant, either Claude Code or Codex, running in a terminal inside Luma World. In the office it appears as a small origami character called a Luma.
Office
The inside of one building: a 3D room with desks, where your agents work. A building can have several floors.
Building
A temple in your city. Each building points at one project folder on your computer, and every agent in it works in that folder.
Desk
Where an agent sits. Each room has a fixed number of desks, and each desk has monitors that show what the agent is doing.
Screen
One conversation an agent is running. Every agent can have up to three at once, and each lights one monitor on its desk. More on screens
Sub-agent
A helper an agent starts to take on part of a job. Sub-agents do not get desks. They fly around their parent's desk as small birds. More on sub-agents
The Circle
A meeting room where you and your agents sit around one table and take turns, with a lantern that shows whose turn it is. More on the Circle
Employee
An agent you have hired with ★ Hire. It keeps its name, desk, voice and memory between sessions. An agent you have not hired is temporary.
Runtime
Which tool an agent runs on: Claude Code or Codex. You pick it by picking a model.
Subscription
The Claude or ChatGPT plan you already pay for. Agents use it through the Claude Code or Codex sign-in on your computer. API keys are only needed to fill gaps. Who pays for what
API key
A key from Anthropic or OpenAI that you paste into Settings → AI. It stands in when Claude Code or Codex is installed but not signed in, and unlocks features such as the Architect's voice. Which features need which keys
Setup screen
The screen that appears when you open the app and neither Claude Code nor Codex is ready. It installs one and signs you in, then opens your office. The setup screen