Multi-Agent System

11 Specialized Agents

11 specialized agents: 4 primary (Tab to cycle), 4 subagents (@mention to invoke), and 3 system agents. Custom agents via markdown files.

Coder Agent

PrimaryDefault

Access: Full (read/edit/bash/web)

Your primary coding agent. Reads, writes, executes, and browses — the full stack. It handles file operations, code editing, command execution, web searches, and package management.

Capabilities

Write, edit, and delete files
Run shell commands and tests
Search and analyze code
Install packages and format code
Browse the web for documentation
Create git commits and PRs

How to Use

bash

/agent coder  or press Tab

Workflow

Use the Coder agent for everyday coding tasks — fixing bugs, adding features, refactoring code, and running tests. It has full access to all tools.

Architect Agent

Primary

Access: Read-only (architecture & design)

Analyzes your codebase architecture and creates high-level design decisions. Focuses on system design, dependency mapping, and architectural patterns.

Capabilities

Read and analyze all files
Map project dependencies and architecture
Identify architectural patterns and anti-patterns
Suggest structural improvements
Design system boundaries and interfaces
Evaluate technology choices

How to Use

bash

/agent architect

Workflow

Switch to Architect when you need high-level design guidance: understanding system architecture, evaluating technology choices, or planning structural changes.

Planner Agent

Primary

Access: Read-only (analysis & planning)

Analyzes your codebase and creates detailed implementation plans before any code is written. Perfect for complex features that need careful thought before execution.

Capabilities

Read and analyze all files
Search code patterns
Create detailed implementation plans
Suggest improvements and refactoring
Identify potential issues
Map project dependencies

How to Use

bash

/agent planner

Workflow

Switch to Planner when you need to understand a codebase before making changes. It will read files, analyze patterns, and produce a step-by-step plan.

Reviewer Agent

Subagent

Access: Read-only (code review)

Reviews code for quality, security vulnerabilities, and best practices. Provides detailed feedback with specific line numbers and suggested fixes.

Capabilities

Review code for security vulnerabilities
Check coding standards and conventions
Identify performance issues
Suggest refactoring opportunities
Verify error handling completeness
Enforce type hint usage

How to Use

bash

@reviewer "review auth.py"

Workflow

Invoke Reviewer as a subagent when you need code review: "Review the changes in src/api/", "Check auth.py for security issues", "Review PR #42 for best practices".

Shell Agent

Primary

Access: Full (infrastructure focused)

Handles DevOps and infrastructure tasks — CI/CD, Docker, Kubernetes, cloud deployments, and environment configuration. Explains what each command does before running.

Capabilities

Configure CI/CD pipelines
Manage Docker containers and images
Deploy to cloud platforms
Set up monitoring and logging
Configure environment variables
Handle infrastructure as code

How to Use

bash

/agent shell

Workflow

Use Shell for infrastructure tasks: "Set up a GitHub Actions pipeline", "Configure Docker for this project", "Deploy to AWS", "Add monitoring to the staging environment".

General Agent

Subagent

Access: Full (multi-task)

General-purpose subagent for researching complex questions and executing multi-step tasks. Use this to run multiple units of work in parallel.

Capabilities

Full tool access for any task
Research and analysis
Execute multi-step workflows
Parallel task execution
File operations when needed
Web research and documentation

How to Use

bash

@general "research this topic"

Workflow

Invoke General as a subagent for complex research or multi-step tasks that should run in a separate context: "@general research the best React state management libraries", "@general analyze the performance of this API endpoint".

Explore Agent

Subagent

Access: Read-only (exploration)

Fast, read-only agent for exploring codebases. Cannot modify files. Perfect for quickly finding files by patterns or searching code for keywords.

Capabilities

Quickly find files by patterns
Search code for keywords
Answer questions about the codebase
Read file contents
List directory structures

How to Use

bash

@explore "find all API routes"

Workflow

Use Explore when you need quick answers about the codebase: "@explore what files import the database module?", "@explore find all TypeScript interfaces in src/types/".

Scout Agent

Subagent

Access: Read-only (research)

External documentation and dependency research agent. Clones repositories to managed cache, inspects library source, and cross-references local code against upstream implementations.

Capabilities

Research external documentation
Clone and inspect dependency repos
Cross-reference with upstream code
Web search and fetch
Compare local vs library implementations

How to Use

bash

@scout "check the React docs"

Workflow

Use Scout for external research: "@scout what is the latest React 19 API for server components?", "@scout check how lodash implements deepClone".

Permission Matrix

Each agent has different permission levels for each tool category. Values: allow (always permit), ask (prompt user), deny (block), config (user-defined).

Permission	Tools	Coder	Architect	Reviewer	Shell	Planner
read	read_file, list_files, search_in_files, glob_search	allow	allow	allow	allow	allow
edit	write_file, edit_file, delete_file	allow	deny	deny	ask	deny
bash	run_command	ask	deny	deny	ask	deny
websearch	web_search, fetch_url	ask	allow	deny	allow	deny
task	subagent invocation	ask	deny	deny	ask	deny

Switching Methods

Slash Command

bash

/agent coder\n/agent architect\n/agent shell

Type /agent followed by the agent name.

Tab Key

text

Press Tab to cycle\nthrough primary agents

Tab to cycle between primary agents. @mention subagents for specialized tasks.

@Mention

bash

@reviewer "review auth.py"\n@planner "analyze test coverage"

Invoke subagents inline with @mention.

Custom Agent Creation

Create custom agents with specific permissions and system prompts in your configuration file.

yaml

# .apex/config.yaml
agents:
  # Code Reviewer - read-only, focused on security
  reviewer:
    description: Code review agent focused on security
    mode: subagent
    permission:
      read: allow
      edit: deny
      bash: deny
      websearch: allow
    prompt: |
      You are a code reviewer focused on security vulnerabilities.
      Always check for: SQL injection, XSS, CSRF, auth issues.
      Provide specific line numbers and fixes.

  # Test Writer - can write test files only
  test-writer:
    description: Writes comprehensive test suites
    mode: subagent
    permission:
      read: allow
      edit: allow      # Can write test files
      bash: allow      # Can run tests
      websearch: deny
    prompt: |
      You are a test writing specialist.
      Write comprehensive pytest test suites.
      Aim for 90%+ coverage on all new code.
      Use fixtures, parametrize, and mocking.

  # Shell Agent - handles infrastructure
  shell:
    description: Shell and deployment agent
    mode: primary
    permission:
      read: allow
      edit: ask
      bash: ask
      websearch: allow
    prompt: |
      You are a Shell/DevOps specialist.
      Help with CI/CD, Docker, Kubernetes, and cloud deployments.
      Always explain what each command does before running.

Best Practices

Plan Before Coding

Use the Planner agent first for complex features. It analyzes your codebase and creates a step-by-step plan before any code is written.

Leverage Subagents

Use @reviewer for code reviews and @planner for planning insights. This keeps your main conversation focused.

Configure Permissions

Customize the permission matrix for your security needs. Use "ask" mode for sensitive operations and "deny" for destructive ones.

Switch Contextually

Switch to Planner for analysis, Coder for implementation, and Shell for infrastructure. Use @mention for subagents like @reviewer, @general, @explore, @scout.

APEX Architecture (v2.0.0)

APEX v2.0.0 features a modular agent architecture — structured messages, snapshots, custom commands, CLI subcommands, gateway proxy, and a typed event bus that powers the agent system.

Structured Parts

Messages are composed of typed parts: text, file, tool_call, tool_result, image, and snapshot. This enables rich context management and precise agent communication.

Snapshots & Undo

Before every destructive action, APEX creates a Git-based snapshot. Use /undo to revert any change and /redo to reapply. Full diff computation between states.

Custom Commands

Create user: and project: commands with template variables. Store in ~/.apex/commands/ for global access or .apex/commands/ for project-specific commands.

Event Bus (25+ Events)

Strongly-typed event bus with events for sessions, files, tools, permissions, LSP, and undo/redo. Plugins and TUI components subscribe for real-time updates.

Session Sharing

Share sessions via Base64-encoded apex://share/{id} links. Recipients can load shared sessions to review conversations, tool calls, and outcomes.

Coder & Planner Agents

The Coder agent has full access to all tools. The Planner agent is read-only — it analyzes and proposes without touching any file. Switch with /agent coder or /agent planner.