# 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

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

### Direct Reference

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

### Run Directly

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

## Usage

### Basic Usage

```bash
# 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

```bash
# 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

```bash
# 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`:

```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:

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

## Advanced Usage

### Code Refactoring

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# Keep VS Code running for editing
code .

# Use OpenCode for AI assistance in another terminal
opencode

# Switch between them as needed
```

### Vim/Neovim

```bash
# 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

```bash
# 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

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

### Writing Tests

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

### Debugging

```bash
# 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](https://github.com/anomalyco/opencode)

## 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](../guides/adding-packages.md) - How to add new packages
- [Quick Start](../QUICKSTART.md) - Getting started guide
- [OpenCode Documentation](https://github.com/anomalyco/opencode) - Official repository and documentation