Creating Agents
An agent in NEXUS is a persistent identity — a name, a persona, and its own on-disk memory — independent of any terminal. Creating or editing an agent never starts a process; Start Shell is the only action that spawns a terminal for it.
Three ways to create one
| Action | What happens |
|---|---|
| New Agent | Creates the agent immediately, with a placeholder name and a generic starting persona, and opens its configuration page — there's no separate setup form. You edit its name and everything else directly on that page. |
| Create with AI | Offers a menu of your configured CLI agents to have a conversation with. Choosing one opens a terminal and starts a scripted interview: it asks you, one question at a time, for a name, its role or purpose, its focus areas, its communication style, and any tools or skills it should use — then recaps what it understood and asks you to confirm or correct before finalizing anything. |
| Import Agent… | Opens a file picker for a previously exported agent definition. You can select more than one file at a time, and importing the same file twice never collides — each import gets its own name. |
New Agent is the fastest path if you just want a working agent to configure by hand. Create with AI is better when you'd rather describe what you want in conversation than fill in fields yourself — see Persona & identity for what each of the five fields it asks about actually means. Import Agent… is for bringing in a definition someone else already built and exported.
Create with AI only commits on confirmation
Nothing the interview learns is saved as it goes. The agent's real name and persona are only written once you explicitly confirm the recap at the end of the conversation — until then, the roster still shows its placeholder name, so an interview you abandon partway through leaves nothing behind but that placeholder.
Managing the roster
The roster gallery lists every agent you've created. Clicking a tile opens that agent's own page; hovering it reveals a small button that opens its mesh capabilities popover directly. Right-clicking a tile opens a fuller menu:
| Menu item | What it does |
|---|---|
| Open Detail | Opens the agent's own configuration page — the same as clicking the tile. |
| Start Shell | Spawns a terminal for the agent — see Running & monitoring. |
| Duplicate | Creates a copy of the agent — see below for exactly what carries over. |
| Change Avatar… | Sets a new avatar without opening the agent's page. |
| Mesh Capabilities… | Opens the same capabilities popover as hovering — see Capabilities & skills. |
| Reveal Home | Opens the agent's home folder on disk. |
| Delete | Removes the agent. |
Renaming isn't done from the roster — it's a field you edit directly on the agent's own page, the same as every other persona field.
A single tile's Delete is immediate — it does not ask for confirmation, unlike deleting from the agent's own page, which does ask ("Delete name?", warning that the agent and its on-disk home are permanently removed, with Delete and Cancel). Keep that difference in mind before right-clicking Delete on a tile you didn't mean to remove.
Duplicate appends " copy" to the name (then " copy 2", and so on for further copies), gives the new agent its own home folder on disk, and carries over its persona, accent color, linked skills, default provider, and mesh-capability toggles. It resets three things rather than copying them: the avatar goes back to the default, autonomy mode resets to Approval, and working directory is left unset.
Selecting more than one agent
⌘-click toggles a single tile in or out of the current selection; Shift-click selects the full range between your last click and the new one, replacing whatever was selected before; ⌘A selects every agent; Escape clears the selection. Selecting at least one tile surfaces a selection bar with three actions:
| Action | What it does |
|---|---|
| Kill All | Stops the live sessions for every selected agent that has one, and closes those session panes. Disabled if none of the current selection has a live session. Runs immediately, with no confirmation. |
| Delete All | Removes the selected agent identities and their on-disk homes, permanently. Asks first — "Delete 1 agent?" or "Delete N agents?" — with Delete and Cancel. |
| Clear Selection | Clears the current selection without changing any agent. |
The Delete or Backspace key triggers the same Delete All confirmation as the button. Kill All is the one to reach for when you want to stop a batch of running shells but keep the agents configured for later; Delete All is for when you want the identities gone too.
Creating an agent from outside NEXUS
Everything above happens inside the app. A connected external CLI agent can also create a new agent programmatically, through the local MCP server's agent_create tool — see MCP Tools if you're integrating against that surface rather than using the roster directly.
Where to go next
- Persona & identity — the fields Create with AI asks about, and how to set them by hand.
- Autonomy modes — what an agent does with its turn once it's created.
- Running & monitoring — Start Shell, and the live status an agent shows once it's running.
- Settings reference — the same identity fields, from the contextual settings panel.