Agents are specialized AI assistants that perform focused tasks within the Agentic workflow. They are invoked by commands to handle specific aspects of research, analysis, and code exploration.
Purpose: Find WHERE files and components live in the codebase.
Capabilities:
- Searches for files by keyword
- Identifies directory patterns
- Groups files by purpose
- Returns structured file lists
Use Cases:
- Finding all files related to a feature
- Discovering test locations
- Mapping code organization
Purpose: Understand HOW specific code works.
Capabilities:
- Analyzes implementation details
- Traces data flow
- Identifies dependencies
- Explains code logic
Use Cases:
- Understanding existing implementations
- Analyzing complex functions
- Tracing system behavior
Purpose: Find similar implementations and patterns.
Capabilities:
- Locates usage examples
- Identifies coding patterns
- Finds similar features
- Provides concrete code examples
Use Cases:
- Finding patterns to follow
- Discovering existing solutions
- Learning codebase conventions
Purpose: Discover relevant documents in thoughts/ directory.
Capabilities:
- Searches documentation by topic
- Finds related research
- Identifies architectural decisions
- Excludes archive/ directory
Use Cases:
- Finding historical context
- Discovering related work
- Understanding decisions
Purpose: Extract insights from specific thought documents.
Capabilities:
- Deep analysis of documents
- Synthesizes key points
- Identifies connections
- Extracts actionable information
Use Cases:
- Understanding architecture
- Reviewing past research
- Extracting requirements
Purpose: Perform web searches and analyze content.
Capabilities:
- Fetches web pages
- Analyzes documentation
- Extracts relevant information
- Provides summaries
Use Cases:
- Researching external libraries
- Finding documentation
- Gathering best practices
Agents can run in parallel for efficiency:
Phase 1: Discovery (parallel)
- codebase-locator: Find relevant files
- thoughts-locator: Find relevant docs
Phase 2: Analysis (parallel, after Phase 1)
- codebase-analyzer: Analyze found code
- thoughts-analyzer: Analyze found docs
Some agents depend on others:
- Locators first: Find what exists
- Analyzers second: Deep dive on findings
- Pattern finders: When seeking examples
Each agent has a markdown configuration file with:
---
description: Agent purpose and capabilities
mode: subagent
model: anthropic/claude-opus-4-1
temperature: 0.1
tools:
grep: true
glob: true
list: true
read: false
write: false
---Detailed prompt explaining:
- Core responsibilities
- Search strategies
- Output format
- Guidelines and constraints
- Spawns codebase-locator to find files
- Spawns thoughts-locator for documentation
- May spawn analyzers for deep dives
- Synthesizes all findings
- Uses codebase-locator for context
- Uses codebase-analyzer for understanding
- Uses pattern-finder for examples
- Creates implementation plan
- Spawn appropriately: Use the right agent for each task
- Batch operations: Run parallel agents when possible
- Wait for completion: Always wait for all agents
- Verify results: Check agent outputs make sense
- Single responsibility: Each agent has one clear job
- Structured output: Return organized, parseable results
- File references: Include specific paths and line numbers
- Tool restrictions: Only enable necessary tools
---
description: Clear, concise description
mode: subagent
model: model-identifier
temperature: 0.1 # Lower for deterministic tasks
tools:
# Enable only needed tools
---
# Agent Name
## Core Responsibilities
What this agent does
## Strategy
How it accomplishes its goals
## Output Format
What it returns
## Guidelines
Important rules and constraints- Use descriptive names:
domain-action.md - Examples:
codebase-locator.md,test-runner.md
- Read-only agents: grep, glob, list, read
- Modification agents: write, edit, patch
- Utility agents: bash, webfetch
- Agents are stateless
- Cannot communicate between instances
- Single response only
- No follow-up interactions
- Limited to configured tools
- Cannot modify their own configuration
- Cannot spawn other agents
- Must complete in single execution
-
Agent returns unexpected results
- Check search terms in prompt
- Verify directory focus
- Review output format requirements
-
Agent takes too long
- Reduce search scope
- Be more specific in prompt
- Break into smaller tasks
-
Agent misses information
- Check if using right agent type
- Verify search patterns
- Consider follow-up search
- Agents evolve with workflow needs
- Updates distributed via
agentic pull - Backward compatibility maintained
- Modify agents for project needs
- Override in local
.opencode/ - Share improvements upstream