opencode-dashboard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gabor Zakhar
+
+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,329 @@
+# OpenCode Dashboard
+
+A real-time browser-based Kanban board that visualizes agent activity in [OpenCode](https://opencode.ai). Watch beads (tasks) move through agent stages -- from ready to done -- as AI agents work on them. Columns are generated dynamically based on your configured agents.
+
+## Installation
+
+1. Add the plugin to your OpenCode config:
+
+```json
+// opencode.json
+{
+  "plugin": ["opencode-dashboard"]
+}
+```
+
+OpenCode will install the plugin automatically on next launch.
+
+2. Run the setup command to install slash commands and (optionally) agent definitions:
+
+```bash
+npx opencode-dashboard setup
+```
+
+This will prompt you to choose between global (`~/.config/opencode/`) or per-project (`.opencode/`) installation. It copies the `/dashboard-start`, `/dashboard-stop`, and `/dashboard-status` commands, plus the shipped agent definitions. Existing files are never overwritten.
+
+## Usage
+
+### Start the Dashboard
+
+Use the slash command in OpenCode:
+
+```
+/dashboard-start
+```
+
+Or use the CLI directly:
+
+```bash
+npx opencode-dashboard start
+```
+
+The dashboard will be available at `http://localhost:3333`.
+
+### Check Status
+
+```
+/dashboard-status
+```
+
+Or via CLI:
+
+```bash
+npx opencode-dashboard status
+```
+
+### Stop the Dashboard
+
+```
+/dashboard-stop
+```
+
+Or via CLI:
+
+```bash
+npx opencode-dashboard stop
+```
+
+### Custom Port
+
+```bash
+npx opencode-dashboard start --port 4000
+```
+
+Or set the `DASHBOARD_PORT` environment variable.
+
+## How It Works
+
+The dashboard has three components:
+
+```
+OpenCode Plugin (plugin/index.ts)
+       |
+       |  POST /api/plugin/event
+       v
+  Bun Server (server/index.ts)
+       |
+       |  SSE /api/events
+       v
+  React Dashboard (dist/)
+```
+
+1. **Plugin** -- An OpenCode plugin that hooks into agent lifecycle events, discovers configured agents, tracks bead state via `bd list --json`, and pushes structured events to the server. Registers custom tools (`dashboard_start`, `dashboard_stop`, `dashboard_status`, `dashboard_open`) for controlling the dashboard from within OpenCode.
+2. **Server** -- A Bun HTTP server that aggregates state from connected plugins, persists it to disk, serves the dashboard frontend, and broadcasts updates to browser clients via Server-Sent Events (SSE).
+3. **Dashboard** -- A React SPA that renders a dynamic Kanban board with real-time updates, animated card transitions, and connection resilience.
+
+### Kanban Columns
+
+Columns are generated dynamically based on your configured agents. Three fixed columns are always present:
+
+| Column | Description |
+|--------|-------------|
+| Ready | Open beads not yet claimed by an agent |
+| Done | Bead closed successfully |
+| Error | Bead blocked, failed, or abandoned |
+
+Agent columns appear between Ready and Done, one per discovered agent. For example, if you have `orchestrator`, `pipeline-builder`, `pipeline-reviewer`, and `pipeline-committer` agents configured, the board will show columns for each of them. Column colors are pulled from the agent's frontmatter `color` field when available.
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0
+- [OpenCode](https://opencode.ai) with plugin support
+- A project using [bd (beads)](https://github.com/anomalyco/beads) for issue tracking
+
+### Clone and Install
+
+```bash
+git clone https://github.com/GZakhar88/opencode-agents-dashboard.git
+cd opencode-agents-dashboard
+bun install
+```
+
+### Running Locally (Frontend + Server only)
+
+This starts the dashboard UI and server **without** the OpenCode plugin. Useful for working on the frontend or server code. No OpenCode or bd needed.
+
+```bash
+# Terminal 1: Start the Bun API server (port 3333)
+bun run server
+
+# Terminal 2: Start the Vite dev server with HMR (port 5173)
+bun run dev
+```
+
+Open `http://localhost:5173`. The Vite dev server proxies `/api/*` requests to the Bun server at `localhost:3333`. The board will show "No projects connected" until a plugin registers — you can test by sending events directly:
+
+```bash
+# Register a fake plugin
+curl -X POST http://localhost:3333/api/plugin/register \
+  -H 'Content-Type: application/json' \
+  -d '{"projectPath": "/tmp/test", "projectName": "test-project"}'
+# Returns: {"pluginId": "some-uuid"}
+
+# Push an event (use the pluginId from above)
+curl -X POST http://localhost:3333/api/plugin/event \
+  -H 'Content-Type: application/json' \
+  -d '{"pluginId": "PASTE_ID_HERE", "event": "bead:discovered", "data": {"bead": {"id": "test-1", "title": "Test bead", "status": "open", "priority": "medium"}}}'
+```
+
+### Running Locally (Full end-to-end with OpenCode)
+
+This connects the plugin to a live OpenCode session so you can test the full pipeline: plugin hooks -> server -> dashboard.
+
+**Step 1: Symlink the plugin into your project**
+
+From the project directory where you run OpenCode (not this repo):
+
+```bash
+# Create the plugins directory if it doesn't exist
+mkdir -p /path/to/your/project/.opencode/plugins
+
+# Symlink the plugin entry point
+ln -sf /path/to/opencode-agents-dashboard/plugin/index.ts \
+       /path/to/your/project/.opencode/plugins/dashboard.ts
+```
+
+OpenCode auto-loads all `.ts` files from `.opencode/plugins/` on startup. The symlink's relative imports resolve from the real file's location, so `../shared/types`, `../server/pid`, etc. all work.
+
+**Step 2: Install commands and agents**
+
+```bash
+# From this repo's directory
+bun run bin/cli.ts setup
+```
+
+Choose "project" to install into `/path/to/your/project/.opencode/`, or "global" for `~/.config/opencode/`. This copies the `/dashboard-start`, `/dashboard-stop`, `/dashboard-status` commands and agent definitions.
+
+**Step 3: Launch OpenCode and start the dashboard**
+
+```bash
+# In your project directory
+DASHBOARD_DEBUG=1 opencode
+```
+
+Then in the OpenCode TUI, type `/dashboard-start`. The plugin will spawn the Bun server and open the dashboard at `http://localhost:3333`.
+
+`DASHBOARD_DEBUG=1` enables verbose plugin logging to stderr — useful for seeing what the plugin is doing.
+
+**Step 4: (Optional) Run Vite dev server for frontend HMR**
+
+If you're working on the frontend and want hot-reload instead of the pre-built `dist/`:
+
+```bash
+# In this repo's directory
+bun run dev
+```
+
+Open `http://localhost:5173` instead of `:3333`. Vite proxies API calls to the running Bun server.
+
+**Cleanup**
+
+To disconnect the plugin from your project:
+
+```bash
+rm /path/to/your/project/.opencode/plugins/dashboard.ts
+```
+
+### Testing
+
+```bash
+bun test
+```
+
+| File | What it tests |
+|------|---------------|
+| `src/hooks/useBoardState.test.ts` | Board state reducer -- all 13 SSE event handlers |
+| `src/hooks/useEventSource.test.ts` | SSE connection, backoff, retry logic |
+| `src/lib/format.test.ts` | Formatting utilities (elapsed time, priority labels) |
+| `server/state.test.ts` | Server state manager (event processing, persistence) |
+| `server/routes.test.ts` | HTTP route handlers (register, event, heartbeat) |
+| `server/sse.test.ts` | SSE client management and broadcasting |
+| `server/diffBeadState.test.ts` | Bead snapshot diffing algorithm |
+
+### Building
+
+```bash
+bun run build        # Build the frontend (outputs to dist/)
+bun run build:check  # Run TypeScript type checking
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `DASHBOARD_PORT` | `3333` | Port for the dashboard server |
+| `DASHBOARD_DEBUG` | (unset) | Set to `1` to enable verbose plugin logging to stderr |
+
+## Project Structure
+
+```
+opencode-dashboard/
+├── agents/                     # Shipped agent definitions (optional install)
+│   ├── orchestrator.md
+│   ├── pipeline-builder.md
+│   ├── pipeline-refactor.md
+│   ├── pipeline-reviewer.md
+│   └── pipeline-committer.md
+├── commands/                   # Slash commands (installed via setup)
+│   ├── dashboard-start.md
+│   ├── dashboard-stop.md
+│   └── dashboard-status.md
+├── plugin/
+│   └── index.ts                # Main plugin entry (npm distribution)
+├── server/
+│   ├── index.ts                # Server entry point (Bun.serve)
+│   ├── routes.ts               # HTTP route handlers (7 endpoints)
+│   ├── sse.ts                  # SSE client management & broadcasting
+│   ├── state.ts                # State manager (events -> state, persistence)
+│   ├── pid.ts                  # PID file management
+│   └── PLUGIN_EVENTS.md        # Event reference documentation
+├── shared/
+│   └── types.ts                # Shared TypeScript types
+├── bin/
+│   └── cli.ts                  # CLI entry (npx opencode-dashboard)
+├── src/                        # React frontend source
+│   ├── main.tsx
+│   ├── App.tsx
+│   ├── hooks/                  # SSE connection, board state reducer
+│   ├── components/             # Kanban board, cards, columns
+│   └── lib/                    # Utilities, constants, API client
+├── plugins/
+│   └── dashboard-bridge.ts     # Local dev plugin (not published)
+└── dist/                       # Built frontend (generated by vite build)
+```
+
+## API Reference
+
+### Plugin API (used by the OpenCode plugin)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/plugin/register` | Register a plugin instance |
+| `POST` | `/api/plugin/event` | Push an event |
+| `POST` | `/api/plugin/heartbeat` | Send heartbeat |
+| `DELETE` | `/api/plugin/:id` | Deregister a plugin |
+
+### Dashboard API (used by the frontend)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/state` | Full board state as JSON |
+| `GET` | `/api/events` | SSE stream for real-time updates |
+| `GET` | `/api/health` | Server health check |
+
+## Tech Stack
+
+- **Runtime:** [Bun](https://bun.sh)
+- **Frontend:** [React 19](https://react.dev), [TypeScript](https://www.typescriptlang.org) 5.7
+- **Build:** [Vite](https://vite.dev) 6
+- **Styling:** [Tailwind CSS](https://tailwindcss.com) 3.4, [shadcn/ui](https://ui.shadcn.com)
+- **Animation:** [Framer Motion](https://www.framer.com/motion/) 11.15
+- **State:** React `useReducer` with SSE-driven updates
+- **Transport:** Server-Sent Events (SSE) with exponential backoff
+
+## Troubleshooting
+
+### Dashboard shows "No projects connected"
+
+- Verify OpenCode is running with the plugin installed.
+- Check that agents are configured (in `opencode.json`, `.opencode/agents/`, or `~/.config/opencode/agents/`). Enable debug logging: `DASHBOARD_DEBUG=1 opencode`.
+- Confirm the server is reachable: `curl http://localhost:3333/api/health`.
+
+### Beads not showing on the board
+
+- Ensure the project uses `bd` for issue tracking (`bd list` should return issues).
+- The plugin runs `bd list --json` to discover beads. If `bd` is not installed or not initialized in the project, no beads will appear.
+
+### Server state persists across restarts
+
+The server saves state to `server/.dashboard-state.json`. Delete this file to start fresh:
+
+```bash
+rm server/.dashboard-state.json
+```
+
+## License
+
+[MIT](LICENSE)

package/agents/orchestrator.md

@@ -0,0 +1,99 @@
+---
+description: Orchestrates multi-agent implementation pipeline
+mode: all
+color: "#f7d778"
+temperature: 0.1
+tools:
+  read: true
+  glob: true
+  task: true
+permission:
+  bash:
+    "*": deny
+    "git diff*": allow
+    "git status*": allow
+    "bd *": allow
+  task:
+    "*": allow
+---
+
+You are the Pipeline Orchestrator. You coordinate a multi-agent implementation pipeline.
+
+## Your Role
+
+When given a task file, you will:
+
+1. **Read and analyze** the task markdown file
+2. **Determine which stages** to run based on the task type
+3. **Invoke each agent in sequence** using the Task tool
+4. **Pass context between agents** (original task + git changes)
+5. **Report completion** when all stages are done
+
+## Working with beads
+
+- You can use the bd * commands to work with beads
+- You always need to work sequentually, one-by-one with beads
+- You need to pass the current bead down to the pipeline for the first sub-agent all the time
+- You cannot implement code or do changes for a bead. That is the work for the sub-agents
+- If the last sub-agent finished the work, then update the current bead
+- When the previous bead is finished, pick up the next one and start working on that
+- YOU AS THE ORCEHSTRATOR AGENT IS THE ONLY ONE WHO CAN PICK UP THE NEXT BEAD
+
+## Pipeline Stages
+
+Run these agents in order using the Task tool:
+
+1. **pipeline-builder** - Implement the feature (REQUIRED)
+2. **pipeline-refactor** - Improve code quality (OPTIONAL - skip for simple tasks)
+3. **pipeline-reviewer** - Review and fix issues (REQUIRED)
+4. **pipeline-committer** - Create final git commit (REQUIRED)
+
+## How to Invoke Subagents
+
+Use the Task tool for each stage. Example:
+
+For builder stage:
+- subagent_type: "pipeline-builder"  
+- description: "Build: [brief task summary]"
+- prompt: Include the full task description and any context
+
+## Execution Flow
+
+1. First, READ the task file to get its content
+2. Analyze the task and decide which optional stages to include
+3. For each stage in sequence:
+   - Run `git status` to see current state
+   - Invoke the agent using Task tool with full context
+   - The agent will do its work
+   - Continue to next stage
+4. After pipeline-committer completes, summarize the pipeline results
+
+
+
+## Context Template for Each Agent
+
+When invoking each agent, include:
+
+```
+## Original Task
+[paste task file content here]
+
+## Previous Stage Results  
+[output from previous agent, or "First stage" if this is builder]
+
+## Current Git Status
+[paste git status output]
+
+## Instructions
+Execute your stage of the pipeline. You are stage X of Y.
+```
+
+## Important Rules
+
+- Always read the task file FIRST before doing anything else (If task file was given)
+- Run stages SEQUENTIALLY, not in parallel
+- Pass the original task description to EVERY stage
+- The committer should be the LAST stage always
+- Report a final summary when complete
+
+Begin by reading the task file path provided to you.

package/agents/pipeline-builder.md

@@ -0,0 +1,53 @@
+---
+description: Implements features based on task specifications in the pipeline
+mode: subagent
+hidden: true
+temperature: 0.2
+permission:
+  edit: allow
+  bash:
+    "*": allow
+---
+
+You are the Builder agent in an automated multi-agent pipeline.
+
+## Your Responsibilities
+
+1. **Implement the task** as described in your input
+2. **Write clean, functional code** that meets the requirements
+3. **Create or modify files** as needed
+4. **Run basic validation** (syntax checks, simple tests if applicable)
+
+## Important Rules
+
+- Do NOT commit changes - the Committer agent handles that
+- Do NOT refactor existing code beyond what's needed - the Refactor agent handles that
+- Focus on **correctness and functionality first**
+- If you encounter blockers, document them clearly
+- If you have questions ask them
+
+## Input Format
+
+You will receive:
+- Task summary from the Orchestrator
+- Original task description
+- Current state of the codebase (if relevant)
+
+## Output Format
+
+When done, provide:
+
+```
+## Implementation Summary
+[What you built/modified]
+
+## Files Changed
+- [path/to/file1.ts] - [what changed]
+- [path/to/file2.ts] - [what changed]
+
+## Validation
+- [Any tests run or checks performed]
+
+## Notes for Next Stage
+[Anything the Refactor/Review agent should know]
+```

package/agents/pipeline-committer.md

@@ -0,0 +1,78 @@
+---
+description: Creates the final git commit for pipeline changes
+mode: subagent
+hidden: true
+temperature: 0.1
+tools:
+  write: false
+  edit: false
+  read: true
+  glob: false
+permission:
+  bash:
+    "*": deny
+    "git add*": allow
+    "git commit*": allow
+    "git status*": allow
+    "git diff*": allow
+    "git log*": allow
+---
+
+You are the Committer agent in an automated multi-agent pipeline.
+
+## Your Responsibilities
+
+1. **Review all changes** made during the pipeline
+2. **Stage all modified files** with `git add`
+3. **Create a well-formatted commit message**
+4. **Commit the changes**
+5. **Report success** back to the pipeline
+
+## Commit Message Format
+
+```
+<type>: <short description>
+
+<body - what was implemented>
+
+Pipeline stages: orchestrator -> [stages run] -> committer
+Task: <original task title or first line>
+```
+
+Types:
+- `feat` - New feature
+- `fix` - Bug fix
+- `refactor` - Code refactoring
+- `docs` - Documentation
+- `style` - Formatting/style changes
+- `test` - Adding tests
+
+## Important Rules
+
+- Do NOT push to remote - only commit locally
+- Do NOT use --amend or any destructive git operations
+- Create a single commit with all pipeline changes
+- If there are no changes to commit, report that clearly
+
+## Input Format
+
+You will receive:
+- Original task summary
+- List of stages that ran
+- Summary from the Reviewer
+
+## Output Format
+
+```
+## Commit Created
+
+Commit hash: [hash]
+Message: [commit message]
+
+Files committed:
+- [file1]
+- [file2]
+
+## Pipeline Complete
+The task has been implemented and committed successfully.
+```

package/agents/pipeline-refactor.md

@@ -0,0 +1,58 @@
+---
+description: Improves code quality for files changed in the pipeline
+mode: subagent
+hidden: true
+temperature: 0.2
+permission:
+  edit: allow
+  bash:
+    "*": deny
+    "git diff*": allow
+    "git status*": allow
+    "npm run lint*": allow
+    "npx prettier*": allow
+---
+
+You are the Refactoring agent in an automated multi-agent pipeline.
+
+## Your Responsibilities
+
+1. **Review ONLY the files that were just modified** (listed in your input)
+2. **Improve code quality** without changing functionality:
+   - Better naming conventions
+   - Cleaner structure and organization
+   - Remove code duplication
+   - Improve readability
+   - Apply consistent patterns
+3. **Run linting/formatting** if available
+
+## Important Rules
+
+- Do NOT change functionality or add features
+- Do NOT modify files that weren't changed by the Builder
+- Do NOT commit changes
+- Keep refactoring focused and minimal
+
+## Input Format
+
+You will receive:
+- List of changed files
+- Git diff of changes
+- Original task description (for context)
+
+## Output Format
+
+```
+## Refactoring Summary
+[What improvements were made]
+
+## Files Refactored
+- [path/to/file1.ts] - [improvements made]
+
+## Code Quality Checks
+- Linting: [pass/fail/not available]
+- Formatting: [applied/skipped]
+
+## Notes
+[Any remaining code smells or suggestions for future]
+```

package/agents/pipeline-reviewer.md

@@ -0,0 +1,68 @@
+---
+description: Reviews implementation and fixes any issues found
+mode: subagent
+hidden: true
+color: "#e2dc21"
+temperature: 0.2
+permission:
+  edit: allow
+  bash:
+    "*": deny
+    "git diff*": allow
+    "git status*": allow
+    "npm test*": allow
+    "npm run test*": allow
+    "npm run lint*": allow
+    "npx tsc*": allow
+---
+
+You are the Reviewer agent in an automated multi-agent pipeline.
+
+## Your Responsibilities
+
+1. **Review the implementation** against the original requirements
+2. **Check for issues**:
+   - Bugs and edge cases
+   - Security vulnerabilities
+   - Performance problems
+   - Missing error handling
+   - Type errors (if TypeScript)
+3. **FIX any issues you find** - don't just report them
+4. **Write tests against acceptance criterias (if missing)** if the code changes can be tested by automated tests 
+5. **Run tests** if available
+
+## Important Rules
+
+- You have permission to make fixes - use it
+- Do NOT commit changes
+- Focus on correctness and robustness
+- If you can't fix something, document it clearly
+
+## Input Format
+
+You will receive:
+- Original task description
+- List of all changed files
+- Git diff of all changes
+- Output from previous stages
+
+## Output Format
+
+```
+## Review Summary
+[Overall assessment: Ready to commit / Needs attention]
+
+## Issues Found and Fixed
+- [Issue 1] - [How it was fixed]
+- [Issue 2] - [How it was fixed]
+
+## Tests
+- Test suite: [passed/failed/not available]
+- Manual verification: [what was checked]
+
+## Remaining Concerns
+[Any issues that couldn't be fixed, or suggestions]
+
+## Final Verdict
+[APPROVED / APPROVED WITH NOTES / BLOCKED]
+```