The Complete Opencode Guide: Tips, Tricks, and Best Practices

February 7, 2025·10 min read·Sudipta Pathak
AI-Assisted Codingopencodeaiproductivitytipscliguide

The Complete Opencode Guide: Tips, Tricks, and Best Practices

After months of daily use building ML systems and infrastructure at JPMorgan Chase, I've discovered powerful patterns and workflows that have completely transformed how I code. This is a living guide that I continuously update as I discover new techniques and Opencode releases new features.

Note: These tips assume you have Opencode CLI installed and basic familiarity with the tool.

Last Updated: February 2025

Act 1: Foundations (Tips 1-15)

Setup & Configuration

Tip 1: Run Opencode from Your Project Root Always start Opencode from the root directory of your project. This ensures proper context and access to all files.

cd /path/to/your/project
opencode

Tip 2: Use /init for Codebase Analysis When starting with a new project, use /init to let Opencode analyze your codebase structure, dependencies, and conventions.

/init

This creates a comprehensive understanding of your project that persists across sessions.

Tip 3: Understand the AGENTS.md Hierarchy Opencode supports hierarchical configuration files:

  • Root AGENTS.md: Global rules for your project
  • Directory AGENTS.md: Specific rules for subdirectories
  • User-level config: Personal preferences in ~/.opencode/config

The system merges these hierarchically, with more specific rules overriding general ones.

Tip 4: Configure Your Default Model Set your preferred model in your config to avoid switching every time:

# In ~/.opencode/config
model: claude-sonnet-4-20250514

Tip 5: Set Up Project-Specific Context Create an AGENTS.md in your project root with:

  • Coding standards
  • Architecture decisions
  • Common patterns
  • Testing requirements
# AGENTS.md

## Project Context
This is a Next.js 15 project using TypeScript and Tailwind CSS.

## Coding Standards
- Use functional components
- Prefer `const` over `let`
- Follow Airbnb ESLint rules

Essential Commands & Shortcuts

Tip 6: Master Keyboard Shortcuts

  • Ctrl+C: Interrupt current operation
  • Ctrl+D: Exit Opencode
  • Tab: Autocomplete commands
  • Up/Down Arrow: Navigate command history

Tip 7: Use /clear to Reset Context When context gets bloated or confusing, reset it:

/clear

This clears the conversation history while keeping your project understanding.

Tip 8: Check Token Usage with /tokens Monitor your context window usage:

/tokens

When you hit ~80% of context, consider starting fresh or using /compact.

Tip 9: Switch Models with /model Different tasks need different models:

/model claude-opus-4-20250514    # Complex reasoning
/model claude-sonnet-4-20250514  # General coding
/model claude-haiku-4-20250514   # Quick tasks

Tip 10: Use /compact for Long Sessions When context gets too long, condense it:

/compact

This summarizes the conversation while preserving critical information.

Safety & Best Practices

Tip 11: Git Is Your Safety Net Always commit before major changes:

git add .
git commit -m "Pre-opencode checkpoint"

Opencode can make sweeping changes—git lets you roll back if needed.

Tip 12: Use /dry-run for Risky Operations Before executing destructive commands:

/dry-run

This shows what Opencode would do without actually doing it.

Tip 13: Review Changes Before Committing Always review with:

git diff

Or ask Opencode:

Show me a summary of all changes made

Tip 14: Define Critical Rules in AGENTS.md Put your most important rules at the top of AGENTS.md:

## Critical Rules
1. NEVER commit secrets or API keys
2. Always write tests for new features
3. Follow the existing code style
4. Run linter before finishing

Tip 15: Use /help to Discover Features Opencode is constantly evolving. Check for new features:

/help

Act 2: Daily Workflow (Tips 16-30)

Planning & Execution

Tip 16: Start Complex Features in "Plan Mode" Before writing code, plan the approach:

I want to add user authentication. Let me think through this step by step:
1. What auth provider should I use?
2. What routes need protection?
3. How should I handle sessions?

This prevents half-baked implementations.

Tip 17: Break Large Tasks into Chunks Instead of "Build the entire app," break it down:

Let's start with just the database schema design

Tip 18: Use Fresh Context for New Features Don't build new features on top of debugging sessions. Clear context first:

/clear
Now let's implement the shopping cart feature...

Tip 19: Condense Context When It Gets Bloated If you're 50+ messages deep:

/compact
Let's continue with the payment integration...

Tip 20: Persist Sessions with Project Files Create PROJECT_CONTEXT.md files for long-running work:

# PROJECT_CONTEXT.md

## Current Feature: Payment Integration
## Status: Implementing Stripe webhook handlers
## Next Steps:
- [ ] Handle successful payments
- [ ] Handle failed payments
- [ ] Update order status

Then tell Opencode: Read PROJECT_CONTEXT.md to understand current state

Verification & Quality

Tip 21: Give Verification Commands After making changes, ask Opencode to verify:

Now run `npm run lint` and `npm run test` to verify everything works

This creates a self-improvement loop.

Tip 22: Use Opus for Complex Tasks For architectural decisions or complex debugging:

/model claude-opus-4-20250514
I need to design a distributed caching layer...

Tip 23: Use Sonnet for General Coding For most day-to-day tasks:

/model claude-sonnet-4-20250514
Add input validation to the signup form

Tip 24: Use Haiku for Quick Tasks For simple, repetitive tasks:

/model claude-haiku-4-20250514
Rename all instances of "userName" to "username"

Context Management

Tip 25: Lazy-Load Large Context Don't dump everything at once. Load context incrementally:

First, let me show you the database schema...
[show schema]

Now, let's look at the API routes...
[show routes]

Tip 26: Use File References Instead of pasting code, reference files:

Look at src/components/UserProfile.tsx and suggest improvements

Tip 27: Pin Important Context For critical information you want to keep:

Remember: We're using React 18 with the new concurrent features

Tip 28: Ask for Summaries When returning to a long session:

Give me a summary of what we've done so far

Tip 29: Use Pattern Examples Show, don't just tell:

Follow this pattern for all new API routes:
```typescript
export async function GET(request: Request) {
  try {
    // Implementation
  } catch (error) {
    // Error handling
  }
}


**Tip 30: Define Done Criteria**
Be explicit about when a task is complete:

This task is done when:

  1. All tests pass
  2. TypeScript compiles without errors
  3. The feature works in the browser
  4. Documentation is updated

---

## Act 3: Power User (Tips 31-42)

### Advanced Features

**Tip 31: Master the Four Primitives**
Opencode has four key composability primitives:

1. **Skills** - Reusable workflows
2. **Commands** - Quick shortcuts
3. **MCPs** - External service integrations
4. **Tools** - Built-in capabilities

**Tip 32: Create Skills for Recurring Workflows**
Define skills in `~/.opencode/skills/`:

```yaml
# ~/.opencode/skills/react-component.yaml
name: Create React Component
description: Creates a new React component with tests and stories
steps:
  - Create component file
  - Create test file
  - Create story file
  - Add to index exports

Then use: /skill react-component

Tip 33: Use Commands for Quick Shorthand Create custom commands:

# ~/.opencode/commands.yaml
test: npm run test
lint: npm run lint
build: npm run build
dev: npm run dev

Use with: /test, /lint, /build, /dev

Tip 34: Integrate External Services with MCPs Connect to external APIs and documentation:

# ~/.opencode/mcp.yaml
services:
  stripe:
    docs_url: https://stripe.com/docs/api
  aws:
    docs_url: https://docs.aws.amazon.com/

Tip 35: Use Tools Effectively Opencode has built-in tools:

  • Read - Read file contents
  • Edit - Modify files
  • Bash - Run shell commands
  • Grep - Search code
  • Glob - Find files

Explicitly ask for them when needed:

Use Glob to find all test files, then Grep to find which ones don't have assertions

Tip 36: Chain Tools Together Combine tools for complex operations:

1. Use Grep to find all console.log statements
2. Use Read to check each file context
3. Use Edit to remove or replace them

Tip 37: Don't Over-Instruct Trust Opencode's defaults. Instead of:

❌ "Read the file, then edit line 5, add a semicolon, then save..."

✅ "Add error handling to the fetchData function"

Tip 38: Let Opencode Ask Questions When requirements are unclear:

I want to add a caching layer. What information do you need?

Tip 39: Use Multi-Tool Execution Run independent tasks in parallel:

Run these simultaneously:
1. npm run lint
2. npm run typecheck
3. npm run test:unit

Tip 40: Create Project Templates For new projects, create starter templates:

Create a new Next.js project with:
- TypeScript
- Tailwind CSS
- ESLint + Prettier
- Husky pre-commit hooks
- Jest + React Testing Library

Tip 41: Use Git Hooks Automate quality checks:

Set up a pre-commit hook that runs:
1. lint-staged
2. TypeScript check
3. Unit tests

Tip 42: Build Custom Workflows Define complex workflows in AGENTS.md:

## Deployment Workflow
1. Run all tests
2. Build production bundle
3. Run security audit
4. Deploy to staging
5. Run smoke tests
6. Deploy to production

Act 4: Advanced (Tips 43-50)

Power Workflows

Tip 43: Run Multiple Opencode Instances Work on different features simultaneously:

# Terminal 1
cd project && opencode

# Terminal 2  
cd project && opencode

# Terminal 3
cd project && opencode

Each has isolated context.

Tip 44: Use Terminal Multiplexing With tmux or iTerm split panes:

┌──────────────┬──────────────┐
│  Editor      │  Opencode    │
│  (vim/code)  │  (main)      │
├──────────────┼──────────────┤
│  Opencode    │  Terminal    │
│  (secondary) │  (logs)      │
└──────────────┴──────────────┘

Tip 45: Enable Notifications Configure your terminal to notify when long-running commands complete:

# In your .zshrc or .bashrc
alias opencode='opencode && terminal-notifier -message "Opencode done"'

Tip 46: Use Git Worktrees for Isolation Work on multiple branches simultaneously:

# Create worktree for feature branch
git worktree add ../project-feature feature-branch

# Start Opencode in worktree
cd ../project-feature && opencode

Tip 47: Browser Integration For web development, use browser tools:

Open Chrome DevTools and check the console for errors

Or use tools like /browser to interact with your app.

Tip 48: Automate with Hooks Use PreToolUse and PostToolUse hooks:

# ~/.opencode/hooks.yaml
PostToolUse:
  Edit:
    - npm run lint:fix
    - git add {{file}}

Tip 49: Explore the Plugin Ecosystem Check for community plugins:

/plugins list

Install useful ones:

/plugins install opencode-plugin-jest

Tip 50: Context is King Remember: Opencode's power comes from context. The more relevant information you provide:

  • Project structure
  • Coding standards
  • Architecture decisions
  • Business requirements
  • Error messages

The better the results you'll get.

Conclusion

These 50 tips represent patterns I've developed over months of daily use. Start with the Foundations, incorporate the Daily Workflow tips, and gradually adopt the Power User and Advanced techniques as you get comfortable.

Key Takeaway: Opencode is a force multiplier for experienced developers. It won't replace your expertise, but it will help you apply it faster and more consistently.

What's your favorite Opencode tip? Let me know in the comments or reach out on LinkedIn.

Quick Reference Card

Essential Commands:
/init          - Analyze codebase
/clear         - Reset context
/compact       - Condense conversation
/tokens        - Check usage
/model         - Switch model
/dry-run       - Preview changes
/help          - Show help

Keyboard Shortcuts:
Ctrl+C         - Interrupt
Ctrl+D         - Exit
Tab            - Autocomplete
Up/Down        - History

Best Practices:
✓ Commit before major changes
✓ Review diffs before committing  
✓ Use /dry-run for risky ops
✓ Define done criteria upfront
✓ Keep AGENTS.md updated

Happy coding! 🚀