Configuration Locations

OpenCode

code

~/.config/opencode/
├── opencode.json          # Main config
├── agent/                 # Custom agent prompts
│   ├── oscar.md
│   ├── scout.md
│   ├── ivan.md
│   └── jester.md
├── skills/                # Reusable skills
│   └── <name>/SKILL.md
└── rules/                 # Always-active rules
    └── RULES.md

Claude Code

code

~/.claude/
├── settings.json          # Main config
├── agents/                # Custom agents
│   └── <name>.md
├── skills/                # Reusable skills
│   └── <name>/SKILL.md
└── CLAUDE.md              # Global instructions

Agent File Structure

Frontmatter (YAML)

yaml

---
tools:
  read: true
  write: false
  edit: false
  glob: true
  grep: true
  bash: true
  task: false
  webfetch: true
  todoread: true
  todowrite: true
  question: true    # Ask user questions
  skill: true       # Load skills

permission:
  bash:
    "git *": allow
    "gh *": allow
    "*": deny
---

Tool Reference

Tool	Purpose	Risk Level
`read`	Read files	Low
`write`	Create/overwrite files	High
`edit`	Modify files	High
`glob`	Find files by pattern	Low
`grep`	Search file contents	Low
`list`	List directories	Low
`bash`	Execute commands	Variable
`task`	Delegate to subagents	Low
`webfetch`	Fetch web content	Medium
`todoread`	Read task list	Low
`todowrite`	Update task list	Low
`question`	Ask user questions	Low
`skill`	Load skill files	Low

Permission Patterns

Restrictive (Read-Only Agent)

yaml

tools:
  read: true
  write: false
  edit: false
  bash: true

permission:
  bash:
    "ls *": allow
    "cat *": allow
    "git status": allow
    "*": deny

Permissive (Full Access)

yaml

tools:
  read: true
  write: true
  edit: true
  bash: true

permission:
  bash:
    "*": allow

Balanced (Common Pattern)

yaml

tools:
  read: true
  write: true
  edit: true
  bash: true

permission:
  bash:
    # Safe commands
    "ls *": allow
    "cat *": allow
    "head *": allow
    "tail *": allow
    
    # Git operations
    "git *": allow
    
    # Python in venv only
    ".venv/bin/*": allow
    
    # Deny everything else
    "*": deny

Agent Roles

Orchestrator (Oscar-style)

•Has task: true to delegate
•Has question: true to interact with user
•Limited direct tool access
•Coordinates other agents

Researcher (Scout-style)

•Read-only access
•Has webfetch: true
•Full search tools (glob, grep)
•No task (can't delegate)

Implementor (Ivan-style)

•Full write access
•Full bash access
•No task (can't delegate)
•Does the actual work

Reviewer (Jester-style)

•Read-only access
•Different model for diversity
•Challenges assumptions
•No write access

Tuning Tips

1. Start Restrictive

Begin with minimal permissions, expand as needed.

2. Use Specific Bash Patterns

yaml

# Good - specific
".venv/bin/pytest *": allow

# Bad - too broad
"*pytest*": allow

3. Separate Concerns

•Orchestrator: coordinates
•Researcher: investigates
•Implementor: changes code
•Reviewer: validates

4. Test Permission Changes

After modifying permissions, test that:

•Allowed commands work
•Denied commands are blocked
•Edge cases are handled

Debugging

Check Active Config

bash

# OpenCode
cat ~/.config/opencode/opencode.json

# View agent prompt
cat ~/.config/opencode/agent/<name>.md

Common Issues

•Tool not working: Check tools: section
•Command denied: Check permission.bash patterns
•Skill not loading: Check skill name matches directory
•Agent not found: Check opencode.json agent definitions