bdeyes

A read-only desktop observatory for Beads. bdeyes turns a ledger into a compact operational outline: what is moving, what is blocked, what is ready, what has gone quiet, and who owns it.

Screenshots

These screenshots come from a generated demo fixture. Every bead ID, title, person, owner, timestamp, comment, and path is fictional; no live ledger data appears.

The containment outline and inspector, with the espresso machine awaiting a ceremonial teaspoon.

Assignee and owner facets compose with the current operational view; unassigned work remains explicit.

Preview status

bdeyes is currently a 0.1.0-preview.2 project.

• Windows 10/11 x64 and Linux x64 are supported preview binary targets.
• Windows behavior is exercised against a live Beads workspace with native UI Automation.
• Linux behavior passed a native Ubuntu 24.04/WSLg smoke against a live workspace and subsequent road use.
• Windows, macOS, and Linux compile and run behavioral tests in CI.
• macOS remains CI-only until it has a native desktop smoke and packaging contract.

The application is intentionally read-only. It is an observability client, not a second task editor.

What it shows

• Active, blocked, ready, aging, all-bead, and epic views.
• A virtualized hierarchy built from authoritative Beads parent relationships.
• Ancestor-preserving search and operational filters.
• Assignee and owner filters, including explicit unassigned work.
• Dependency, progress, activity, comment, and containment details.
• Keyboard expansion and accessible Tree/TreeItem semantics.
• Automatic one-minute background refresh while no inspector is open; manual refresh preserves readable inspector state.

Requirements

• A Beads workspace.
• bd installed and configured for that workspace.
• Preview compatibility is verified with bd 1.2.2.

A self-contained release does not require the .NET runtime. Building from source requires the .NET 10 SDK; creating release archives also requires Python 3.

Install and run on Windows

1. Install and configure bd.
2. Download the win-x64 archive from the bdeyes GitHub release.
3. Extract the complete archive and run Bdeyes.exe.
4. Choose a repository containing an active Beads workspace.

Windows may warn about an unsigned preview binary. Before running it, compare the archive hash with the .sha256 file attached to the same release:

Get-FileHash -Algorithm SHA256 .\bdeyes-0.1.0-preview.2-win-x64.zip

You can open a workspace directly from the extracted archive:

.\Bdeyes.exe --workspace C:\path\to\workspace

Install and run on Linux

1. Install and configure bd.
2. Download the linux-x64 archive and its .sha256 sidecar from the bdeyes GitHub release.
3. Verify and extract the complete archive:

sha256sum --check bdeyes-0.1.0-preview.2-linux-x64.tar.gz.sha256
tar -xzf bdeyes-0.1.0-preview.2-linux-x64.tar.gz

4. Launch bdeyes from a desktop session and choose a Beads workspace:

./Bdeyes --workspace /path/to/workspace

The archive is self-contained; a normal Linux desktop supplies the display and input libraries used by Avalonia.

Finding bd

bdeyes resolves the CLI in this order:

1. A path explicitly saved in bd setup.
2. BDEYES_BD.
3. The process PATH.
4. Conservative platform install locations.

Open bd setup to inspect the selected executable and version, browse to another executable, test it without opening a workspace, save it, or return to automatic discovery.

bdeyes stores only the optional executable path. It does not read or store a ledger password, server credential, or Beads credential file. Authentication remains owned by bd and its protected credential store.

Read-only boundary

Every ledger command enters global bd --readonly mode. bdeyes:

• invokes the installed bd CLI;
• consumes JSON emitted by bd;
• never reads Dolt tables directly;
• never imports .beads/issues.jsonl; and
• exposes no mutation command.

Read-only does not mean non-sensitive. Issue titles, descriptions, comments, ownership, and dependency data are rendered on screen. Protect screenshots and desktop access according to the sensitivity of the workspace.

Local settings

bdeyes stores local UI state under the operating system's local application-data directory in bdeyes/settings.json. The file contains only:

• the last workspace path;
• expanded issue IDs; and
• an optional bd executable path.

Deleting this file resets local bdeyes state. It does not modify the Beads workspace.

Build and test

dotnet restore Bdeyes.slnx
dotnet build Bdeyes.slnx --configuration Release --no-restore
dotnet test Bdeyes.slnx --configuration Release --no-build

Run from source:

dotnet run --project src/Bdeyes/Bdeyes.csproj -- --workspace /path/to/workspace

Create deterministic self-contained preview archives and SHA-256 sidecars:

python scripts/package-preview.py --runtime win-x64

python3 scripts/package-preview.py --runtime linux-x64

Contributions should preserve the CLI-only read boundary and include behavioral coverage for any changed user-facing contract.

Reporting problems

Use GitHub Issues for reproducible, non-sensitive bugs and feature requests. For security-sensitive reports, follow SECURITY.md. Never include ledger passwords, credential files, private keys, or confidential bead content in a report.

License

bdeyes is available under the MIT License. Use it, modify it, and redistribute it under those terms.