Skip to main content

How to Install and Use OpenCode: A Complete Guide

BlogsOpenCodeAITerminalCLIAbout 8 min

How to Install and Use OpenCode: A Complete Guide

OpenCode is an open-source AI coding agent that brings the power of artificial intelligence directly to your terminal. Unlike traditional AI coding tools that live in editors or browsers, OpenCode provides a terminal-based interface, desktop app, and IDE extension—all designed to make you more productive as a developer. This comprehensive guide will walk you through everything you need to know to install, configure, and use OpenCode effectively.

What is OpenCode?

OpenCode is an AI-powered coding assistant that helps you:

  • Write code faster with intelligent code generation and completion
  • Debug efficiently by analyzing errors and suggesting fixes
  • Understand codebases through natural language queries
  • Add features with automated planning and implementation
  • Review code with AI-powered analysis and suggestions
  • Automate workflows using AI agents and custom tools

It supports multiple LLM providers including Anthropic, OpenAI, Google, and others, giving you the flexibility to choose the models that work best for your needs.

System Requirements

Prerequisites

Before installing OpenCode, ensure you have:

  1. Modern Terminal Emulator (for TUI usage):

  2. Node.js (for npm/bun/pnpm/yarn installation):

    • Node.js v18 or higher recommended

  3. API Keys for LLM providers:

    • Anthropic API key (for Claude models)
    • OpenAI API key (for GPT models)
    • Or keys from other supported providers

Installation Methods

The quickest way to install OpenCode is using the official install script:

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

This method works on macOS, Linux, and Windows (with Git Bash or WSL).

Method 2: Using Node.js Package Managers

Using npm:

npm install -g opencode-ai

Using Bun:

bun install -g opencode-ai

Using pnpm:

pnpm install -g opencode-ai

Using Yarn:

yarn global add opencode-ai

Method 3: Using Homebrew (macOS & Linux)

brew install opencode

Method 4: Using Paru (Arch Linux)

paru -S opencode-bin

Method 5: Windows-Specific Installations

Using Chocolatey:

choco install opencode

Using Scoop:

scoop bucket add extras
scoop install extras/opencode

Using Mise:

mise use -g github:sst/opencode

Method 6: Docker

For containerized usage:

docker run -it --rm ghcr.io/sst/opencode

Method 7: Download Binary

You can download the pre-compiled binary directly from the GitHub Releases page.

Verify Installation

After installation, verify it's working:

opencode --version

You should see the version number displayed.

Initial Configuration

OpenCode Zen is a curated list of models tested and verified by the OpenCode team. It's the easiest way to get started.

  1. Start OpenCode:
cd /path/to/your/project
opencode
  1. Run the connect command in the TUI:
/connect

  1. Select "opencode" from the provider list

  2. Visit the authentication URL: opencode.ai/auth

  3. Sign in and add billing details (or use free credits if available)

  4. Copy your API key and paste it into the terminal when prompted

Connecting to Other Providers

You can also connect OpenCode to other LLM providers:

Using the /connect Command:

/connect

Select your preferred provider (Anthropic, OpenAI, Google, etc.) and follow the authentication flow.

Using CLI Authentication:

opencode auth login

This will guide you through configuring API keys for any provider available on Models.dev.

List Configured Providers:

opencode auth list

or the short version:

opencode auth ls

Logout from a Provider:

opencode auth logout

Setting Up Project Context

After configuring a provider, initialize OpenCode for your project:

  1. Navigate to your project:
cd /path/to/your/project
  1. Start OpenCode:
opencode
  1. Run the init command:
/init

This analyzes your project structure and creates an AGENTS.md file in the project root. This file helps OpenCode understand your coding patterns, frameworks, and project architecture.

Tip: Commit the AGENTS.md file to Git. This helps maintain consistency across your team and improves OpenCode's understanding of your project over time.

Using the Terminal User Interface (TUI)

OpenCode's TUI provides an interactive experience in your terminal.

Starting the TUI

Simply run:

opencode

Or with optional flags:

# Continue the last session
opencode --continue

# Continue a specific session
opencode --session <session-id>

# Start with a prompt
opencode --prompt "Explain this codebase"

# Use a specific model
opencode --model anthropic/claude-sonnet-4-5

# Use a specific agent
opencode --agent plan

Basic TUI Navigation

  • Scroll: Use mouse wheel or arrow keys
  • Switch modes: Press Tab to toggle between Plan mode and Build mode
  • Run commands: Type / to access command palette
  • Search files: Use @ to fuzzy search for files in your project
  • Exit: Press Ctrl+C or use /exit

Asking Questions

You can ask OpenCode questions about your codebase:

How is authentication handled in @packages/functions/src/api/index.ts

Use the @ symbol to reference specific files. OpenCode will analyze those files and provide detailed explanations.

Adding Features

OpenCode excels at adding new features through its two-mode workflow:

Step 1: Plan Mode

  1. Switch to Plan mode by pressing Tab
  2. Describe what you want:
When a user deletes a note, we'd like to flag it as deleted in the database.
Then create a screen that shows all the recently deleted notes.
From this screen, the user can undelete a note or permanently delete it.
  1. Review the suggested plan
  2. Iterate with feedback:
We'd like to design this new screen using a design I've used before.
[Image #1] Take a look at this image and use it as a reference.

Tip: You can drag and drop images into the terminal. OpenCode will scan and analyze them.

Step 2: Build Mode

  1. Switch to Build mode by pressing Tab again
  2. Approve the implementation:
Sounds good! Go ahead and make the changes.

OpenCode will then implement the feature, creating and modifying files as needed.

Making Direct Changes

For straightforward changes, you can skip the plan phase:

We need to add authentication to the /settings route.
Take a look at how this is handled in the /notes route
in @packages/functions/src/notes.ts and implement the same logic
in @packages/functions/src/settings.ts

Undoing and Redoing Changes

Made a mistake? Use the undo command:

/undo

This reverts the last set of changes and lets you refine your prompt.

To redo undone changes:

/redo

You can run /undo multiple times to revert multiple changes.

CLI Commands

OpenCode provides a powerful CLI for programmatic access and automation.

Running Direct Prompts

Execute OpenCode non-interactively:

opencode run "Explain how closures work in JavaScript"

Useful for scripting, automation, or quick answers without launching the TUI.

Managing Models

List all available models:

opencode models

Filter by provider:

opencode models anthropic

Refresh the model cache (useful when new models are added):

opencode models --refresh

Show verbose model information including costs:

opencode models --verbose

Starting a Headless Server

Start an HTTP server for API access:

opencode serve

With custom port:

opencode serve --port 3000

This is useful for integrating OpenCode into web applications or for faster response times in scripts (avoiding MCP server cold boot).

Attaching to a Server

In one terminal, start the server:

opencode serve

In another terminal, attach to it for faster execution:

opencode run --attach http://localhost:4096 "Explain async/await in JavaScript"

Managing Agents

Create a new custom agent:

opencode agent create

This guides you through creating an agent with custom system prompts and tool configurations.

GitHub Integration

Install the GitHub agent for repository automation:

opencode github install

This sets up GitHub Actions workflows for automated code review and issue handling.

Upgrading OpenCode

Upgrade to the latest version:

opencode upgrade

Or to a specific version:

opencode upgrade v0.1.48

Specify the installation method if needed:

opencode upgrade --method brew

Configuration

OpenCode supports flexible configuration through JSON config files.

Configuration Locations

Config files are merged together (not replaced), allowing you to have global, project-specific, and custom configs.

  1. Global Config: ~/.config/opencode/opencode.json

    • Use for themes, providers, keybinds, and general settings

  2. Project Config: opencode.json in project root

    • Use for project-specific providers, agents, or settings
    • Safe to commit to Git

  3. Custom Config Path: Set via OPENCODE_CONFIG environment variable

  4. Custom Config Directory: Set via OPENCODE_CONFIG_DIR environment variable

Basic Configuration Example

Create a config file with this structure:

{
  "$schema": "https://opencode.ai/config.json",
  
  // Theme selection
  "theme": "opencode",
  
  // Main model to use
  "model": "anthropic/claude-sonnet-4-5",
  
  // Smaller model for lightweight tasks
  "small_model": "anthropic/claude-haiku-4-5",
  
  // Auto-update settings
  "autoupdate": true
}

Configuring Providers

Configure API keys directly in config:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    },
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}"
      }
    }
  }
}

Using environment variables is recommended for security. Use {env:VARIABLE_NAME} syntax.

Using File References

You can also reference files for sensitive data:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

Custom Commands

Define custom commands for repetitive tasks:

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run full test suite with coverage report and show any failures.\nFocus on failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

Use custom commands in TUI by typing /test or /component MyComponent.

Custom Agents

Create specialized agents:

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Permissions Configuration

Control what OpenCode can do without asking:

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

This requires user approval for edit and bash operations.

Code Formatters

Configure formatters to automatically format code:

{
  "$schema": "https://opencode.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": false
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

TUI Settings

Customize the terminal interface:

{
  "$schema": "https://opencode.ai/config.json",
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": {
      "enabled": true
    }
  }
}

Advanced Features

Sharing Conversations

Share your conversations with your team:

/share

This creates a shareable link and copies it to your clipboard. Conversations are not shared by default.

Configure sharing behavior:

{
  "share": "manual"  // "manual", "auto", or "disabled"
}

MCP Servers

Model Context Protocol (MCP) servers extend OpenCode's capabilities:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  }
}

Instructions and Rules

Provide project-specific instructions:

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "CONTRIBUTING.md",
    "docs/guidelines.md",
    ".cursor/rules/*.md"
  ]
}

OpenCode will use these files to understand your project's coding standards and conventions.

Environment Variables

Configure OpenCode using environment variables:

# Automatically share sessions
export OPENCODE_AUTO_SHARE=true

# Path to custom config
export OPENCODE_CONFIG=/path/to/config.json

# Path to config directory
export OPENCODE_CONFIG_DIR=/path/to/config-dir

# Disable auto-update
export OPENCODE_DISABLE_AUTOUPDATE=true

# Disable default plugins
export OPENCODE_DISABLE_DEFAULT_PLUGINS=true

# Enable experimental models
export OPENCODE_ENABLE_EXPERIMENTAL_MODELS=true

# Enable Exa web search
export OPENCODE_ENABLE_EXA=true

Experimental Features

Enable experimental features:

export OPENCODE_EXPERIMENTAL=true

Specific experimental features:

# Enable icon discovery
export OPENCODE_EXPERIMENTAL_ICON_DISCOVERY=true

# Disable copy on select in TUI
export OPENCODE_EXPERIMENTAL_DISABLE_COPY_ON_SELECT=true

# Set max output length for bash commands
export OPENCODE_EXPERIMENTAL_BASH_MAX_OUTPUT_LENGTH=10000

# Set default timeout for bash commands (ms)
export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=30000

Best Practices

Effective Prompting

  1. Be specific: Provide clear, detailed instructions
  2. Use context: Reference files with @ for better understanding
  3. Provide examples: Show examples of what you want
  4. Break it down: Complex tasks work better in steps

Working with Large Projects

  1. Use /init: Let OpenCode understand your project structure
  2. Reference specific files: Use @ to limit context
  3. Use Plan mode: Review plans before implementation
  4. Incremental changes: Make small, manageable changes

Cost Optimization

  1. Use smaller models: Configure small_model for lightweight tasks
  2. Plan before build: Review in Plan mode to reduce iterations
  3. Custom commands: Define efficient workflows for common tasks
  4. Monitor usage: Check provider dashboards for usage stats

Security Best Practices

  1. Never commit API keys: Use environment variables
  2. Use permissions: Configure permission to require approval for sensitive operations
  3. Review changes: Always review OpenCode's suggested changes
  4. Use separate keys: Create API keys specifically for OpenCode with appropriate limits

Troubleshooting

Installation Issues

Problem: Command not found after installation

Solution:

  • Verify installation: which opencode
  • Check PATH: echo $PATH
  • Try full path: ~/.local/bin/opencode
  • Reinstall using alternative method

Authentication Issues

Problem: API key not recognized

Solution:

  • Verify key is correct: opencode auth list
  • Check environment variables: echo $ANTHROPIC_API_KEY
  • Re-authenticate: opencode auth login

Performance Issues

Problem: Slow response times

Solution:

  • Use opencode serve for faster execution
  • Switch to a faster model
  • Use smaller context windows
  • Disable unused tools in config

TUI Issues

Problem: Terminal display issues

Solution:

  • Use a modern terminal emulator (WezTerm, Alacritty, etc.)
  • Check terminal supports 24-bit colors
  • Try different theme
  • Disable scroll acceleration if experiencing issues

Model Issues

Problem: Model not found

Solution:

  • Refresh model list: opencode models --refresh
  • Check provider is configured: opencode auth list
  • Verify model name format: provider/model
  • Check provider has the model available

Integrating OpenCode into Your Workflow

Daily Development

  1. Morning: Run /init to sync with latest code changes
  2. Feature work: Use Plan mode to design, then Build mode to implement
  3. Debugging: Ask questions about errors with file references
  4. Code review: Use custom code reviewer agent
  5. Documentation: Generate docs using custom commands

Team Collaboration

  1. Share configs: Commit opencode.json and AGENTS.md to Git
  2. Share conversations: Use /share to discuss implementations
  3. Custom commands: Define team-specific commands in project config
  4. Consistent agents: Use shared agent definitions for consistency

CI/CD Integration

  1. GitHub agent: Install for automated PR reviews
  2. Testing: Use custom test commands in CI
  3. Code quality: Configure formatters and permissions

Conclusion

OpenCode represents a new paradigm in AI-assisted development by bringing powerful AI capabilities directly to your terminal. With its flexible configuration options, support for multiple LLM providers, and intuitive TUI interface, it's designed to enhance your productivity without disrupting your existing workflow.

Key Takeaways:

  • Install using the install script or your preferred package manager
  • Configure API keys through /connect or opencode auth login
  • Initialize projects with /init for better context understanding
  • Use Plan mode for complex features, Build mode for direct changes
  • Customize with config files, commands, and agents
  • Leverage CLI commands for automation and scripting
  • Practice good security habits with API keys and permissions

Next Steps:

Ready to supercharge your development workflow?
Check out LightNode's AI-optimized hosting solutions for deploying AI-powered applications with dedicated GPU instances and scalable infrastructure.

OpenCode is open source and constantly evolving. Contribute to the project, report issues, or share your experience to help make it even better for everyone. Happy coding!

Save Big on Cheap VPS Hosting