Skip to main content
Common questions about OpenCode, installation, usage, and troubleshooting.

​
General

OpenCode is an AI coding agent CLI tool that helps developers with software engineering tasks. It’s a powerful command-line interface that uses large language models to assist with coding, debugging, refactoring, and more.OpenCode can:
  • Write and edit code across multiple files
  • Debug and fix issues
  • Refactor and optimize code
  • Generate documentation
  • Answer questions about your codebase
OpenCode is designed as a CLI-first tool that gives you full control over your development workflow. Unlike IDE-specific tools, OpenCode:
  • Works in any terminal environment
  • Supports multiple AI providers (OpenAI, Anthropic, Google, and more)
  • Offers a plugin system for extensibility
  • Provides both TUI (Terminal UI) and web interfaces
  • Has an active open-source community building plugins and integrations
OpenCode itself is free and open-source software licensed under the MIT license. However, you’ll need API access to AI providers (like OpenAI or Anthropic) which have their own pricing.Some community plugins provide alternative authentication methods that can reduce or eliminate API costs by using existing subscriptions.
OpenCode supports multiple AI providers including:
  • OpenAI (GPT-4, GPT-3.5)
  • Anthropic (Claude)
  • Google (Gemini)
  • And many more through community plugins
To add support for a new provider, contribute to models.dev.

​
Installation & Setup

The easiest way to install OpenCode is via npm:
npm install -g opencode
Or using your preferred package manager:
# Using Yarn
yarn global add opencode

# Using pnpm
pnpm add -g opencode
For development, see the Contributing guide for instructions on building from source.
OpenCode will prompt you to configure your API keys when you first run it. You can also manually configure them:
opencode config
Your configuration is stored securely in your home directory.
OpenCode requires:
  • Node.js 18 or higher (for npm installation)
  • Bun 1.3+ (for development)
  • A terminal emulator with modern features
  • API access to at least one supported AI provider
OpenCode runs on macOS, Linux, and Windows (via WSL).

​
Usage

Navigate to your project directory and run:
opencode
This will start the TUI (Terminal User Interface) where you can interact with the AI agent. You can also use specific commands:
# Start web interface
opencode web

# Start headless server
opencode serve

# Run in a specific directory
opencode /path/to/project
OpenCode supports various commands:
  • opencode - Start TUI in current directory
  • opencode web - Start web interface
  • opencode serve - Start headless API server
  • opencode attach <url> - Attach to existing server
  • opencode --help - Show all available commands
Within the TUI, you can use slash commands like /help, /clear, /exit, and more.
Yes! OpenCode is designed to work alongside your IDE. Some community projects provide deeper integration:Check out the Ecosystem page for more integrations.
OpenCode has a plugin system that allows you to extend functionality. To install plugins, you typically:
  1. Install the plugin package via npm
  2. Configure it in your OpenCode settings
Some plugins may have additional setup steps. Check the plugin’s documentation for specific instructions.See the Ecosystem page for available plugins.

​
Troubleshooting

If OpenCode appears to hang:
  1. Check if the AI provider’s API is responsive
  2. Verify your API key is valid and has sufficient credits
  3. Try restarting OpenCode
  4. Check for any error messages in the terminal
If you’re using shell commands that require interactive input, consider using the opencode-shell-strategy plugin to prevent TTY-related hangs.
Rate limit errors mean you’re making too many requests to the AI provider’s API. To resolve:
  1. Wait for the rate limit to reset (usually a few minutes)
  2. Consider upgrading your API plan for higher limits
  3. Use the opencode-dynamic-context-pruning plugin to optimize token usage
To help the AI better understand your codebase:
  1. Provide clear, specific instructions
  2. Reference specific files or functions
  3. Use the opencode-type-inject plugin for better type awareness
  4. Break down complex tasks into smaller steps
To report a bug:
  1. Check if the issue already exists in GitHub Issues
  2. Use the Bug Report template when creating a new issue
  3. Include:
    • OpenCode version (opencode --version)
    • Your operating system
    • Steps to reproduce
    • Expected vs. actual behavior
    • Any error messages
See the Contributing guide for more details.
If you need help:

​
Development & Contributing

We welcome contributions! See the Contributing guide for detailed instructions.The most common contributions are:
  • Bug fixes
  • Documentation improvements
  • New LSP/formatter support
  • Provider integrations
  • Performance improvements
To build a plugin:
  1. Use the opencode plugin template as a starting point
  2. Follow the plugin API documentation
  3. Test your plugin locally with bun dev
  4. Submit your plugin to the Ecosystem
Check out existing plugins on the Ecosystem page for inspiration.
OpenCode is open-source and available on GitHub:github.com/anomalyco/opencodeThe repository includes:
  • Core OpenCode logic
  • TUI and web interfaces
  • Desktop app
  • Plugin system
  • Documentation
The development workflow is:
  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Test locally with bun dev
  5. Open a PR following the Contributing guidelines
See the Contributing guide for detailed setup instructions.

​
Community

Join the OpenCode community:
Check out the Ecosystem page for:
  • Plugins that extend OpenCode
  • Projects built on OpenCode
  • Pre-configured agents
  • Integrations with other tools
You can also browse awesome-opencode for a curated list.
Yes! If you’ve built something with OpenCode:
  1. Fork the OpenCode repository
  2. Add your project to the ecosystem documentation
  3. Submit a PR with a brief description
See the Contributing guide for PR guidelines.

​
Still have questions?

Join our Discord

Chat with the community and get help from maintainers and other users.