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.

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.