Implementing an RPC monitoring solution with a web-ui as implementation example. (#244)

* bd sync: 2025-10-30 12:12:27

* Working on frontend

* bd sync: 2025-11-06 16:55:55

* feat: finish bd monitor human viewer

* Merge conflicts resolved and added tests

* bd sync: 2025-11-06 17:23:41

* bd sync: 2025-11-06 17:34:52

* feat: Add reload button and multiselect status filter to monitor

- Changed status filter from single select to multiselect with 'Open' selected by default
- Added reload button with visual feedback (hover/active states)
- Updated filterIssues() to handle multiple selected statuses
- Added reloadData() function that reloads both stats and issues
- Improved responsive design for mobile devices
- Filter controls now use flexbox layout with better spacing

* fix: Update monitor statistics to show Total, In Progress, Open, Closed

- Replaced 'Ready to Work' stat with 'In Progress' stat
- Reordered stats to show logical progression: Total -> In Progress -> Open -> Closed
- Updated loadStats() to fetch in-progress count from stats API
- Removed unnecessary separate API call for ready count

* fix: Correct API field names in monitor stats JavaScript

The JavaScript was using incorrect field names (stats.total, stats.by_status)
that don't match the actual types.Statistics struct which uses flat fields
with underscores (total_issues, in_progress_issues, etc).

Fixed by updating loadStats() to use correct field names:
- stats.total -> stats.total_issues
- stats.by_status?.['in-progress'] -> stats.in_progress_issues
- stats.by_status?.open -> stats.open_issues
- stats.by_status?.closed -> stats.closed_issues

Fixes beads-9

* bd sync: 2025-11-06 17:51:24

* bd sync: 2025-11-06 17:56:09

* fix: Make monitor require daemon to prevent SQLite locking

Implemented Option 1 from beads-eel: monitor now requires daemon and never
opens direct SQLite connection.

Changes:
- Added 'monitor' to noDbCommands list in main.go to skip normal DB initialization
- Added validateDaemonForMonitor() PreRun function that:
  - Finds database path using beads.FindDatabasePath()
  - Validates daemon is running and healthy
  - Fails gracefully with clear error message if no daemon
  - Only uses RPC connection, never opens SQLite directly

Benefits:
- Eliminates SQLite locking conflicts between monitor and daemon
- Users can now close/update issues via CLI while monitor runs
- Clear error messages guide users to start daemon first

Fixes beads-eel

* bd sync: 2025-11-06 18:03:50

* docs: Add bd daemons restart subcommand documentation

Added documentation for the 'bd daemons restart' subcommand across all documentation files:

- commands/daemons.md: Added full restart subcommand section with synopsis, description, arguments, flags, and examples
- README.md: Added restart examples to daemon management section
- AGENTS.md: Added restart examples with --json flag for agents

The restart command gracefully stops and starts a specific daemon by workspace path or PID,
useful after upgrading bd or when a daemon needs refreshing.

Fixes beads-11

* bd sync: 2025-11-06 18:13:16

* Separated the web ui from the general monitoring functionality

---------

Co-authored-by: Steve Yegge <stevey@sourcegraph.com>

docs/CLAUDE.md

@@ -1,10 +1,119 @@
+# CLAUDE.md
 
-<!-- bd integration note -->
-**Note**: This project uses [bd (beads)](https://github.com/steveyegge/beads) for issue tracking. Use `bd` commands or the beads MCP server instead of markdown TODOs. See AGENTS.md for workflow details.
-<!-- /bd integration note -->
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-# Instructions for Claude
+## Project Overview
 
-This file has been moved to **AGENTS.md** to support all AI agents, not just Claude.
+**beads** (command: `bd`) is a git-backed issue tracker for AI-supervised coding workflows. We dogfood our own tool.
 
-Please refer to [AGENTS.md](AGENTS.md) for complete instructions on working with the beads project.
+**IMPORTANT**: See [AGENTS.md](AGENTS.md) for complete workflow instructions, bd commands, and development guidelines.
+
+## Architecture Overview
+
+### Three-Layer Design
+
+1. **Storage Layer** (`internal/storage/`)
+   - Interface-based design in `storage.go`
+   - SQLite implementation in `storage/sqlite/`
+   - Memory backend in `storage/memory/` for testing
+   - Extensions can add custom tables via `UnderlyingDB()` (see EXTENDING.md)
+
+2. **RPC Layer** (`internal/rpc/`)
+   - Client/server architecture using Unix domain sockets (Windows named pipes)
+   - Protocol defined in `protocol.go`
+   - Server split into focused files: `server_core.go`, `server_issues_epics.go`, `server_labels_deps_comments.go`, etc.
+   - Per-workspace daemons communicate via `.beads/bd.sock`
+
+3. **CLI Layer** (`cmd/bd/`)
+   - Cobra-based commands (one file per command: `create.go`, `list.go`, etc.)
+   - Commands try daemon RPC first, fall back to direct database access
+   - All commands support `--json` for programmatic use
+   - Main entry point in `main.go`
+
+### Distributed Database Pattern
+
+The "magic" is in the auto-sync between SQLite and JSONL:
+
+```
+SQLite DB (.beads/beads.db, gitignored)
+    ↕ auto-sync (5s debounce)
+JSONL (.beads/issues.jsonl, git-tracked)
+    ↕ git push/pull
+Remote JSONL (shared across machines)
+```
+
+- **Write path**: CLI → SQLite → JSONL export → git commit
+- **Read path**: git pull → JSONL import → SQLite → CLI
+- **Collision handling**: `bd import --resolve-collisions` (see AGENTS.md)
+
+Core implementation:
+- Export: `cmd/bd/export.go`, `cmd/bd/autoflush.go`
+- Import: `cmd/bd/import.go`, `cmd/bd/autoimport.go`
+- Collision detection: `internal/importer/importer.go`
+
+### Key Data Types
+
+See `internal/types/types.go`:
+- `Issue`: Core work item (title, description, status, priority, etc.)
+- `Dependency`: Four types (blocks, related, parent-child, discovered-from)
+- `Label`: Flexible tagging system
+- `Comment`: Threaded discussions
+- `Event`: Full audit trail
+
+### Daemon Architecture
+
+Each workspace gets its own daemon process:
+- Auto-starts on first command (unless disabled)
+- Handles auto-sync, batching, and background operations
+- Socket at `.beads/bd.sock` (or `.beads/bd.pipe` on Windows)
+- Version checking prevents mismatches after upgrades
+- Manage with `bd daemons` command (see AGENTS.md)
+
+## Common Development Commands
+
+```bash
+# Build and test
+go build -o bd ./cmd/bd
+go test ./...
+go test -coverprofile=coverage.out ./...
+
+# Run linter (baseline warnings documented in docs/LINTING.md)
+golangci-lint run ./...
+
+# Version management
+./scripts/bump-version.sh 0.9.3 --commit
+
+# Local testing
+./bd init --prefix test
+./bd create "Test issue" -p 1
+./bd ready
+```
+
+## Testing Philosophy
+
+- Unit tests live next to implementation (`*_test.go`)
+- Integration tests use real SQLite databases (`:memory:` or temp files)
+- Script-based tests in `cmd/bd/testdata/*.txt` (see `scripttest_test.go`)
+- RPC layer has extensive isolation and edge case coverage
+
+## Important Notes
+
+- **Always read AGENTS.md first** - it has the complete workflow
+- Use `bd --no-daemon` in git worktrees (see AGENTS.md for why)
+- Install git hooks for zero-lag sync: `./examples/git-hooks/install.sh`
+- Run `bd sync` at end of agent sessions to force immediate flush/commit/push
+- Check for duplicates proactively: `bd duplicates --auto-merge`
+- Use `--json` flags for all programmatic use
+
+## Key Files
+
+- **AGENTS.md** - Complete workflow and development guide (READ THIS!)
+- **README.md** - User-facing documentation
+- **ADVANCED.md** - Advanced features (rename, merge, compaction)
+- **EXTENDING.md** - How to add custom tables to the database
+- **LABELS.md** - Complete label system guide
+- **CONFIG.md** - Configuration system
+
+## When Adding Features
+
+See AGENTS.md "Adding a New Command" and "Adding Storage Features" sections for step-by-step guidance.