e7f532db93
* 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>
120 lines
4.0 KiB
Markdown
120 lines
4.0 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**beads** (command: `bd`) is a git-backed issue tracker for AI-supervised coding workflows. We dogfood our own tool.
|
|
|
|
**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.
|