From 291e3a0744d4a0192654c8afdbe3d1636c9c0890 Mon Sep 17 00:00:00 2001 From: m3tm3re Date: Sat, 7 Mar 2026 10:46:06 +0100 Subject: [PATCH] docs: update docs for removed packages (opencode, beads) - Fix broken beads reference in pkgs/default.nix - Convert opencode.md to deprecation notice with llm-agents.nix link - Convert beads.md to removal notice - Remove beads, opencode, openspec from README.md packages table - Remove beads, opencode from docs/README.md packages list --- README.md | 3 - docs/README.md | 2 - docs/packages/beads.md | 225 ++---------------------- docs/packages/opencode.md | 347 +++----------------------------------- pkgs/default.nix | 1 - 5 files changed, 33 insertions(+), 545 deletions(-) diff --git a/README.md b/README.md index 4e39219..725c8e5 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,6 @@ nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps | Package | Description | | ------------------ | ------------------------------------- | -| `beads` | Lightweight memory system for AI coding agents with graph-based issue tracking | | `code2prompt` | Convert code to prompts | | `hyprpaper-random` | Random wallpaper setter for Hyprpaper | | `launch-webapp` | Launch web applications | @@ -48,9 +47,7 @@ nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#zellij-ps | `msty-studio` | Msty Studio application | | `n8n` | Free and source-available fair-code licensed workflow automation tool | | `notesmd-cli` | Obsidian CLI (Community) - Interact with Obsidian in the terminal | -| `opencode` | AI coding agent built for the terminal | | `opencode-desktop` | OpenCode Desktop App with Wayland support (includes workaround for upstream issue #11755) | -| `openspec` | Spec-driven development (SDD) for AI coding assistants | | `pomodoro-timer` | Pomodoro timer utility | | `rofi-project-opener` | Rofi-based project launcher | | `sidecar` | Companion tool for CLI agents with diffs, file trees, and task management | diff --git a/docs/README.md b/docs/README.md index 61c8b26..824e2a7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -28,7 +28,6 @@ Step-by-step guides for common tasks: 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 - [hyprpaper-random](./packages/hyprpaper-random.md) - Random wallpaper setter for Hyprpaper - [launch-webapp](./packages/launch-webapp.md) - Launch web applications @@ -36,7 +35,6 @@ Documentation for all custom packages: - [msty-studio](./packages/msty-studio.md) - Msty Studio application - [n8n](./packages/n8n.md) - Free and source-available fair-code licensed workflow automation tool - [notesmd-cli](./packages/notesmd-cli.md) - Obsidian CLI (Community) - Interact with Obsidian in the terminal -- [opencode](./packages/opencode.md) - AI coding agent built for terminal - [pomodoro-timer](./packages/pomodoro-timer.md) - Pomodoro timer utility - [rofi-project-opener](./packages/rofi-project-opener.md) - Rofi-based project launcher with custom args - [sidecar](./packages/sidecar.md) - Companion tool for CLI agents with diffs, file trees, and task management diff --git a/docs/packages/beads.md b/docs/packages/beads.md index 24e169b..349bae1 100644 --- a/docs/packages/beads.md +++ b/docs/packages/beads.md @@ -1,220 +1,23 @@ -# beads +# beads (Removed) -Lightweight memory system for AI coding agents with graph-based issue tracking. +> **Note**: The `beads` package has been removed from this repository. -## Description +## Why was it removed? -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. +The beads package was removed as it is no longer actively used. -## Features +## What was beads? -- 🧠 **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 +Beads was a lightweight memory system for AI coding agents with graph-based issue tracking. It provided: +- Persistent memory across AI sessions +- Graph-based issue tracking with dependencies +- Discovered work tracking +- Git integration -## 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 +If you need beads, you can still build it from source: ```bash -nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#beads +git clone https://github.com/steveyegge/beads +cd beads +go build ./cmd/bd ``` - -## 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 diff --git a/docs/packages/opencode.md b/docs/packages/opencode.md index 5ad3ab5..dc5fff8 100644 --- a/docs/packages/opencode.md +++ b/docs/packages/opencode.md @@ -1,346 +1,37 @@ -# opencode +# opencode (Deprecated) -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. +> **Note**: The `opencode` package has been removed from this repository. -## Description +## Why was it removed? -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. +OpenCode (CLI version) has been removed because there is now a well-maintained upstream repository for AI coding tools: -## Features +**[numtide/llm-agents.nix](https://github.com/numtide/llm-agents.nix)** -- 🤖 **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 +This repository provides Nix packages for various AI coding agents, including OpenCode and others, with active maintenance and updates. -## Installation +## What should I use instead? -### Via Overlay +Use the [llm-agents.nix](https://github.com/numtide/llm-agents.nix) flake directly: ```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" + inputs = { + llm-agents.url = "github:numtide/llm-agents.nix"; + }; + + outputs = { inputs, ... }: { + # Access packages via inputs.llm-agents.packages.${system} + }; } ``` -### 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 +Or run directly: ```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" +nix run github:numtide/llm-agents.nix#opencode ``` -### Bug Fixing +## What about opencode-desktop? -```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 +The `opencode-desktop` package remains available in this repository as it includes a Wayland support workaround for [upstream issue #11755](https://github.com/opencode-ai/opencode/issues/11755). Once this issue is resolved upstream, `opencode-desktop` may also be removed in favor of the llm-agents.nix repository. diff --git a/pkgs/default.nix b/pkgs/default.nix index 9003652..4109419 100644 --- a/pkgs/default.nix +++ b/pkgs/default.nix @@ -5,7 +5,6 @@ }: { # Custom packages registry # Each package is defined in its own directory under pkgs/ - beads = pkgs.callPackage ./beads {}; sidecar = pkgs.callPackage ./sidecar {}; td = pkgs.callPackage ./td {}; code2prompt = pkgs.callPackage ./code2prompt {};