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

Updating Global Configuration

After making changes to the nano project agents, you need to sync them with the global configuration:

When to Update

• Edited agent prompts
• Added new agents
• Removed existing agents
• Modified agent configurations
• Changed opencode.json settings

Update Steps

1. Copy Changes to Global Location

# Navigate to nano project directory
cd /path/to/nano-opencode-agents

# Copy updated agent files
cp .opencode/agent/* ~/.config/opencode/agent/
cp prompts/* ~/.config/opencode/prompts/

# Update global config if needed
cp opencode.json ~/.config/opencode/config.json

2. Verify the Update

# Check that files are current
ls -la ~/.config/opencode/agent/
ls -la ~/.config/opencode/prompts/
cat ~/.config/opencode/config.json

3. Test Global Agents

# Test from any directory
cd /tmp
opencode  # Should load updated agents

Specific Update Scenarios

Prompt Edits

# Single prompt update
cp prompts/cleanup.txt ~/.config/opencode/prompts/

New Agent Added

# Copy new agent and update config
cp .opencode/agent/new-agent.md ~/.config/opencode/agent/
cp prompts/new-agent.txt ~/.config/opencode/prompts/
# Update ~/.config/opencode/config.json with new agent entry

Agent Removal

# Remove from global location
rm ~/.config/opencode/agent/removed-agent.md
rm ~/.config/opencode/prompts/removed-agent.txt
# Remove from ~/.config/opencode/config.json

Configuration Changes

# Update global config completely
cp opencode.json ~/.config/opencode/config.json

Workflow Recommendation

1. Make changes in nano project (version controlled)
2. Test locally in nano project directory
3. Commit changes to git repository
4. Sync to global using the steps above
5. Verify globally by testing from another directory

This workflow ensures:

• Version control of all changes
• Clean separation between development and deployment
• Easy rollback if needed
• Shareable configuration for team members

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.