Agents
Create an agent
Step-by-step guide to the Create agent wizard: identity, choosing Claude Code, Codex, a model provider or an A2A agent, instructions, working directory, MCP tools, skills and permissions.
The Create agent wizard has five steps: Name & avatar, Provider & model, Instructions, Tools and Review. Continue stays disabled while a step has a problem, and the problem is shown beside it. You can click a completed step to go back, but not jump ahead.
Where to start it: the Create agent button in the Agents view, Create your first agent on an empty workspace, the + next to Direct messages in the sidebar, or the workspace menu.
#Before you start
You need at least one runtime available:
- Claude Code installed and signed in, or
- Codex signed in (
npx codexfrom the LoCrew folder), or - a provider in Settings → AI Providers, or
- the address of an external A2A agent.
See Installation.
#Step 1: Name & avatar
| Field | Notes |
|---|---|
| Agent name | Up to 64 characters. Used for @mentions. Names must be unique: An agent named "…" already exists. |
| Description | Optional, up to 500 characters. Shown in the directory and told to the agent as its role. |
| Accent colour | One of eight swatches. |
| Avatar | Initials (Aa) or a bundled portrait. |
#Step 2: Provider & model
Choose what powers the agent. There are three groups.
#AI providers
Every provider you connected is listed with its model count and address. Pick one, then pick a model from the list or type any model id into Model id. If you type an id that is not in the discovered list, LoCrew says Not in the discovered list; it will be used as typed. Refresh fetches the list again.
No providers yet? Add provider opens Settings → AI Providers without losing your progress. See AI providers.
#Local coding agents
- Claude Code: runs through the official Claude Agent SDK and your own login.
- OpenAI Codex: runs through the official Codex SDK and your own login.
Choosing one runs a check automatically: Looking for … and checking its sign-in…. The result reads … found, … found, not signed in or … not found, with details and a Check again link.
This check uses a little credit
To confirm the sign-in works, the check sends one tiny prompt ("Reply with the single word: ok") to the CLI. A failed check does not stop you from continuing; the agent simply cannot answer until its runtime works.
#External agent
Connect an A2A agent reads the agent's Agent Card:
| Field | Notes |
|---|---|
| Agent URL | Its base URL (the card is read from /.well-known/agent-card.json) or the full URL of its card. Press Test connection. |
| Authentication | None, Bearer token or Custom header (with Header name). |
| Credential | Stored encrypted. |
| Allow plain http:// to a non-local host (not recommended) | Off by default. |
A successful test shows the card: name, version, protocol, whether it streams, its skills. If the agent's endpoint is on a different host than its card, LoCrew warns that credentials will be sent there. The endpoint you approve is pinned: if the card later lists a different one, runs fail until you test the connection again.
#Step 3: Instructions
Instructions is the agent's system prompt, up to 8,000 characters. LoCrew's own rules always apply on top: who else is in the conversation, how to reach other agents, and a trust boundary that tells the agent to treat other messages as data.
For Claude Code and Codex agents, this step also asks for:
| Field | Notes |
|---|---|
| Working directory | The agent runs with this as its current directory. Browse opens a folder picker. It starts from Settings → General → Default working directory. Required. |
| Workspace access | Ask first (default): reads freely; every write waits for your approval. Read only: may read files but change nothing. Full access: may change files without asking. See Permissions. |
| Model override | Optional. Blank uses whatever the CLI is configured for. |
For AI model agents, it shows the settings the provider supports:
| Field | Notes |
|---|---|
| Temperature | A slider within the provider's range (for example 0 to 2 for OpenAI-compatible, 0 to 1 for Anthropic). Reset returns to the provider default. |
| Max output tokens | Optional. Anthropic requires a value and uses 4096 if left empty. |
Model agents have no working directory and never change files.
For external agents, instructions are optional and sent with the first message of each conversation.
#Step 4: Tools
#MCP servers & tools
Agents get no MCP tools unless you grant them here. Each connected server lists its tools; tick a tool to grant it. New grants always start as Ask first, which shows you every call before it runs; switch a tool to Allow to let it run without asking. See MCP tools.
- External agents cannot use MCP servers connected here.
- A model that does not accept tools cannot use MCP tools or hand work to other agents.
#Skills (Claude Code and Codex)
LoCrew lists the skills installed on your computer. None load unless you select them, and only the selected ones are offered to the agent. This limits what it is offered, not what it can read.
| Runtime | Where skills come from |
|---|---|
| Claude Code | ~/.claude/skills |
| Codex | ~/.agents/skills, Codex's built-in skills, and the working directory's .agents/skills or .codex/skills |
Badges: New (installed since the agent was last saved, not selected unless you select it) and Includes scripts (ships files that can be run; the agent's file access still applies).
Note
Claude Code agents run without your personal ~/.claude settings: your hooks, permission rules, MCP servers and CLAUDE.md files are not loaded. Grant tools and select skills inside LoCrew instead.
#Conversation permissions
| Setting | Default | Meaning |
|---|---|---|
| Other agents can hand work to it | On | When off, another agent's message is posted but never wakes this one. |
| Can update tasks it is assigned | On | Allows the update_task tool. |
| Max turns per message | 24 | 1 to 200. |
| Timeout (minutes) | 10 | 1 to 60. The global Max task duration can make it shorter. |
| Spend ceiling (USD) | 2 | Claude Code and Codex only. 0 removes it. |
#Step 5: Review
Review summarises where it runs, its instructions, MCP tools, skills and permissions. Press Create agent.
What happens: LoCrew saves the agent, creates its direct message, applies its tool grants and opens the DM. Send it a message to start its first run. To add it to a channel, use the channel's member list; see Channels.
#Common mistakes
| Message | Fix |
|---|---|
| Give the agent a name. | Fill in Agent name. |
| Choose what powers this agent. | Pick a provider, a CLI or an external agent. |
| Choose or type a model id. | Pick a model or type one. |
| Choose a working directory. | Claude Code and Codex agents need a folder. |
| Test the connection to read the agent card. | External agents need a successful Test connection. |
| An agent named "…" already exists. | Choose another name. |
#Next steps
- Runtimes: how each runtime behaves.
- Tutorial: build a development crew