Complete guide for developing on the OpenAgents repository
This guide covers everything you need to know to develop agents, commands, tools, and contribute to the OpenAgents ecosystem.
- Getting Started
- Repository Structure
- Development Workflow
- Creating New Agents
- Testing
- Best Practices
- Common Tasks
- Troubleshooting
- OpenCode CLI installed (installation guide)
- Node.js 18+ (for testing framework)
- Git for version control
- Bash (macOS/Linux) or Git Bash (Windows)
# Clone the repository
git clone https://github.com/darrenhinde/OpenAgents.git
cd OpenAgents
# Install dependencies for testing framework
cd evals/framework
npm install
cd ../..# Validate registry
make validate-registry
# Run tests
cd evals/framework
npm testopencode-agents/
├── .opencode/ # OpenCode configuration
│ ├── agent/ # Agent prompts (category-based)
│ │ ├── core/
│ │ │ ├── openagent.md # Universal orchestrator
│ │ │ └── opencoder.md # Development specialist
│ │ ├── meta/
│ │ │ └── system-builder.md # System architect
│ │ ├── development/
│ │ │ ├── frontend-specialist.md
│ │ │ └── backend-specialist.md
│ │ ├── content/
│ │ │ └── copywriter.md
│ │ └── subagents/ # Specialized subagents
│ │ ├── code/ # Code-related subagents
│ │ ├── core/ # Core functionality subagents
│ │ ├── system-builder/ # System building subagents
│ │ └── utils/ # Utility subagents
│ ├── command/ # Slash commands
│ │ ├── openagents/ # OpenAgents-specific commands
│ │ │ └── new-agents/ # Agent creation system ⭐
│ │ └── prompt-engineering/ # Prompt optimization commands
│ ├── context/ # Context files
│ │ ├── core/ # Core context (standards, workflows)
│ │ ├── project/ # Project-specific context
│ │ └── system-builder-templates/ # Templates
│ ├── plugin/ # Plugins and integrations
│ ├── prompts/ # Prompt library (model variants, category-based)
│ │ ├── core/
│ │ │ ├── openagent/ # OpenAgent variants
│ │ │ └── opencoder/ # OpenCoder variants
│ │ └── development/
│ │ └── frontend-specialist/ # Frontend specialist variants
│ └── tool/ # Utility tools
├── evals/ # Testing framework
│ ├── agents/ # Agent test suites
│ │ ├── openagent/ # OpenAgent tests
│ │ └── opencoder/ # OpenCoder tests
│ ├── framework/ # Test framework code
│ │ ├── src/ # Framework source
│ │ └── scripts/ # Test utilities
│ └── results/ # Test results
├── scripts/ # Automation scripts
│ ├── registry/ # Registry management
│ ├── prompts/ # Prompt management
│ └── testing/ # Test utilities
├── docs/ # Documentation
│ ├── agents/ # Agent documentation
│ ├── contributing/ # Contribution guides
│ ├── features/ # Feature documentation
│ └── guides/ # User guides
└── registry.json # Component registry
Main agent prompts organized by category. These are the "brains" of the system:
- core/openagent.md - Universal orchestrator with plan-first workflow
- core/opencoder.md - Development specialist for direct code execution
- meta/system-builder.md - System architecture generator
- development/ - Development specialist agents (frontend, backend, devops)
- content/ - Content creation agents (copywriter, technical-writer)
- subagents/ - Specialized helpers for specific tasks
Slash commands that users can invoke:
- openagents/new-agents/ - ⭐ NEW: Agent creation system with research-backed principles
- prompt-engineering/ - Prompt optimization tools
Context files that agents load on-demand:
- core/ - Standards, patterns, workflows
- project/ - Project-specific context (CLAUDE.md pattern)
Prompt library with model-specific variants (category-based structure):
- Allows experimentation without breaking main branch
- Each variant has test results documented
- Organized by category matching agent structure (core/, development/, etc.)
Comprehensive testing framework:
- agents/ - Test suites for each agent (8 essential tests)
- framework/ - Testing infrastructure
- results/ - Test results and reports
git checkout -b feature/my-new-featureFollow the appropriate guide:
# Validate structure
./scripts/registry/validate-component.sh
# Run tests
cd evals/framework
npm test -- --agent=your-agent
# Test manually
opencode --agent=your-agentgit add .
git commit -m "feat: add new feature"
git push origin feature/my-new-feature- Use conventional commit format in PR title
- Fill out PR template completely
- Ensure CI passes
We now have a streamlined system for creating agents following Anthropic 2025 research best practices.
# Use the agent creation command
/create-agent my-agent-name
# Or invoke directly
opencode "Create a new agent called 'python-dev' for Python development"The system generates:
- Minimal agent prompt (~500 tokens at "right altitude")
- Project context file (CLAUDE.md pattern)
- 8 comprehensive tests (planning, context, incremental, tools, errors, thinking, compaction, completion)
- Test configuration
- Registry entry
The agent creation system follows these proven patterns:
Why: Code changes are deeply dependent. Sub-agents can't coordinate edits to the same file.
Application:
- Use ONE lead agent with tool-based sub-functions
- NOT autonomous sub-agents for coding
- Multi-agent only for truly independent tasks (static analysis, test execution, code search)
Why: "Find the smallest possible set of high-signal tokens that maximize likelihood of desired outcome"
The Balance:
| Too Vague | Right Altitude ✅ | Too Rigid |
|---|---|---|
| "Write good code" | Clear heuristics + examples | 50-line prompt with edge cases |
Application:
- Clear heuristics, not exhaustive rules
- Examples > edge case lists
- Show ONE canonical example, not 20 scenarios
Why: Prevents "drowning in irrelevant information"
Application:
- Tools load context on demand (not pre-loaded)
- CLAUDE.md pattern for project context
- File metadata guides behavior
Why: "Tool ambiguity is one of the biggest failure modes"
Application:
<tool name="read_file">
<purpose>Load specific file for analysis or modification</purpose>
<when_to_use>You need to examine or edit a file</when_to_use>
<when_not_to_use>You already have the file content in context</when_not_to_use>
</tool>Why: Improved instruction-following and reasoning efficiency
Application:
- Trigger thinking before complex tasks
- "Think hard about how to approach this problem..."
- Phrases mapped to thinking budget (think, think hard, think harder)
Why: Maintain context efficiency over long-horizon tasks
Application:
- Agent writes notes to persistent memory
- Summarizes when context fills
- Preserves: architectural decisions, unresolved bugs, implementation details
- Discards: redundant tool outputs
Why: "Parallel tool calling cut research time by up to 90%"
Application:
- Can do in parallel: Run linter, execute tests, check type errors
- NOT in parallel: Apply fix, then test (sequential)
Why: "Token usage explains 80% of performance variance"
Measure:
- ✅ Does it solve the task?
- ✅ Token usage reasonable?
- ✅ Tool calls appropriate?
- ❌ NOT: "Did it follow exact steps I imagined?"
If you prefer manual creation, follow this structure:
1. Create Agent File (.opencode/agent/my-agent.md)
---
description: "Brief one-line description"
mode: primary
temperature: 0.1
tools:
read: true
write: true
edit: true
bash: true
glob: true
grep: true
permissions:
bash:
"rm -rf *": "ask"
"sudo *": "deny"
edit:
"**/*.env*": "deny"
"**/*.key": "deny"
---
# My Agent
<role>
Clear, concise role - what this agent does
</role>
<approach>
1. Read and understand the context
2. Think about the approach before acting
3. Implement changes incrementally
4. Verify each step with appropriate tools
5. Complete with clear summary
</approach>
<heuristics>
- Decompose problems before implementing
- Use tools intentionally (not speculatively)
- Verify outputs before claiming completion
- Stop on errors and report (don't auto-fix blindly)
</heuristics>
<output>
Always include:
- What you did
- Why you did it that way
- Test/validation results
</output>
<examples>
<example name="Typical Use Case">
**User**: "typical request"
**Agent**:
1. Read relevant files
2. Think about approach
3. Implement change
4. Verify
**Result**: Expected outcome
</example>
</examples>2. Create Context File (.opencode/context/project/my-agent-context.md)
# My Agent Context
## Key Commands
- command 1: what it does
- command 2: what it does
## File Structure
- path pattern: what goes here
## Code Style
- style rule 1
- style rule 2
## Workflow Rules
- workflow rule 1
- workflow rule 2
## Before Committing
1. check 1
2. check 23. Create Test Suite
Use the test generator:
/create-tests my-agentOr manually create 8 tests in evals/agents/my-agent/tests/:
planning/planning-approval-001.yamlcontext-loading/context-before-code-001.yamlimplementation/incremental-001.yamlimplementation/tool-usage-001.yamlerror-handling/stop-on-failure-001.yamlimplementation/extended-thinking-001.yamllong-horizon/compaction-001.yamlcompletion/handoff-001.yaml
4. Register Agent
The registry auto-updates on merge to main, or manually:
./scripts/registry/register-component.shPre-built templates are available in:
.opencode/command/openagents/new-agents/templates/
├── agent-template.md # Minimal agent template
├── context-template.md # CLAUDE.md pattern
├── test-config-template.yaml # Test configuration
└── test-*.yaml # 8 test templates
Commands are slash commands users can invoke.
---
description: "What this command does"
---
# Command Name
<target_argument> $ARGUMENTS </target_argument>
<role>
What this command specializes in
</role>
<task>
Specific objective of this command
</task>
<workflow>
<step_1>
Action and process
</step_1>
<step_2>
Action and process
</step_2>
</workflow>See .opencode/command/openagents/new-agents/create-agent.md for a complete example.
Tools are TypeScript utilities that agents can use.
/**
* Tool Name
*
* Brief description of what this tool does
*/
export function myTool(param: string): string {
// Implementation
return result;
}Place tools in .opencode/tool/my-tool/index.ts
We use a comprehensive evaluation framework in evals/framework/.
# Run all tests
cd evals/framework
npm test
# Run tests for specific agent
npm test -- --agent=openagent
# Run specific category
npm test -- --agent=openagent --category=planning
# Run single test
npm test -- --agent=openagent --test=planning-approval-001
# Verbose output
npm test -- --verboseEach agent should have 8 essential test types:
- Planning & Approval - Verify plan-first approach
- Context Loading - Ensure just-in-time context retrieval
- Incremental Implementation - Verify step-by-step execution
- Tool Usage - Check correct tool selection
- Error Handling - Verify stop-on-failure behavior
- Extended Thinking - Check decomposition before coding
- Compaction - Verify long session handling
- Completion - Check proper output and handoff
id: test-id-001
name: Test Name
description: |
What this test verifies
category: planning
agent: my-agent
model: anthropic/claude-sonnet-4-5
prompt: |
Test prompt
behavior:
mustContain:
- "expected text"
mustNotContain:
- "forbidden text"
mustUseAnyOf: [[tool1], [tool2]]
minToolCalls: 1
expectedViolations:
- rule: rule-name
shouldViolate: false
severity: error
approvalStrategy:
type: auto-approve
timeout: 30000
tags:
- tag1
- tag2Use the templates in .opencode/command/openagents/new-agents/templates/ as starting points.
✅ Do:
- Keep system prompts minimal (~500 tokens)
- Use clear heuristics, not exhaustive rules
- Provide ONE canonical example
- Define tools with clear purpose and when to use/not use
- Load context on-demand (just-in-time)
- Measure outcomes: Does it solve the task?
❌ Don't:
- Create sub-agents for dependent tasks (code is sequential)
- Pre-load entire codebase into context
- Write exhaustive edge case lists in prompts
- Give vague tool descriptions
- Use multi-agent if you could use single agent + tools
- Minimize tool calls (some redundancy is fine)
- Use clear, concise language
- Include examples
- Add code blocks with syntax highlighting
- Use proper heading hierarchy
- Follow existing code style
- Add JSDoc comments
- Use TypeScript types (no
any) - Export functions explicitly
- Use
set -efor error handling - Add comments for complex logic
- Use meaningful variable names
- Include help text
- kebab-case for file names:
my-new-agent.md - PascalCase for TypeScript types/interfaces
- camelCase for variables and functions
# 1. Edit the agent file
vim .opencode/agent/my-agent.md
# 2. Test changes
cd evals/framework
npm test -- --agent=my-agent
# 3. Update tests if needed
vim evals/agents/my-agent/tests/...
# 4. Commit
git add .
git commit -m "feat: improve my-agent behavior"# 1. Create test file
vim evals/agents/my-agent/tests/new-category/new-test-001.yaml
# 2. Update config
vim evals/agents/my-agent/config/config.yaml
# Add new category to testPaths
# 3. Run test
cd evals/framework
npm test -- --agent=my-agent --test=new-test-001# 1. Copy template
cp .opencode/prompts/core/openagent/TEMPLATE.md .opencode/prompts/core/openagent/my-variant.md
# 2. Edit variant
vim .opencode/prompts/core/openagent/my-variant.md
# 3. Test variant
./scripts/prompts/test-prompt.sh core/openagent my-variant
# 4. Update README with results
vim .opencode/prompts/core/openagent/README.md# Validate component structure
./scripts/registry/validate-component.sh
# Ensure using default prompts
./scripts/prompts/validate-pr.sh
# Run all tests
cd evals/framework
npm test
# Validate registry
make validate-registryProblem: Tests fail after making changes
Solution:
- Check test output for specific failures
- Run with
--verboseflag for details - Verify agent follows expected behavior
- Update tests if behavior intentionally changed
Problem: make validate-registry fails
Solution:
- Check
registry.jsonsyntax - Ensure all referenced files exist
- Verify frontmatter in agent files is valid YAML
- Run
./scripts/registry/validate-component.shfor details
Problem: Agent doesn't load context files
Solution:
- Verify context file exists in
.opencode/context/ - Check agent has
readtool enabled - Ensure context file path is correct
- Test with simple prompt that requires context
Problem: Custom tool not accessible to agent
Solution:
- Verify tool is in
.opencode/tool/my-tool/index.ts - Check tool is exported properly
- Ensure agent has tool enabled in frontmatter
- Rebuild if needed:
cd .opencode/tool && npm run build
- Contributing Guide - General contribution guidelines
- Agent Creation System - Detailed agent creation guide
- Research-Backed Prompt Design - Prompt engineering principles
- Test Design Guide - Writing effective tests
- OpenAgent - Universal orchestrator example
- OpenCoder - Development specialist example
- Subagents - Specialized subagent examples
- Test Suites - Comprehensive test examples
- Issues: Open an issue for bugs or feature requests
- Discussions: Use GitHub Discussions for questions
- Security: Email security issues privately
Happy developing! 🚀