Custom Agents

Go to Settings (Ctrl+,) and find Custom Agents in the left nav under the AI Behavior group - it is always visible and does not require 'Show advanced settings'.

Each agent you create shows a summary card: name, a tool badge (all tools or N tools), and optional badges for pinned model and read-only mode. Disabled agents show a disabled badge and are hidden from the picker.

1. Open Settings → Custom Agents.
2. Click + New Agent (top right of the section).
3. Fill in the form:
   • Name (required, max 100 chars) - must be unique per user.
   • Description (optional, max 500 chars) - shown only in Settings.
   • System prompt (required, max 6000 chars) - replaces the default agent identity. The app's safety guardrails are always appended and cannot be removed.
   • Model (optional) - a model string like claude-opus-4-8 or qwen2.5-coder:32b. Leave blank to use whatever model the Agent panel is currently set to.
   • Allowed tools - checkboxes from the live tool registry. Leave all unchecked to pass through all of the Agent panel's tools. Checking specific tools narrows to only those.
   • Read-only filesystem - blocks all file writes and deletes when this agent is active.
   • Max iterations (1–50) - leave blank for the default of 25.
4. Click Save.

Edit: Click Edit on any agent card. The form opens inline - no page transition. Change any fields and click Save. Name uniqueness is re-checked on update.

Disable: Open the edit form and turn off the Enabled toggle. The agent disappears from the picker but stays in your list with a disabled badge. Re-enable it the same way.

Delete: Click Delete on the card. A confirmation dialog appears before anything is removed. Deletion is permanent.

If an agent is selected in the picker when it gets disabled or deleted, the picker falls back to Default automatically.

The profile picker appears in the Agent panel header (right side, next to the Context button) once you have at least one custom agent.

1. Open Code mode (Ctrl+2) and open the Agent panel (Ctrl+L).
2. Click the robot-icon dropdown button in the panel header. It shows Default (muted text) when no custom agent is selected, or the agent name (purple highlight) when one is active.
3. Select an agent from the list. The change takes effect on the next message you send.
4. To return to normal behavior, select Default.

The custom agent only applies when sending from the Agent panel. It does not affect the Research, Debug, or Advisor panels.

Custom agent tool restrictions are a second filter on top of the Agent panel's allowlist.

The rule: effective tools = panel allowlist ∩ custom agent allowlist

• If the custom agent's allowlist is empty, no extra narrowing happens - all of the panel's tools pass through.
• If it lists specific tools, only those tools (that the panel also allows) are available.
• A custom agent cannot grant access to tools the panel doesn't already permit.

The model only sees tools within its effective allowlist - tools outside it are not offered to the LLM at all. If the model tries to call a blocked tool anyway, the execution gate returns: Tool "X" is not available to the selected agent. Available tools: ... and the loop continues.

The shell tool, when it's in the allowlist, still requires user approval in Ask mode. A custom agent profile cannot change the permission mode (Ask / Act / Plan).

When Read-only filesystem is enabled on an agent, the execution gate blocks all file write operations regardless of what the panel permits.

Blocked operations: file_system write, create, delete, append, rename, and mkdir - plus str_replace.

Still allowed: all read operations (open, list, search).

Error returned to the model: The selected agent is read-only. File [op] operations are not allowed.

Note: if the Agent panel itself is already set to read-only in its panel config, both restrictions apply - the agent's read-only flag adds to, not replaces, panel-level restrictions. The FileSystemTool sandbox (locking all file access to the ./workspace directory) always applies, independent of this flag.

The Max iterations value you set on a custom agent is always clamped against your global agent setting:

effective max = min(custom agent max iterations, Settings → Agent → max iterations)

So even if you set 50, the loop will not exceed your configured global limit. Custom agents can only lower the budget, never raise it above your global cap.

Tool names in the allowlist are pulled from the live tool registry at the time you open the form, so MCP tools you've connected appear in the list automatically.