opencode-beads 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Josh Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# opencode-beads
+
+[Beads](https://github.com/steveyegge/beads) issue tracker integration for [OpenCode](https://opencode.ai).
+
+## Installation
+
+Install the beads CLI:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+```
+
+See the [beads installation guide](https://github.com/steveyegge/beads/blob/main/docs/INSTALLING.md) for alternative methods (Homebrew, Windows, AUR, etc.).
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-beads"]
+}
+```
+
+## Features
+
+- **Context injection** - Automatically runs `bd prime` on session start and after compaction, keeping your agent aware of current issues
+- **Commands** - All beads operations available as `/bd-*` commands
+- **Task agent** - Autonomous issue completion via `beads-task-agent` subagent
+
+## Usage
+
+This plugin brings beads into OpenCode. For learning how to use beads itself - workflows, commands, best practices - see the [beads documentation](https://github.com/steveyegge/beads).
+
+The plugin automatically injects beads context on session start and after compaction, so your agent stays oriented.
+
+## Commands
+
+Commands are available as `/bd-*` and mirror the `bd` CLI. See the [beads documentation](https://github.com/steveyegge/beads) for the full command reference.
+
+## Agent
+
+### beads-task-agent
+
+A subagent for autonomous issue completion. Designed to work through issues independently, updating status and handling dependencies.
+
+## License
+
+opencode-beads is licensed under the MIT license. See the [`LICENSE`](LICENSE) file for more information.
+
+---
+
+opencode-beads is not built by, or affiliated with, the OpenCode team.
+
+OpenCode is ©2025 Anomaly.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "opencode-beads",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A plugin for OpenCode that provides integration with the beads issue tracker.",
+  "author": "Josh Thomas <josh@joshthomas.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joshuadavidthomas/opencode-beads"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "beads",
+    "agent",
+    "ai"
+  ],
+  "main": "src/plugin.ts",
+  "files": ["src", "vendor", "README.md"],
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.0.143",
+    "@opencode-ai/sdk": "^1.0.143",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^22.0.0",
+    "typescript": "~5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,145 @@
+/**
+ * OpenCode Beads Plugin
+ *
+ * Integrates the beads issue tracker with OpenCode.
+ *
+ * Features:
+ * - Context injection via `bd prime` on session start and after compaction
+ * - Commands parsed from beads command definitions
+ * - Task agent for autonomous issue completion
+ */
+
+import type { Plugin, PluginInput } from "@opencode-ai/plugin";
+import { CLI_GUIDANCE, loadAgent, loadCommands } from "./vendor";
+
+type OpencodeClient = PluginInput["client"];
+
+/**
+ * Get the current model/agent context for a session by querying messages.
+ *
+ * Mirrors OpenCode's internal lastModel() logic to find the most recent
+ * user message. Used during event handling when we don't have direct access
+ * to the current user message's context.
+ */
+async function getSessionContext(
+  client: OpencodeClient,
+  sessionID: string
+): Promise<
+  { model?: { providerID: string; modelID: string }; agent?: string } | undefined
+> {
+  try {
+    const response = await client.session.messages({
+      path: { id: sessionID },
+      query: { limit: 50 },
+    });
+
+    if (response.data) {
+      for (const msg of response.data) {
+        if (msg.info.role === "user" && "model" in msg.info && msg.info.model) {
+          return { model: msg.info.model, agent: msg.info.agent };
+        }
+      }
+    }
+  } catch {
+    // On error, return undefined (let opencode use its default)
+  }
+
+  return undefined;
+}
+
+/**
+ * Inject beads context into a session.
+ *
+ * Runs `bd prime` and injects the output along with CLI guidance.
+ * Silently skips if bd is not installed or not initialized.
+ */
+async function injectBeadsContext(
+  client: OpencodeClient,
+  $: PluginInput["$"],
+  sessionID: string,
+  context?: { model?: { providerID: string; modelID: string }; agent?: string }
+): Promise<void> {
+  try {
+    const primeOutput = await $`bd prime`.text();
+
+    if (!primeOutput || primeOutput.trim() === "") {
+      return;
+    }
+
+    const beadsContext = `<beads-context>
+${primeOutput.trim()}
+</beads-context>
+
+${CLI_GUIDANCE}`;
+
+    // Inject content via noReply + synthetic
+    // Must pass model and agent to prevent mode/model switching
+    await client.session.prompt({
+      path: { id: sessionID },
+      body: {
+        noReply: true,
+        model: context?.model,
+        agent: context?.agent,
+        parts: [{ type: "text", text: beadsContext, synthetic: true }],
+      },
+    });
+  } catch {
+    // Silent skip if bd prime fails (not installed or not initialized)
+  }
+}
+
+
+export const BeadsPlugin: Plugin = async ({ client, $ }) => {
+  const [commands, agents] = await Promise.all([loadCommands(), loadAgent()]);
+
+  const injectedSessions = new Set<string>();
+
+  return {
+    "chat.message": async (_input, output) => {
+      const sessionID = output.message.sessionID;
+
+      // Skip if already injected this session
+      if (injectedSessions.has(sessionID)) return;
+
+      // Check if session already has messages (handles plugin reload/reconnection)
+      try {
+        const existing = await client.session.messages({
+          path: { id: sessionID },
+          query: { limit: 1 },
+        });
+
+        if (existing.data && existing.data.length > 0) {
+          injectedSessions.add(sessionID);
+          return;
+        }
+      } catch {
+        // On error, proceed with injection
+      }
+
+      injectedSessions.add(sessionID);
+
+      // Use output.message which has the resolved model/agent values
+      // This ensures our injected noReply message has identical model/agent
+      // to the real user message, preventing mode/model switching
+      await injectBeadsContext(client, $, sessionID, {
+        model: output.message.model,
+        agent: output.message.agent,
+      });
+    },
+
+    event: async ({ event }) => {
+      if (event.type === "session.compacted") {
+        const sessionID = event.properties.sessionID;
+        const context = await getSessionContext(client, sessionID);
+        await injectBeadsContext(client, $, sessionID, context);
+      }
+    },
+
+    config: async (config) => {
+      config.command = { ...config.command, ...commands };
+      config.agent = { ...config.agent, ...agents };
+    },
+  };
+};
+
+export default BeadsPlugin;

package/src/vendor.ts

@@ -0,0 +1,155 @@
+/**
+ * Vendor file loaders for beads plugin.
+ *
+ * The vendor directory contains beads command definitions and agent prompts
+ * synced from the upstream beads repository via scripts/sync-beads.sh.
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { Config } from "@opencode-ai/sdk";
+
+function getVendorDir(): string {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  return path.join(__dirname, "..", "vendor");
+}
+
+interface ParsedMarkdown {
+  frontmatter: Record<string, string | undefined>;
+  body: string;
+}
+
+function parseMarkdownWithFrontmatter(content: string): ParsedMarkdown | null {
+  const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+  const match = content.match(frontmatterRegex);
+
+  if (!match) {
+    return null;
+  }
+
+  const frontmatterStr = match[1];
+  const body = match[2];
+
+  if (frontmatterStr === undefined || body === undefined) {
+    return null;
+  }
+
+  const frontmatter: Record<string, string | undefined> = {};
+
+  for (const line of frontmatterStr.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex === -1) continue;
+
+    const key = trimmed.slice(0, colonIndex).trim();
+    let value = trimmed.slice(colonIndex + 1).trim();
+
+    // Handle quoted strings
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+
+    // Handle empty array syntax like []
+    if (value === "[]") {
+      value = "";
+    }
+
+    frontmatter[key] = value;
+  }
+
+  return { frontmatter, body: body.trim() };
+}
+
+async function readVendorFile(relativePath: string): Promise<string | null> {
+  try {
+    const fullPath = path.join(getVendorDir(), relativePath);
+    return await fs.readFile(fullPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+async function listVendorFiles(relativePath: string): Promise<string[]> {
+  try {
+    const fullPath = path.join(getVendorDir(), relativePath);
+    return await fs.readdir(fullPath);
+  } catch {
+    return [];
+  }
+}
+
+export const CLI_GUIDANCE = `<beads-cli-guidance>
+Beads MCP tools are not available. Use the \`bd\` CLI via bash instead:
+
+- \`init\` → \`bd init [prefix]\`
+- \`ready\` → \`bd ready --json\`
+- \`show\` → \`bd show <id> --json\`
+- \`create\` → \`bd create "title" -t bug|feature|task -p 0-4 --json\`
+- \`update\` → \`bd update <id> --status in_progress --json\`
+- \`close\` → \`bd close <id> --reason "message" --json\`
+- \`reopen\` → \`bd reopen <id> --json\`
+- \`dep\` → \`bd dep add <from> <to> --type blocks|discovered-from --json\`
+- \`list\` → \`bd list --status open --json\`
+- \`blocked\` → \`bd blocked --json\`
+- \`stats\` → \`bd stats --json\`
+- \`sync\` → \`bd sync\`
+
+MCP tools map directly to bd CLI commands. If a tool is not listed above, try \`bd <tool> --help\`.
+
+Always use \`--json\` flag for structured output.
+</beads-cli-guidance>`;
+
+export async function loadAgent(): Promise<Config["agent"]> {
+  const content = await readVendorFile("agents/task-agent.md");
+  if (!content) return {};
+
+  const parsed = parseMarkdownWithFrontmatter(content);
+  if (!parsed) return {};
+
+  const description =
+    parsed.frontmatter.description ?? "Beads task completion agent";
+
+  return {
+    "beads-task-agent": {
+      description,
+      prompt: CLI_GUIDANCE + "\n" + parsed.body,
+      mode: "subagent",
+    },
+  };
+}
+
+export async function loadCommands(): Promise<Config["command"]> {
+  const files = await listVendorFiles("commands");
+  const commands: Config["command"] = {};
+
+  for (const file of files) {
+    if (!file.endsWith(".md")) continue;
+
+    const content = await readVendorFile(`commands/${file}`);
+    if (!content) continue;
+
+    const parsed = parseMarkdownWithFrontmatter(content);
+    if (!parsed) continue;
+
+    const name = `bd-${file.replace(".md", "")}`;
+
+    const argHint = parsed.frontmatter["argument-hint"];
+    const baseDescription = parsed.frontmatter.description ?? name;
+    const description = argHint
+      ? `${baseDescription} (${argHint})`
+      : baseDescription;
+
+    commands[name] = {
+      description,
+      template: parsed.body,
+    };
+  }
+
+  return commands;
+}

package/vendor/agents/task-agent.md

@@ -0,0 +1,60 @@
+---
+description: Autonomous agent that finds and completes ready tasks
+---
+
+You are a task-completion agent for beads. Your goal is to find ready work and complete it autonomously.
+
+# Agent Workflow
+
+1. **Find Ready Work**
+   - Use the `ready` MCP tool to get unblocked tasks
+   - Prefer higher priority tasks (P0 > P1 > P2 > P3 > P4)
+   - If no ready tasks, report completion
+
+2. **Claim the Task**
+   - Use the `show` tool to get full task details
+   - Use the `update` tool to set status to `in_progress`
+   - Report what you're working on
+
+3. **Execute the Task**
+   - Read the task description carefully
+   - Use available tools to complete the work
+   - Follow best practices from project documentation
+   - Run tests if applicable
+
+4. **Track Discoveries**
+   - If you find bugs, TODOs, or related work:
+     - Use `create` tool to file new issues
+     - Use `dep` tool with `discovered-from` to link them
+   - This maintains context for future work
+
+5. **Complete the Task**
+   - Verify the work is done correctly
+   - Use `close` tool with a clear completion message
+   - Report what was accomplished
+
+6. **Continue**
+   - Check for newly unblocked work with `ready`
+   - Repeat the cycle
+
+# Important Guidelines
+
+- Always update issue status (`in_progress` when starting, close when done)
+- Link discovered work with `discovered-from` dependencies
+- Don't close issues unless work is actually complete
+- If blocked, use `update` to set status to `blocked` and explain why
+- Communicate clearly about progress and blockers
+
+# Available Tools
+
+Via beads MCP server:
+- `ready` - Find unblocked tasks
+- `show` - Get task details
+- `update` - Update task status/fields
+- `create` - Create new issues
+- `dep` - Manage dependencies
+- `close` - Complete tasks
+- `blocked` - Check blocked issues
+- `stats` - View project stats
+
+You are autonomous but should communicate your progress clearly. Start by finding ready work!

package/vendor/commands/blocked.md

@@ -0,0 +1,15 @@
+---
+description: Show blocked issues
+argument-hint: []
+---
+
+Show all issues that are blocked by dependencies.
+
+Use `bd blocked` to see which issues have blockers preventing them from being worked on. This is the inverse of `bd ready` - it shows what's NOT ready.
+
+Blocked issues have one or more dependencies with type "blocks" that are still open. Once all blocking dependencies are closed, the issue becomes ready and will appear in `bd ready`.
+
+Useful for:
+- Understanding why work is stuck
+- Identifying critical path items
+- Planning dependency resolution

package/vendor/commands/close.md

@@ -0,0 +1,18 @@
+---
+description: Close a completed issue
+argument-hint: [issue-id] [reason]
+---
+
+Close a beads issue that's been completed.
+
+If arguments are provided:
+- $1: Issue ID
+- $2+: Completion reason (optional)
+
+If the issue ID is missing, ask for it. Optionally ask for a reason describing what was done.
+
+Use the beads MCP `close` tool to close the issue. Show confirmation with the issue details.
+
+After closing, suggest checking for:
+- Dependent issues that might now be unblocked (use `ready` tool)
+- New work discovered during this task (use `create` tool with `discovered-from` link)

package/vendor/commands/comments.md

@@ -0,0 +1,28 @@
+---
+description: View or manage comments on an issue
+argument-hint: [issue-id]
+---
+
+View or add comments to a beads issue.
+
+## View Comments
+
+To view all comments on an issue:
+- $1: Issue ID (e.g., bd-123)
+
+Use the beads CLI `bd comments <issue-id>` to list all comments. Show them to the user with timestamps and authors.
+
+## Add Comment
+
+To add a comment:
+- $1: "add"
+- $2: Issue ID
+- $3: Comment text (or use -f flag for file input)
+
+Use `bd comments add <issue-id> "comment text"` to add a comment. Confirm the comment was added successfully.
+
+Comments are useful for:
+- Progress updates during work
+- Design notes or technical decisions
+- Links to related resources
+- Questions or blockers

package/vendor/commands/compact.md

@@ -0,0 +1,31 @@
+---
+description: Compact old closed issues using semantic summarization
+argument-hint: [--all] [--id issue-id] [--dry-run]
+---
+
+Reduce database size by summarizing closed issues no longer actively referenced.
+
+## Compaction Tiers
+
+- **Tier 1**: Semantic compression (30+ days closed, ~70% size reduction)
+- **Tier 2**: Ultra compression (90+ days closed, ~95% size reduction)
+
+## Usage
+
+- **Preview candidates**: `bd compact --dry-run`
+- **Compact all eligible**: `bd compact --all`
+- **Compact specific issue**: `bd compact --id bd-42`
+- **Force compact**: `bd compact --id bd-42 --force` (bypass age checks)
+- **View statistics**: `bd compact --stats`
+
+## Options
+
+- **--tier**: Choose compaction tier (1 or 2, default: 1)
+- **--workers**: Parallel workers (default: 5)
+- **--batch-size**: Issues per batch (default: 10)
+
+## Important
+
+This is **permanent graceful decay** - original content is discarded. Use `bd restore <id>` to view full history from git if needed.
+
+Useful for long-running projects to keep database size manageable.

package/vendor/commands/create.md

@@ -0,0 +1,19 @@
+---
+description: Create a new issue interactively
+argument-hint: [title] [type] [priority]
+---
+
+Create a new beads issue. If arguments are provided:
+- $1: Issue title
+- $2: Issue type (bug, feature, task, epic, chore)
+- $3: Priority (0-4, where 0=critical, 4=backlog)
+
+If arguments are missing, ask the user for:
+1. Issue title (required)
+2. Issue type (default: task)
+3. Priority (default: 2)
+4. Description (optional)
+
+Use the beads MCP `create` tool to create the issue. Show the created issue ID and details to the user.
+
+Optionally ask if this issue should be linked to another issue (discovered-from, blocks, parent-child, related).

package/vendor/commands/daemon.md

@@ -0,0 +1,58 @@
+---
+description: Manage background sync daemon
+argument-hint: [--start] [--stop] [--status] [--health]
+---
+
+Manage the per-project background daemon that handles database connections and syncs with git.
+
+## Per-Project Daemon (LSP Model)
+
+Each project runs its own daemon at `.beads/bd.sock` for complete database isolation.
+
+> On Windows this file stores the daemon's loopback TCP endpoint metadata—leave it in place so bd can reconnect.
+
+**Why per-project daemons?**
+- Complete database isolation between projects
+- No cross-project pollution or git worktree conflicts
+- Simpler mental model: one project = one database = one daemon
+- Follows LSP (Language Server Protocol) architecture
+
+**Note:** Global daemon support was removed in v0.16.0. The `--global` flag is no longer functional.
+
+## When to Use Daemon Mode
+
+**✅ You SHOULD use daemon mode if:**
+- Working in a team with git remote sync
+- Want automatic commit/push of issue changes
+- Need background auto-sync (5-second debounce)
+- Making frequent bd commands (performance benefit from connection pooling)
+
+**❌ You DON'T need daemon mode if:**
+- Solo developer with local-only tracking
+- Working in git worktrees (use --no-daemon to avoid conflicts)
+- Running one-off commands or scripts
+- Debugging database issues (direct mode is simpler)
+
+**Local-only users:** Direct mode (default without daemon) is perfectly fine. The daemon mainly helps with git sync automation. You can still use `bd sync` manually when needed.
+
+**Performance note:** For most operations, the daemon provides minimal performance benefit. The main value is automatic JSONL export (5s debounce) and optional git sync (--auto-commit, --auto-push).
+
+## Common Operations
+
+- **Start**: `bd daemon --start` (or auto-starts on first `bd` command)
+- **Stop**: `bd daemon --stop`
+- **Status**: `bd daemon --status`
+- **Health**: `bd daemon --health` - shows uptime, cache stats, performance metrics
+- **Metrics**: `bd daemon --metrics` - detailed operational telemetry
+
+## Sync Options
+
+- **--auto-commit**: Automatically commit JSONL changes
+- **--auto-push**: Automatically push commits to remote
+- **--interval**: Sync check interval (default: 5m)
+
+The daemon provides:
+- Connection pooling and caching
+- Better performance for frequent operations
+- Automatic JSONL sync (5-second debounce)
+- Optional git sync