Agent Worlds
This guide covers the Agent World plugin and native conversation integration planned for Locus v3.0. It requires a Locus build with version-1 plugin screen support; installing the plugin in an older build does not add that support.
Agent World opens a separate window where your saved agents become residents of Orbital Locus Outpost or captains in The Local Line. Select an agent to continue a real Locus conversation, open the shared Crew Chat, or follow a request that needs your attention.
Exploring a world makes no model calls. Sending a message uses the agent's configured model, account, tools, and permissions, just as it does elsewhere in Locus.
Install and enter
Agent World is an optional Locus extension. The v3.0 source package includes it at plugins/agent-world, with a local marketplace definition at .agents/plugins/marketplace.json.
- Open the project you want to work in.
- Open Settings → Extensions in a compatible Locus build.
- If the Locus source repository's marketplace has not been discovered from the current workspace, add that repository directory as a local marketplace.
- Install Agent World, review its screen capabilities, and enable it for your project.
- Choose Open. Installed, enabled screens are also available from the Work menu.
Both themes, the 3D runtime, and prepared artwork come with the plugin. You do not need Node, a Meshy account, or a generation API key to install and use it. This is a Locus screen extension and requires the Locus host.
The world stays with the project it opened in. Its project name appears in the window. Switching projects in the main window does not redirect that world's conversations or queued work.
Add your agents
Open the main Agent page and choose New Agent. Give the agent a name, instructions, and a configured model. Saving creates its named sidebar group and first chat, and the saved profile appears in the world.
From Manage Agent → Add…, add a New chat, On a schedule, When an event arrives, or When a price changes. These conversations and automations belong to the same saved agent and use its saved configuration and access. See Agents & Automation for setup and trigger details.
Residents represent those saved profiles. Changing artwork or switching themes preserves the underlying agent identity, conversations, and permissions.
Choose and explore a world
Use the theme menu to switch worlds. Locus remembers your selection.
| World | What you see |
|---|---|
| Orbital Locus Outpost | A planted space campus with commons, lounges, and workstations. Available agents explore; working agents return to their stations. |
| The Local Line | An ocean of islands, ships, and AI-inspired landmarks. Each visible agent has a stable ship design and home island. Available ships patrol, while working agents return to their pier and bring a small crew ashore. |
Outpost's Agent Appearance menu offers Mixed, Pandas, and Explorers. Mixed is the default for new preferences and combines pandas, people, and robots. Appearance is remembered separately from the theme, and existing residents keep their assigned kind when the roster changes.
The Local Line includes a voyage chart, Recurse Mountain, the Thread Line, RAM Belts, and islands such as Water 7B, Wano Weights, and Whole Cache. Its ships and shore characters are an unofficial One Piece-inspired fan-art interpretation.
Use Move map to drag across the scene or Rotate to orbit. Arrow keys and WASD move the map, scrolling zooms, and Reset view restores the overview. Click an agent, ship, or label to select it. Hovering over or selecting a wandering agent pauses its movement so it is easier to interact with.
The searchable Residents and Your fleet lists provide keyboard access. A sector displays up to twelve agents, and the roster reaches agents in other sectors. The native Residents button also opens a list beside the scene.
Locus follows macOS's reduced-motion setting. Ambient wandering, ship rocking, wakes, moving water, drifting scenery, and camera inertia stop. A ship can still return to its berth when its work state changes.
Work with a resident
Selecting a resident opens Agent workspace in Outpost or Captain’s Quarters in The Local Line. This pane uses Locus's native conversation and composer, including attachments, voice, model controls, tools, skills, work modes, task controls, approvals, and questions.
Use Chat for the conversation, Agent details for the inspector, or Crew Chat for the shared conversation. Expand workspace gives the pane the whole window; Show world brings the scene back beside it.
The agent's actions menu offers New conversation, Edit agent…, and Manage agent…. A resident's conversation is saved per project and reused when you return. Starting a new conversation changes which chat that resident opens next; the previous chat remains in Locus history with its original agent identity. Finish or stop active work before replacing its conversation.
The world and main workspace share native conversation controls. If another chat becomes active, use Resume conversation to return to the selected agent. Locus may require you to finish or stop the foreground task before switching.
Closing the world or returning to the map does not stop agent work. Use Stop in the conversation or on a Crew Chat reply to interrupt it.
Talk in Crew Chat
Crew Chat is available from the main Agent page and both worlds, with the same saved history for each project. Every saved agent is a member. Each selected member replies through a separate real conversation using its own configured model and access.
- Choose Crew Chat.
- Select a member button to insert a mention, or type
@Name. Member buttons handle names with spaces or duplicates. - Write your request and check the To: recipient preview.
- Send the message, then follow each reply's progress. Choose Open task to inspect its native conversation, Review request when it needs a decision, or Stop to interrupt that reply.
Explicit mentions select only the agents you named. Unknown or ambiguous mentions must be resolved before sending.
Without mentions, Locus matches declared capability tags and roles to the request. It usually selects the strongest match and can include a complementary helper for a request with distinct tasks. If no clear match exists, it can continue with the last agent that completed a reply, a sole generalist, or the only available agent. Otherwise, add detail or mention someone. It does not broadcast an unmatched request to every agent, and choosing recipients does not make an extra model call.
Recent shared messages provide context for replies, and work follows Locus's normal queue. Restoring saved history reconnects to accepted work when possible; it does not automatically resend an interrupted, unsent reply. Check its status before sending a new request.
Crew history stays with its project. If another window has opened a different project's Crew Chat, Open this crew returns the world to its own shared conversation.
Follow requests and handoffs
Ping Ping, the snail communicator at the top right, appears when an agent has an approval or input request. Select it to open the exact native conversation that needs your decision. When several requests are pending, browse them individually.
You can collapse Ping Ping to a pill or hide it. Show alerts restores it, and the display preference is remembered. Hiding the card does not resolve the underlying request.
In The Local Line, Ship signals lists approval requests, questions, and recorded handoffs. Courier skiffs visualize recent results or shared context actually passed between agents. A planned dependency alone does not create a delivery. Open a handoff to inspect its details and continue in the receiving conversation; a shared team conversation is labeled Shared task.
The scene receives event identifiers and short labels. Full messages, request details, and handoff content remain in the native Locus panels.
Access and availability
The plugin requests three screen capabilities:
| Capability | Purpose |
|---|---|
agents.read | Show saved agent names, roles, and activity labels. |
agents.interact | Select agents and open their native conversations, requests, controls, or Crew Chat. |
world.preferences | Remember the theme and resident appearance. |
The local 3D screen has no external network access and receives no API keys or conversation transcripts. Model requests and tools run through native Locus, where the existing permission modes, account selection, and agent restrictions apply. Opening a world does not expand an agent's access.
If an agent's account is unavailable, its model is no longer configured, its worker cannot connect, or its saved profile has been removed, Locus shows the problem instead of silently choosing another account or profile. Review the native conversation and agent settings to resolve it.
If the 3D renderer fails, use the native Residents list to continue, or close and reopen the world. Disabling the extension or removing its screen access closes the world and revokes its screen connection.
A standalone browser preview uses a clearly labeled demonstration roster. Its residents, alerts, and handoffs illustrate the interface and cannot start real agent tasks. To work with your saved agents, open the installed plugin inside Locus.