Nano - OpenCode Agents Project

A minimal project structure for creating and managing custom OpenCode agents.

Project Structure

nano/
├── opencode.json           # Main agent configuration
├── .opencode/agent/        # Custom agents (markdown format)
│   └── docs-writer.md     # Documentation writer agent
├── prompts/               # Agent prompt files
│   ├── build.txt          # Build agent prompt
│   ├── cleanup.txt        # Cleanup agent prompt
│   ├── security.txt       # Security auditor prompt
│   └── review.txt        # Code review prompt
└── README.md             # This file

Available Agents

Primary Agents

• build: Full development agent with all tools enabled
• plan: Analysis and planning agent (read-only)

Subagents

• @cleanup: Repository cleanup and maintenance
• @security: Security auditing and vulnerability assessment
• @docs-writer: Technical writing and documentation
• @review: Code review and quality assessment

Usage

Switching Between Primary Agents

Use Tab key to cycle between build and plan agents.

Using Subagents

Mention subagents with @ in your messages:

@cleanup help me clean up this repository
@security audit this code for vulnerabilities
@docs-writer create documentation for this API
@review review my recent changes

Configuration

Adding New Agents

1. JSON Configuration: Edit opencode.json
2. Markdown Files: Add new .md files to .opencode/agent/
3. Prompt Files: Add corresponding prompts to prompts/

Agent Types

• Primary: Main agents you interact with directly
• Subagent: Specialized agents invoked for specific tasks

Customization

Models

Each agent can use different models optimized for their tasks:

• Fast models for planning and analysis
• Capable models for implementation
• Specialized models for specific domains

Tools & Permissions

Configure which tools each agent can access:

• File operations (read, write, edit)
• System commands (bash)
• Web access (webfetch)
• Custom permissions and restrictions

Temperature

Control creativity vs. determinism:

• 0.0-0.2: Focused, analytical tasks
• 0.3-0.5: Balanced development work
• 0.6-1.0: Creative and exploratory tasks

Examples

Repository Cleanup

@cleanup analyze this repository and suggest cleanup

Security Audit

@security check for security vulnerabilities in this code

Documentation Generation

@docs-writer create API documentation for this module

Code Review

@review review my recent commits for best practices

Development

Creating New Agents

Use OpenCode CLI to create new agents:

opencode agent create

Testing Agents

Test agents in isolation before integrating:

@new-agent test this functionality

Agent Configuration Examples

JSON Configuration

{
  "agent": {
    "my-agent": {
      "description": "Custom agent for specific task",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "temperature": 0.3,
      "prompt": "{file:./prompts/my-agent.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": false
      }
    }
  }
}

Markdown Configuration

---
description: Custom agent for specific task
mode: subagent
model: anthropic/claude-sonnet-4-20250514
temperature: 0.3
tools:
  write: true
  edit: true
  bash: false
---

You are a specialized agent for...

Agent Permissions

Permission Levels

• allow: Grant unrestricted access
• ask: Prompt for confirmation before action
• deny: Completely disable the tool

Example Permissions

{
  "permission": {
    "bash": {
      "git push": "ask",
      "git status": "allow",
      "*": "deny"
    },
    "edit": "ask",
    "webfetch": "allow"
  }
}

Best Practices

Agent Design

• Keep agents focused on specific tasks
• Use appropriate temperature settings
• Configure minimal necessary permissions
• Write clear, specific prompts

Security

• Restrict dangerous operations with permissions
• Use ask for potentially destructive actions
• Review agent configurations regularly

Performance

• Use faster models for simple tasks
• Reserve powerful models for complex work
• Consider token usage and costs

Resources

• OpenCode Documentation
• Agent Configuration Guide
• Available Models
• Permissions Documentation

Using with Different Projects

This OpenCode agents project can be used with any existing project. Here are several methods to integrate the agents:

Method 1: Copy Configuration to Existing Project

Step 1: Copy Agent Files

# Navigate to your existing project
cd /path/to/your/project

# Copy OpenCode configuration
cp -r /path/to/nano-opencode-agents/.opencode ./
cp /path/to/nano-opencode-agents/opencode.json ./
cp -r /path/to/nano-opencode-agents/prompts ./

Step 2: Verify Structure

Your project should now have:

your-project/
├── .opencode/
│   └── agent/
│       └── docs-writer.md
├── prompts/
│   ├── build.txt
│   ├── cleanup.txt
│   ├── security.txt
│   └── review.txt
├── opencode.json
└── (your existing project files)

Step 3: Start OpenCode

# Navigate to your project
cd /path/to/your/project

# Start OpenCode
opencode

Method 2: Global Configuration

Step 1: Install Globally

# Copy to global OpenCode config directory
mkdir -p ~/.config/opencode/agent ~/.config/opencode/prompts
cp /path/to/nano-opencode-agents/.opencode/agent/* ~/.config/opencode/agent/
cp /path/to/nano-opencode-agents/prompts/* ~/.config/opencode/prompts/

Step 2: Create Global config.json

# Create global config file with all agents
cat > ~/.config/opencode/config.json << 'EOF'
{
  "agents": {
    "build": {
      "type": "prompt",
      "path": "prompts/build.txt"
    },
    "cleanup": {
      "type": "prompt", 
      "path": "prompts/cleanup.txt"
    },
    "security": {
      "type": "prompt",
      "path": "prompts/security.txt"
    },
    "review": {
      "type": "prompt",
      "path": "prompts/review.txt"
    },
    "docs-writer": {
      "type": "markdown",
      "path": "agent/docs-writer.md"
    },
    "plan": {
      "type": "json",
      "path": "agent/plan.json"
    }
  }
}
EOF

Step 3: Verify Global Setup

# Check global configuration
ls -la ~/.config/opencode/
cat ~/.config/opencode/config.json

# Test from any directory
cd /tmp
opencode  # Will load global agents

Global Structure

~/.config/opencode/
├── config.json          # Main configuration
├── agent/              # Markdown/JSON agents
│   └── docs-writer.md  # Documentation writer
└── prompts/            # Text-based prompts
    ├── build.txt       # Build automation
    ├── cleanup.txt     # Repository cleanup
    ├── review.txt      # Code review
    └── security.txt    # Security analysis

Method 3: Project-Specific Customization

Step 1: Initialize Project

cd /path/to/your/project

# Create OpenCode structure
mkdir -p .opencode/agent prompts

Step 2: Copy Base Configuration

# Copy agent configurations
cp /path/to/nano-opencode-agents/opencode.json ./
cp -r /path/to/nano-opencode-agents/.opencode/agent/* .opencode/agent/
cp -r /path/to/nano-opencode-agents/prompts/* prompts/

Step 3: Customize for Your Project

Edit opencode.json to match your project needs:

• Adjust models based on your preferences
• Modify permissions for your workflow
• Add project-specific agents

Method 4: Selective Agent Installation

Step 1: Choose Specific Agents

# Only copy cleanup agent
cp /path/to/nano-opencode-agents/.opencode/agent/docs-writer.md .opencode/agent/
cp /path/to/nano-opencode-agents/prompts/cleanup.txt prompts/

Step 2: Create Minimal opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "cleanup": {
      "description": "Repository cleanup and maintenance",
      "mode": "subagent",
      "prompt": "{file:./prompts/cleanup.txt}",
      "tools": { "write": true, "bash": true }
    }
  }
}

Usage Examples

Once Configured, Use Agents Like This:

# Start OpenCode in your project
opencode

# Switch between primary agents with Tab
# Use subagents with @ mentions

@cleanup help me organize this project
@security audit my authentication code
@docs-writer create API documentation
@review review my recent changes

Project-Specific Customization Ideas

For Web Development Projects:

• Add frontend agent for UI/UX work
• Add backend agent for server-side logic
• Add testing agent for test automation

For Data Science Projects:

• Add analysis agent for data exploration
• Add visualization agent for charts/plots
• Add ml agent for machine learning tasks

For DevOps Projects:

• Add deployment agent for CI/CD
• Add monitoring agent for observability
• Add infrastructure agent for cloud resources

Best Practices for Integration

Configuration Management:

1. Start small - add agents as needed
2. Test locally before committing
3. Version control your agent configurations
4. Document customizations for your team

Permission Management:

1. Restrict dangerous operations with ask permissions
2. Allow read operations freely
3. Customize per project type
4. Review regularly for security

Performance Optimization:

1. Use fast models for simple tasks
2. Reserve powerful models for complex work
3. Consider token costs and usage
4. Cache frequently used prompts

Troubleshooting

Common Issues:

• Agents not showing: Check file paths in opencode.json
• Permission errors: Verify tool configurations
• Model not found: Check model names and availability
• Prompt not loading: Verify file paths exist

Debug Steps:

1. Check OpenCode logs for errors
2. Validate JSON syntax
3. Test with minimal configuration
4. Verify file permissions

Contributing

To contribute new agents or improvements:

1. Fork the project
2. Create a new branch
3. Add your agent configuration
4. Test thoroughly
5. Submit a pull request

License

This project is provided as a template for OpenCode agent development. Feel free to adapt and modify for your specific needs.