nixpkgs/docs/packages/opencode.md

opencode

AI coding agent built for the terminal that can build anything. Combines a TypeScript/JavaScript core with a Go-based TUI for an interactive AI coding experience.

Description

OpenCode is a terminal-based AI coding agent designed for power users. It provides a comprehensive development environment with AI assistance, code generation, refactoring, and project management capabilities. The tool features a sophisticated TUI (Terminal User Interface) built with Go, while the core functionality is implemented in TypeScript/JavaScript.

Features

• 🤖 AI-Powered Coding: Generate, refactor, and optimize code with AI assistance
• 🖥️ Modern TUI: Beautiful terminal interface built with Go
• 🔍 Code Understanding: Parse and understand existing codebases
• 🌳 Tree-Sitter Integration: Accurate syntax highlighting and code structure analysis
• 📁 Project Management: Navigate and manage projects efficiently
• 🧠 Multi-LLM Support: Works with various language models (OpenAI, Anthropic, etc.)
• 📝 Code Generation: Create new files and features from natural language
• 🔄 Refactoring: Intelligent code refactoring with AI
• 🐛 Bug Detection: Find and fix bugs automatically
• 📚 Context Awareness: Maintains context across editing sessions
• 🎯 Task Orchestration: Break down and execute complex tasks
• 💾 Local Development: Runs entirely on your machine

Installation

Via Overlay

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    opencode
  ];
}

Direct Reference

{pkgs, ...}: {
  environment.systemPackages = with pkgs; [
    inputs.m3ta-nixpkgs.packages.${pkgs.system}.opencode
  ];
}

Run Directly

nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#opencode

Usage

Basic Usage

# Start OpenCode in current directory
opencode

# Open specific project
opencode /path/to/project

# Start with specific task description
opencode "Fix the login bug"

# Show help
opencode --help

# Show version
opencode --version

Interactive Commands

OpenCode provides an interactive TUI with various commands:

• Navigation: Arrow keys to move, Enter to select
• Search: / to search files, ? for help
• Edit: e to edit selected file
• Command Palette: Ctrl+p to access commands
• AI Chat: Ctrl+c to open AI chat
• Exit: q or Ctrl+d to quit

AI Chat Mode

# Start OpenCode
opencode

# Enter AI chat mode (Ctrl+c)
# Ask questions, request code changes, etc.
# Examples:
# - "Generate a REST API endpoint for user management"
# - "Refactor this function to use async/await"
# - "Find and fix potential memory leaks"
# - "Add unit tests for this module"

Task Management

# Ask OpenCode to work on a specific task
opencode "Implement authentication with JWT tokens"

# The agent will:
# 1. Understand the codebase
# 2. Plan the implementation
# 3. Generate necessary code
# 4. Make the changes
# 5. Verify the implementation

Configuration

Environment Variables

• OPENCODE_API_KEY: API key for LLM provider
• OPENCODE_MODEL: Default model to use (e.g., gpt-4, claude-3-opus)
• OPENCODE_PROVIDER: LLM provider (openai, anthropic, etc.)
• OPENCODE_MAX_TOKENS: Maximum tokens for responses
• OPENCODE_TEMPERATURE: Sampling temperature (0-1)
• OPENCODE_CONFIG: Path to configuration file

Configuration File

Create ~/.opencode/config.json:

{
  "model": "gpt-4",
  "provider": "openai",
  "maxTokens": 4096,
  "temperature": 0.7,
  "systemPrompt": "You are a helpful coding assistant"
}

Project-Specific Config

Create .opencode.json in your project:

{
  "include": ["src/**/*.ts", "tests/**/*.ts"],
  "exclude": ["node_modules", "dist", "*.test.ts"],
  "systemPrompt": "You are a TypeScript expert"
}

Advanced Usage

Code Refactoring

# Ask for refactoring suggestions
opencode "Review and refactor src/utils.ts for better performance"

# Apply refactoring automatically
opencode "Optimize the database queries in src/db/*.ts"

Bug Fixing

# Describe the bug
opencode "Fix the race condition in the payment processing module"

# OpenCode will:
# 1. Analyze the code
# 2. Identify the issue
# 3. Propose and implement fixes
# 4. Verify the solution

Feature Implementation

# Request new features
opencode "Add support for OAuth2 authentication"

# Be specific about requirements
opencode "Create a REST API with these endpoints: GET /users, POST /users, PUT /users/:id, DELETE /users/:id"

Code Review

# Get code review
opencode "Review src/api/*.ts for security vulnerabilities"

# Check for best practices
opencode "Review the entire codebase and suggest improvements following SOLID principles"

Documentation Generation

# Generate documentation
opencode "Add JSDoc comments to all functions in src/utils.ts"

# Create README
opencode "Generate a comprehensive README.md for this project"

Integration with Editors

VS Code

OpenCode can work alongside your editor:

# Keep VS Code running for editing
code .

# Use OpenCode for AI assistance in another terminal
opencode

# Switch between them as needed

Vim/Neovim

# Use Vim/Neovim as your editor
vim src/main.ts

# Use OpenCode for complex tasks
opencode "Refactor the authentication module"

Use Cases

Learning New Codebases

# OpenCode will:
# 1. Analyze the code structure
# 2. Explain how components work
# 3. Answer questions about the code
opencode "Explain how this project handles user authentication"

Porting Code

# Port from one language to another
opencode "Port this Python function to TypeScript"

Writing Tests

# Generate unit tests
opencode "Add comprehensive unit tests for src/utils.ts with 100% coverage"

Debugging

# Get help with debugging
opencode "I'm getting a null pointer exception in src/api/users.ts. Help me debug it"

Keyboard Shortcuts

Global

• Ctrl+p - Open command palette
• Ctrl+c - Open AI chat
• Ctrl+s - Save current file
• Ctrl+q - Quit
• ? - Show help

Navigation

• j / k - Down / Up
• h / l - Left / Right
• gg - Go to top
• G - Go to bottom
• / - Search
• n - Next search result
• N - Previous search result

File Operations

• e - Edit file
• o - Open in external editor
• d - Delete file (with confirmation)
• y - Yank (copy)
• p - Paste

Build Information

• Version: 1.1.18
• Language: TypeScript/JavaScript (core), Go (TUI)
• Runtime: Bun
• License: MIT
• Source: GitHub

Dependencies

• bun - JavaScript runtime and package manager
• fzf - Fuzzy finder for file selection
• ripgrep - Fast text search
• models-dev - Model definitions and schemas

Platform Support

• Linux (aarch64, x86_64)
• macOS (aarch64, x86_64)

Notes

• Includes a patch to relax Bun version check (changed to warning instead of error)
• Shell completions are installed for supported platforms (excludes x86_64-darwin)
• Tree-sitter WASM files are patched to use absolute store paths
• JSON schema is generated and installed to $out/share/opencode/schema.json

Tips and Best Practices

Getting Started

1. Start Small: Begin with simple tasks to get familiar with the interface
2. Provide Context: Give clear, detailed descriptions of what you want
3. Iterate: Work with OpenCode iteratively, refining requests as needed
4. Review Changes: Always review AI-generated code before committing

Effective Prompts

• Be specific about requirements
• Provide examples of expected behavior
• Mention constraints or preferences
• Break complex tasks into smaller steps

Project Structure

• Keep your project well-organized
• Use consistent naming conventions
• Add clear comments to complex logic
• Maintain a clean git history

Related

• Adding Packages - How to add new packages
• Quick Start - Getting started guide
• OpenCode Documentation - Official repository and documentation