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.

If a pinned local model is not installed, the card says so - for example "Social Media Agent is pinned to Qwen3.6-27B-Q4_K_M.gguf, which is not installed. It will run on whatever model is loaded instead." The agent-picker dropdown marks the same agent * - not installed*. Bodega does not repair the pin for you: the agent still runs, on whichever model llama.cpp currently has loaded, and you decide whether to re-pin it or install the model. This check covers .gguf pins only - those are the ones Bodega can verify against your llama.cpp library. A cloud model id is not checked, because the model list Bodega holds covers only the provider you are currently using.

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 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 same profile picker appears in Chat mode's header (next to the New Chat button) and in Code mode's Agent panel header (right side, next to the Context button) once you have at least one custom agent - it's one shared list either way, so an agent you create shows up in both places immediately.

1. In Chat mode, the picker is always visible in the top bar. In Code mode, open the Agent panel (Ctrl+L) first.
2. Click the robot-icon dropdown button. 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 applies when sending from Chat mode's composer or Code mode's Agent panel - the two run the same backend pipeline and resolve to the same panel configuration, so a given agent's narrowing behaves identically in both. It does not affect the Research, Debug, or Advisor panels; those never receive the selected agent at all.

What is not identical between the two is the starting tool set. Chat mode applies its own mode filter first (no shell, no writes without an attached folder), so the same agent legitimately has fewer tools in Chat mode than in Code mode. See How tool restriction works below.

A custom agent's allowlist only ever removes tools. It is intersected with the restrictions already in force - it is never a grant.

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

• Mode filter - in Chat mode, a fixed set of tools is permitted regardless of anything else: web search and fetch, memory and knowledge queries, document creation, deep research, the docs and mixture tools, the read-only code tools (file_system, grep, glob, code_search, find_symbol), session lookup, and the preview/browser tools. shell is never available in Chat mode. str_replace and file_system writes become available only once you attach a folder to the chat session (chat menu → Link project folder). Code mode's Agent panel applies no mode filter.
• Panel allowlist - Chat mode's composer and Code mode's Agent panel both resolve to the all-tools Agent configuration, so this term narrows nothing for either. The Research, Debug, and Advisor panels have their own narrower allowlists.
• Custom agent allowlist - empty means no extra narrowing. If it lists specific tools, only those that survive the two terms above are available.

The consequence worth internalising: putting shell in a custom agent's allowlist does not give that agent shell access in Chat mode. The mode filter runs first and blocks it. An agent is not a way to escalate.

The model is only shown tools within its effective set, so it usually won't try a blocked one. If it does - through a text-extracted call that bypasses the tool list, say - the execution gate refuses it and returns Tool "X" is not available to the selected agent. Available tools: ..., and the loop continues rather than failing the turn.

The shell tool, where it is available at all, still requires user approval in Ask mode. A custom agent profile has no permission-mode or capability field - Ask / Act / Plan and the sandbox are decided elsewhere and can never be derived from an agent definition.

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.

Four fields decide how an agent behaves when it is not you picking it.

Runs on is the provider that serves the agent's model. Leave it on My active provider and nothing changes. Pick a different one and the agent runs there while you keep working on yours - the point being that an expensive cloud model can plan while a free local model does the typing. When you change it, name the model the way THAT provider names it (for Ollama, a pulled tag like qwen3.8:27b), because the fallbacks are names in your own provider's namespace.

When spawned as a sub-agent picks the sandbox. Worktree: the agent edits a throwaway copy of your project and its diff is verified before anything reaches your files - a diff that fails verification is discarded. Read-only: it runs in place and can only report. Ignored when you pick the agent yourself; it only applies to a spawned run.

Reasoning effort is a per-turn thinking budget for models that support one. Blank uses the provider's default.

The main agent may spawn this is off until you turn it on. Off, only you can select the agent. On, the main agent can hand it a task with the spawn_agent tool. Turn it on deliberately: a spawnable agent on a cloud provider spends money without you clicking anything, which is why each sub-agent run has its own cap under Settings → Agent.

Calling spawn_agent is treated as a write - in Ask mode it pauses for your approval like any other write, even when the agent it spawns is read-only.

A spawned agent can run in the background: the main agent keeps working and the report arrives on a later turn - including a turn where you just ask a plain question and the agent makes no tool calls of its own - with a strip under the conversation showing what is running - click a chip to open it and see the child's tool calls as they happen, plus its report once it finishes. Before a local child starts, Bodega checks whether it fits in VRAM beside your loaded model: a foreground child may cost one model swap out and back (logged), but a background child that would force the daemon to swap models on every request is refused outright rather than thrash. Only ONE agent on a local provider runs at a time, however many are allowed overall - two local models generating at once on one GPU is what that limit is for. Stopping the run cancels its sub-agents within about a second and discards their worktrees.

In an unattended run - the CLI, a Loop, a background run - spawning is off unless you turn it on, because nobody is there to stop a run that keeps handing out work. bodega run --subagents turns it on for one run, and there is a matching switch under Settings → Agent. The rule that a sub-agent cannot spawn a sub-agent is enforced separately and no setting relaxes it.

Sub-agents are off entirely until you enable them under Settings → Agent → Sub-agents. Existing agents are unaffected: their provider is blank (your active one) and none of them are spawnable until you say so.

The system prompt you write replaces the agent identity section of the prompt, not the entire system prompt. Dynamic context - date, project rules, memory, working directory - is still assembled normally on every turn.

If the model you're running has a context window of 16,384 tokens or fewer, Bodega trims the surrounding context to stop it overflowing. It drops the decision log, the project map file, the file listing, cached tool-approach hints, and any non-pinned knowledge cards, and truncates project rules to 2 KB. Your system prompt is kept - the trim targets the assembled context around it, not the agent identity. Note this keys off the model's declared window size, not how full the conversation currently is, so it either applies for the whole session or not at all.

Separately, Bodega builds a shorter system prompt when the resolved window is small: at or below 16,384 tokens on a cloud model, and at or below 32,768 tokens on a local model, where the window is derived from what fits in your VRAM rather than from the model's declared maximum. Your agent's system prompt is included on that shorter path too, trimmed to the first 2,000 characters if it is longer - the trim is written to the log when it happens. Until August 2026 it was dropped entirely on that path, which made a custom agent look active while behaving like the default one, and only on local models.

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 run starts under your configured global setting. Custom agents can only lower the starting budget; the loop may still extend a run that keeps making progress, toward agent.max_iterations_ceiling.

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.

Selecting a custom agent is now visible everywhere, not just in the picker: in Code mode, the status bar shows the agent's name and its pinned model (Reviewer · qwen3:8b) in the accent color with the agent icon, and the Agent panel header shows the pinned model that will actually answer. In Chat mode, the picker button itself shows the same name-and-model readout. Pick Default in the dropdown to go back to the standard agent.

The selection is a single, shared choice - not one setting per mode. Switching modes does not deselect your custom agent: pick an agent in Code mode's Agent panel and it's still selected (same picker, same name) if you switch to Chat mode, and vice versa. If you want them to differ, you have to switch back yourself.

Export (Settings → Custom Agents) downloads every agent as a single bodega-agents.json bundle - name, system prompt, pinned model, tool allowlist, read-only flag, iteration cap. Import reads a bundle and creates the agents; a name that already exists is imported with an (imported) suffix rather than overwriting yours. Bundles are plain JSON: share them in a repo, a gist, or chat.