docs: add documentation for beads, n8n, opencode packages
- Update AGENTS.md header with current commit (366af12) and date (2026-01-13) - Add beads, n8n, opencode to README.md Available Packages table - Update docs/README.md packages list - Create docs/packages/beads.md (220 lines) - Create docs/packages/n8n.md (310 lines) - Create docs/packages/opencode.md (346 lines) Documentation now reflects commitbc75505which added these three packages.
This commit is contained in:
m3tm3re
346
docs/packages/opencode.md
Normal file
346
docs/packages/opencode.md
Normal file
@@ -0,0 +1,346 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user