Mastering OpenCode: The Ultimate Guide to Local-First AI Coding

OpenCode is more than just another AI coding assistant. It's a local-first, autonomous coding agent designed to act as a true pair programmer. Unlike simple autocomplete tools, OpenCode understands your entire repository, plans complex refactors, and executes terminal commands—all while keeping your code secure on your machine.

In this ultimate guide, we'll cover everything you need to go from zero to mastering OpenCode's most advanced features.

1. Installation: Your Gateway to Autonomous Coding

Getting started is designed to be frictionless. OpenCode runs natively in your terminal, which means it works wherever you do—whether that's VS Code, JetBrains, or a standalone shell.

Quick Install (Mac, Linux, Windows WSL)

The fastest way to install is via our official script:

curl -fsSL "https://opencode.ai/install" | bash

Alternative: npm Package

If you prefer managing tools via Node.js, you can install OpenCode globally:

npm install -g opencode-ai

Once installed, simply type opencode to verify the installation and launch the UI.

2. Models & Providers: Limitless Choice (BYOK)

One of OpenCode's core philosophies is Model Neutrality. We don't lock you into a single "black box" model. Instead, we let you bring your own keys (BYOK) or connect to your existing AI subscriptions.

Authenticating

To connect your preferred model provider, run:

opencode auth login

This interactive command will guide you through signing in with:

• Anthropic (Claude 4.5 Sonnet, Opus)
• OpenAI (GPT-5, o1-preview)
• Google (Gemini 3 Pro, 1.5 Pro)
• Models.dev (Access to 75+ open source & hosted models)

Managing Models

You can switch models on the fly depending on the task. Use a faster model for simple fixes and a stronger reasoning model for architecture planning.

# List all available models
opencode models

# Refresh model list after adding a new provider
opencode models --refresh

Going Local with Ollama

For ultimate privacy and offline capability, OpenCode supports local models via Ollama. Point OpenCode to your local instance to code without any data leaving your network—perfect for enterprise environments or working on sensitive IP.

3. Core Workflow: Interactive vs. One-Off

OpenCode adapts to how you want to work.

The Interactive Session

The most powerful way to use OpenCode is an Interactive Session. Run opencode in your project root to enter a persistent chat environment.

• Context Aware: The agent reads your file structure and LSP signals.
• Multi-Turn: You can refine the plan, ask for corrections, and iterate.
• Tool Use: The agent can read files, edit code, and run tests autonomously.

The One-Off Command

For quick tasks where you don't need a full conversation, use opencode run. This is perfect for "fire and forget" instructions.

# Summarize the repo and suggest improvements
opencode run "Analyze this codebase and propose a refactoring plan for performance"

# Quick fix
opencode run "Fix the type error in src/utils/helper.ts"

4. Agents & Permissions: Safety First

Giving an AI access to your terminal and file system requires trust. OpenCode solves this with a robust Permissions System and specialized Agents.

Granular Permissions

You control exactly what the agent can do. Set permissions globally or per-session:

• Allow: The agent executes commands and edits files automatically.
• Ask: The agent must request your approval for every action (default for sensitive operations).
• Deny: The agent is strictly forbidden from performing the action.

specialized Agents: Plan vs. Build

To minimize risk, we recommend a split-workflow:

1. Plan Agent: Use a "Planner" model to analyze code and draft a strategy. Keep this agent in Read-Only or Ask mode.
2. Build Agent: Once the plan is approved, switch to a "Builder" agent with Allow permissions to execute the changes rapidly.

5. Advanced Features: Multi-Session & Sharing

Real-world engineering isn't linear. OpenCode supports advanced workflows to match your multitasking needs.

Parallel Sessions

Don't let a long-running refactor block your quick bug fix. OpenCode allows you to run multiple parallel sessions.

• Session A: "Refactor the authentication middleware."
• Session B: "Fix the CSS z-index bug on the homepage."

These sessions operate independently, ensuring context doesn't bleed between tasks.

Shareable Links

Need to show a teammate what the AI did? Use /share to generate a rigorous, read-only log of your session.

• Collaboration: Send a link to a PR reviewer so they can see why changes were made.
• Documentation: Save successful sessions as "recipes" for future tasks.
• Privacy Control: Sharing is off by default. You explicitly control what gets published.

Conclusion

OpenCode is built for developers who want the power of AI without sacrificing control or privacy. By mastering these workflows—choosing the right models, leveraging granular permissions, and utilizing parallel sessions—you can transform OpenCode from a simple helper into a tireless autonomous partner.

Ready to start? Install OpenCode now and experience the future of local-first engineering.