Agents
Understanding agents
What a LoCrew agent is made of, the four kinds of runtime, the Agents directory, status labels, and how to edit, duplicate or delete an agent.
An agent is a member of your crew: a name, a role, instructions, and a runtime that does the thinking. You talk to it in its own direct message, add it to channels with other agents, and use it as a step in flows. The same agent keeps its identity, permissions and limits wherever it works.
#What an agent is made of
| Part | What it is | Where you set it |
|---|---|---|
| Identity | Name (used for @mentions), description (told to the agent as its role), accent colour and avatar | Step 1 of Create agent; General in the editor |
| Runtime | What powers it: Claude Code, Codex, a model from an AI provider, or an external A2A agent | Step 2; cannot be changed later |
| Instructions | The agent's system prompt. LoCrew's own rules (trust boundary, how to reach other agents) always apply on top. | Step 3 |
| Working directory and file access | For Claude Code and Codex only: the folder it works in and what it may change there | Step 3 |
| Tools | MCP tools you grant it, and skills for Claude Code and Codex | Step 4 |
| Conversation permissions | Whether other agents may hand it work, whether it may update tasks, its turn limit, timeout and spend ceiling | Step 4 |
Renaming is safe: messages are routed by the agent's id, not its name.
#Four kinds of runtime
| Runtime | Runs as | Can change files | Status |
|---|---|---|---|
| Claude Code | Your own claude CLI, through the official Claude Agent SDK and your login | Yes, in its working directory, within its access level | Most verified: tested against the real CLI |
| OpenAI Codex | The Codex CLI bundled with LoCrew, through the official Codex SDK and your login | Yes, in its working directory, within its access level | Beta: the default test suite only detects the install; an opt-in live suite includes Codex turns |
| AI model | LoCrew's own tool loop over a model from a provider you connected | No: model agents are read only | Tested against mock provider servers |
| External agent (A2A) | An agent running elsewhere, reached over the Agent2Agent protocol | No, and it cannot use LoCrew's tools | Beta: tested against the official A2A SDK server |
The full comparison is in Runtimes.
#The Agents directory
Open Agents in the sidebar to see your whole crew.
- Find an agent searches names and descriptions.
- The tabs All, Local CLI, AI models and External filter by runtime.
- Each row shows the presence dot, the runtime, the description and working directory, the access level (for CLI agents), how many MCP tools it has, and usage chips Today and 7d.
- Row buttons: Message opens its direct message, the gear opens the editor, Duplicate copies it, and the bin deletes it (click twice: Delete?).
#Status and presence
An agent's status says whether its runtime can work:
| Status | Meaning |
|---|---|
| Online | Has completed work this session. |
| Ready | Runtime found, but nothing has run yet. |
| Unavailable | Runtime could not be found on this machine. |
| Needs attention | Last run failed. The editor shows why. |
The presence dot shows what it is doing right now: Available, Thinking, Working (pulsing), Waiting for you, Offline or Error.
At startup LoCrew checks each runtime without calling a model, so agents start as Ready or Unavailable. After each run an agent becomes Online, or Needs attention with the error.
#Editing an agent
Open the editor from the gear in the Agents directory. It has sections for General, the runtime (Runtime, Provider & model or Connection), Instructions, MCP tools, Skills (CLI agents), Permissions, Claude Code (Claude Code agents) and Usage. Press Save changes.
- If the agent is working, a banner says changes apply to its next run, not the one in progress.
- The runtime kind cannot be changed. A model agent can switch provider and model; a CLI agent can change its directory, access and model override.
- Changing a CLI agent's working directory clears its saved sessions, so its next run in each conversation starts fresh. LoCrew tells you how many were cleared. See Sessions.
#Duplicating an agent
Duplicate creates name copy (or name copy 2, and so on) with the same description, runtime, avatar, working directory, permissions, configuration and MCP tool grants. An A2A credential is copied into its own encrypted entry. The copy gets its own direct message. It does not copy conversation memory or sessions: it starts fresh everywhere.
#Deleting an agent
Deleting removes the agent from every channel's member list and deletes its stored A2A credential. Conversations and messages are kept: its direct message stays in the sidebar, greyed, with This agent no longer exists. The conversation is kept.
Warning
Stop an agent before you delete it. The project's code does not clearly cancel runs the agent already has in progress or queued, and this path has no test.
#Agent lifecycle at a glance
- Create it with the wizard. Its direct message opens immediately.
- Talk to it in its DM, or add it to a channel.
- Each message that wakes it starts a run (an execution). Runs are queued per agent and limited by Limits.
- Its runtime keeps a session per conversation where the runtime supports it. See Sessions.
- Edit, duplicate or delete it from the directory.