Skip to main content
Agents are specialized assistants with their own prompt, model, and tool permissions. There are two types:
  • Primary agents are the assistants you interact with directly and handle your main conversation.
  • Subagents are invoked by primary agents for specific tasks, or manually by @ mentioning them in your message (e.g. @explore find where sessions are created).
Each agent has different permissions and tool access; for example, Build uses all tools according to your permissions while Plan and Ask are restricted.
Use Tab (or Shift+Tab to go backwards) to cycle through primary agents, or /agents (Ctrl+X then A) to pick one.
Symbiotic Code comes with 4 primary agents, 4 subagents, and a dedicated mode for running shell commands.

​
Primary agents

​
Build

The default agent. It can use all tools, following your configured permissions. Use Build for standard development work where you need full access to file operations and system commands.

​
Plan

A restricted agent designed for planning and analysis. We use a permission system to give you more control and prevent unintended changes:
  • file edits are denied, except for plan files (Markdown files in .symbiotic/plans/)
  • the agent is instructed to only read and inspect, and not to run commands that modify your system
This agent is useful when you want the LLM to analyze code, suggest changes, or create plans without making any actual modifications to your codebase. When the plan is ready, switch to Build to implement it.

​
Ask

A read-only agent for getting answers and explanations without any risk of modifying your codebase. It can read and search files, search the web, and run security scans, but cannot edit files or run shell commands. Use Ask when you want to understand code before changing it, or when learning about patterns in your codebase.

​
Debug

A specialized agent for diagnosing and fixing bugs using an evidence-based methodology. Debug mode never fixes bugs based on code alone. It requires actual runtime evidence. The debug agent follows a systematic workflow:
  1. Gather context (errors, stack traces, logs)
  2. Form hypotheses about the cause
  3. Add instrumentation to test all hypotheses
  4. Reproduce and analyze logs
  5. Fix only with log proof of the root cause
  6. Verify with logs, then remove the instrumentation
Use Debug when you’re investigating unexpected behavior, tracking down errors, or need a methodical approach to complex bugs.

​
Subagents

Use /subagents (Ctrl+O) to view the subagents running in the current session.

​
Shell mode

Type ! at the start of the prompt to switch to shell mode, then enter a command to run it directly without any AI processing. Press Esc to exit shell mode.

​
Custom agents

You can create custom agents as Markdown files in ~/.config/symbiotic/agents/ (global) or .symbiotic/agents/ (project), in the agent section of your configuration file, or interactively with symbiotic agent create. You can also override built-in agents (for example their model), or disable them with "disable": true. Run symbiotic agent list to see all available agents. To change the agent used when none is specified, set default_agent to a primary agent in your configuration file. See custom agents for more information.