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
@@ -1,7 +1,7 @@
|
|||||||
# m3ta-nixpkgs Knowledge Base
|
# m3ta-nixpkgs Knowledge Base
|
||||||
|
|
||||||
**Generated:** 2025-12-30
|
**Generated:** 2026-01-13
|
||||||
**Commit:** c5e1610
|
**Commit:** 366af12
|
||||||
**Branch:** master
|
**Branch:** master
|
||||||
|
|
||||||
## OVERVIEW
|
## OVERVIEW
|
||||||
|
|||||||
@@ -40,11 +40,14 @@ nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps
|
|||||||
|
|
||||||
| Package | Description |
|
| Package | Description |
|
||||||
| ------------------ | ------------------------------------- |
|
| ------------------ | ------------------------------------- |
|
||||||
|
| `beads` | Lightweight memory system for AI coding agents with graph-based issue tracking |
|
||||||
| `code2prompt` | Convert code to prompts |
|
| `code2prompt` | Convert code to prompts |
|
||||||
| `hyprpaper-random` | Random wallpaper setter for Hyprpaper |
|
| `hyprpaper-random` | Random wallpaper setter for Hyprpaper |
|
||||||
| `launch-webapp` | Launch web applications |
|
| `launch-webapp` | Launch web applications |
|
||||||
| `mem0` | AI memory assistant with vector storage |
|
| `mem0` | AI memory assistant with vector storage |
|
||||||
| `msty-studio` | Msty Studio application |
|
| `msty-studio` | Msty Studio application |
|
||||||
|
| `n8n` | Free and source-available fair-code licensed workflow automation tool |
|
||||||
|
| `opencode` | AI coding agent built for the terminal |
|
||||||
| `pomodoro-timer` | Pomodoro timer utility |
|
| `pomodoro-timer` | Pomodoro timer utility |
|
||||||
| `rofi-project-opener` | Rofi-based project launcher |
|
| `rofi-project-opener` | Rofi-based project launcher |
|
||||||
| `stt-ptt` | Push to Talk Speech to Text |
|
| `stt-ptt` | Push to Talk Speech to Text |
|
||||||
|
|||||||
@@ -28,11 +28,14 @@ Step-by-step guides for common tasks:
|
|||||||
|
|
||||||
Documentation for all custom packages:
|
Documentation for all custom packages:
|
||||||
|
|
||||||
|
- [beads](./packages/beads.md) - Lightweight memory system for AI coding agents with graph-based issue tracking
|
||||||
- [code2prompt](./packages/code2prompt.md) - Convert code to prompts
|
- [code2prompt](./packages/code2prompt.md) - Convert code to prompts
|
||||||
- [hyprpaper-random](./packages/hyprpaper-random.md) - Random wallpaper setter for Hyprpaper
|
- [hyprpaper-random](./packages/hyprpaper-random.md) - Random wallpaper setter for Hyprpaper
|
||||||
- [launch-webapp](./packages/launch-webapp.md) - Launch web applications
|
- [launch-webapp](./packages/launch-webapp.md) - Launch web applications
|
||||||
- [mem0](./packages/mem0.md) - AI memory assistant with vector storage
|
- [mem0](./packages/mem0.md) - AI memory assistant with vector storage
|
||||||
- [msty-studio](./packages/msty-studio.md) - Msty Studio application
|
- [msty-studio](./packages/msty-studio.md) - Msty Studio application
|
||||||
|
- [n8n](./packages/n8n.md) - Free and source-available fair-code licensed workflow automation tool
|
||||||
|
- [opencode](./packages/opencode.md) - AI coding agent built for terminal
|
||||||
- [pomodoro-timer](./packages/pomodoro-timer.md) - Pomodoro timer utility
|
- [pomodoro-timer](./packages/pomodoro-timer.md) - Pomodoro timer utility
|
||||||
- [rofi-project-opener](./packages/rofi-project-opener.md) - Rofi-based project launcher with custom args
|
- [rofi-project-opener](./packages/rofi-project-opener.md) - Rofi-based project launcher with custom args
|
||||||
- [stt-ptt](./packages/stt-ptt.md) - Push to Talk Speech to Text using Whisper
|
- [stt-ptt](./packages/stt-ptt.md) - Push to Talk Speech to Text using Whisper
|
||||||
|
|||||||
220
docs/packages/beads.md
Normal file
220
docs/packages/beads.md
Normal file
@@ -0,0 +1,220 @@
|
|||||||
|
# beads
|
||||||
|
|
||||||
|
Lightweight memory system for AI coding agents with graph-based issue tracking.
|
||||||
|
|
||||||
|
## Description
|
||||||
|
|
||||||
|
beads is a command-line tool designed to provide persistent memory and issue tracking for AI coding agents. It features a graph-based system for managing issues, dependencies, and discovered work across development sessions.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- 🧠 **Persistent Memory**: Store and retrieve context across AI sessions
|
||||||
|
- 📊 **Graph-Based Issue Tracking**: Manage issues with dependency relationships
|
||||||
|
- 🔄 **Discovered Work**: Track work discovered during development
|
||||||
|
- 🎯 **Multi-Session Continuity**: Resume work from previous sessions
|
||||||
|
- 📝 **Git Integration**: Seamless integration with git workflows
|
||||||
|
- 🐚 **Shell Completions**: Bash, Fish, and Zsh completions included
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Via Overlay
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{pkgs, ...}: {
|
||||||
|
environment.systemPackages = with pkgs; [
|
||||||
|
beads
|
||||||
|
];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Direct Reference
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{pkgs, ...}: {
|
||||||
|
environment.systemPackages = with pkgs; [
|
||||||
|
inputs.m3ta-nixpkgs.packages.${pkgs.system}.beads
|
||||||
|
];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run Directly
|
||||||
|
|
||||||
|
```bash
|
||||||
|
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#beads
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Basic Commands
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Show available issues ready to work on
|
||||||
|
bd ready
|
||||||
|
|
||||||
|
# Create a new issue
|
||||||
|
bd create "Fix authentication bug" --type bug --priority 2
|
||||||
|
|
||||||
|
# Show issue details
|
||||||
|
bd show beads-123
|
||||||
|
|
||||||
|
# Update issue status
|
||||||
|
bd update beads-123 --status in_progress
|
||||||
|
|
||||||
|
# Close completed issues
|
||||||
|
bd close beads-123
|
||||||
|
|
||||||
|
# Sync with git remote
|
||||||
|
bd sync
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue Types
|
||||||
|
|
||||||
|
- `task`: General tasks
|
||||||
|
- `bug`: Bug fixes
|
||||||
|
- `feature`: New features
|
||||||
|
- `epic`: Large-scale initiatives
|
||||||
|
|
||||||
|
### Priority Levels
|
||||||
|
|
||||||
|
- `0` (P0): Critical
|
||||||
|
- `1` (P1): High
|
||||||
|
- `2` (P2): Medium
|
||||||
|
- `3` (P3): Low
|
||||||
|
- `4` (P4): Backlog
|
||||||
|
|
||||||
|
### Dependency Management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Add dependency (beads-123 depends on beads-456)
|
||||||
|
bd dep add beads-123 beads-456
|
||||||
|
|
||||||
|
# Show blocked issues
|
||||||
|
bd blocked
|
||||||
|
|
||||||
|
# Show what blocks an issue
|
||||||
|
bd show beads-123 --blocked-by
|
||||||
|
```
|
||||||
|
|
||||||
|
## Advanced Usage
|
||||||
|
|
||||||
|
### Finding Work
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Show ready tasks (no blockers)
|
||||||
|
bd ready
|
||||||
|
|
||||||
|
# Show all open issues
|
||||||
|
bd list --status open
|
||||||
|
|
||||||
|
# Show in-progress work
|
||||||
|
bd list --status in_progress
|
||||||
|
```
|
||||||
|
|
||||||
|
### Assignment
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Assign issue to yourself
|
||||||
|
bd update beads-123 --assignee username
|
||||||
|
|
||||||
|
# Create assigned issue
|
||||||
|
bd create "Review PR" --assignee reviewer
|
||||||
|
```
|
||||||
|
|
||||||
|
### Bulk Operations
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Close multiple issues at once
|
||||||
|
bd close beads-123 beads-456 beads-789
|
||||||
|
|
||||||
|
# Close with reason
|
||||||
|
bd close beads-123 --reason "Completed in v1.2.0"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Hooks
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install git hooks for automatic sync
|
||||||
|
bd hooks install
|
||||||
|
|
||||||
|
# Remove hooks
|
||||||
|
bd hooks uninstall
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
- `BEADS_DATA_DIR`: Custom directory for beads data (default: `.beads/`)
|
||||||
|
- `BEADS_CONFIG`: Custom configuration file path
|
||||||
|
- `BEADS_EDITOR`: Default editor for editing issues
|
||||||
|
|
||||||
|
### Git Integration
|
||||||
|
|
||||||
|
beads integrates with git for version-controlled issue tracking:
|
||||||
|
|
||||||
|
- Automatic sync before commits (via hooks)
|
||||||
|
- Issue references in commit messages
|
||||||
|
- Branch name tracking
|
||||||
|
- Git-aware issue states
|
||||||
|
|
||||||
|
## Workflow Integration
|
||||||
|
|
||||||
|
### Typical Development Workflow
|
||||||
|
|
||||||
|
1. **Start session**: `bd prime` or check `bd ready`
|
||||||
|
2. **Claim work**: `bd update beads-123 --status in_progress`
|
||||||
|
3. **Work on task**: Implement changes
|
||||||
|
4. **Discover new work**: `bd create "Discovered subtask"` as needed
|
||||||
|
5. **Complete task**: `bd close beads-123`
|
||||||
|
6. **Sync**: `bd sync` (automatic via hooks)
|
||||||
|
|
||||||
|
### Team Collaboration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create issue and assign
|
||||||
|
bd create "Implement feature X" --assignee dev1
|
||||||
|
|
||||||
|
# Review assigned work
|
||||||
|
bd list --assignee yourname
|
||||||
|
|
||||||
|
# Close with review notes
|
||||||
|
bd close beads-123 --reason "Reviewed and approved"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Shell Completions
|
||||||
|
|
||||||
|
beads provides shell completions for bash, fish, and zsh:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Bash completions are auto-loaded
|
||||||
|
source <(bd completion bash)
|
||||||
|
|
||||||
|
# Fish completions
|
||||||
|
bd completion fish | source
|
||||||
|
|
||||||
|
# Zsh completions
|
||||||
|
bd completion zsh > ~/.zfunc/_bd
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build Information
|
||||||
|
|
||||||
|
- **Version**: 0.47.1
|
||||||
|
- **Language**: Go
|
||||||
|
- **License**: MIT
|
||||||
|
- **Source**: [GitHub](https://github.com/steveyegge/beads)
|
||||||
|
|
||||||
|
## Platform Support
|
||||||
|
|
||||||
|
- Linux
|
||||||
|
- macOS
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Tests are disabled in the Nix package due to git worktree operations that fail in the sandbox
|
||||||
|
- Security tests on Darwin are skipped due to `/etc/passwd` unavailability in sandbox
|
||||||
|
- Shell completions are installed for platforms that can execute the build target
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
|
||||||
|
- [Quick Start](../QUICKSTART.md) - Getting started guide
|
||||||
310
docs/packages/n8n.md
Normal file
310
docs/packages/n8n.md
Normal file
@@ -0,0 +1,310 @@
|
|||||||
|
# n8n
|
||||||
|
|
||||||
|
Free and source-available fair-code licensed workflow automation tool. Easily automate tasks across different services.
|
||||||
|
|
||||||
|
## Description
|
||||||
|
|
||||||
|
n8n (pronounced "n-eight-n") is a workflow automation tool that helps you connect different services and automate tasks without writing code. It features a visual node-based editor for creating workflows with hundreds of integrations.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- 🎨 **Visual Workflow Editor**: Drag-and-drop interface for creating workflows
|
||||||
|
- 🔗 **Hundreds of Integrations**: Connect to popular services (Slack, GitHub, Google, etc.)
|
||||||
|
- 🔄 **Webhook Support**: Trigger workflows via HTTP requests
|
||||||
|
- 📝 **Code Node**: Execute JavaScript/TypeScript code within workflows
|
||||||
|
- 🚀 **Cloud & Self-Hosted**: Use n8n Cloud or self-host on your own infrastructure
|
||||||
|
- 📊 **Data Transformation**: Map and transform data between services
|
||||||
|
- ⏰ **Scheduling**: Run workflows on schedules (cron-like)
|
||||||
|
- 🔒 **Security**: Credential management and secure data handling
|
||||||
|
- 🎯 **Fair-Code License**: Source available with usage restrictions for commercial use
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Via Overlay
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{pkgs, ...}: {
|
||||||
|
environment.systemPackages = with pkgs; [
|
||||||
|
n8n
|
||||||
|
];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Direct Reference
|
||||||
|
|
||||||
|
```nix
|
||||||
|
{pkgs, ...}: {
|
||||||
|
environment.systemPackages = with pkgs; [
|
||||||
|
inputs.m3ta-nixpkgs.packages.${pkgs.system}.n8n
|
||||||
|
];
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Run Directly
|
||||||
|
|
||||||
|
```bash
|
||||||
|
nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#n8n
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### Basic Usage
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start n8n (default configuration)
|
||||||
|
n8n start
|
||||||
|
|
||||||
|
# Start with custom configuration file
|
||||||
|
n8n start --config /path/to/config
|
||||||
|
|
||||||
|
# Run in worker mode (for production with queue)
|
||||||
|
n8n worker
|
||||||
|
|
||||||
|
# Execute a workflow from file
|
||||||
|
n8n execute /path/to/workflow.json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Development Mode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start with tunnel (external access)
|
||||||
|
n8n start --tunnel
|
||||||
|
|
||||||
|
# Disable telemetry
|
||||||
|
n8n start --no-telemetry
|
||||||
|
|
||||||
|
# Specify workflow directory
|
||||||
|
n8n start --workflows /path/to/workflows
|
||||||
|
|
||||||
|
# Enable/disable features
|
||||||
|
n8n start --enable-editor
|
||||||
|
n8n start --disable-metrics
|
||||||
|
```
|
||||||
|
|
||||||
|
### Workflow Management
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Export workflow to file
|
||||||
|
n8n export:workflow --id=123 --output=workflow.json
|
||||||
|
|
||||||
|
# Import workflow from file
|
||||||
|
n8n import:workflow --input=workflow.json
|
||||||
|
|
||||||
|
# Execute workflow
|
||||||
|
n8n execute:workflow --id=123
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
### Environment Variables
|
||||||
|
|
||||||
|
- `N8N_BASIC_AUTH_ACTIVE`: Enable basic authentication (default: false)
|
||||||
|
- `N8N_BASIC_AUTH_USER`: Basic auth username
|
||||||
|
- `N8N_BASIC_AUTH_PASSWORD`: Basic auth password
|
||||||
|
- `N8N_ENCRYPTION_KEY`: Encryption key for credentials
|
||||||
|
- `N8N_HOST`: Host URL for web UI (default: localhost)
|
||||||
|
- `N8N_PORT`: Port for web UI (default: 5678)
|
||||||
|
- `N8N_PROTOCOL`: Protocol (http or https)
|
||||||
|
- `N8N_PATH`: Path to mount n8n (default: /)
|
||||||
|
- `N8N_EDITOR_BASE_URL`: Base URL for editor
|
||||||
|
- `N8N_WEBHOOK_URL`: URL for webhook endpoints
|
||||||
|
- `N8N_TIMEZONE`: Timezone for execution (default: UTC)
|
||||||
|
- `N8N_LOG_LEVEL`: Logging level (output, warn, error, verbose)
|
||||||
|
- `N8N_LOG_OUTPUT`: Log output destination (console, file)
|
||||||
|
- `N8N_METRICS`: Enable metrics collection (default: true)
|
||||||
|
- `DB_TYPE`: Database type (sqlite3db, postgresdb, mysqldb)
|
||||||
|
- `DB_SQLITE_VACUUM_ON_STARTUP`: Vacuum SQLite on startup
|
||||||
|
|
||||||
|
### Database Configuration
|
||||||
|
|
||||||
|
By default, n8n uses SQLite for simplicity. For production, use PostgreSQL or MySQL:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# PostgreSQL
|
||||||
|
export DB_TYPE=postgresdb
|
||||||
|
export DB_POSTGRESDB_HOST=localhost
|
||||||
|
export DB_POSTGRESDB_PORT=5432
|
||||||
|
export DB_POSTGRESDB_DATABASE=n8n
|
||||||
|
export DB_POSTGRESDB_USER=n8n
|
||||||
|
export DB_POSTGRESDB_PASSWORD=yourpassword
|
||||||
|
|
||||||
|
# MySQL/MariaDB
|
||||||
|
export DB_TYPE=mysqldb
|
||||||
|
export DB_MYSQLDB_HOST=localhost
|
||||||
|
export DB_MYSQLDB_PORT=3306
|
||||||
|
export DB_MYSQLDB_DATABASE=n8n
|
||||||
|
export DB_MYSQLDB_USER=n8n
|
||||||
|
export DB_MYSQLDB_PASSWORD=yourpassword
|
||||||
|
```
|
||||||
|
|
||||||
|
### Security
|
||||||
|
|
||||||
|
Set up encryption for credentials:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Generate encryption key
|
||||||
|
export N8N_ENCRYPTION_KEY=$(openssl rand -base64 32)
|
||||||
|
|
||||||
|
# Use in production
|
||||||
|
export N8N_ENCRYPTION_KEY="your-32-char-encryption-key"
|
||||||
|
```
|
||||||
|
|
||||||
|
## NixOS Module
|
||||||
|
|
||||||
|
For NixOS, use the n8n module from nixpkgs for a complete service configuration:
|
||||||
|
|
||||||
|
```nix
|
||||||
|
services.n8n = {
|
||||||
|
enable = true;
|
||||||
|
settings = {
|
||||||
|
host = "0.0.0.0";
|
||||||
|
port = 5678;
|
||||||
|
timezone = "UTC";
|
||||||
|
};
|
||||||
|
environment = {
|
||||||
|
N8N_ENCRYPTION_KEY = "your-encryption-key";
|
||||||
|
DB_TYPE = "postgresdb";
|
||||||
|
DB_POSTGRESDB_HOST = "/var/run/postgresql";
|
||||||
|
DB_POSTGRESDB_DATABASE = "n8n";
|
||||||
|
};
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
## Use Cases
|
||||||
|
|
||||||
|
### Webhook Automation
|
||||||
|
|
||||||
|
Trigger workflows via HTTP requests:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start n8n with tunnel for public URL
|
||||||
|
n8n start --tunnel
|
||||||
|
|
||||||
|
# Create webhook workflow in UI
|
||||||
|
# Workflow receives data from external service
|
||||||
|
# Process and send to another service
|
||||||
|
```
|
||||||
|
|
||||||
|
### Scheduled Tasks
|
||||||
|
|
||||||
|
Run tasks on a schedule:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// In workflow editor, use Schedule Trigger
|
||||||
|
// Set cron expression: "0 9 * * *" (daily at 9 AM)
|
||||||
|
// Connect to nodes that perform tasks
|
||||||
|
```
|
||||||
|
|
||||||
|
### Data Sync Between Services
|
||||||
|
|
||||||
|
Keep data synchronized:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create workflow with:
|
||||||
|
# 1. Webhook trigger (service A)
|
||||||
|
# 2. Data transformation node
|
||||||
|
# 3. HTTP request node (service B)
|
||||||
|
# 4. Response back to service A
|
||||||
|
```
|
||||||
|
|
||||||
|
### Automated Reporting
|
||||||
|
|
||||||
|
Generate and send reports:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Workflow steps:
|
||||||
|
// 1. Schedule trigger (daily/weekly)
|
||||||
|
// 2. Database query node
|
||||||
|
// 3. Data formatting
|
||||||
|
// 4. Email or Slack notification
|
||||||
|
```
|
||||||
|
|
||||||
|
## Integration Examples
|
||||||
|
|
||||||
|
### Slack Integration
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Create Slack notification workflow
|
||||||
|
// 1. Trigger (webhook or schedule)
|
||||||
|
// 2. Process data
|
||||||
|
// 3. Send message to Slack channel
|
||||||
|
```
|
||||||
|
|
||||||
|
### GitHub Integration
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// GitHub repository automation
|
||||||
|
// 1. GitHub webhook trigger (push, PR, issue)
|
||||||
|
// 2. Conditional logic
|
||||||
|
// 3. Actions (create issue, comment, etc.)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Email Automation
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// Email processing workflow
|
||||||
|
// 1. Email trigger (IMAP)
|
||||||
|
// 2. Parse email content
|
||||||
|
// 3. Process data
|
||||||
|
// 4. Send response or forward
|
||||||
|
```
|
||||||
|
|
||||||
|
## Performance Optimization
|
||||||
|
|
||||||
|
### Production Tips
|
||||||
|
|
||||||
|
- Use PostgreSQL or MySQL instead of SQLite
|
||||||
|
- Enable queue mode with Redis
|
||||||
|
- Use worker nodes for scaling
|
||||||
|
- Configure proper resource limits
|
||||||
|
- Set up load balancing for web UI
|
||||||
|
|
||||||
|
### Queue Mode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start main n8n process
|
||||||
|
export QUEUE_BULL_REDIS_HOST=redis-server
|
||||||
|
export QUEUE_BULL_REDIS_PORT=6379
|
||||||
|
n8n start
|
||||||
|
|
||||||
|
# Start worker processes
|
||||||
|
n8n worker
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build Information
|
||||||
|
|
||||||
|
- **Version**: 2.4.1
|
||||||
|
- **Language**: TypeScript/JavaScript (Node.js)
|
||||||
|
- **Package Manager**: pnpm
|
||||||
|
- **License**: Sustainable Use (Fair-Code)
|
||||||
|
- **Source**: [GitHub](https://github.com/n8n-io/n8n)
|
||||||
|
|
||||||
|
## Dependencies
|
||||||
|
|
||||||
|
- `nodejs` - JavaScript runtime
|
||||||
|
- `pnpm` - Package manager (build-time)
|
||||||
|
- `python3` - Required for SQLite bindings
|
||||||
|
- `node-gyp` - Node.js native addon build tool
|
||||||
|
- `libkrb5` - Kerberos authentication
|
||||||
|
- `libmongocrypt` - MongoDB encryption
|
||||||
|
- `libpq` - PostgreSQL client library
|
||||||
|
|
||||||
|
## Platform Support
|
||||||
|
|
||||||
|
- Linux
|
||||||
|
- macOS
|
||||||
|
|
||||||
|
## Notes
|
||||||
|
|
||||||
|
- Package has ~80,000 files, so stripping and ELF patching are disabled for performance
|
||||||
|
- SQLite3 bindings are rebuilt during build phase
|
||||||
|
- TypeScript files and source maps are removed in preInstall phase
|
||||||
|
- Non-deterministic files (.turbo, .modules.yaml, types) are removed
|
||||||
|
- Node modules are pruned to production dependencies only
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [Adding Packages](../guides/adding-packages.md) - How to add new packages
|
||||||
|
- [Quick Start](../QUICKSTART.md) - Getting started guide
|
||||||
|
- [n8n Documentation](https://docs.n8n.io) - Official documentation
|
||||||
|
- [n8n Community](https://community.n8n.io) - Community forum
|
||||||
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