Single-Agent vs Multi-Agent Modes

Agent OS adapts to work with any AI coding tool through two operational modes:

• Multi-agent mode for tools that support subagents (currently only Claude Code)
• Single-agent mode for everything else

You can use one mode or both modes simultaneously for flexibility. Each project installation can be configured to use one or both modes.

Multi-agent mode

When to use multi-agent mode

Multi-agent mode is designed for tools that support the ability to orchestrate and delegate tasks to multiple specialized subagents.

Currently, multi-agent mode in Agent OS can only be used with Claude Code. All other tools are supported by single-agent mode.

How multi-agent mode works

Your main AI becomes an orchestrator, delegating to specialized subagents. Each subagent has:

• Focused expertise in one area (database, frontend, API, etc.)
• Only the standards and context relevant to their specialization
• Specific verification partners for quality checks

Developer experience with multi-agent mode

1. Run each phase of the Agent OS workflow with a single command like /create-spec or /implement-spec
2. The orchestrator analyzes requirements and creates a plan
3. Verifier agents review the work for quality
4. You get a complete, tested implementation

File structure with multi-agent mode

.claude/agents/agent-os/
Specialized subagents compiled from your roles

.claude/commands/agent-os/
Orchestration commands that run the Agent OS workflow, where each will delegate to agents

agent-os/roles/
Your list of implementer and verifier agents that are available for assignments during the implementation phase.

Single-agent mode

When to use single-agent mode

Single-agent mode works with every AI coding tool—Cursor, GitHub Copilot, ChatGPT, or any other AI coding tool.

"Single-agent mode" refers to the paradigm where you chat directly with your one coding agent via the chat interface of your AI coding tool.

Can Claude Code be used in single-agent mode? Yes. While Claude Code has the benefit of having the subagents feature (making it eligible for multi-agent mode), you can also use Agent OS in single-agent mode when using Claude Code (if single-agent mode is installed in your project).

How single-agent mode works

When Agent OS is compiled into your project with single-agent mode, it generates numbered prompts for running the Agent OS workflow, which you would feed into your AI coding tool sequentially. Each prompt includes:

• Clear instructions for that specific step
• Relevant standards and patterns
• Expected outputs and success criteria

Developer experience with single-agent mode

1. Agent OS generates numbered prompts for your specification
2. You copy or reference the each prompt in your AI tool sequentially
3. The AI completes that step with focused context
4. You review the work and proceed to the next prompt
5. Each step builds toward your complete implementation

File structure with single-agent mode

agent-os/commands/
Main workflow commands broken into steps

agent-os/specs/[spec-name]/implementation/prompts/
Generated prompts to run for the implementation of each spec.

agent-os/roles/
Your list of implementer and verifier roles that are available for assignments during the implementation phase. While these are not actual subagents, they carry the same benefit of having specialized coding standards and instructions that are relevant to their current task.

Technical differences

Using both modes simultaneously

You can install both modes simultaneously for flexibility. This can be useful for Claude Code code users who also use other tools (like Cursor), or want to flexibility to shift between the multi-agent (more autonomous) and single-agent (more manual control) styles of Agent OS workflow.

Installation for both modes

If you always want to use both modes by default, then this default in your base installation's ~/agent-os/config.yml:

multi_agent_mode: true
multi_agent_tool: claude-code
single_agent_mode: true
single_agent_tool: generic

If your base config is not set to use both modes by default, then you can enable both modes during an individual project installation using the --multi-agent-mode and --single-agent-mode flags.

~/agent-os/scripts/project-install.sh --multi-agent-mode true --single-agent-mode true