Tips & Tricks

Practical tips to get the most out of OpenCode. This is a living document — new tips will be added as we discover more effective workflows.

Effective Prompting

Be Specific and Detailed

Talk to OpenCode like you would a junior developer. Provide enough context:

❌ Fix the auth bug
✅ The login page at @src/pages/Login.tsx throws a 401 error when the user 
   submits valid credentials. Check the auth handler in 
   @src/api/auth.ts and fix the token validation logic.

Use @ File References

Press @ to fuzzy search for files. This includes file content in the prompt, giving the LLM precise context:

Take a look at how routing is handled in @src/router/index.ts and add a 
new route for the dashboard page.

Provide Examples

When asking for new code, reference existing patterns:

Create a new API endpoint for user preferences. Follow the same pattern 
used in @src/api/notes.ts for error handling and response format.

Drag and Drop Images

Drag images directly into the terminal for visual context:

• UI mockups for design references
• Screenshots of bugs
• Architecture diagrams
• Design system tokens

Workflow Strategies

Plan Before You Build

For complex features, always start in Plan mode (Tab to switch):

1. Plan — Describe the feature, review the AI's plan
2. Iterate — Refine the plan with feedback
3. Build — Switch to Build mode and ask it to implement

This prevents wasted time on incorrect implementations.

Use Undo Aggressively

Don't hesitate to /undo if the result isn't right. It's a core part of the workflow:

/undo          # Revert changes, shows original prompt
# Tweak the prompt
/undo          # Undo multiple times if needed
/redo          # Redo if you went too far

Break Down Large Tasks

Instead of one massive prompt, break work into smaller steps:

Step 1: "Create the database schema for user preferences"
Step 2: "Add the API endpoints using the schema from step 1"
Step 3: "Create the frontend settings page that calls these endpoints"

Multi-Session Workflows

OpenCode supports multiple sessions on the same project. Use this for parallel tasks:

• Session 1: Working on a feature
• Session 2: Fixing a bug in a different part of the codebase
• Session 3: Writing tests

Context Management

Keep Context Focused

The LLM has a limited context window. Help it by:

• Referencing specific files with @ instead of describing them
• Breaking long conversations into new sessions
• Using Plan mode first to narrow down which files need changes

Compaction

When conversations get long, OpenCode can automatically compact the context:

{
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000
  }
}

• auto — Automatically compact when context is full
• prune — Remove old tool outputs to save tokens
• reserved — Token buffer to avoid overflow during compaction

Use Instructions Files

Point OpenCode to project-specific guidelines:

{
  "instructions": [
    "CONTRIBUTING.md",
    "docs/coding-standards.md",
    ".cursor/rules/*.md"
  ]
}

This ensures the AI follows your team's conventions.

Permission Control

Recommended Setup for Teams

For team environments, require approval for destructive actions:

{
  "permission": {
    "edit": "ask",
    "bash": "ask",
    "write": "ask",
    "read": "allow",
    "grep": "allow",
    "glob": "allow"
  }
}

Lock Down MCP Servers

Use wildcards to control all tools from an MCP server:

{
  "permission": {
    "mymcp_*": "ask"
  }
}

Local Model Tips

Choose the Right Model

• Small, fast tasks: Use smaller models (Haiku, Gemma) for quick Q&A
• Complex coding: Use larger models (Claude Sonnet/Opus, GPT-4) for multi-file changes
• Budget-conscious: Use OpenCode Go or local models via Ollama

Ollama Performance

When using Ollama locally:

• Increase num_ctx to at least 16k–32k for tool calls to work
• Use quantized models for faster response times
• Ensure you have enough VRAM for the model size

Set a Small Model

Configure a cheaper model for lightweight tasks:

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Project Organization

Commit AGENTS.md

After running /init, commit the generated AGENTS.md to your repo. This helps OpenCode understand your project across sessions.

Use .opencode Directory

Organize project-specific customizations:

.opencode/
├── agents/       # Project-specific agents
├── commands/     # Project-specific commands
├── skills/       # Project-specific skills
└── plugins/      # Project-specific plugins

Share Useful Sessions

After solving a tricky problem, share the session with your team:

/share

This creates a reference link others can learn from.

Performance Tips

Disable Snapshots for Large Repos

If OpenCode is slow on large repositories:

{
  "snapshot": false
}

Note: this disables undo/redo functionality.

Configure File Watcher Ignores

Exclude noisy directories:

{
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

Use .ignore for Search Scope

Control which files tools like grep and glob can search:

# .ignore
!node_modules/
!dist/

Keyboard Shortcuts

Key	Action
Tab	Switch between Build and Plan modes
@	Fuzzy search for file references
/	Open command menu

Customize keybinds in tui.json:

{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {}
}

Further Reading

• Official Documentation
• Discord Community — Get help and share tips
• GitHub Issues — Report bugs
• Changelog — Stay up to date