Agents & Delegation

Agents are specialized AI personas with different instructions, models, and tool access patterns. Gee-Code includes 13 built-in agent archetypes and supports custom agents.

Built-in Archetypes

Agent	Role	Description
explore	Codebase Explorer	Fast, read-only exploration. Uses Glob, Grep, Read.
researcher	Research Specialist	Web search, local search, broad research.
architect	System Designer	Architecture analysis, trade-offs, design documents.
code	Programmer	Writing, editing, and refactoring code.
test	QA Engineer	Test writing, test runner execution, coverage analysis.
docs	Technical Writer	Documentation generation and improvement.
review	Code Reviewer	Code review, best practices, security analysis.
debug	Debugger	Troubleshooting, log analysis, root cause identification.
devops	DevOps Engineer	Infrastructure, CI/CD, deployment, monitoring.
data	Data Analyst	SQL queries, data analysis, visualization.
artist	Creative Artist	Image and video generation using FAL models.
designer	UI/UX Designer	Interface design, component creation, styling.
synthesis	Research Synthesizer	Multi-source research compilation.

Switching Agents

/agent code          # Switch to the code agent
/agent researcher    # Switch to researcher
/agent               # Show current agent and list available

Your current agent affects how the AI approaches tasks — a code agent focuses on implementation, while an architect agent thinks about system design.

Delegating Tasks

Use /delegate to route a task to a specific agent without switching your active agent:

/delegate researcher Find all REST API patterns used in the codebase
/delegate code Refactor the authentication middleware to use async/await
/delegate review Check the new login endpoint for security issues

The delegate agent runs the task independently and returns results to your conversation.

How Agents Differ

Each archetype configures:

Property	Description
Model	Which AI model to use (claude-sonnet for speed, claude-opus for complex)
Instructions	Detailed behavioral rules and tool usage patterns
Depth	Maximum tool recursion depth (default: 10)
Role	A concise description shown in the agent list

Custom Agents

Create agents on the fly:

CreateAgent(
    name="api-specialist",
    description="Expert in REST API design and implementation",
    system_prompt="You are an API design specialist who follows OpenAPI standards..."
)

Or define agents in plugin files:

.gee/plugins/my-plugin/
  agents/
    api-specialist.md

Agent definition format:

---
name: api-specialist
description: Expert in REST API design
model: claude-sonnet
---

# Instructions

You are a specialized agent for API design...

Bead-Based Delegation

For complex tasks, agents work through the bead system — a dependency graph of tasks:

1. AI creates a bead plan with agent assignments
2. You review and approve
3. Beads execute in parallel where possible
4. Results flow through the dependency graph

/plan Refactor the auth module   # Creates bead plan with agent assignments
/beads approve                   # Approve for execution
/run                             # Execute (parallel by default)

Agent Types

Agents come from multiple sources:

Source	Persistence	Example
Built-in archetypes	Always available	explore, code, architect
Skill-bundled	Available when skill is active	Agents defined in skill frontmatter
Plugin-defined	Available when plugin is installed	Agents in .gee/plugins/
User-created	Persists until deleted	Created via CreateAgent

Next Steps

• Planning & Execution — task decomposition with beads
• Flights & Swarms — parallel agent orchestration
• Creating Agents — full guide to building agents
• Agents Reference — quick-reference table of all 13 built-in archetypes