docs: port user docs into the Mintlify site tree under docs/
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
This commit is contained in:
parent
0e017821f4
commit
a86a2c5dfc
77 changed files with 7683 additions and 1908 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Dolt Backend Documentation
|
||||
|
||||
The canonical Dolt backend guide is [DOLT.md](DOLT.md).
|
||||
The canonical Dolt backend guide is [architecture/dolt.md](architecture/dolt.md).
|
||||
|
||||
The previous long-form duplicate of this file has been staged at
|
||||
[staged-for-removal/DOLT-BACKEND.md](../engdocs/staged-for-removal/DOLT-BACKEND.md).
|
||||
|
|
|
|||
740
docs/DOLT.md
740
docs/DOLT.md
|
|
@ -1,737 +1,7 @@
|
|||
# Dolt Backend for Beads
|
||||
|
||||
Beads uses Dolt as its storage backend. Dolt provides a version-controlled SQL database with cell-level merge, native branching, and two deployment modes.
|
||||
|
||||
## Why Dolt?
|
||||
|
||||
- **Native version control** — cell-level diffs and merges, not line-based
|
||||
- **Multi-writer support** — server mode enables concurrent agents
|
||||
- **Built-in history** — every write creates a Dolt commit
|
||||
- **Native branching** — Dolt branches independent of git branches
|
||||
- **Single-binary option** — embedded mode for solo users (no server needed)
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Install Dolt (Server Mode Only)
|
||||
|
||||
Embedded mode includes everything in the `bd` binary; no separate Dolt install
|
||||
is needed. Install the standalone `dolt` CLI only when you want to run server
|
||||
mode or work directly with the database via `dolt sql`.
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install dolt
|
||||
|
||||
# Linux
|
||||
curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash
|
||||
|
||||
# Verify installation
|
||||
dolt version
|
||||
```
|
||||
|
||||
### New Project
|
||||
|
||||
```bash
|
||||
# Embedded mode (single writer, no server — default for standalone)
|
||||
bd init
|
||||
|
||||
# Server mode (multi-writer, e.g. orchestrator)
|
||||
gt dolt start # Start the Dolt server
|
||||
bd init --server # Initialize with server mode
|
||||
```
|
||||
|
||||
### Migrate from SQLite (Legacy)
|
||||
|
||||
If upgrading from an older version that used SQLite:
|
||||
|
||||
> **Note:** The `bd migrate --to-dolt` command was removed in v0.58.0.
|
||||
> For pre-0.50 installations with JSONL data, use the migration script:
|
||||
>
|
||||
> ```bash
|
||||
> scripts/migrate-jsonl-to-dolt.sh
|
||||
> ```
|
||||
>
|
||||
> See [Troubleshooting](TROUBLESHOOTING.md#circuit-breaker-server-appears-down-failing-fast) if you encounter connection errors after migration.
|
||||
|
||||
Migration creates backups automatically. Your original SQLite database is preserved as `beads.backup-pre-dolt-*.db`.
|
||||
|
||||
## Modes of Operation
|
||||
|
||||
### Embedded Mode (Solo / Standalone)
|
||||
|
||||
In-process Dolt engine — no separate server needed. This is the default for
|
||||
standalone Beads users. The `bd` binary includes everything; just `bd init` and go.
|
||||
|
||||
- Single-writer (one process at a time)
|
||||
- Data lives in `.beads/embeddeddolt/` alongside your code
|
||||
- Push to GitHub with `bd dolt push` — code and issues in one repo
|
||||
- Zero ops: no server, no ports, no PID files
|
||||
|
||||
### Server Mode (Multi-Writer / Orchestrator)
|
||||
|
||||
Connects to a running `dolt sql-server` for multi-client access.
|
||||
|
||||
```bash
|
||||
# Start the server (orchestrator)
|
||||
gt dolt start
|
||||
|
||||
# Or manually
|
||||
cd ~/.dolt-data/beads && dolt sql-server --port 3307
|
||||
```
|
||||
|
||||
```bash
|
||||
# Initialize in server mode
|
||||
bd init --server
|
||||
|
||||
# Or switch via environment variable
|
||||
export BEADS_DOLT_SERVER_MODE=1
|
||||
```
|
||||
|
||||
```yaml
|
||||
# .beads/config.yaml (server mode settings)
|
||||
dolt:
|
||||
mode: server
|
||||
host: 127.0.0.1
|
||||
port: 3307
|
||||
user: root
|
||||
```
|
||||
|
||||
Switch to server mode when you need:
|
||||
- Multiple agents writing simultaneously
|
||||
- Orchestrator multi-rig setups
|
||||
- Federation with remote peers
|
||||
|
||||
## Migrating Between Backends
|
||||
|
||||
You can migrate data between embedded mode and server mode using `bd backup`.
|
||||
Both directions preserve full Dolt commit history.
|
||||
|
||||
`bd export` is not a substitute for this flow. JSONL exports contain issue
|
||||
records from the issues table for migration and interoperability; they do not
|
||||
capture Dolt branches, full commit history, working-set state, or non-issue
|
||||
tables. Use `bd backup` or a manual Dolt backup when you need a restorable
|
||||
database backup.
|
||||
|
||||
### Server → Embedded
|
||||
|
||||
1. **Create a backup from the server-mode project:**
|
||||
|
||||
```bash
|
||||
# In the server-mode project directory
|
||||
bd backup init /path/to/backup-dir
|
||||
bd backup sync
|
||||
```
|
||||
|
||||
2. **Create a new embedded-mode project and restore:**
|
||||
|
||||
```bash
|
||||
mkdir new-project && cd new-project
|
||||
bd init # creates an embedded-mode project by default
|
||||
bd backup restore --force /path/to/backup-dir
|
||||
```
|
||||
|
||||
`--force` overwrites the freshly-initialized database with the backup
|
||||
contents. The restore automatically:
|
||||
- Updates `metadata.json` to match the restored project identity
|
||||
- Registers the backup directory for future `bd backup sync`
|
||||
- Backfills the embedded migration tracker (`schema_migrations`)
|
||||
|
||||
3. **Verify:**
|
||||
|
||||
```bash
|
||||
bd list
|
||||
bd backup status
|
||||
```
|
||||
|
||||
### Embedded → Server
|
||||
|
||||
1. **Create a backup from the embedded-mode project:**
|
||||
|
||||
```bash
|
||||
# In the embedded-mode project directory
|
||||
bd backup init /path/to/backup-dir
|
||||
bd backup sync
|
||||
```
|
||||
|
||||
2. **Create a new server-mode project and restore:**
|
||||
|
||||
```bash
|
||||
mkdir new-project && cd new-project
|
||||
bd init --server # creates a server-mode project
|
||||
bd backup restore --force /path/to/backup-dir
|
||||
```
|
||||
|
||||
3. **Verify:**
|
||||
|
||||
```bash
|
||||
bd list
|
||||
bd backup status
|
||||
```
|
||||
|
||||
### Backup Commands Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bd backup init <path>` | Register a backup destination (filesystem or DoltHub URL) |
|
||||
| `bd backup sync` | Push database to the configured backup destination |
|
||||
| `bd backup restore [path]` | Restore from a backup directory (`--force` to overwrite) |
|
||||
| `bd backup remove` | Unregister the backup destination |
|
||||
| `bd backup status` | Show backup configuration and last sync time |
|
||||
|
||||
### Notes
|
||||
|
||||
- Data locations differ between modes: `.beads/embeddeddolt/` (embedded) vs `.beads/dolt/` (server)
|
||||
- The backup directory is a full Dolt backup, not an `issues.jsonl` export — it can be on a local drive, NAS, or DoltHub
|
||||
- You can also migrate via Dolt remotes (`bd dolt push` / `bd dolt pull`) if both projects share a remote
|
||||
|
||||
The sections below are the canonical backend migration reference.
|
||||
|
||||
## Federation (Peer-to-Peer Sync)
|
||||
|
||||
Federation lets independent Dolt-backed workspaces ("towns") sync issues
|
||||
directly with each other via `bd federation add-peer`/`sync`/`status`,
|
||||
without a central hub. Credentials are AES-256 encrypted and stored locally.
|
||||
|
||||
See [FEDERATION.md](FEDERATION.md) for the full setup guide, including
|
||||
peer configuration, sovereignty tiers, sync/status/topology details, and
|
||||
troubleshooting.
|
||||
|
||||
## Dolt Remotes
|
||||
|
||||
Use `bd dolt remote add` to configure remotes. This ensures the running Dolt SQL
|
||||
server sees the remote immediately. Remotes added directly with the `dolt` CLI
|
||||
are written to filesystem config and may not be visible to the server until
|
||||
restart.
|
||||
|
||||
```bash
|
||||
# DoltHub (public or private)
|
||||
bd dolt remote add origin https://doltremoteapi.dolthub.com/org/beads
|
||||
|
||||
# S3
|
||||
bd dolt remote add origin aws://[bucket]/path/to/repo
|
||||
|
||||
# GCS
|
||||
bd dolt remote add origin gs://[bucket]/path/to/repo
|
||||
|
||||
# Git SSH (GitHub, GitLab, etc.)
|
||||
bd dolt remote add origin git+ssh://git@github.com/org/repo.git
|
||||
|
||||
# Local file system
|
||||
bd dolt remote add origin file:///path/to/remote
|
||||
```
|
||||
|
||||
### Push/Pull
|
||||
|
||||
```bash
|
||||
bd dolt push
|
||||
bd dolt pull
|
||||
```
|
||||
|
||||
`bd dolt remote add` registers the remote through the Dolt store API. SQL
|
||||
remotes are the source of truth for `bd dolt remote list`, `bd dolt push`, and
|
||||
`bd dolt pull`.
|
||||
|
||||
For git-protocol remotes, credentialed external-server remotes, and cloud
|
||||
remotes whose credentials are only present in the current shell, `bd dolt push`
|
||||
and `bd dolt pull` automatically materialize a matching local CLI remote before
|
||||
using the `dolt` CLI transport. The CLI remote is a local transport mirror, not
|
||||
a separate configuration source.
|
||||
|
||||
If you are upgrading from an older beads version and previously added remotes
|
||||
with raw `dolt remote add`, re-register them with `bd dolt remote add <name>
|
||||
<url>` so they are visible through SQL. `bd doctor` reports legacy CLI-only or
|
||||
mismatched CLI remotes under `Dolt Remote Migration`.
|
||||
|
||||
> **Sharing a Git repo**: Dolt stores data under `refs/dolt/data`, separate
|
||||
> from standard Git refs (`refs/heads/`, `refs/tags/`). You can safely point a
|
||||
> `git+ssh://` remote at the same repository as your project source code. See
|
||||
> [Dolt Git Remotes](https://docs.dolthub.com/concepts/dolt/git/remotes).
|
||||
|
||||
### List/Remove Remotes
|
||||
|
||||
```bash
|
||||
bd dolt remote list # Shows SQL-configured remotes
|
||||
bd dolt remote remove origin # Removes the remote
|
||||
```
|
||||
|
||||
## Contributor Onboarding (Clone Bootstrap)
|
||||
|
||||
When someone clones a repository that uses Dolt backend:
|
||||
|
||||
1. Run `bd bootstrap` in the clone
|
||||
2. If the git remote has `refs/dolt/data` (pushed via `bd dolt push`),
|
||||
`bd bootstrap` auto-detects it and clones the database from the remote
|
||||
3. Work continues normally — all existing issues are available
|
||||
|
||||
**No manual steps required** beyond `bd bootstrap`. The auto-detect:
|
||||
- Probes `origin` for `refs/dolt/data`
|
||||
- Clones the Dolt database from the remote (instead of creating a fresh one)
|
||||
- Configures the Dolt remote for future `bd dolt push`/`pull`
|
||||
|
||||
If `sync.remote` is set in `.beads/config.yaml`, that takes precedence
|
||||
over auto-detection. Any Dolt-compatible remote URL is supported (DoltHub,
|
||||
S3, GCS, file, or git). On brand-new projects, `bd init` auto-detects
|
||||
`git origin` and persists it as `sync.remote`, so the first `bd dolt push`
|
||||
publishes Dolt history to `refs/dolt/data` on the same git remote.
|
||||
|
||||
### Verifying Bootstrap Worked
|
||||
|
||||
```bash
|
||||
bd list # Should show issues
|
||||
bd vc log # Should show initial commit
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server Not Running
|
||||
|
||||
**Symptom:** Connection refused errors when using server mode.
|
||||
|
||||
```
|
||||
failed to create database: dial tcp 127.0.0.1:3307: connect: connection refused
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
gt dolt start # Orchestrator command
|
||||
# Or
|
||||
gt dolt status # Check if running
|
||||
```
|
||||
|
||||
### Bootstrap Not Running
|
||||
|
||||
**Symptom:** `bd list` shows nothing on fresh clone.
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
ls .beads/dolt/ # Should NOT exist (pre-bootstrap)
|
||||
BD_DEBUG=1 bd list # See bootstrap output
|
||||
```
|
||||
|
||||
**Force bootstrap:**
|
||||
```bash
|
||||
rm -rf .beads/dolt # Remove broken state
|
||||
bd list # Re-triggers bootstrap
|
||||
```
|
||||
|
||||
### Database Corruption
|
||||
|
||||
**Symptom:** Queries fail, inconsistent data.
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
bd doctor # Basic checks
|
||||
bd doctor --deep # Full validation
|
||||
bd doctor --server # Server mode checks (if applicable)
|
||||
```
|
||||
|
||||
**Recovery options:**
|
||||
|
||||
1. **Repair what's fixable:**
|
||||
```bash
|
||||
bd doctor --fix
|
||||
```
|
||||
|
||||
2. **Rebuild from remote:**
|
||||
```bash
|
||||
rm -rf .beads/dolt
|
||||
bd list # Re-triggers bootstrap
|
||||
```
|
||||
|
||||
### Already Committed `.beads/dolt/` to Git
|
||||
|
||||
If you accidentally committed a Dolt data directory:
|
||||
|
||||
1. Update gitignore: `bd doctor --fix`
|
||||
2. Remove it from git tracking: `git rm --cached -r .beads/dolt/` (or `.beads/embeddeddolt/`)
|
||||
3. Commit the removal: `git commit -m "fix: remove accidentally committed dolt data"`
|
||||
4. To purge from history, use [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) or `git filter-repo`
|
||||
|
||||
### Lock Contention (Embedded Mode)
|
||||
|
||||
**Symptom:** "database is locked" errors.
|
||||
|
||||
Embedded mode is single-writer (enforced via file lock). If you need concurrent
|
||||
access, switch to server mode. See [Migrating Between Backends](#migrating-between-backends).
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
```yaml
|
||||
# .beads/config.yaml
|
||||
|
||||
# Dolt settings
|
||||
dolt:
|
||||
# Auto-commit Dolt history after writes (default: on for embedded, off for server)
|
||||
auto-commit: on # on | off
|
||||
|
||||
# Storage mode (default: embedded)
|
||||
mode: embedded # embedded | server
|
||||
# Server mode settings (only used when mode: server)
|
||||
host: 127.0.0.1
|
||||
port: 3307
|
||||
user: root
|
||||
# Password: env var or credentials file (see below)
|
||||
|
||||
# Shared server mode (GH#2377): all projects share a single Dolt server
|
||||
# at ~/.beads/shared-server/. Each project uses its own database (prefix-based).
|
||||
# Eliminates port conflicts and reduces resource usage on multi-project machines.
|
||||
shared-server: false # true | false
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `BEADS_DOLT_PASSWORD` | Server mode password (highest priority) |
|
||||
| `BEADS_CREDENTIALS_FILE` | Path to credentials file (overrides default location) |
|
||||
| `BEADS_DOLT_SERVER_MODE` | Enable server mode (set to "1") |
|
||||
| `BEADS_DOLT_SERVER_HOST` | Server host (default: 127.0.0.1) |
|
||||
| `BEADS_DOLT_SERVER_PORT` | Server port (default: 3307, or 3308 in shared mode) |
|
||||
| `BEADS_DOLT_SERVER_TLS` | Enable TLS (set to "1" or "true") |
|
||||
| `BEADS_DOLT_SERVER_USER` | MySQL connection user |
|
||||
| `BEADS_DOLT_SHARED_SERVER` | Enable shared server mode (set to "1" or "true") |
|
||||
| `DOLT_REMOTE_USER` | Clone/push/pull auth user |
|
||||
| `DOLT_REMOTE_PASSWORD` | Clone/push/pull auth password |
|
||||
| `BD_DOLT_AUTO_COMMIT` | Override auto-commit setting |
|
||||
|
||||
### Credentials File
|
||||
|
||||
For multi-server setups, you can store passwords in an INI-style credentials file
|
||||
instead of juggling environment variables per project. Passwords are looked up by
|
||||
`[host:port]` section, so each project automatically gets the right password based
|
||||
on its configured server.
|
||||
|
||||
**Password resolution order:**
|
||||
1. `BEADS_DOLT_PASSWORD` env var (highest priority, existing behavior)
|
||||
2. Credentials file lookup by `[host:port]` (using the resolved runtime port)
|
||||
3. Empty string (no password)
|
||||
|
||||
**Port resolution note:** The `[host:port]` used for credential lookup matches the
|
||||
resolved runtime port (from the port file, env var, or config — in that priority
|
||||
order), not necessarily the port stored in `metadata.json`. This matters when using
|
||||
IAP tunnels: if your tunnel maps remote:3307 to localhost:3308, store your password
|
||||
under `[127.0.0.1:3308]` and the credentials file will match the actual connection.
|
||||
|
||||
**Default location:** `~/.config/beads/credentials` (Linux/macOS), `%APPDATA%\beads\credentials` (Windows)
|
||||
|
||||
**Override location:** Set `BEADS_CREDENTIALS_FILE` env var.
|
||||
|
||||
**File format:**
|
||||
|
||||
```ini
|
||||
# ~/.config/beads/credentials
|
||||
[127.0.0.1:3307]
|
||||
password=localDevPassword
|
||||
|
||||
[beads.company.com:3307]
|
||||
password=teamServerPassword
|
||||
|
||||
[10.0.1.50:3308]
|
||||
password=officePassword
|
||||
```
|
||||
|
||||
**Permissions:** On Linux/macOS, a warning is printed to stderr if the file is
|
||||
readable by group or others (mirrors ssh behavior). Set permissions with:
|
||||
|
||||
```bash
|
||||
chmod 600 ~/.config/beads/credentials
|
||||
```
|
||||
|
||||
## Dolt Version Control
|
||||
|
||||
Dolt maintains its own version history, separate from Git:
|
||||
|
||||
```bash
|
||||
# View Dolt commit history
|
||||
bd vc log
|
||||
|
||||
# Show diff between Dolt commits
|
||||
bd vc diff HEAD~1 HEAD
|
||||
|
||||
# Create manual checkpoint
|
||||
bd vc commit -m "Checkpoint before refactor"
|
||||
```
|
||||
|
||||
### Auto-Commit Behavior
|
||||
|
||||
In **embedded mode** (standalone default), each `bd` write command creates a Dolt commit:
|
||||
|
||||
```bash
|
||||
bd create "New issue" # Creates issue + Dolt commit
|
||||
```
|
||||
|
||||
In **server mode** (orchestrator), auto-commit defaults to OFF because the server
|
||||
manages its own transaction lifecycle. Firing `DOLT_COMMIT` after every write
|
||||
under concurrent load causes 'database is read only' errors.
|
||||
|
||||
Override for batch operations (embedded) or explicit commits (server):
|
||||
|
||||
```bash
|
||||
bd --dolt-auto-commit off create "Issue 1"
|
||||
bd --dolt-auto-commit off create "Issue 2"
|
||||
bd vc commit -m "Batch: created issues"
|
||||
```
|
||||
|
||||
## Server Management (Orchestrator)
|
||||
|
||||
The orchestrator provides integrated Dolt server management:
|
||||
|
||||
```bash
|
||||
gt dolt start # Start server (background)
|
||||
gt dolt stop # Stop server
|
||||
gt dolt status # Show server status
|
||||
gt dolt logs # View server logs
|
||||
gt dolt sql # Open SQL shell
|
||||
```
|
||||
|
||||
Server runs on port 3307 (avoids MySQL conflict on 3306).
|
||||
|
||||
### Standalone-to-managed-city handoff
|
||||
|
||||
When an existing standalone project is later added to a managed city or
|
||||
orchestrator, avoid letting two Dolt servers become sources of truth for the
|
||||
same beads database name. A common split-brain symptom is that `.beads/dolt-server.port`
|
||||
points at the old standalone server while the shell environment points `bd` at
|
||||
the managed server with `BEADS_DOLT_PORT` or `BEADS_DOLT_SERVER_PORT`.
|
||||
|
||||
Check before migrating:
|
||||
|
||||
```bash
|
||||
bd doctor
|
||||
bd dolt status
|
||||
```
|
||||
|
||||
`bd doctor` warns when the runtime managed port differs from the local port
|
||||
file. The warning is intentionally diagnostic only; do not delete the local port
|
||||
file until the standalone store has been exported and imported into the managed
|
||||
server.
|
||||
|
||||
Safe manual handoff:
|
||||
|
||||
```bash
|
||||
# From the standalone project, without managed-city port overrides:
|
||||
unset BEADS_DOLT_PORT BEADS_DOLT_SERVER_PORT
|
||||
bd backup
|
||||
bd export > /tmp/beads-standalone.jsonl
|
||||
bd dolt stop
|
||||
|
||||
# Then enter the managed-city environment and import into its Dolt server:
|
||||
bd import /tmp/beads-standalone.jsonl
|
||||
bd doctor
|
||||
```
|
||||
|
||||
After `bd doctor` shows one healthy store and the imported issue count is
|
||||
correct, archive the old local Dolt data directory instead of deleting it
|
||||
immediately. Keep the backup until the managed city has been pushed or otherwise
|
||||
snapshotted.
|
||||
|
||||
### Shared Server Mode
|
||||
|
||||
On machines with multiple beads projects, each project normally starts its own Dolt server.
|
||||
Shared server mode runs a single Dolt server at `~/.beads/shared-server/` that serves all projects:
|
||||
|
||||
```bash
|
||||
# Enable for this project
|
||||
bd dolt set shared-server true
|
||||
|
||||
# Or enable machine-wide via environment variable
|
||||
export BEADS_DOLT_SHARED_SERVER=1
|
||||
|
||||
# Or enable during init
|
||||
bd init --prefix myproject --shared-server
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- No port conflicts between projects (single server on port 3308, avoids orchestrator on 3307)
|
||||
- Reduced resource usage (one process instead of many)
|
||||
- Automatic database isolation (each project uses its own database name)
|
||||
|
||||
**How it works:**
|
||||
- Server state files (PID, port, lock, log) live in `~/.beads/shared-server/`
|
||||
- Dolt data directory: `~/.beads/shared-server/dolt/`
|
||||
- Each project's database is stored as a subdirectory (e.g., `~/.beads/shared-server/dolt/myproject/`)
|
||||
- The file lock mechanism ensures safe concurrent access from multiple projects
|
||||
- Default port is 3308 (not 3307) to avoid conflict with the orchestrator. Override with `BEADS_DOLT_SERVER_PORT` or `dolt.port` in config.yaml
|
||||
|
||||
**Important:** Each project on a shared server **must have a unique prefix** (database name).
|
||||
Two projects with the same prefix share the same database — if this happens accidentally,
|
||||
the project identity check will detect the mismatch and refuse to connect, preventing
|
||||
silent data corruption. Always use distinct prefixes when running `bd init --shared-server`.
|
||||
|
||||
```bash
|
||||
# Check shared server status from any project
|
||||
bd dolt status
|
||||
|
||||
# Show full configuration including shared mode
|
||||
bd dolt show
|
||||
```
|
||||
|
||||
### Data Location (Orchestrator)
|
||||
|
||||
```
|
||||
<town-root>/.dolt-data/
|
||||
├── hq/ # Town beads (hq-*)
|
||||
├── my-project/ # Project rig (mp-*)
|
||||
├── beads/ # Beads rig (bd-*)
|
||||
└── other-project/ # Other rig (op-*)
|
||||
```
|
||||
|
||||
### Central Dolt Server (macOS LaunchAgent)
|
||||
|
||||
If you do not use the orchestrator but still want a single persistent Dolt
|
||||
server for multiple projects on macOS, run a custom `LaunchAgent` instead of
|
||||
spawning per-project embedded instances.
|
||||
|
||||
#### Why Not `brew services start dolt`?
|
||||
|
||||
After installing Dolt with `brew install dolt`, the natural next step is
|
||||
`brew services start dolt`. However, the Homebrew formula runs
|
||||
`dolt sql-server` without the `--config` flag, and Dolt does not auto-discover
|
||||
`config.yaml` from its working directory. The config file must be passed
|
||||
explicitly with `--config <file>`.
|
||||
|
||||
#### Setup with a Custom LaunchAgent
|
||||
|
||||
Install Dolt and initialize its data directory:
|
||||
|
||||
```bash
|
||||
brew install dolt
|
||||
cd /opt/homebrew/var/dolt && dolt init
|
||||
```
|
||||
|
||||
Configure Dolt for port 3307:
|
||||
|
||||
```yaml
|
||||
# /opt/homebrew/var/dolt/config.yaml
|
||||
log_level: info
|
||||
|
||||
listener:
|
||||
host: 127.0.0.1
|
||||
port: 3307
|
||||
max_connections: 100
|
||||
|
||||
behavior:
|
||||
autocommit: true
|
||||
```
|
||||
|
||||
Create the LaunchAgent plist:
|
||||
|
||||
```bash
|
||||
cat > ~/Library/LaunchAgents/com.local.dolt-server.plist << 'EOF'
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
||||
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>com.local.dolt-server</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/opt/homebrew/bin/dolt</string>
|
||||
<string>sql-server</string>
|
||||
<string>--config</string>
|
||||
<string>/opt/homebrew/var/dolt/config.yaml</string>
|
||||
</array>
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/opt/homebrew/var/dolt</string>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
<key>StandardOutPath</key>
|
||||
<string>/opt/homebrew/var/log/dolt.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/opt/homebrew/var/log/dolt-error.log</string>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
```
|
||||
|
||||
Load and verify the service:
|
||||
|
||||
```bash
|
||||
launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist
|
||||
mysql -h 127.0.0.1 -P 3307 -u root -e "SELECT 1"
|
||||
```
|
||||
|
||||
Point beads at the central server:
|
||||
|
||||
```bash
|
||||
export BEADS_DOLT_SERVER_MODE=1
|
||||
export BEADS_DOLT_SERVER_PORT=3307
|
||||
```
|
||||
|
||||
Manage the service:
|
||||
|
||||
```bash
|
||||
# Stop
|
||||
launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist
|
||||
|
||||
# Restart
|
||||
launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist
|
||||
launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist
|
||||
|
||||
# Check logs
|
||||
tail -f /opt/homebrew/var/log/dolt.log
|
||||
```
|
||||
|
||||
## Advanced Dolt Usage
|
||||
|
||||
The `dolt` CLI lets you operate directly on the database for power-user
|
||||
workflows. The data directory depends on your mode: `.beads/embeddeddolt/`
|
||||
(embedded) or `.beads/dolt/` (server).
|
||||
|
||||
### Branching
|
||||
|
||||
```bash
|
||||
cd .beads/dolt # or .beads/embeddeddolt for embedded mode
|
||||
dolt branch feature-x
|
||||
dolt checkout feature-x
|
||||
```
|
||||
|
||||
### Time Travel
|
||||
|
||||
```bash
|
||||
dolt log
|
||||
dolt checkout <commit-hash>
|
||||
dolt sql -q "SELECT * FROM issues"
|
||||
```
|
||||
|
||||
### Diff and Blame
|
||||
|
||||
```bash
|
||||
dolt diff main feature-x
|
||||
dolt blame issues
|
||||
```
|
||||
|
||||
## Migration Cleanup
|
||||
|
||||
After successful migration from SQLite, you may have backup files:
|
||||
|
||||
```
|
||||
.beads/beads.backup-pre-dolt-20260122-213600.db
|
||||
.beads/sqlite.backup-pre-dolt-20260123-192812.db
|
||||
```
|
||||
|
||||
These are safe to delete once you've verified Dolt is working:
|
||||
|
||||
```bash
|
||||
# Verify Dolt works
|
||||
bd list
|
||||
bd doctor
|
||||
|
||||
# Then clean up (after appropriate waiting period)
|
||||
rm .beads/*.backup-*.db
|
||||
```
|
||||
|
||||
**Recommendation:** Keep backups for at least a week before deleting.
|
||||
|
||||
## See Also
|
||||
|
||||
- [SYNC_CONCEPTS.md](SYNC_CONCEPTS.md) - The conceptual model behind cross-machine sync (Dolt source of truth, wire format, anti-patterns)
|
||||
- [SYNC_SETUP.md](SYNC_SETUP.md) - Setting up sync across multiple computers
|
||||
- [FEDERATION.md](FEDERATION.md) - Peer-to-peer federation setup
|
||||
- [CONFIG.md](CONFIG.md) - Full configuration reference
|
||||
- [DEPENDENCIES.md](DEPENDENCIES.md) - Dependencies and gates
|
||||
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git worktrees and protected branches
|
||||
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - General troubleshooting
|
||||
This guide moved to [architecture/dolt.md](architecture/dolt.md) as part of the
|
||||
Mintlify docs site under `docs/`. This pointer stays because released `bd`
|
||||
binaries and older links reference `docs/DOLT.md` (including the
|
||||
`#standalone-to-managed-city-handoff` runbook, now at
|
||||
[architecture/dolt.md](architecture/dolt.md#standalone-to-managed-city-handoff)).
|
||||
|
|
|
|||
|
|
@ -1,205 +1,6 @@
|
|||
# JSON Output Schema Contract
|
||||
|
||||
Last reviewed: 2026-05-08
|
||||
|
||||
Freshness source: `cmd/bd/output.go`, `cmd/bd/errors.go`, and
|
||||
`cmd/bd/protocol/json_contract_test.go`.
|
||||
|
||||
All `bd` commands that support `--json` output can wrap their response in
|
||||
a uniform envelope by setting `BD_JSON_ENVELOPE=1`. This will become the
|
||||
default format in v2.0.
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Opt in to the envelope format
|
||||
|
||||
```bash
|
||||
export BD_JSON_ENVELOPE=1
|
||||
```
|
||||
|
||||
### Envelope format (BD_JSON_ENVELOPE=1, default in v2.0)
|
||||
|
||||
Every `--json` command wraps output as:
|
||||
|
||||
```json
|
||||
{"schema_version": 1, "data": <original-payload>}
|
||||
```
|
||||
|
||||
The original payload is untouched inside `.data` — no type corruption,
|
||||
no field injection. Works identically for objects, arrays, and maps.
|
||||
|
||||
### Updating consumers
|
||||
|
||||
```bash
|
||||
# Before (legacy):
|
||||
bd list --json | jq '.[0].id'
|
||||
bd show beads-abc --json | jq '.title'
|
||||
|
||||
# After (envelope):
|
||||
bd list --json | jq '.data[0].id'
|
||||
bd show beads-abc --json | jq '.data.title'
|
||||
|
||||
# Version check:
|
||||
bd show beads-abc --json | jq '.schema_version'
|
||||
```
|
||||
|
||||
### Timeline
|
||||
|
||||
- **Current release**: Legacy format is default. Set `BD_JSON_ENVELOPE=1` to opt in.
|
||||
A deprecation notice is printed to stderr when `--json` is used without the env var.
|
||||
- **v2.0**: Envelope becomes the default. `BD_JSON_ENVELOPE=0` available as
|
||||
temporary escape hatch for one release cycle.
|
||||
|
||||
## Schema Version
|
||||
|
||||
Current version: **1**
|
||||
|
||||
The `schema_version` field is an integer that increments when:
|
||||
- Fields are added, renamed, or removed
|
||||
- Output structure changes (e.g., nesting depth)
|
||||
- Field types change (e.g., string to integer)
|
||||
|
||||
Additive changes (new optional fields) do NOT bump the version.
|
||||
|
||||
## Output Formats
|
||||
|
||||
### Envelope mode (BD_JSON_ENVELOPE=1)
|
||||
|
||||
All commands emit a uniform envelope:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"data": {
|
||||
"id": "beads-abc",
|
||||
"title": "Example issue",
|
||||
"status": "open"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Arrays are wrapped the same way:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"data": [
|
||||
{"id": "beads-abc", "title": "First"},
|
||||
{"id": "beads-def", "title": "Second"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Legacy mode (default, until v2.0)
|
||||
|
||||
### Object commands (show, create, close, update, etc.)
|
||||
|
||||
Commands that return a single issue or result emit a JSON object with
|
||||
`schema_version` as a top-level field alongside the data:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"id": "beads-abc",
|
||||
"title": "Example issue",
|
||||
"status": "open",
|
||||
"priority": 1,
|
||||
"issue_type": "task",
|
||||
"created_at": "2026-04-20T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### List commands (list, ready, search, stale, etc.)
|
||||
|
||||
Commands that return multiple items emit a raw JSON array:
|
||||
|
||||
```json
|
||||
[
|
||||
{"id": "beads-abc", "title": "First", ...},
|
||||
{"id": "beads-def", "title": "Second", ...}
|
||||
]
|
||||
```
|
||||
|
||||
### Error output (stderr)
|
||||
|
||||
Errors with `--json` active emit JSON to stderr:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"error": "issue not found: beads-xyz",
|
||||
"code": "not_found"
|
||||
}
|
||||
```
|
||||
|
||||
## Field Contracts by Command
|
||||
|
||||
### bd list --json
|
||||
|
||||
Required fields per item:
|
||||
- `id` (string): Issue ID (e.g., "beads-abc")
|
||||
- `title` (string): Issue title
|
||||
- `status` (string): open, in_progress, closed, deferred
|
||||
- `priority` (number): 0-4
|
||||
- `issue_type` (string): bug, feature, task, epic, chore
|
||||
- `created_at` (string): RFC3339 timestamp
|
||||
|
||||
Optional fields:
|
||||
- `description`, `owner`, `updated_at`, `closed_at`
|
||||
- `labels` (string[]): Attached labels
|
||||
- `dependencies` (object[]): Dependency records
|
||||
- `dependency_count`, `dependent_count`, `comment_count` (number)
|
||||
- `parent` (string|null): Parent issue ID
|
||||
|
||||
### bd ready --json
|
||||
|
||||
Same schema as `bd list --json`. Items are filtered to unblocked issues only.
|
||||
Each item includes `dependency_count`, `dependent_count`, `comment_count`,
|
||||
and optional `parent` fields.
|
||||
|
||||
### bd blocked --json
|
||||
|
||||
Returns issues that are blocked by unresolved dependencies.
|
||||
Each item includes all standard issue fields plus:
|
||||
- `blocked_by_count` (number): Number of blocking dependencies
|
||||
- `blocked_by` (string[]): IDs of blocking issues
|
||||
|
||||
### bd show --json
|
||||
|
||||
Returns a single object (not wrapped in `items`). Same required fields as list
|
||||
items, plus:
|
||||
- `description` (string)
|
||||
- `acceptance_criteria` (string)
|
||||
- `dependencies` (object[]): Full dependency records
|
||||
- `comments` (object[]): Comment thread
|
||||
|
||||
### `import --json`
|
||||
|
||||
Returns a summary object when `--json` is active:
|
||||
- `source` (string): File path or "stdin"
|
||||
- `created` (number): Issues created
|
||||
- `skipped` (number): Issues skipped (dedup)
|
||||
- `dedup_skipped` (number): Issues skipped by `--dedup` title match
|
||||
- `memories` (number): Memory records imported
|
||||
- `ids` (string[]): IDs of created issues
|
||||
- `dry_run` (boolean): Whether `--dry-run` was active
|
||||
|
||||
### bd export --json
|
||||
|
||||
Outputs JSONL (one JSON object per line), not wrapped in an envelope.
|
||||
Each line is a self-contained issue or memory record. `schema_version`
|
||||
is included per line.
|
||||
|
||||
## Consumer Guidelines
|
||||
|
||||
1. **Check `schema_version`** on object output. If the version is
|
||||
higher than expected, log a warning but attempt to parse anyway
|
||||
(additive changes are backward-compatible).
|
||||
|
||||
2. **For list commands**, parse the output as a JSON array directly.
|
||||
|
||||
3. **Ignore unknown fields**. New fields may be added without bumping
|
||||
the schema version.
|
||||
|
||||
4. **Use `--json` flag**, not `--format json`. The `--json` flag is
|
||||
the stable contract; `--format` is for human-readable variants.
|
||||
This reference moved to [reference/json-schema.md](reference/json-schema.md) as
|
||||
part of the Mintlify docs site under `docs/`. This pointer stays because
|
||||
released `bd` binaries reference `docs/JSON_SCHEMA.md` in schema-migration
|
||||
messages.
|
||||
|
|
|
|||
392
docs/PLUGIN.md
392
docs/PLUGIN.md
|
|
@ -1,390 +1,6 @@
|
|||
# Beads Claude Code Plugin
|
||||
|
||||
AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple slash commands and MCP tools.
|
||||
|
||||
## What is Beads?
|
||||
|
||||
Beads (`bd`) is an issue tracker designed specifically for AI-supervised coding workflows. It helps AI agents and developers:
|
||||
- Track work with a simple CLI
|
||||
- Discover and link related tasks during development
|
||||
- Maintain context across coding sessions
|
||||
- Sync issues via Dolt remotes for distributed workflows
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Install beads CLI:
|
||||
```bash
|
||||
curl -sSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
2. Install Python and uv (for MCP server):
|
||||
```bash
|
||||
# Install uv (if not already installed)
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
### Install Plugin
|
||||
|
||||
There are two ways to install the beads plugin:
|
||||
|
||||
#### Option 1: From GitHub (Recommended)
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
/plugin marketplace add gastownhall/beads
|
||||
/plugin install beads
|
||||
```
|
||||
|
||||
#### Option 2: Local Development
|
||||
|
||||
```bash
|
||||
# Clone the repository (shell command)
|
||||
git clone https://github.com/gastownhall/beads
|
||||
cd beads
|
||||
```
|
||||
|
||||
Then in Claude Code:
|
||||
|
||||
```
|
||||
# Add local marketplace (Claude Code command)
|
||||
/plugin marketplace add ./beads
|
||||
|
||||
# Install plugin
|
||||
/plugin install beads
|
||||
```
|
||||
|
||||
**Note:** If you want to install the plugin from a different repo, first `cd` to that repo's directory in your terminal, then use `./beads` (or the relative path to the beads directory) in Claude Code.
|
||||
|
||||
### Restart Claude Code
|
||||
|
||||
After installation, restart Claude Code to activate the MCP server.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize beads in your project
|
||||
/beads:init
|
||||
|
||||
# Create your first issue
|
||||
/beads:create "Set up project structure" feature 1
|
||||
|
||||
# See what's ready to work on
|
||||
/beads:ready
|
||||
|
||||
# Show full workflow guide
|
||||
/beads:workflow
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
### Version Management
|
||||
|
||||
- **`/beads:version`** - Check bd CLI, plugin, and MCP server versions
|
||||
|
||||
### Core Workflow Commands
|
||||
|
||||
- **`/beads:ready`** - Find tasks with no blockers, ready to work on
|
||||
- **`/beads:create [title] [type] [priority]`** - Create a new issue interactively
|
||||
- **`/beads:show [issue-id]`** - Show detailed information about an issue
|
||||
- **`/beads:update [issue-id] [status]`** - Update issue status or other fields
|
||||
- **`/beads:close [issue-id] [reason]`** - Close a completed issue
|
||||
|
||||
### Project Management
|
||||
|
||||
- **`/beads:init`** - Initialize beads in the current project
|
||||
- **`/beads:workflow`** - Show the AI-supervised issue workflow guide
|
||||
- **`/beads:stats`** - Show project statistics and progress
|
||||
|
||||
### Agents
|
||||
|
||||
- **`@task-agent`** - Autonomous agent that finds and completes ready tasks
|
||||
|
||||
## MCP Tools Available
|
||||
|
||||
The plugin includes a full-featured MCP server with these tools:
|
||||
|
||||
- **`init`** - Initialize bd in current directory
|
||||
- **`create`** - Create new issue (bug, feature, task, epic, chore)
|
||||
- **`list`** - List issues with filters (status, priority, type, assignee)
|
||||
- **`ready`** - Find tasks with no blockers ready to work on
|
||||
- **`show`** - Show detailed issue info including dependencies
|
||||
- **`update`** - Update issue (status, priority, design, notes, etc)
|
||||
- **`close`** - Close completed issue
|
||||
- **`dep`** - Add dependency (blocks, related, parent-child, discovered-from)
|
||||
- **`blocked`** - Get blocked issues
|
||||
- **`stats`** - Get project statistics
|
||||
|
||||
### MCP Resources
|
||||
|
||||
- **`beads://quickstart`** - Interactive quickstart guide
|
||||
|
||||
## Workflow
|
||||
|
||||
The beads workflow is designed for AI agents but works great for humans too:
|
||||
|
||||
1. **Find ready work**: `/beads:ready`
|
||||
2. **Claim your task**: `/beads:update <id> in_progress`
|
||||
3. **Work on it**: Implement, test, document
|
||||
4. **Discover new work**: Create issues for bugs/TODOs found during work
|
||||
5. **Complete**: `/beads:close <id> "Done: <summary>"`
|
||||
6. **Repeat**: Check for newly unblocked tasks
|
||||
|
||||
## Issue Types
|
||||
|
||||
- **`bug`** - Something broken that needs fixing
|
||||
- **`feature`** - New functionality
|
||||
- **`task`** - Work item (tests, docs, refactoring)
|
||||
- **`epic`** - Large feature composed of multiple issues
|
||||
- **`chore`** - Maintenance work (dependencies, tooling)
|
||||
|
||||
## Priority Levels
|
||||
|
||||
- **`0`** - Critical (security, data loss, broken builds)
|
||||
- **`1`** - High (major features, important bugs)
|
||||
- **`2`** - Medium (nice-to-have features, minor bugs)
|
||||
- **`3`** - Low (polish, optimization)
|
||||
- **`4`** - Backlog (future ideas)
|
||||
|
||||
## Dependency Types
|
||||
|
||||
- **`blocks`** - Hard dependency (issue X blocks issue Y from starting)
|
||||
- **`related`** - Soft relationship (issues are connected)
|
||||
- **`parent-child`** - Epic/subtask relationship
|
||||
- **`discovered-from`** - Track issues discovered during work
|
||||
|
||||
Only `blocks` dependencies affect the ready work queue.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Auto-Approval Configuration
|
||||
|
||||
By default, Claude Code asks for confirmation every time the beads MCP server wants to run a command. This is a security feature, but it can disrupt workflow during active development.
|
||||
|
||||
**Available Options:**
|
||||
|
||||
#### 1. Auto-Approve All Beads Tools (Recommended for Trusted Projects)
|
||||
|
||||
Add to your Claude Code `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledMcpjsonServers": ["beads"]
|
||||
}
|
||||
```
|
||||
|
||||
This auto-approves all beads commands without prompting.
|
||||
|
||||
#### 2. Auto-Approve Project MCP Servers
|
||||
|
||||
Add to your Claude Code `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enableAllProjectMcpServers": true
|
||||
}
|
||||
```
|
||||
|
||||
This auto-approves all MCP servers defined in your project's `.mcp.json` file. Useful when working across multiple projects with different MCP requirements.
|
||||
|
||||
#### 3. Manual Approval (Default)
|
||||
|
||||
No configuration needed. Claude Code will prompt for approval on each MCP tool invocation.
|
||||
|
||||
**Security Trade-offs:**
|
||||
|
||||
- **Manual approval (default)**: Maximum safety, but interrupts workflow frequently
|
||||
- **Server-level auto-approval**: Convenient for trusted projects, but allows any beads operation without confirmation
|
||||
- **Project-level auto-approval**: Good balance for multi-project workflows with project-specific trust levels
|
||||
|
||||
**Limitation:** Claude Code doesn't currently support per-tool approval granularity. You cannot auto-approve only read operations (like `bd ready`, `bd show`) while requiring confirmation for mutations (like `bd create`, `bd update`). It's all-or-nothing at the server level.
|
||||
|
||||
**Recommended Configuration:**
|
||||
|
||||
For active development on trusted projects where you're frequently using beads:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledMcpjsonServers": ["beads"]
|
||||
}
|
||||
```
|
||||
|
||||
For more information, see the [Claude Code settings documentation](https://docs.claude.com/en/docs/claude-code/settings).
|
||||
|
||||
### Environment Variables
|
||||
|
||||
The MCP server supports these environment variables:
|
||||
|
||||
- **`BEADS_PATH`** - Path to bd executable (default: `bd` in PATH)
|
||||
- **`BEADS_DB`** - Path to beads database file (default: auto-discover from cwd)
|
||||
- **`BEADS_ACTOR`** - Actor name for audit trail (default: `$USER`)
|
||||
- **`BEADS_NO_AUTO_FLUSH`** - Disable automatic sync (default: `false`)
|
||||
- **`BEADS_NO_AUTO_IMPORT`** - Disable automatic import (default: `false`)
|
||||
|
||||
To customize, edit your Claude Code MCP settings or the plugin configuration.
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Task Management
|
||||
|
||||
```bash
|
||||
# Create a high-priority bug
|
||||
/beads:create "Fix authentication" bug 1
|
||||
|
||||
# See ready work
|
||||
/beads:ready
|
||||
|
||||
# Start working on bd-10
|
||||
/beads:update bd-10 in_progress
|
||||
|
||||
# Complete the task
|
||||
/beads:close bd-10 "Fixed auth token validation"
|
||||
```
|
||||
|
||||
### Discovering Work During Development
|
||||
|
||||
```bash
|
||||
# Working on bd-10, found a related bug
|
||||
/beads:create "Add rate limiting to API" feature 2
|
||||
|
||||
# Link it to current work (via MCP tool)
|
||||
# Use `dep` tool: issue="bd-11", depends_on="bd-10", type="discovered-from"
|
||||
|
||||
# Close original task
|
||||
/beads:close bd-10 "Done, discovered bd-11 for rate limiting"
|
||||
```
|
||||
|
||||
### Using the Task Agent
|
||||
|
||||
```bash
|
||||
# Let the agent find and complete ready work
|
||||
@task-agent
|
||||
|
||||
# The agent will:
|
||||
# 1. Find ready work with `ready` tool
|
||||
# 2. Claim a task by updating status
|
||||
# 3. Execute the work
|
||||
# 4. Create issues for discoveries
|
||||
# 5. Close when complete
|
||||
# 6. Repeat
|
||||
```
|
||||
|
||||
## Auto-Sync with Dolt
|
||||
|
||||
Beads automatically commits changes to Dolt history after every write operation. This enables seamless collaboration:
|
||||
|
||||
```bash
|
||||
# Make changes
|
||||
bd create "Add feature" -p 1
|
||||
|
||||
# Changes are automatically committed to Dolt history
|
||||
# Sync with remotes when ready:
|
||||
bd dolt push
|
||||
|
||||
# Pull changes from collaborators:
|
||||
bd dolt pull
|
||||
bd ready # Shows issues ready to work on (with fresh data)
|
||||
```
|
||||
|
||||
## Updating
|
||||
|
||||
The beads plugin has three components that may need updating:
|
||||
|
||||
### 1. Plugin Updates
|
||||
|
||||
Check for plugin updates:
|
||||
```bash
|
||||
/plugin update beads
|
||||
```
|
||||
|
||||
Claude Code will pull the latest version from GitHub. After updating, **restart Claude Code** to apply MCP server changes.
|
||||
|
||||
### 2. bd CLI Updates
|
||||
|
||||
The plugin requires the `bd` CLI to be installed. Update it separately:
|
||||
|
||||
```bash
|
||||
# Quick update
|
||||
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
|
||||
# Or with Go (server-mode only)
|
||||
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
|
||||
# Or with Go (embedded-capable)
|
||||
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### 3. Version Compatibility
|
||||
|
||||
The MCP server **automatically checks** bd CLI version on startup and will fail with a clear error if your version is too old.
|
||||
|
||||
Check version compatibility manually:
|
||||
```bash
|
||||
/beads:version
|
||||
```
|
||||
|
||||
This will show:
|
||||
- bd CLI version
|
||||
- Plugin version
|
||||
- MCP server status
|
||||
- Compatibility warnings if versions mismatch
|
||||
|
||||
**Recommended update workflow:**
|
||||
1. Check versions: `/beads:version`
|
||||
2. Update bd CLI if needed (see above)
|
||||
3. Update plugin: `/plugin update beads`
|
||||
4. Restart Claude Code
|
||||
5. Verify: `/beads:version`
|
||||
|
||||
### Version Numbering
|
||||
|
||||
Beads follows semantic versioning. The plugin version tracks the bd CLI version:
|
||||
- Plugin 0.9.2 requires bd CLI >= 0.9.0 (checked automatically at startup)
|
||||
- Major version bumps may introduce breaking changes
|
||||
- Check CHANGELOG.md for release notes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Plugin not appearing
|
||||
|
||||
1. Check installation: `/plugin list`
|
||||
2. Restart Claude Code
|
||||
3. Verify `bd` is in PATH: `which bd`
|
||||
4. Check uv is installed: `which uv`
|
||||
|
||||
### MCP server not connecting
|
||||
|
||||
1. Check MCP server list: `/mcp`
|
||||
2. Look for "beads" server with plugin indicator
|
||||
3. Restart Claude Code to reload MCP servers
|
||||
4. Check logs for errors
|
||||
|
||||
### Commands not working
|
||||
|
||||
1. Make sure you're in a project with beads initialized: `/beads:init`
|
||||
2. Check if database exists: `ls -la .beads/`
|
||||
3. Try direct MCP tool access instead of slash commands
|
||||
4. Check the beads CLI works: `bd --help`
|
||||
|
||||
### MCP tool errors
|
||||
|
||||
1. Verify `bd` executable location: `BEADS_PATH` env var
|
||||
2. Check `bd` works in terminal: `bd stats`
|
||||
3. Review MCP server logs in Claude Code
|
||||
4. Try reinitializing: `/beads:init`
|
||||
|
||||
## Learn More
|
||||
|
||||
- **GitHub**: https://github.com/gastownhall/beads
|
||||
- **Documentation**: See README.md in the repository
|
||||
- **Examples**: Check `examples/` directory for integration patterns
|
||||
- **MCP Server**: See `integrations/beads-mcp/` for server details
|
||||
|
||||
## Contributing
|
||||
|
||||
Found a bug or have a feature idea? Create an issue in the beads repository!
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see LICENSE file in the repository.
|
||||
This guide moved to [integrations/claude-code-plugin.md](integrations/claude-code-plugin.md)
|
||||
as part of the Mintlify docs site under `docs/`. This pointer stays because
|
||||
released `bd` binaries reference `docs/PLUGIN.md` (for example in `bd doctor`
|
||||
fix suggestions).
|
||||
|
|
|
|||
258
docs/RECOVERY.md
258
docs/RECOVERY.md
|
|
@ -1,251 +1,11 @@
|
|||
# Recovery Playbooks
|
||||
|
||||
Last reviewed: 2026-06-09
|
||||
|
||||
Freshness source: `cmd/bd/init.go`, `cmd/bd/init_safety.go`,
|
||||
`cmd/bd/init_safety_test.go`, and `cmd/bd/dolt.go`.
|
||||
|
||||
This document lives next to the ADRs and matches the structure of `bd`'s
|
||||
error messages: each named refusal in `bd init` and `bd dolt push`/`pull`
|
||||
points here to a labeled anchor with step-by-step recovery instructions.
|
||||
|
||||
See also: `bd help init-safety`, and
|
||||
[ADR 0002 — `bd init` safety invariants](../engdocs/adr/0002-init-safety-invariants.md).
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [init-force-refused — `bd init --force`/`--reinit-local` refused because origin has Dolt history](#init-force-refused)
|
||||
- [init-token-missing — `--discard-remote` refused because `--destroy-token` is missing or wrong](#init-token-missing)
|
||||
- [init-local-exists — `bd init` refused because local data already exists](#init-local-exists)
|
||||
- [pk-fork-refused — `bd dolt pull`/`push` refused because a table has different primary keys in its common ancestor](#pk-fork-refused)
|
||||
|
||||
---
|
||||
|
||||
## init-force-refused
|
||||
|
||||
**Exit code:** `10` (`ExitRemoteDivergenceRefused`)
|
||||
|
||||
**Symptom**
|
||||
|
||||
```
|
||||
bd init refuses: remote 'origin' already has Dolt history (refs/dolt/data).
|
||||
Why: this init mode would create or reuse local history instead of
|
||||
adopting the remote. ...
|
||||
```
|
||||
|
||||
**Why this happens**
|
||||
|
||||
`bd init --force` (or `--reinit-local`) tells `bd` to bypass the local
|
||||
data-safety guard. `bd init --from-jsonl` selects a local JSONL export as
|
||||
the source. But the remote already has project history. Proceeding would
|
||||
create an orphan local Dolt branch with no common ancestor on origin. The
|
||||
next `bd dolt push` would either fail (no common ancestor) or — worse, if
|
||||
force-pushed — destroy the team's data.
|
||||
|
||||
**Recovery paths**
|
||||
|
||||
Pick the one that matches your intent.
|
||||
|
||||
### 1. You want to adopt the remote's history (most common)
|
||||
|
||||
```
|
||||
bd bootstrap
|
||||
```
|
||||
|
||||
This clones the remote's Dolt database into a fresh local `.beads/`.
|
||||
Your local state is ignored; the team's history becomes yours.
|
||||
|
||||
### 2. You want to diagnose what went wrong before deciding
|
||||
|
||||
```
|
||||
bd doctor
|
||||
bd dolt status
|
||||
```
|
||||
|
||||
`bd doctor` walks the local + remote state and names concrete problems.
|
||||
`bd dolt status` shows the Dolt-level view. Neither modifies anything.
|
||||
|
||||
### 3. You intentionally want to overwrite the remote's history (destructive)
|
||||
|
||||
This is a cross-boundary operation that affects every collaborator. You
|
||||
need to pair the local-source init (`--reinit-local` or `--from-jsonl`)
|
||||
with `--discard-remote`. In interactive mode `bd` will prompt for
|
||||
confirmation; in non-interactive mode you must supply a `--destroy-token`.
|
||||
See `bd help init-safety` for the token format.
|
||||
|
||||
After `bd init --reinit-local --discard-remote`, your next
|
||||
`bd dolt push` must be a history-replacing push. Coordinate with your
|
||||
team before doing this.
|
||||
|
||||
---
|
||||
|
||||
## init-token-missing
|
||||
|
||||
**Exit code:** `12` (`ExitDestroyTokenMissing`)
|
||||
|
||||
**Symptom**
|
||||
|
||||
```
|
||||
bd init refuses: --discard-remote requires an explicit destroy-token in non-interactive mode.
|
||||
```
|
||||
|
||||
**Why this happens**
|
||||
|
||||
You're running non-interactively (CI, agent, piped input) and passed
|
||||
`--discard-remote`. Destructive cross-boundary operations cannot be
|
||||
authorized silently.
|
||||
|
||||
**Recovery paths**
|
||||
|
||||
### 1. Run interactively
|
||||
|
||||
Re-run in a TTY. `bd init --reinit-local --discard-remote` will prompt
|
||||
you to type the destroy-token at confirmation time.
|
||||
|
||||
### 2. Supply the token explicitly (CI/automation)
|
||||
|
||||
The token format is `DESTROY-<issue-prefix>`. For a project whose issue
|
||||
prefix is `bd`:
|
||||
|
||||
```
|
||||
bd init --reinit-local --discard-remote --destroy-token=DESTROY-bd
|
||||
```
|
||||
|
||||
Automation should template the token from project state, not from error
|
||||
output. See [ADR 0002 — Invariant 4](../engdocs/adr/0002-init-safety-invariants.md)
|
||||
for why the token is never echoed in `bd`'s error messages.
|
||||
|
||||
---
|
||||
|
||||
## init-local-exists
|
||||
|
||||
**Exit code:** `11` (`ExitLocalExistsRefused`)
|
||||
|
||||
**Symptom**
|
||||
|
||||
```
|
||||
Refusing to destroy N issues in non-interactive mode.
|
||||
See 'bd help init-safety' for the required --destroy-token format.
|
||||
```
|
||||
|
||||
Or, in interactive mode, you declined the typed `destroy N issues`
|
||||
confirmation.
|
||||
|
||||
**Why this happens**
|
||||
|
||||
Local `.beads/` has existing issues. `bd init --reinit-local` would
|
||||
permanently destroy them.
|
||||
|
||||
**Recovery paths**
|
||||
|
||||
### 1. Export first, then proceed
|
||||
|
||||
```
|
||||
bd export > issue-export.jsonl
|
||||
bd init --reinit-local
|
||||
```
|
||||
|
||||
`issue-export.jsonl` lets you re-import individual issues if needed. It is not
|
||||
a full database backup; use `bd backup` when the Dolt database is healthy
|
||||
enough to create a restorable backup before reinitializing.
|
||||
|
||||
### 2. Investigate why you hit this
|
||||
|
||||
If you did NOT expect `bd init` to be the right command here, run
|
||||
`bd doctor` first — you may be looking at a server config issue that a
|
||||
re-init won't fix.
|
||||
|
||||
---
|
||||
|
||||
## pk-fork-refused
|
||||
|
||||
**Symptom**
|
||||
|
||||
```
|
||||
$ bd dolt pull
|
||||
Error: ... cannot merge because table dependencies has different primary keys in its common ancestor
|
||||
```
|
||||
|
||||
(or the variant without `in its common ancestor`). `bd` follows the error
|
||||
with a short version of the recovery recipe below.
|
||||
|
||||
**Why this happens**
|
||||
|
||||
The two histories being merged disagree about a table's *primary key set* —
|
||||
not about row contents. Dolt can cell-merge rows, but it refuses outright to
|
||||
merge a table whose primary key was reshaped differently on each side (or
|
||||
whose common ancestor had a different primary key than both sides). The
|
||||
refusal happens before any row conflicts materialize, so `bd dolt pull`'s
|
||||
conflict auto-resolver never gets a chance to run. **Retrying never helps**:
|
||||
the histories are permanently un-mergeable.
|
||||
|
||||
The usual cause is upgrading `bd` independently on two clones while un-synced
|
||||
changes existed on both sides, across a release whose schema migrations
|
||||
reshape a primary key. Concretely: the
|
||||
[#4259](https://github.com/gastownhall/beads/issues/4259) incident — clones
|
||||
straddling the `0041`/`0043`/`0050` reshapes of `dependencies` (v1.0.4 →
|
||||
v1.0.6) hit exactly this on the first post-upgrade pull if both sides had
|
||||
unpushed dependency edits.
|
||||
|
||||
The remote-migrate prevention gate (v1.0.6+) exists to stop this from being
|
||||
created: it refuses to auto-migrate a remote-backed database and tells you to
|
||||
designate a single migrator. This playbook is for when the fork already
|
||||
exists.
|
||||
|
||||
**Recovery: bootstrap from one canonical clone**
|
||||
|
||||
The forked histories cannot be merged, so one side must be chosen as
|
||||
canonical and every other clone re-cloned from it. Issue *data* survives via
|
||||
JSONL export/import; only the un-mergeable Dolt *history* is discarded on the
|
||||
non-canonical clones.
|
||||
|
||||
### 1. Pick the canonical clone
|
||||
|
||||
Usually the most complete / most recently active clone. To compare, run on
|
||||
each clone (read-only):
|
||||
|
||||
```
|
||||
bd stats
|
||||
bd dolt status
|
||||
```
|
||||
|
||||
### 2. On the canonical clone: upgrade, migrate, force-push
|
||||
|
||||
```
|
||||
bd version # confirm the new bd binary
|
||||
bd doctor # sanity-check before publishing
|
||||
bd dolt push --force # make the remote authoritative
|
||||
```
|
||||
|
||||
(`bd`'s migration gate may block here; run `bd migrate --force` on the
|
||||
canonical clone — that is exactly the designated-migrator case the gate is
|
||||
asking about. `BD_ALLOW_REMOTE_MIGRATE=1` is the env-var equivalent for
|
||||
scripted use.)
|
||||
|
||||
### 3. On EVERY other clone: save local-only work, re-clone, re-apply
|
||||
|
||||
```
|
||||
bd export --all -o /tmp/beads-local.jsonl # safety net for un-synced work
|
||||
rm -rf .beads/dolt # discard the un-mergeable history
|
||||
bd bootstrap # re-clone from the remote
|
||||
bd import /tmp/beads-local.jsonl # re-apply local-only work
|
||||
```
|
||||
|
||||
`bd import` has upsert semantics: issues that only existed on this clone are
|
||||
re-created, newer local edits are applied, and rows older than what the
|
||||
remote already has are skipped. Spot-check with `bd stats` afterwards.
|
||||
|
||||
### Prevention (upgrades across PK-reshaping migrations)
|
||||
|
||||
- **Sync before upgrading**: `bd dolt push` + `bd dolt pull` on every clone
|
||||
while all clones still run the *old* version, then stop editing. Once the new
|
||||
binary is installed, `bd dolt push`/`bd dolt pull` are gated too, so this must
|
||||
happen first.
|
||||
- **One designated migrator**: upgrade one machine, let it migrate, then
|
||||
`bd dolt push`.
|
||||
- **Every other clone adopts, does not pull**: after the migrator pushes, each
|
||||
other clone upgrades the binary and runs `bd bootstrap` to adopt the migrated
|
||||
database. `bd dolt pull` is *refused* while the clone still has pending
|
||||
migrations, so do not rely on it; the "sync before" step above is what
|
||||
preserves these clones' work, because `bd bootstrap` replaces the local
|
||||
database.
|
||||
The pattern-coded recovery playbooks moved to
|
||||
[recovery/init-safety.md](recovery/init-safety.md) as part of the Mintlify docs
|
||||
site under `docs/`. This pointer stays because released `bd` binaries link to
|
||||
`docs/RECOVERY.md` runbooks by anchor:
|
||||
|
||||
- `#init-force-refused` → [recovery/init-safety.md](recovery/init-safety.md#init-force-refused)
|
||||
- `#init-token-missing` → [recovery/init-safety.md](recovery/init-safety.md#init-token-missing)
|
||||
- `#init-local-exists` → [recovery/init-safety.md](recovery/init-safety.md#init-local-exists)
|
||||
- `#pk-fork-refused` → [recovery/init-safety.md](recovery/init-safety.md#pk-fork-refused)
|
||||
|
|
|
|||
|
|
@ -1,277 +1,6 @@
|
|||
# Storage Backends
|
||||
|
||||
Beads uses Dolt as its default storage backend, and Dolt remains the reference implementation. You can also point `bd` at Postgres, MySQL, or SQLite — every backend implements the full issue-tracking core, and the only thing you give up off Dolt is version control.
|
||||
|
||||
One seam, one shared core: the issue-tracking semantics are written once (in `issueops`) and shared by *every* backend — Dolt runs them natively, the SQL family runs them through one thin per-engine dialect. Each backend is a store adapter over that shared core. Version control lives only in the Dolt store; on the SQL backends it returns one clean, typed error.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
CLI["bd CLI"] --> SEAM["Storage interface<br/>one seam — every backend satisfies all of it"]
|
||||
|
||||
SEAM --> CORE["CORE — issueops<br/>CRUD · search · deps · ready/claim · ordering · id-mint<br/>written once, shared by EVERY backend"]
|
||||
SEAM --> CAPS["CAPABILITIES — version control<br/>history · branch · remotes · sync"]
|
||||
|
||||
CORE --> DS["Dolt store<br/>runs the core natively"]
|
||||
CORE --> KIT["sqlkit.Store<br/>SQL-family adapter · Dialect / Readiness / Claim"]
|
||||
|
||||
DS --> DOLT[("Dolt — embedded / server<br/>the conformance ORACLE")]
|
||||
KIT --> PGD["pgdialect"] --> PG[("Postgres")]
|
||||
KIT --> MYD["mysqldialect"] --> MY[("MySQL")]
|
||||
KIT --> LTD["sqlitedialect"] --> LT[("SQLite")]
|
||||
|
||||
CAPS -->|"implemented in the Dolt store"| DS
|
||||
CAPS -->|"generated typed-unsupported shell"| SHELL["Postgres / MySQL / SQLite<br/>operation X not supported"]
|
||||
|
||||
DOLT -. "conformance-tested: SQL family matches Dolt byte-for-byte" .-> KIT
|
||||
```
|
||||
|
||||
<details>
|
||||
<summary>Plain-text version of the diagram</summary>
|
||||
|
||||
```
|
||||
bd CLI
|
||||
|
|
||||
Storage interface
|
||||
|
|
||||
+-------------------------+--------------------------+
|
||||
| |
|
||||
CORE (every backend) CAPABILITIES (Dolt-only)
|
||||
issueops -- CRUD, search, deps, version control:
|
||||
ready/claim, ordering, id-mint, history, branch, remotes, sync
|
||||
cycle checks: written ONCE |
|
||||
| +-> Dolt store: implemented
|
||||
+--------------------+ +-> Postgres/MySQL/SQLite:
|
||||
| | generated typed-"unsupported"
|
||||
Dolt store sqlkit.Store (operation "X" not supported)
|
||||
runs the core SQL-family adapter
|
||||
natively (Dialect/Readiness/Claim)
|
||||
| |
|
||||
[Dolt engine] +------+------+---------+
|
||||
embedded/server pgdialect mysqldialect sqlitedialect
|
||||
= conformance | | |
|
||||
ORACLE Postgres MySQL SQLite
|
||||
|
||||
issueops is shared by EVERY backend (Dolt included); each backend is a store
|
||||
adapter over it. Dolt runs the core's SQL natively and adds version control;
|
||||
the SQL family runs it through one thin dialect per engine, and is
|
||||
conformance-tested to match the Dolt oracle byte-for-byte.
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Why Choose a Backend?
|
||||
|
||||
- **Dolt stays the default** — `bd init` with no flags behaves exactly as before, and Dolt is the only backend with history, branching, and sync
|
||||
- **Postgres / MySQL** — put your issues in the database your team already runs, backs up, and monitors; many writers, one server
|
||||
- **SQLite** — a single file inside `.beads/`, zero servers, zero credentials, pure-Go driver
|
||||
- **Same `bd` everywhere** — create, list, ready, deps, claims, labels, comments, search all behave identically on every backend; conformance tests enforce it against the Dolt reference
|
||||
- **Clean degradation** — Dolt-only commands don't half-work on SQL backends; they return one clear, typed error
|
||||
|
||||
## Pick Your Backend
|
||||
|
||||
| Backend | Best for | History | Server needed | Credentials |
|
||||
|---|---|---|---|---|
|
||||
| `dolt` (default) | Solo or team work where you want issue history, branching, `bd dolt push`/`pull` | Yes | No (embedded) / optional | Only in server mode |
|
||||
| `sqlite` | Solo work, throwaway workspaces, CI sandboxes, air-gapped machines | No | No | None |
|
||||
| `postgres` | Teams with an existing Postgres; many workspaces share one database via per-workspace schemas | No | Yes | Ladder (below) |
|
||||
| `mysql` | Teams with an existing MySQL; each workspace gets its own database | No | Yes | Ladder (below) |
|
||||
|
||||
Rules of thumb:
|
||||
|
||||
- If you want `bd history`, `bd dolt push`, time-travel, or federation — use **Dolt**. It is the only backend that tracks history.
|
||||
- If you want the smallest possible footprint and don't need history — use **SQLite**.
|
||||
- If your organization already operates Postgres or MySQL and you want issues living next to everything else your DBAs manage — use **Postgres** or **MySQL**. Multi-writer concurrency comes from the database server itself.
|
||||
- If in doubt, use the default. `bd init` without `--backend` is Dolt, unchanged.
|
||||
|
||||
## Getting Started
|
||||
|
||||
The backend is chosen once, at `bd init` time, and recorded in `.beads/metadata.json`. Every later `bd` command reads it from there — no per-command flags.
|
||||
|
||||
### Dolt (default)
|
||||
|
||||
```bash
|
||||
bd init --prefix myproj
|
||||
```
|
||||
|
||||
Nothing changes. See [DOLT.md](DOLT.md) for embedded vs. server mode.
|
||||
|
||||
### SQLite
|
||||
|
||||
```bash
|
||||
bd init --backend=sqlite --prefix myproj
|
||||
|
||||
# Optional: choose the database file (relative to .beads/; default beads.db)
|
||||
bd init --backend=sqlite --sqlite-path=issues.db --prefix myproj
|
||||
```
|
||||
|
||||
That's it — no server, no credentials. Foreign keys and immediate-transaction locking are configured automatically.
|
||||
|
||||
### Postgres
|
||||
|
||||
Each Beads workspace lives in its own Postgres **schema**, so many workspaces can share one database.
|
||||
|
||||
```bash
|
||||
bd init --backend=postgres \
|
||||
--pg-url='postgres://bd:onlyforinit@db.example.com:5432/beads?sslmode=require' \
|
||||
--pg-schema=myproj \
|
||||
--prefix myproj
|
||||
```
|
||||
|
||||
- `--pg-url` — a standard `postgres://` URL. If omitted, `bd init` falls back to the `BEADS_POSTGRES_URL` environment variable.
|
||||
- `--pg-schema` — the schema this workspace owns; created and pinned via `search_path`.
|
||||
|
||||
> **Note:** `bd init` connects with the URL exactly as given, so embed the password
|
||||
> in `--pg-url` for init. It is stripped before anything is written to disk —
|
||||
> `.beads/metadata.json` stores only the password-free DSN — and every later
|
||||
> command resolves the password through the credential ladder below.
|
||||
|
||||
```bash
|
||||
# For all subsequent commands, supply the password via any ladder rung, e.g.:
|
||||
export BEADS_PG_PASSWORD_COMMAND='vault kv get -field=password secret/beads/pg'
|
||||
|
||||
bd create "first issue" -p 1
|
||||
bd ready
|
||||
```
|
||||
|
||||
### MySQL
|
||||
|
||||
Each Beads workspace gets its own MySQL **database**.
|
||||
|
||||
```bash
|
||||
bd init --backend=mysql \
|
||||
--mysql-url='bd:onlyforinit@tcp(db.example.com:3306)/' \
|
||||
--mysql-database=myproj_beads \
|
||||
--prefix myproj
|
||||
```
|
||||
|
||||
- `--mysql-url` — go-sql-driver DSN grammar: `user:password@tcp(host:port)/` (note the trailing slash, no scheme). Falls back to `BEADS_MYSQL_URL` if omitted.
|
||||
- `--mysql-database` — the database this workspace owns.
|
||||
|
||||
Same rule as Postgres: embed the password in `--mysql-url` for init only; it is redacted before persisting, and later commands use the ladder:
|
||||
|
||||
```bash
|
||||
export BEADS_MYSQL_PASSWORD_COMMAND='vault kv get -field=password secret/beads/mysql'
|
||||
# or a static password:
|
||||
export BEADS_MYSQL_PASSWORD=...
|
||||
```
|
||||
|
||||
> **Note:** the MySQL DSN grammar cannot carry a password without a username.
|
||||
> `bd` refuses such DSNs loudly rather than silently connecting passwordless.
|
||||
|
||||
## Credentials & Override Layers
|
||||
|
||||
SQLite needs no credentials. For Postgres and MySQL, the password is resolved fresh at open time by a **ladder** of sources, highest priority first. The first *configured* rung wins, and a configured rung that fails aborts the connection — it never silently falls through to a lower rung.
|
||||
|
||||
Precedence, per backend:
|
||||
|
||||
1. **Password embedded in the DSN** — a password inside `BEADS_POSTGRES_URL` / `BEADS_MYSQL_URL` wins outright; no ladder runs.
|
||||
2. **Credential command** — `BEADS_PG_PASSWORD_COMMAND` / `BEADS_MYSQL_PASSWORD_COMMAND`
|
||||
3. **Static env var** — `BEADS_PG_PASSWORD` / `BEADS_MYSQL_PASSWORD`
|
||||
4. **Credentials file** — an entry matching the DSN's `host:port`
|
||||
5. **Driver-native fallback** — Postgres only: `PGPASSWORD`, `~/.pgpass`, `PGPASSFILE` still work when nothing above is configured. MySQL has no driver-native fallback; with nothing configured it attempts an empty password.
|
||||
|
||||
> **Note the naming asymmetry:** the URL variables use full names
|
||||
> (`BEADS_POSTGRES_URL`, `BEADS_MYSQL_URL`) while the password variables
|
||||
> abbreviate Postgres (`BEADS_PG_PASSWORD`, `BEADS_PG_PASSWORD_COMMAND`).
|
||||
> There is no `BEADS_PG_URL`.
|
||||
|
||||
### The credential command (rotating secrets)
|
||||
|
||||
This is the same idiom as kubectl's ExecCredential, the AWS CLI's `credential_process`, and git credential helpers: `bd` runs your command with `sh -c` (30-second timeout) and reads the secret from stdout. Output can be a bare token, a kubectl-style JSON envelope (`{"token": "...", "expirationTimestamp": "..."}`), or an OAuth-style one (`{"access_token": "...", "expires_in": 900}`). Results are cached in-process and refreshed shortly before expiry, so repeated opens don't re-spawn your helper.
|
||||
|
||||
```bash
|
||||
# Vault
|
||||
export BEADS_PG_PASSWORD_COMMAND="vault kv get -field=password secret/beads/pg"
|
||||
|
||||
# AWS RDS IAM auth (15-minute tokens; caching and expiry are handled for you)
|
||||
export BEADS_PG_PASSWORD_COMMAND="aws rds generate-db-auth-token \
|
||||
--hostname db.example.com --port 5432 --username bd"
|
||||
```
|
||||
|
||||
The command variables are read from the environment only — never from workspace metadata — because a persisted command would be arbitrary code executed on every `bd` invocation.
|
||||
|
||||
### The credentials file (static, per-host)
|
||||
|
||||
The lowest configured rung is an INI-style file keyed by `host:port`, at `~/.config/beads/credentials` (Linux/macOS) or `%APPDATA%\beads\credentials` (Windows); override the path with `BEADS_CREDENTIALS_FILE`.
|
||||
|
||||
```ini
|
||||
# ~/.config/beads/credentials (chmod 600)
|
||||
[127.0.0.1:5432]
|
||||
password=localDevPassword
|
||||
|
||||
[db.example.com:3306]
|
||||
password=teamServerPassword
|
||||
```
|
||||
|
||||
If the file is readable by group or others, `bd` prints an ssh-style warning. The file rung is deliberately forgiving: a missing file or unmatched section just means "not configured" and the ladder continues — fail-closed behavior is reserved for rungs you explicitly configured, like a command.
|
||||
|
||||
### Dolt server credentials
|
||||
|
||||
The Dolt backend in server mode has its own rungs: `BEADS_DOLT_PASSWORD`, then the credentials file, with `BEADS_DOLT_SERVER_USER` overriding the username. There is also `BEADS_DOLT_CREDENTIAL_COMMAND`, an *identity* credential: the minted token is presented as the connection username to an authenticating gateway server, which verifies it and routes to the database. This is for gateway deployments only — the direct Postgres/MySQL backends reject `BEADS_PG_CREDENTIAL_COMMAND` / `BEADS_MYSQL_CREDENTIAL_COMMAND` with an error telling you to use the `_PASSWORD_COMMAND` form instead.
|
||||
|
||||
### Secrets never reach disk
|
||||
|
||||
`bd init` redacts the password from your URL before writing `.beads/metadata.json`, using the database driver's own parser, and then re-parses to verify nothing survived — refusing to init rather than persisting a secret it can't prove is gone. Check for yourself:
|
||||
|
||||
```bash
|
||||
cat .beads/metadata.json
|
||||
# {"backend":"postgres","postgres_dsn":"postgres://bd@db.example.com:5432/beads?sslmode=require", ...}
|
||||
```
|
||||
|
||||
## What You Keep and What You Give Up
|
||||
|
||||
Every backend implements the complete issue-tracking core — the same shared implementation, not a re-derivation per backend:
|
||||
|
||||
- Issue CRUD, bulk creates, close/reopen/delete
|
||||
- Search, counts, filtering, sorting
|
||||
- Dependencies, cycle detection, dependency trees
|
||||
- Ready/blocked work queries, claims and leases
|
||||
- Labels, comments, the full event/audit trail
|
||||
- Config, metadata slots, statistics, transactions, streaming iterators
|
||||
|
||||
What is Dolt-only — by design, since these *are* version control:
|
||||
|
||||
- **History & time travel** — `bd history`, as-of queries, diffs
|
||||
- **Branching & merging** — branch, checkout, merge, conflict resolution
|
||||
- **Remotes & sync** — `bd dolt push` / `bd dolt pull`, fetch, sync
|
||||
- **Federation** — peer management
|
||||
- **Compaction** — snapshot-based memory compaction
|
||||
|
||||
On Postgres, MySQL, and SQLite these operations don't limp along or approximate — each returns one clean, typed error:
|
||||
|
||||
```
|
||||
$ bd history myproj-9q9
|
||||
Error: failed to get history: operation "History" not supported by the sqlite backend
|
||||
```
|
||||
|
||||
`bd init` sets the expectation up front:
|
||||
|
||||
```
|
||||
✓ bd initialized with the SQLite backend
|
||||
History: not tracked (SQLite backend has no version control; use Dolt for history)
|
||||
```
|
||||
|
||||
A few practical consequences:
|
||||
|
||||
- Writes on SQL backends are durable the moment the command returns — each write commits its own SQL transaction. (`bd`'s internal commit hooks become harmless no-ops, not errors.)
|
||||
- The Dolt-only maintenance tail (auto-commit, auto-export, auto-backup, auto-push) is skipped automatically on non-Dolt backends.
|
||||
- "Sync" on Postgres/MySQL is your database server: everyone connects to the same database, so there is nothing to push or pull. Back up issues with your normal database tooling, or `bd export` for JSONL interoperability.
|
||||
|
||||
## How It Stays Correct
|
||||
|
||||
The SQL backends are held to the embedded-Dolt reference by a conformance harness, run locally and in CI (with real Postgres and MySQL servers) on every pull request:
|
||||
|
||||
- **Tier 1 (in-process):** the same behavior corpus the Dolt reference passes — CRUD, search, dependencies, ready/blocked, claims and leases, plus a ~94-case audit corpus of edge behaviors — runs against every backend. Two extra gates make capability gaps impossible to hide: a completeness test proves the set of unsupported operations exactly matches an audited allowlist, and a contract test calls every one of them to prove it returns the typed error rather than panicking or lying.
|
||||
- **Tier 2 (end-to-end):** a real `bd` binary runs `bd init --backend=...` and a CLI scenario corpus in an isolated workspace per backend, and the normalized output must be byte-identical to the Dolt reference. Known-divergence entries are visible in the registry and can only shrink — currently there are none.
|
||||
|
||||
```bash
|
||||
./scripts/conformance.sh
|
||||
# Postgres/MySQL profiles self-skip unless you point them at a server:
|
||||
BEADS_PG_TEST_URL="postgres://user:pass@127.0.0.1:5432/beads_test" \
|
||||
BEADS_MYSQL_TEST_URL="user:pass@tcp(127.0.0.1:3306)/" \
|
||||
./scripts/conformance.sh
|
||||
```
|
||||
|
||||
Adding a new backend is one declarative profile entry in `test/conformance/profiles.go` plus a store-factory arm; both tiers pick it up automatically.
|
||||
|
||||
See [DOLT.md](DOLT.md) for the default backend, [CONFIG.md](CONFIG.md) for configuration, and [TROUBLESHOOTING.md](TROUBLESHOOTING.md) if a connection misbehaves.
|
||||
This guide moved to [architecture/storage-backends.md](architecture/storage-backends.md)
|
||||
as part of the Mintlify docs site under `docs/`. This pointer stays because
|
||||
released `bd` binaries reference `docs/STORAGE-BACKENDS.md` (for example in
|
||||
`bd init --backend` help).
|
||||
|
|
|
|||
739
docs/architecture/dolt.md
Normal file
739
docs/architecture/dolt.md
Normal file
|
|
@ -0,0 +1,739 @@
|
|||
---
|
||||
title: Dolt Backend for Beads
|
||||
---
|
||||
|
||||
Beads uses Dolt as its storage backend. Dolt provides a version-controlled SQL database with cell-level merge, native branching, and two deployment modes.
|
||||
|
||||
## Why Dolt?
|
||||
|
||||
- **Native version control** — cell-level diffs and merges, not line-based
|
||||
- **Multi-writer support** — server mode enables concurrent agents
|
||||
- **Built-in history** — every write creates a Dolt commit
|
||||
- **Native branching** — Dolt branches independent of git branches
|
||||
- **Single-binary option** — embedded mode for solo users (no server needed)
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Install Dolt (Server Mode Only)
|
||||
|
||||
Embedded mode includes everything in the `bd` binary; no separate Dolt install
|
||||
is needed. Install the standalone `dolt` CLI only when you want to run server
|
||||
mode or work directly with the database via `dolt sql`.
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install dolt
|
||||
|
||||
# Linux
|
||||
curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash
|
||||
|
||||
# Verify installation
|
||||
dolt version
|
||||
```
|
||||
|
||||
### New Project
|
||||
|
||||
```bash
|
||||
# Embedded mode (single writer, no server — default for standalone)
|
||||
bd init
|
||||
|
||||
# Server mode (multi-writer, e.g. orchestrator)
|
||||
gt dolt start # Start the Dolt server
|
||||
bd init --server # Initialize with server mode
|
||||
```
|
||||
|
||||
### Migrate from SQLite (Legacy)
|
||||
|
||||
If upgrading from an older version that used SQLite:
|
||||
|
||||
> **Note:** The `bd migrate --to-dolt` command was removed in v0.58.0.
|
||||
> For pre-0.50 installations with JSONL data, use the migration script:
|
||||
>
|
||||
> ```bash
|
||||
> scripts/migrate-jsonl-to-dolt.sh
|
||||
> ```
|
||||
>
|
||||
> See [Troubleshooting](/reference/troubleshooting#circuit-breaker-server-appears-down-failing-fast) if you encounter connection errors after migration.
|
||||
|
||||
Migration creates backups automatically. Your original SQLite database is preserved as `beads.backup-pre-dolt-*.db`.
|
||||
|
||||
## Modes of Operation
|
||||
|
||||
### Embedded Mode (Solo / Standalone)
|
||||
|
||||
In-process Dolt engine — no separate server needed. This is the default for
|
||||
standalone Beads users. The `bd` binary includes everything; just `bd init` and go.
|
||||
|
||||
- Single-writer (one process at a time)
|
||||
- Data lives in `.beads/embeddeddolt/` alongside your code
|
||||
- Push to GitHub with `bd dolt push` — code and issues in one repo
|
||||
- Zero ops: no server, no ports, no PID files
|
||||
|
||||
### Server Mode (Multi-Writer / Orchestrator)
|
||||
|
||||
Connects to a running `dolt sql-server` for multi-client access.
|
||||
|
||||
```bash
|
||||
# Start the server (orchestrator)
|
||||
gt dolt start
|
||||
|
||||
# Or manually
|
||||
cd ~/.dolt-data/beads && dolt sql-server --port 3307
|
||||
```
|
||||
|
||||
```bash
|
||||
# Initialize in server mode
|
||||
bd init --server
|
||||
|
||||
# Or switch via environment variable
|
||||
export BEADS_DOLT_SERVER_MODE=1
|
||||
```
|
||||
|
||||
```yaml
|
||||
# .beads/config.yaml (server mode settings)
|
||||
dolt:
|
||||
mode: server
|
||||
host: 127.0.0.1
|
||||
port: 3307
|
||||
user: root
|
||||
```
|
||||
|
||||
Switch to server mode when you need:
|
||||
- Multiple agents writing simultaneously
|
||||
- Orchestrator multi-rig setups
|
||||
- Federation with remote peers
|
||||
|
||||
## Migrating Between Backends
|
||||
|
||||
You can migrate data between embedded mode and server mode using `bd backup`.
|
||||
Both directions preserve full Dolt commit history.
|
||||
|
||||
`bd export` is not a substitute for this flow. JSONL exports contain issue
|
||||
records from the issues table for migration and interoperability; they do not
|
||||
capture Dolt branches, full commit history, working-set state, or non-issue
|
||||
tables. Use `bd backup` or a manual Dolt backup when you need a restorable
|
||||
database backup.
|
||||
|
||||
### Server → Embedded
|
||||
|
||||
1. **Create a backup from the server-mode project:**
|
||||
|
||||
```bash
|
||||
# In the server-mode project directory
|
||||
bd backup init /path/to/backup-dir
|
||||
bd backup sync
|
||||
```
|
||||
|
||||
2. **Create a new embedded-mode project and restore:**
|
||||
|
||||
```bash
|
||||
mkdir new-project && cd new-project
|
||||
bd init # creates an embedded-mode project by default
|
||||
bd backup restore --force /path/to/backup-dir
|
||||
```
|
||||
|
||||
`--force` overwrites the freshly-initialized database with the backup
|
||||
contents. The restore automatically:
|
||||
- Updates `metadata.json` to match the restored project identity
|
||||
- Registers the backup directory for future `bd backup sync`
|
||||
- Backfills the embedded migration tracker (`schema_migrations`)
|
||||
|
||||
3. **Verify:**
|
||||
|
||||
```bash
|
||||
bd list
|
||||
bd backup status
|
||||
```
|
||||
|
||||
### Embedded → Server
|
||||
|
||||
1. **Create a backup from the embedded-mode project:**
|
||||
|
||||
```bash
|
||||
# In the embedded-mode project directory
|
||||
bd backup init /path/to/backup-dir
|
||||
bd backup sync
|
||||
```
|
||||
|
||||
2. **Create a new server-mode project and restore:**
|
||||
|
||||
```bash
|
||||
mkdir new-project && cd new-project
|
||||
bd init --server # creates a server-mode project
|
||||
bd backup restore --force /path/to/backup-dir
|
||||
```
|
||||
|
||||
3. **Verify:**
|
||||
|
||||
```bash
|
||||
bd list
|
||||
bd backup status
|
||||
```
|
||||
|
||||
### Backup Commands Reference
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bd backup init <path>` | Register a backup destination (filesystem or DoltHub URL) |
|
||||
| `bd backup sync` | Push database to the configured backup destination |
|
||||
| `bd backup restore [path]` | Restore from a backup directory (`--force` to overwrite) |
|
||||
| `bd backup remove` | Unregister the backup destination |
|
||||
| `bd backup status` | Show backup configuration and last sync time |
|
||||
|
||||
### Notes
|
||||
|
||||
- Data locations differ between modes: `.beads/embeddeddolt/` (embedded) vs `.beads/dolt/` (server)
|
||||
- The backup directory is a full Dolt backup, not an `issues.jsonl` export — it can be on a local drive, NAS, or DoltHub
|
||||
- You can also migrate via Dolt remotes (`bd dolt push` / `bd dolt pull`) if both projects share a remote
|
||||
|
||||
The sections below are the canonical backend migration reference.
|
||||
|
||||
## Federation (Peer-to-Peer Sync)
|
||||
|
||||
Federation lets independent Dolt-backed workspaces ("towns") sync issues
|
||||
directly with each other via `bd federation add-peer`/`sync`/`status`,
|
||||
without a central hub. Credentials are AES-256 encrypted and stored locally.
|
||||
|
||||
See [FEDERATION.md](/multi-agent/federation) for the full setup guide, including
|
||||
peer configuration, sovereignty tiers, sync/status/topology details, and
|
||||
troubleshooting.
|
||||
|
||||
## Dolt Remotes
|
||||
|
||||
Use `bd dolt remote add` to configure remotes. This ensures the running Dolt SQL
|
||||
server sees the remote immediately. Remotes added directly with the `dolt` CLI
|
||||
are written to filesystem config and may not be visible to the server until
|
||||
restart.
|
||||
|
||||
```bash
|
||||
# DoltHub (public or private)
|
||||
bd dolt remote add origin https://doltremoteapi.dolthub.com/org/beads
|
||||
|
||||
# S3
|
||||
bd dolt remote add origin aws://[bucket]/path/to/repo
|
||||
|
||||
# GCS
|
||||
bd dolt remote add origin gs://[bucket]/path/to/repo
|
||||
|
||||
# Git SSH (GitHub, GitLab, etc.)
|
||||
bd dolt remote add origin git+ssh://git@github.com/org/repo.git
|
||||
|
||||
# Local file system
|
||||
bd dolt remote add origin file:///path/to/remote
|
||||
```
|
||||
|
||||
### Push/Pull
|
||||
|
||||
```bash
|
||||
bd dolt push
|
||||
bd dolt pull
|
||||
```
|
||||
|
||||
`bd dolt remote add` registers the remote through the Dolt store API. SQL
|
||||
remotes are the source of truth for `bd dolt remote list`, `bd dolt push`, and
|
||||
`bd dolt pull`.
|
||||
|
||||
For git-protocol remotes, credentialed external-server remotes, and cloud
|
||||
remotes whose credentials are only present in the current shell, `bd dolt push`
|
||||
and `bd dolt pull` automatically materialize a matching local CLI remote before
|
||||
using the `dolt` CLI transport. The CLI remote is a local transport mirror, not
|
||||
a separate configuration source.
|
||||
|
||||
If you are upgrading from an older beads version and previously added remotes
|
||||
with raw `dolt remote add`, re-register them with `bd dolt remote add <name>
|
||||
<url>` so they are visible through SQL. `bd doctor` reports legacy CLI-only or
|
||||
mismatched CLI remotes under `Dolt Remote Migration`.
|
||||
|
||||
> **Sharing a Git repo**: Dolt stores data under `refs/dolt/data`, separate
|
||||
> from standard Git refs (`refs/heads/`, `refs/tags/`). You can safely point a
|
||||
> `git+ssh://` remote at the same repository as your project source code. See
|
||||
> [Dolt Git Remotes](https://docs.dolthub.com/concepts/dolt/git/remotes).
|
||||
|
||||
### List/Remove Remotes
|
||||
|
||||
```bash
|
||||
bd dolt remote list # Shows SQL-configured remotes
|
||||
bd dolt remote remove origin # Removes the remote
|
||||
```
|
||||
|
||||
## Contributor Onboarding (Clone Bootstrap)
|
||||
|
||||
When someone clones a repository that uses Dolt backend:
|
||||
|
||||
1. Run `bd bootstrap` in the clone
|
||||
2. If the git remote has `refs/dolt/data` (pushed via `bd dolt push`),
|
||||
`bd bootstrap` auto-detects it and clones the database from the remote
|
||||
3. Work continues normally — all existing issues are available
|
||||
|
||||
**No manual steps required** beyond `bd bootstrap`. The auto-detect:
|
||||
- Probes `origin` for `refs/dolt/data`
|
||||
- Clones the Dolt database from the remote (instead of creating a fresh one)
|
||||
- Configures the Dolt remote for future `bd dolt push`/`pull`
|
||||
|
||||
If `sync.remote` is set in `.beads/config.yaml`, that takes precedence
|
||||
over auto-detection. Any Dolt-compatible remote URL is supported (DoltHub,
|
||||
S3, GCS, file, or git). On brand-new projects, `bd init` auto-detects
|
||||
`git origin` and persists it as `sync.remote`, so the first `bd dolt push`
|
||||
publishes Dolt history to `refs/dolt/data` on the same git remote.
|
||||
|
||||
### Verifying Bootstrap Worked
|
||||
|
||||
```bash
|
||||
bd list # Should show issues
|
||||
bd vc log # Should show initial commit
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server Not Running
|
||||
|
||||
**Symptom:** Connection refused errors when using server mode.
|
||||
|
||||
```
|
||||
failed to create database: dial tcp 127.0.0.1:3307: connect: connection refused
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```bash
|
||||
gt dolt start # Orchestrator command
|
||||
# Or
|
||||
gt dolt status # Check if running
|
||||
```
|
||||
|
||||
### Bootstrap Not Running
|
||||
|
||||
**Symptom:** `bd list` shows nothing on fresh clone.
|
||||
|
||||
**Check:**
|
||||
```bash
|
||||
ls .beads/dolt/ # Should NOT exist (pre-bootstrap)
|
||||
BD_DEBUG=1 bd list # See bootstrap output
|
||||
```
|
||||
|
||||
**Force bootstrap:**
|
||||
```bash
|
||||
rm -rf .beads/dolt # Remove broken state
|
||||
bd list # Re-triggers bootstrap
|
||||
```
|
||||
|
||||
### Database Corruption
|
||||
|
||||
**Symptom:** Queries fail, inconsistent data.
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
bd doctor # Basic checks
|
||||
bd doctor --deep # Full validation
|
||||
bd doctor --server # Server mode checks (if applicable)
|
||||
```
|
||||
|
||||
**Recovery options:**
|
||||
|
||||
1. **Repair what's fixable:**
|
||||
```bash
|
||||
bd doctor --fix
|
||||
```
|
||||
|
||||
2. **Rebuild from remote:**
|
||||
```bash
|
||||
rm -rf .beads/dolt
|
||||
bd list # Re-triggers bootstrap
|
||||
```
|
||||
|
||||
### Already Committed `.beads/dolt/` to Git
|
||||
|
||||
If you accidentally committed a Dolt data directory:
|
||||
|
||||
1. Update gitignore: `bd doctor --fix`
|
||||
2. Remove it from git tracking: `git rm --cached -r .beads/dolt/` (or `.beads/embeddeddolt/`)
|
||||
3. Commit the removal: `git commit -m "fix: remove accidentally committed dolt data"`
|
||||
4. To purge from history, use [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) or `git filter-repo`
|
||||
|
||||
### Lock Contention (Embedded Mode)
|
||||
|
||||
**Symptom:** "database is locked" errors.
|
||||
|
||||
Embedded mode is single-writer (enforced via file lock). If you need concurrent
|
||||
access, switch to server mode. See [Migrating Between Backends](#migrating-between-backends).
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
```yaml
|
||||
# .beads/config.yaml
|
||||
|
||||
# Dolt settings
|
||||
dolt:
|
||||
# Auto-commit Dolt history after writes (default: on for embedded, off for server)
|
||||
auto-commit: on # on | off
|
||||
|
||||
# Storage mode (default: embedded)
|
||||
mode: embedded # embedded | server
|
||||
# Server mode settings (only used when mode: server)
|
||||
host: 127.0.0.1
|
||||
port: 3307
|
||||
user: root
|
||||
# Password: env var or credentials file (see below)
|
||||
|
||||
# Shared server mode (GH#2377): all projects share a single Dolt server
|
||||
# at ~/.beads/shared-server/. Each project uses its own database (prefix-based).
|
||||
# Eliminates port conflicts and reduces resource usage on multi-project machines.
|
||||
shared-server: false # true | false
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `BEADS_DOLT_PASSWORD` | Server mode password (highest priority) |
|
||||
| `BEADS_CREDENTIALS_FILE` | Path to credentials file (overrides default location) |
|
||||
| `BEADS_DOLT_SERVER_MODE` | Enable server mode (set to "1") |
|
||||
| `BEADS_DOLT_SERVER_HOST` | Server host (default: 127.0.0.1) |
|
||||
| `BEADS_DOLT_SERVER_PORT` | Server port (default: 3307, or 3308 in shared mode) |
|
||||
| `BEADS_DOLT_SERVER_TLS` | Enable TLS (set to "1" or "true") |
|
||||
| `BEADS_DOLT_SERVER_USER` | MySQL connection user |
|
||||
| `BEADS_DOLT_SHARED_SERVER` | Enable shared server mode (set to "1" or "true") |
|
||||
| `DOLT_REMOTE_USER` | Clone/push/pull auth user |
|
||||
| `DOLT_REMOTE_PASSWORD` | Clone/push/pull auth password |
|
||||
| `BD_DOLT_AUTO_COMMIT` | Override auto-commit setting |
|
||||
|
||||
### Credentials File
|
||||
|
||||
For multi-server setups, you can store passwords in an INI-style credentials file
|
||||
instead of juggling environment variables per project. Passwords are looked up by
|
||||
`[host:port]` section, so each project automatically gets the right password based
|
||||
on its configured server.
|
||||
|
||||
**Password resolution order:**
|
||||
1. `BEADS_DOLT_PASSWORD` env var (highest priority, existing behavior)
|
||||
2. Credentials file lookup by `[host:port]` (using the resolved runtime port)
|
||||
3. Empty string (no password)
|
||||
|
||||
**Port resolution note:** The `[host:port]` used for credential lookup matches the
|
||||
resolved runtime port (from the port file, env var, or config — in that priority
|
||||
order), not necessarily the port stored in `metadata.json`. This matters when using
|
||||
IAP tunnels: if your tunnel maps remote:3307 to localhost:3308, store your password
|
||||
under `[127.0.0.1:3308]` and the credentials file will match the actual connection.
|
||||
|
||||
**Default location:** `~/.config/beads/credentials` (Linux/macOS), `%APPDATA%\beads\credentials` (Windows)
|
||||
|
||||
**Override location:** Set `BEADS_CREDENTIALS_FILE` env var.
|
||||
|
||||
**File format:**
|
||||
|
||||
```ini
|
||||
# ~/.config/beads/credentials
|
||||
[127.0.0.1:3307]
|
||||
password=localDevPassword
|
||||
|
||||
[beads.company.com:3307]
|
||||
password=teamServerPassword
|
||||
|
||||
[10.0.1.50:3308]
|
||||
password=officePassword
|
||||
```
|
||||
|
||||
**Permissions:** On Linux/macOS, a warning is printed to stderr if the file is
|
||||
readable by group or others (mirrors ssh behavior). Set permissions with:
|
||||
|
||||
```bash
|
||||
chmod 600 ~/.config/beads/credentials
|
||||
```
|
||||
|
||||
## Dolt Version Control
|
||||
|
||||
Dolt maintains its own version history, separate from Git:
|
||||
|
||||
```bash
|
||||
# View Dolt commit history
|
||||
bd vc log
|
||||
|
||||
# Show diff between Dolt commits
|
||||
bd vc diff HEAD~1 HEAD
|
||||
|
||||
# Create manual checkpoint
|
||||
bd vc commit -m "Checkpoint before refactor"
|
||||
```
|
||||
|
||||
### Auto-Commit Behavior
|
||||
|
||||
In **embedded mode** (standalone default), each `bd` write command creates a Dolt commit:
|
||||
|
||||
```bash
|
||||
bd create "New issue" # Creates issue + Dolt commit
|
||||
```
|
||||
|
||||
In **server mode** (orchestrator), auto-commit defaults to OFF because the server
|
||||
manages its own transaction lifecycle. Firing `DOLT_COMMIT` after every write
|
||||
under concurrent load causes 'database is read only' errors.
|
||||
|
||||
Override for batch operations (embedded) or explicit commits (server):
|
||||
|
||||
```bash
|
||||
bd --dolt-auto-commit off create "Issue 1"
|
||||
bd --dolt-auto-commit off create "Issue 2"
|
||||
bd vc commit -m "Batch: created issues"
|
||||
```
|
||||
|
||||
## Server Management (Orchestrator)
|
||||
|
||||
The orchestrator provides integrated Dolt server management:
|
||||
|
||||
```bash
|
||||
gt dolt start # Start server (background)
|
||||
gt dolt stop # Stop server
|
||||
gt dolt status # Show server status
|
||||
gt dolt logs # View server logs
|
||||
gt dolt sql # Open SQL shell
|
||||
```
|
||||
|
||||
Server runs on port 3307 (avoids MySQL conflict on 3306).
|
||||
|
||||
### Standalone-to-managed-city handoff
|
||||
|
||||
When an existing standalone project is later added to a managed city or
|
||||
orchestrator, avoid letting two Dolt servers become sources of truth for the
|
||||
same beads database name. A common split-brain symptom is that `.beads/dolt-server.port`
|
||||
points at the old standalone server while the shell environment points `bd` at
|
||||
the managed server with `BEADS_DOLT_PORT` or `BEADS_DOLT_SERVER_PORT`.
|
||||
|
||||
Check before migrating:
|
||||
|
||||
```bash
|
||||
bd doctor
|
||||
bd dolt status
|
||||
```
|
||||
|
||||
`bd doctor` warns when the runtime managed port differs from the local port
|
||||
file. The warning is intentionally diagnostic only; do not delete the local port
|
||||
file until the standalone store has been exported and imported into the managed
|
||||
server.
|
||||
|
||||
Safe manual handoff:
|
||||
|
||||
```bash
|
||||
# From the standalone project, without managed-city port overrides:
|
||||
unset BEADS_DOLT_PORT BEADS_DOLT_SERVER_PORT
|
||||
bd backup
|
||||
bd export > /tmp/beads-standalone.jsonl
|
||||
bd dolt stop
|
||||
|
||||
# Then enter the managed-city environment and import into its Dolt server:
|
||||
bd import /tmp/beads-standalone.jsonl
|
||||
bd doctor
|
||||
```
|
||||
|
||||
After `bd doctor` shows one healthy store and the imported issue count is
|
||||
correct, archive the old local Dolt data directory instead of deleting it
|
||||
immediately. Keep the backup until the managed city has been pushed or otherwise
|
||||
snapshotted.
|
||||
|
||||
### Shared Server Mode
|
||||
|
||||
On machines with multiple beads projects, each project normally starts its own Dolt server.
|
||||
Shared server mode runs a single Dolt server at `~/.beads/shared-server/` that serves all projects:
|
||||
|
||||
```bash
|
||||
# Enable for this project
|
||||
bd dolt set shared-server true
|
||||
|
||||
# Or enable machine-wide via environment variable
|
||||
export BEADS_DOLT_SHARED_SERVER=1
|
||||
|
||||
# Or enable during init
|
||||
bd init --prefix myproject --shared-server
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- No port conflicts between projects (single server on port 3308, avoids orchestrator on 3307)
|
||||
- Reduced resource usage (one process instead of many)
|
||||
- Automatic database isolation (each project uses its own database name)
|
||||
|
||||
**How it works:**
|
||||
- Server state files (PID, port, lock, log) live in `~/.beads/shared-server/`
|
||||
- Dolt data directory: `~/.beads/shared-server/dolt/`
|
||||
- Each project's database is stored as a subdirectory (e.g., `~/.beads/shared-server/dolt/myproject/`)
|
||||
- The file lock mechanism ensures safe concurrent access from multiple projects
|
||||
- Default port is 3308 (not 3307) to avoid conflict with the orchestrator. Override with `BEADS_DOLT_SERVER_PORT` or `dolt.port` in config.yaml
|
||||
|
||||
**Important:** Each project on a shared server **must have a unique prefix** (database name).
|
||||
Two projects with the same prefix share the same database — if this happens accidentally,
|
||||
the project identity check will detect the mismatch and refuse to connect, preventing
|
||||
silent data corruption. Always use distinct prefixes when running `bd init --shared-server`.
|
||||
|
||||
```bash
|
||||
# Check shared server status from any project
|
||||
bd dolt status
|
||||
|
||||
# Show full configuration including shared mode
|
||||
bd dolt show
|
||||
```
|
||||
|
||||
### Data Location (Orchestrator)
|
||||
|
||||
```
|
||||
<town-root>/.dolt-data/
|
||||
├── hq/ # Town beads (hq-*)
|
||||
├── my-project/ # Project rig (mp-*)
|
||||
├── beads/ # Beads rig (bd-*)
|
||||
└── other-project/ # Other rig (op-*)
|
||||
```
|
||||
|
||||
### Central Dolt Server (macOS LaunchAgent)
|
||||
|
||||
If you do not use the orchestrator but still want a single persistent Dolt
|
||||
server for multiple projects on macOS, run a custom `LaunchAgent` instead of
|
||||
spawning per-project embedded instances.
|
||||
|
||||
#### Why Not `brew services start dolt`?
|
||||
|
||||
After installing Dolt with `brew install dolt`, the natural next step is
|
||||
`brew services start dolt`. However, the Homebrew formula runs
|
||||
`dolt sql-server` without the `--config` flag, and Dolt does not auto-discover
|
||||
`config.yaml` from its working directory. The config file must be passed
|
||||
explicitly with `--config <file>`.
|
||||
|
||||
#### Setup with a Custom LaunchAgent
|
||||
|
||||
Install Dolt and initialize its data directory:
|
||||
|
||||
```bash
|
||||
brew install dolt
|
||||
cd /opt/homebrew/var/dolt && dolt init
|
||||
```
|
||||
|
||||
Configure Dolt for port 3307:
|
||||
|
||||
```yaml
|
||||
# /opt/homebrew/var/dolt/config.yaml
|
||||
log_level: info
|
||||
|
||||
listener:
|
||||
host: 127.0.0.1
|
||||
port: 3307
|
||||
max_connections: 100
|
||||
|
||||
behavior:
|
||||
autocommit: true
|
||||
```
|
||||
|
||||
Create the LaunchAgent plist:
|
||||
|
||||
```bash
|
||||
cat > ~/Library/LaunchAgents/com.local.dolt-server.plist << 'EOF'
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
|
||||
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>com.local.dolt-server</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/opt/homebrew/bin/dolt</string>
|
||||
<string>sql-server</string>
|
||||
<string>--config</string>
|
||||
<string>/opt/homebrew/var/dolt/config.yaml</string>
|
||||
</array>
|
||||
<key>WorkingDirectory</key>
|
||||
<string>/opt/homebrew/var/dolt</string>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
<key>StandardOutPath</key>
|
||||
<string>/opt/homebrew/var/log/dolt.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/opt/homebrew/var/log/dolt-error.log</string>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
```
|
||||
|
||||
Load and verify the service:
|
||||
|
||||
```bash
|
||||
launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist
|
||||
mysql -h 127.0.0.1 -P 3307 -u root -e "SELECT 1"
|
||||
```
|
||||
|
||||
Point beads at the central server:
|
||||
|
||||
```bash
|
||||
export BEADS_DOLT_SERVER_MODE=1
|
||||
export BEADS_DOLT_SERVER_PORT=3307
|
||||
```
|
||||
|
||||
Manage the service:
|
||||
|
||||
```bash
|
||||
# Stop
|
||||
launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist
|
||||
|
||||
# Restart
|
||||
launchctl unload ~/Library/LaunchAgents/com.local.dolt-server.plist
|
||||
launchctl load ~/Library/LaunchAgents/com.local.dolt-server.plist
|
||||
|
||||
# Check logs
|
||||
tail -f /opt/homebrew/var/log/dolt.log
|
||||
```
|
||||
|
||||
## Advanced Dolt Usage
|
||||
|
||||
The `dolt` CLI lets you operate directly on the database for power-user
|
||||
workflows. The data directory depends on your mode: `.beads/embeddeddolt/`
|
||||
(embedded) or `.beads/dolt/` (server).
|
||||
|
||||
### Branching
|
||||
|
||||
```bash
|
||||
cd .beads/dolt # or .beads/embeddeddolt for embedded mode
|
||||
dolt branch feature-x
|
||||
dolt checkout feature-x
|
||||
```
|
||||
|
||||
### Time Travel
|
||||
|
||||
```bash
|
||||
dolt log
|
||||
dolt checkout <commit-hash>
|
||||
dolt sql -q "SELECT * FROM issues"
|
||||
```
|
||||
|
||||
### Diff and Blame
|
||||
|
||||
```bash
|
||||
dolt diff main feature-x
|
||||
dolt blame issues
|
||||
```
|
||||
|
||||
## Migration Cleanup
|
||||
|
||||
After successful migration from SQLite, you may have backup files:
|
||||
|
||||
```
|
||||
.beads/beads.backup-pre-dolt-20260122-213600.db
|
||||
.beads/sqlite.backup-pre-dolt-20260123-192812.db
|
||||
```
|
||||
|
||||
These are safe to delete once you've verified Dolt is working:
|
||||
|
||||
```bash
|
||||
# Verify Dolt works
|
||||
bd list
|
||||
bd doctor
|
||||
|
||||
# Then clean up (after appropriate waiting period)
|
||||
rm .beads/*.backup-*.db
|
||||
```
|
||||
|
||||
**Recommendation:** Keep backups for at least a week before deleting.
|
||||
|
||||
## See Also
|
||||
|
||||
- [SYNC_CONCEPTS.md](/core-concepts/sync-concepts) - The conceptual model behind cross-machine sync (Dolt source of truth, wire format, anti-patterns)
|
||||
- [SYNC_SETUP.md](/getting-started/sync-setup) - Setting up sync across multiple computers
|
||||
- [FEDERATION.md](/multi-agent/federation) - Peer-to-peer federation setup
|
||||
- [CONFIG.md](/reference/configuration) - Full configuration reference
|
||||
- [DEPENDENCIES.md](/core-concepts/dependencies) - Dependencies and gates
|
||||
- [GIT_INTEGRATION.md](/reference/git-integration) - Git worktrees and protected branches
|
||||
- [TROUBLESHOOTING.md](/reference/troubleshooting) - General troubleshooting
|
||||
213
docs/architecture/index.md
Normal file
213
docs/architecture/index.md
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
---
|
||||
title: Architecture Overview
|
||||
description: "Understanding Beads' three-layer data model"
|
||||
---
|
||||
|
||||
This document explains how Beads' architecture works with Dolt as its storage backend.
|
||||
|
||||
## Architecture
|
||||
|
||||
Beads uses **Dolt** as its sole storage backend -- a version-controlled SQL database that provides git-like semantics (branch, merge, diff, push, pull) natively at the database level.
|
||||
|
||||
By default, Dolt runs in **embedded mode** (in-process, no separate server). For multi-writer
|
||||
setups (multiple agents, orchestrator), switch to **server mode** which connects to a
|
||||
running `dolt sql-server`. See the [Dolt Server Mode](#dolt-server-mode) section below for details.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph DOLT["🗄️ Dolt Database"]
|
||||
D[(".beads/dolt/<br/><i>Version-Controlled SQL</i>")]
|
||||
end
|
||||
|
||||
subgraph REMOTE["🌐 Dolt Remotes"]
|
||||
R[("DoltHub / S3 / GCS<br/><i>Sync & Backup</i>")]
|
||||
end
|
||||
|
||||
D <-->|"bd dolt push/pull"| R
|
||||
|
||||
U((User)) -->|"bd create<br/>bd update"| D
|
||||
D -->|"bd list<br/>bd show"| U
|
||||
|
||||
style DOLT fill:#2d5a27,stroke:#4a9c3e,color:#fff
|
||||
style REMOTE fill:#1a4a6e,stroke:#3a8ac4,color:#fff
|
||||
```
|
||||
|
||||
<Info>
|
||||
**Source of Truth**
|
||||
**Dolt** is the source of truth. Every write auto-commits to Dolt history, providing full version control, branching, and merge capabilities at the database level.
|
||||
|
||||
Recovery is straightforward: pull from a Dolt remote with `bd dolt pull`, or restore from a Dolt-native backup with `bd backup restore`.
|
||||
</Info>
|
||||
|
||||
### Why Dolt?
|
||||
|
||||
- **Version-controlled SQL**: Full SQL queries with native version control
|
||||
- **Cell-level merge**: Concurrent changes merge automatically at the field level
|
||||
- **Multi-writer**: Server mode supports concurrent agents
|
||||
- **Native branching**: Dolt branches independent of git branches
|
||||
- **Works offline**: All queries run against local database
|
||||
- **Portable**: `bd export` produces JSONL for migration and interoperability
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Write Path
|
||||
```text
|
||||
User runs bd create
|
||||
→ Dolt database updated
|
||||
→ Auto-committed to Dolt history
|
||||
```
|
||||
|
||||
### Read Path
|
||||
```text
|
||||
User runs bd list
|
||||
→ Dolt SQL query
|
||||
→ Results returned immediately
|
||||
```
|
||||
|
||||
### Sync Path
|
||||
```text
|
||||
User runs bd dolt push
|
||||
→ Commits pushed to Dolt remote
|
||||
|
||||
User runs bd dolt pull
|
||||
→ Remote commits fetched and merged
|
||||
```
|
||||
|
||||
### Multi-Machine Sync Considerations
|
||||
|
||||
When working across multiple machines or clones:
|
||||
|
||||
1. **Always sync before switching machines**
|
||||
```bash
|
||||
bd dolt push # Push changes before leaving
|
||||
```
|
||||
|
||||
2. **Pull before creating new issues**
|
||||
```bash
|
||||
bd dolt pull # Pull changes first on new machine
|
||||
bd create "New issue"
|
||||
```
|
||||
|
||||
3. **Avoid parallel edits** - If two machines create issues simultaneously without syncing, Dolt's cell-level merge handles most conflicts automatically
|
||||
|
||||
See [Sync Failures Recovery](/recovery/sync-failures) for data loss prevention in multi-machine workflows (Pattern A5/C3).
|
||||
|
||||
## Dolt Server Mode
|
||||
|
||||
The Dolt server handles background synchronization and database operations:
|
||||
|
||||
- Manages the Dolt database backend
|
||||
- Handles auto-commit for change tracking
|
||||
- Provides concurrent access for multiple agents
|
||||
- Logs available at `.beads/dolt/sql-server.log`
|
||||
|
||||
<Tip>
|
||||
Start the Dolt server with `bd dolt start`. Check health with `bd doctor`.
|
||||
</Tip>
|
||||
|
||||
### Embedded Mode (No Server)
|
||||
|
||||
For CI/CD pipelines, containers, and single-use scenarios, no server is needed. Beads operates in embedded mode automatically when no Dolt server is running:
|
||||
|
||||
```bash
|
||||
bd create "CI-generated issue"
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
**When embedded mode is appropriate:**
|
||||
- CI/CD pipelines (Jenkins, GitHub Actions)
|
||||
- Docker containers
|
||||
- Ephemeral environments
|
||||
- Scripts that should not leave background processes
|
||||
|
||||
### Multi-Clone Scenarios
|
||||
|
||||
<Warning>
|
||||
**Race Conditions in Multi-Clone Workflows**
|
||||
When multiple git clones of the same repository run sync operations simultaneously, race conditions can occur during push/pull operations. This is particularly common in:
|
||||
- Multi-agent AI workflows (multiple Claude/GPT instances)
|
||||
- Developer workstations with multiple checkouts
|
||||
- Worktree-based development workflows
|
||||
|
||||
**Prevention:**
|
||||
1. Stop the Dolt server (`bd dolt stop`) before switching between clones
|
||||
2. Dolt handles worktrees natively in server mode
|
||||
3. Use embedded mode for automated workflows
|
||||
</Warning>
|
||||
|
||||
See [Sync Failures Recovery](/recovery/sync-failures) for sync race condition troubleshooting (Pattern B2).
|
||||
|
||||
## Recovery Model
|
||||
|
||||
Dolt's version control makes recovery straightforward:
|
||||
|
||||
1. **Lost database?** → Pull from Dolt remote: `bd dolt pull`
|
||||
2. **Have a backup?** → Restore it: `bd backup restore [path] --force`
|
||||
3. **Merge conflicts?** → Dolt handles cell-level merge natively
|
||||
|
||||
### Universal Recovery Sequence
|
||||
|
||||
The following sequence resolves the majority of reported issues. For detailed procedures, see [Recovery Runbooks](/recovery/index).
|
||||
|
||||
```bash
|
||||
bd dolt stop # Stop Dolt server (prevents race conditions)
|
||||
git worktree prune # Clean orphaned worktrees
|
||||
bd dolt pull # Pull from Dolt remote
|
||||
bd dolt start # Restart server
|
||||
```
|
||||
|
||||
<Warning>
|
||||
**Use `bd doctor --fix` With Care**
|
||||
Always back up and preview before running `bd doctor --fix`:
|
||||
|
||||
1. **Back up first:** `cp -r .beads .beads.backup`
|
||||
2. **Preview changes:** `bd doctor --dry-run` — shows what would be fixed without making changes
|
||||
3. **Review diagnostics:** `bd doctor` (no flags) — diagnostic only, no changes made
|
||||
4. **Then fix:** `bd doctor --fix` — or `bd doctor --fix -i` to confirm each fix individually
|
||||
|
||||
**Why caution?** The `--fix` flag may remove dependencies it flags as circular, including valid parent-child relationships. Use `--fix-child-parent` only if you're certain the flagged deps are invalid.
|
||||
|
||||
**Other diagnostic tools:**
|
||||
- `bd blocked` — check which issues are blocked and why
|
||||
- `bd show <issue-id>` — inspect a specific issue's state
|
||||
</Warning>
|
||||
|
||||
See [Recovery](/recovery/index) for specific procedures and [Database Corruption Recovery](/recovery/database-corruption) for Dolt recovery steps.
|
||||
|
||||
## Design Decisions
|
||||
|
||||
### Why Dolt?
|
||||
|
||||
Dolt is a version-controlled SQL database that provides git-like semantics natively. Unlike plain SQLite (binary merge conflicts) or JSONL (slow queries), Dolt gives you both fast SQL queries and proper merge semantics.
|
||||
|
||||
### Why not a cloud server?
|
||||
|
||||
Beads is designed for offline-first, local-first development. The Dolt server runs locally -- no cloud dependency, no downtime, no vendor lock-in, and full functionality on airplanes or in restricted networks.
|
||||
|
||||
### Trade-offs
|
||||
|
||||
| Benefit | Trade-off |
|
||||
|---------|-----------|
|
||||
| Works offline | No real-time collaboration |
|
||||
| Version-controlled database | Requires Dolt server |
|
||||
| Cell-level merge | Requires initial setup |
|
||||
| Local-first speed | Manual sync to remotes |
|
||||
| SQL queries | Dolt binary dependency |
|
||||
|
||||
### When NOT to use Beads
|
||||
|
||||
Beads is not suitable for:
|
||||
|
||||
- **Large teams (10+)** — Git-based sync doesn't scale well for high-frequency concurrent edits
|
||||
- **Non-developers** — Requires Git and command-line familiarity
|
||||
- **Real-time collaboration** — No live updates; requires explicit sync
|
||||
- **Cross-repository tracking** — Issues are scoped to a single repository
|
||||
- **Rich media attachments** — Designed for text-based issue tracking
|
||||
|
||||
For these use cases, consider GitHub Issues, Linear, or Jira.
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Recovery Runbooks](/recovery/index) — Step-by-step procedures for common issues
|
||||
- [CLI Reference](/cli-reference/index) — Complete command documentation
|
||||
- [Getting Started](/index) — Installation and first steps
|
||||
278
docs/architecture/storage-backends.md
Normal file
278
docs/architecture/storage-backends.md
Normal file
|
|
@ -0,0 +1,278 @@
|
|||
---
|
||||
title: Storage Backends
|
||||
---
|
||||
|
||||
Beads uses Dolt as its default storage backend, and Dolt remains the reference implementation. You can also point `bd` at Postgres, MySQL, or SQLite — every backend implements the full issue-tracking core, and the only thing you give up off Dolt is version control.
|
||||
|
||||
One seam, one shared core: the issue-tracking semantics are written once (in `issueops`) and shared by *every* backend — Dolt runs them natively, the SQL family runs them through one thin per-engine dialect. Each backend is a store adapter over that shared core. Version control lives only in the Dolt store; on the SQL backends it returns one clean, typed error.
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
CLI["bd CLI"] --> SEAM["Storage interface<br/>one seam — every backend satisfies all of it"]
|
||||
|
||||
SEAM --> CORE["CORE — issueops<br/>CRUD · search · deps · ready/claim · ordering · id-mint<br/>written once, shared by EVERY backend"]
|
||||
SEAM --> CAPS["CAPABILITIES — version control<br/>history · branch · remotes · sync"]
|
||||
|
||||
CORE --> DS["Dolt store<br/>runs the core natively"]
|
||||
CORE --> KIT["sqlkit.Store<br/>SQL-family adapter · Dialect / Readiness / Claim"]
|
||||
|
||||
DS --> DOLT[("Dolt — embedded / server<br/>the conformance ORACLE")]
|
||||
KIT --> PGD["pgdialect"] --> PG[("Postgres")]
|
||||
KIT --> MYD["mysqldialect"] --> MY[("MySQL")]
|
||||
KIT --> LTD["sqlitedialect"] --> LT[("SQLite")]
|
||||
|
||||
CAPS -->|"implemented in the Dolt store"| DS
|
||||
CAPS -->|"generated typed-unsupported shell"| SHELL["Postgres / MySQL / SQLite<br/>operation X not supported"]
|
||||
|
||||
DOLT -. "conformance-tested: SQL family matches Dolt byte-for-byte" .-> KIT
|
||||
```
|
||||
|
||||
<Accordion title="Plain-text version of the diagram">
|
||||
|
||||
```
|
||||
bd CLI
|
||||
|
|
||||
Storage interface
|
||||
|
|
||||
+-------------------------+--------------------------+
|
||||
| |
|
||||
CORE (every backend) CAPABILITIES (Dolt-only)
|
||||
issueops -- CRUD, search, deps, version control:
|
||||
ready/claim, ordering, id-mint, history, branch, remotes, sync
|
||||
cycle checks: written ONCE |
|
||||
| +-> Dolt store: implemented
|
||||
+--------------------+ +-> Postgres/MySQL/SQLite:
|
||||
| | generated typed-"unsupported"
|
||||
Dolt store sqlkit.Store (operation "X" not supported)
|
||||
runs the core SQL-family adapter
|
||||
natively (Dialect/Readiness/Claim)
|
||||
| |
|
||||
[Dolt engine] +------+------+---------+
|
||||
embedded/server pgdialect mysqldialect sqlitedialect
|
||||
= conformance | | |
|
||||
ORACLE Postgres MySQL SQLite
|
||||
|
||||
issueops is shared by EVERY backend (Dolt included); each backend is a store
|
||||
adapter over it. Dolt runs the core's SQL natively and adds version control;
|
||||
the SQL family runs it through one thin dialect per engine, and is
|
||||
conformance-tested to match the Dolt oracle byte-for-byte.
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
## Why Choose a Backend?
|
||||
|
||||
- **Dolt stays the default** — `bd init` with no flags behaves exactly as before, and Dolt is the only backend with history, branching, and sync
|
||||
- **Postgres / MySQL** — put your issues in the database your team already runs, backs up, and monitors; many writers, one server
|
||||
- **SQLite** — a single file inside `.beads/`, zero servers, zero credentials, pure-Go driver
|
||||
- **Same `bd` everywhere** — create, list, ready, deps, claims, labels, comments, search all behave identically on every backend; conformance tests enforce it against the Dolt reference
|
||||
- **Clean degradation** — Dolt-only commands don't half-work on SQL backends; they return one clear, typed error
|
||||
|
||||
## Pick Your Backend
|
||||
|
||||
| Backend | Best for | History | Server needed | Credentials |
|
||||
|---|---|---|---|---|
|
||||
| `dolt` (default) | Solo or team work where you want issue history, branching, `bd dolt push`/`pull` | Yes | No (embedded) / optional | Only in server mode |
|
||||
| `sqlite` | Solo work, throwaway workspaces, CI sandboxes, air-gapped machines | No | No | None |
|
||||
| `postgres` | Teams with an existing Postgres; many workspaces share one database via per-workspace schemas | No | Yes | Ladder (below) |
|
||||
| `mysql` | Teams with an existing MySQL; each workspace gets its own database | No | Yes | Ladder (below) |
|
||||
|
||||
Rules of thumb:
|
||||
|
||||
- If you want `bd history`, `bd dolt push`, time-travel, or federation — use **Dolt**. It is the only backend that tracks history.
|
||||
- If you want the smallest possible footprint and don't need history — use **SQLite**.
|
||||
- If your organization already operates Postgres or MySQL and you want issues living next to everything else your DBAs manage — use **Postgres** or **MySQL**. Multi-writer concurrency comes from the database server itself.
|
||||
- If in doubt, use the default. `bd init` without `--backend` is Dolt, unchanged.
|
||||
|
||||
## Getting Started
|
||||
|
||||
The backend is chosen once, at `bd init` time, and recorded in `.beads/metadata.json`. Every later `bd` command reads it from there — no per-command flags.
|
||||
|
||||
### Dolt (default)
|
||||
|
||||
```bash
|
||||
bd init --prefix myproj
|
||||
```
|
||||
|
||||
Nothing changes. See [DOLT.md](/architecture/dolt) for embedded vs. server mode.
|
||||
|
||||
### SQLite
|
||||
|
||||
```bash
|
||||
bd init --backend=sqlite --prefix myproj
|
||||
|
||||
# Optional: choose the database file (relative to .beads/; default beads.db)
|
||||
bd init --backend=sqlite --sqlite-path=issues.db --prefix myproj
|
||||
```
|
||||
|
||||
That's it — no server, no credentials. Foreign keys and immediate-transaction locking are configured automatically.
|
||||
|
||||
### Postgres
|
||||
|
||||
Each Beads workspace lives in its own Postgres **schema**, so many workspaces can share one database.
|
||||
|
||||
```bash
|
||||
bd init --backend=postgres \
|
||||
--pg-url='postgres://bd:onlyforinit@db.example.com:5432/beads?sslmode=require' \
|
||||
--pg-schema=myproj \
|
||||
--prefix myproj
|
||||
```
|
||||
|
||||
- `--pg-url` — a standard `postgres://` URL. If omitted, `bd init` falls back to the `BEADS_POSTGRES_URL` environment variable.
|
||||
- `--pg-schema` — the schema this workspace owns; created and pinned via `search_path`.
|
||||
|
||||
> **Note:** `bd init` connects with the URL exactly as given, so embed the password
|
||||
> in `--pg-url` for init. It is stripped before anything is written to disk —
|
||||
> `.beads/metadata.json` stores only the password-free DSN — and every later
|
||||
> command resolves the password through the credential ladder below.
|
||||
|
||||
```bash
|
||||
# For all subsequent commands, supply the password via any ladder rung, e.g.:
|
||||
export BEADS_PG_PASSWORD_COMMAND='vault kv get -field=password secret/beads/pg'
|
||||
|
||||
bd create "first issue" -p 1
|
||||
bd ready
|
||||
```
|
||||
|
||||
### MySQL
|
||||
|
||||
Each Beads workspace gets its own MySQL **database**.
|
||||
|
||||
```bash
|
||||
bd init --backend=mysql \
|
||||
--mysql-url='bd:onlyforinit@tcp(db.example.com:3306)/' \
|
||||
--mysql-database=myproj_beads \
|
||||
--prefix myproj
|
||||
```
|
||||
|
||||
- `--mysql-url` — go-sql-driver DSN grammar: `user:password@tcp(host:port)/` (note the trailing slash, no scheme). Falls back to `BEADS_MYSQL_URL` if omitted.
|
||||
- `--mysql-database` — the database this workspace owns.
|
||||
|
||||
Same rule as Postgres: embed the password in `--mysql-url` for init only; it is redacted before persisting, and later commands use the ladder:
|
||||
|
||||
```bash
|
||||
export BEADS_MYSQL_PASSWORD_COMMAND='vault kv get -field=password secret/beads/mysql'
|
||||
# or a static password:
|
||||
export BEADS_MYSQL_PASSWORD=...
|
||||
```
|
||||
|
||||
> **Note:** the MySQL DSN grammar cannot carry a password without a username.
|
||||
> `bd` refuses such DSNs loudly rather than silently connecting passwordless.
|
||||
|
||||
## Credentials & Override Layers
|
||||
|
||||
SQLite needs no credentials. For Postgres and MySQL, the password is resolved fresh at open time by a **ladder** of sources, highest priority first. The first *configured* rung wins, and a configured rung that fails aborts the connection — it never silently falls through to a lower rung.
|
||||
|
||||
Precedence, per backend:
|
||||
|
||||
1. **Password embedded in the DSN** — a password inside `BEADS_POSTGRES_URL` / `BEADS_MYSQL_URL` wins outright; no ladder runs.
|
||||
2. **Credential command** — `BEADS_PG_PASSWORD_COMMAND` / `BEADS_MYSQL_PASSWORD_COMMAND`
|
||||
3. **Static env var** — `BEADS_PG_PASSWORD` / `BEADS_MYSQL_PASSWORD`
|
||||
4. **Credentials file** — an entry matching the DSN's `host:port`
|
||||
5. **Driver-native fallback** — Postgres only: `PGPASSWORD`, `~/.pgpass`, `PGPASSFILE` still work when nothing above is configured. MySQL has no driver-native fallback; with nothing configured it attempts an empty password.
|
||||
|
||||
> **Note the naming asymmetry:** the URL variables use full names
|
||||
> (`BEADS_POSTGRES_URL`, `BEADS_MYSQL_URL`) while the password variables
|
||||
> abbreviate Postgres (`BEADS_PG_PASSWORD`, `BEADS_PG_PASSWORD_COMMAND`).
|
||||
> There is no `BEADS_PG_URL`.
|
||||
|
||||
### The credential command (rotating secrets)
|
||||
|
||||
This is the same idiom as kubectl's ExecCredential, the AWS CLI's `credential_process`, and git credential helpers: `bd` runs your command with `sh -c` (30-second timeout) and reads the secret from stdout. Output can be a bare token, a kubectl-style JSON envelope (`{"token": "...", "expirationTimestamp": "..."}`), or an OAuth-style one (`{"access_token": "...", "expires_in": 900}`). Results are cached in-process and refreshed shortly before expiry, so repeated opens don't re-spawn your helper.
|
||||
|
||||
```bash
|
||||
# Vault
|
||||
export BEADS_PG_PASSWORD_COMMAND="vault kv get -field=password secret/beads/pg"
|
||||
|
||||
# AWS RDS IAM auth (15-minute tokens; caching and expiry are handled for you)
|
||||
export BEADS_PG_PASSWORD_COMMAND="aws rds generate-db-auth-token \
|
||||
--hostname db.example.com --port 5432 --username bd"
|
||||
```
|
||||
|
||||
The command variables are read from the environment only — never from workspace metadata — because a persisted command would be arbitrary code executed on every `bd` invocation.
|
||||
|
||||
### The credentials file (static, per-host)
|
||||
|
||||
The lowest configured rung is an INI-style file keyed by `host:port`, at `~/.config/beads/credentials` (Linux/macOS) or `%APPDATA%\beads\credentials` (Windows); override the path with `BEADS_CREDENTIALS_FILE`.
|
||||
|
||||
```ini
|
||||
# ~/.config/beads/credentials (chmod 600)
|
||||
[127.0.0.1:5432]
|
||||
password=localDevPassword
|
||||
|
||||
[db.example.com:3306]
|
||||
password=teamServerPassword
|
||||
```
|
||||
|
||||
If the file is readable by group or others, `bd` prints an ssh-style warning. The file rung is deliberately forgiving: a missing file or unmatched section just means "not configured" and the ladder continues — fail-closed behavior is reserved for rungs you explicitly configured, like a command.
|
||||
|
||||
### Dolt server credentials
|
||||
|
||||
The Dolt backend in server mode has its own rungs: `BEADS_DOLT_PASSWORD`, then the credentials file, with `BEADS_DOLT_SERVER_USER` overriding the username. There is also `BEADS_DOLT_CREDENTIAL_COMMAND`, an *identity* credential: the minted token is presented as the connection username to an authenticating gateway server, which verifies it and routes to the database. This is for gateway deployments only — the direct Postgres/MySQL backends reject `BEADS_PG_CREDENTIAL_COMMAND` / `BEADS_MYSQL_CREDENTIAL_COMMAND` with an error telling you to use the `_PASSWORD_COMMAND` form instead.
|
||||
|
||||
### Secrets never reach disk
|
||||
|
||||
`bd init` redacts the password from your URL before writing `.beads/metadata.json`, using the database driver's own parser, and then re-parses to verify nothing survived — refusing to init rather than persisting a secret it can't prove is gone. Check for yourself:
|
||||
|
||||
```bash
|
||||
cat .beads/metadata.json
|
||||
# {"backend":"postgres","postgres_dsn":"postgres://bd@db.example.com:5432/beads?sslmode=require", ...}
|
||||
```
|
||||
|
||||
## What You Keep and What You Give Up
|
||||
|
||||
Every backend implements the complete issue-tracking core — the same shared implementation, not a re-derivation per backend:
|
||||
|
||||
- Issue CRUD, bulk creates, close/reopen/delete
|
||||
- Search, counts, filtering, sorting
|
||||
- Dependencies, cycle detection, dependency trees
|
||||
- Ready/blocked work queries, claims and leases
|
||||
- Labels, comments, the full event/audit trail
|
||||
- Config, metadata slots, statistics, transactions, streaming iterators
|
||||
|
||||
What is Dolt-only — by design, since these *are* version control:
|
||||
|
||||
- **History & time travel** — `bd history`, as-of queries, diffs
|
||||
- **Branching & merging** — branch, checkout, merge, conflict resolution
|
||||
- **Remotes & sync** — `bd dolt push` / `bd dolt pull`, fetch, sync
|
||||
- **Federation** — peer management
|
||||
- **Compaction** — snapshot-based memory compaction
|
||||
|
||||
On Postgres, MySQL, and SQLite these operations don't limp along or approximate — each returns one clean, typed error:
|
||||
|
||||
```
|
||||
$ bd history myproj-9q9
|
||||
Error: failed to get history: operation "History" not supported by the sqlite backend
|
||||
```
|
||||
|
||||
`bd init` sets the expectation up front:
|
||||
|
||||
```
|
||||
✓ bd initialized with the SQLite backend
|
||||
History: not tracked (SQLite backend has no version control; use Dolt for history)
|
||||
```
|
||||
|
||||
A few practical consequences:
|
||||
|
||||
- Writes on SQL backends are durable the moment the command returns — each write commits its own SQL transaction. (`bd`'s internal commit hooks become harmless no-ops, not errors.)
|
||||
- The Dolt-only maintenance tail (auto-commit, auto-export, auto-backup, auto-push) is skipped automatically on non-Dolt backends.
|
||||
- "Sync" on Postgres/MySQL is your database server: everyone connects to the same database, so there is nothing to push or pull. Back up issues with your normal database tooling, or `bd export` for JSONL interoperability.
|
||||
|
||||
## How It Stays Correct
|
||||
|
||||
The SQL backends are held to the embedded-Dolt reference by a conformance harness, run locally and in CI (with real Postgres and MySQL servers) on every pull request:
|
||||
|
||||
- **Tier 1 (in-process):** the same behavior corpus the Dolt reference passes — CRUD, search, dependencies, ready/blocked, claims and leases, plus a ~94-case audit corpus of edge behaviors — runs against every backend. Two extra gates make capability gaps impossible to hide: a completeness test proves the set of unsupported operations exactly matches an audited allowlist, and a contract test calls every one of them to prove it returns the typed error rather than panicking or lying.
|
||||
- **Tier 2 (end-to-end):** a real `bd` binary runs `bd init --backend=...` and a CLI scenario corpus in an isolated workspace per backend, and the normalized output must be byte-identical to the Dolt reference. Known-divergence entries are visible in the registry and can only shrink — currently there are none.
|
||||
|
||||
```bash
|
||||
./scripts/conformance.sh
|
||||
# Postgres/MySQL profiles self-skip unless you point them at a server:
|
||||
BEADS_PG_TEST_URL="postgres://user:pass@127.0.0.1:5432/beads_test" \
|
||||
BEADS_MYSQL_TEST_URL="user:pass@tcp(127.0.0.1:3306)/" \
|
||||
./scripts/conformance.sh
|
||||
```
|
||||
|
||||
Adding a new backend is one declarative profile entry in `test/conformance/profiles.go` plus a store-factory arm; both tiers pick it up automatically.
|
||||
|
||||
See [DOLT.md](/architecture/dolt) for the default backend, [CONFIG.md](/reference/configuration) for configuration, and [TROUBLESHOOTING.md](/reference/troubleshooting) if a connection misbehaves.
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Beads Community Tools
|
||||
---
|
||||
title: Community Tools
|
||||
---
|
||||
|
||||
A curated list of community-built UIs, extensions, and integrations for Beads. Ranked by activity and maturity.
|
||||
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Adaptive ID Length
|
||||
---
|
||||
title: Adaptive ID Length
|
||||
---
|
||||
|
||||
**Feature:** bd-ea2a13
|
||||
**Status:** Implemented (v0.21+)
|
||||
|
|
@ -212,10 +214,10 @@ bd config set issue_id_mode hash
|
|||
- **Hash IDs** (this document): Collision-free across parallel branches and agents; IDs are less predictable but always unique.
|
||||
- **Counter IDs**: Human-friendly and sequential; require care in multi-branch workflows where counters can diverge.
|
||||
|
||||
See [CONFIG.md](CONFIG.md) for full documentation on `issue_id_mode=counter`, including migration
|
||||
See [CONFIG.md](/reference/configuration) for full documentation on `issue_id_mode=counter`, including migration
|
||||
guidance and per-prefix counter isolation.
|
||||
|
||||
## Related
|
||||
|
||||
- [Migration Guide](../README.md#migration) - Converting from sequential to hash IDs
|
||||
- [Configuration](CONFIG.md) - All configuration options
|
||||
- [Migration Guide](https://github.com/gastownhall/beads/blob/main/README.md#migration) - Converting from sequential to hash IDs
|
||||
- [Configuration](/reference/configuration) - All configuration options
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Dependencies and Gates
|
||||
---
|
||||
title: Dependencies and Gates
|
||||
---
|
||||
|
||||
Beads includes a full dependency system for ordering work and a gate system
|
||||
for bridging external conditions (PR merges, CI runs, timers) into the
|
||||
|
|
@ -319,8 +321,8 @@ bd ready # Only "Design" is ready
|
|||
|
||||
## See Also
|
||||
|
||||
- [QUICKSTART.md](QUICKSTART.md) — First steps with dependencies
|
||||
- [MOLECULES.md](MOLECULES.md) — Molecule workflows using gates and dependencies
|
||||
- [MULTI_REPO_AGENTS.md](MULTI_REPO_AGENTS.md) — Cross-repo dependency patterns
|
||||
- [DOLT.md](DOLT.md) — Dolt backend configuration
|
||||
- [CLI_REFERENCE.md](CLI_REFERENCE.md) — Full command reference
|
||||
- [QUICKSTART.md](/getting-started/quickstart) — First steps with dependencies
|
||||
- [MOLECULES.md](/workflows/molecules) — Molecule workflows using gates and dependencies
|
||||
- [MULTI_REPO_AGENTS.md](/multi-agent/coordination) — Cross-repo dependency patterns
|
||||
- [DOLT.md](/architecture/dolt) — Dolt backend configuration
|
||||
- [CLI_REFERENCE.md](/cli-reference/index) — Full command reference
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Graph Links in Beads
|
||||
---
|
||||
title: Graph Links in Beads
|
||||
---
|
||||
|
||||
Beads supports several types of links between issues to create a knowledge graph. These links enable rich querying and traversal beyond simple blocking dependencies.
|
||||
|
||||
|
|
@ -274,6 +276,6 @@ Build conversation chains (via orchestrator mail):
|
|||
|
||||
## See Also
|
||||
|
||||
- [Messaging](../engdocs/messaging.md) - Mail commands and threading
|
||||
- [Dependencies](QUICKSTART.md#dependencies) - Blocking dependencies
|
||||
- [CLI Reference](CLI_REFERENCE.md) - All commands
|
||||
- [Messaging](https://github.com/gastownhall/beads/blob/main/engdocs/messaging.md) - Mail commands and threading
|
||||
- [Dependencies](/getting-started/quickstart#dependencies) - Blocking dependencies
|
||||
- [CLI Reference](/cli-reference/index) - All commands
|
||||
125
docs/core-concepts/hash-ids.md
Normal file
125
docs/core-concepts/hash-ids.md
Normal file
|
|
@ -0,0 +1,125 @@
|
|||
---
|
||||
title: Hash-based IDs
|
||||
---
|
||||
|
||||
Understanding beads' collision-resistant ID system.
|
||||
|
||||
## The Problem
|
||||
|
||||
Traditional sequential IDs (`#1`, `#2`, `#3`) break when:
|
||||
- Multiple agents create issues simultaneously
|
||||
- Different branches have independent numbering
|
||||
- Forks diverge and later merge
|
||||
|
||||
## The Solution
|
||||
|
||||
Beads uses hash-based IDs:
|
||||
|
||||
```
|
||||
bd-a1b2c3 # Short hash
|
||||
bd-f14c # Even shorter
|
||||
bd-a3f8e9.1 # Hierarchical (child of bd-a3f8e9)
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- Globally unique (content-based hash)
|
||||
- No coordination needed between creators
|
||||
- Merge-friendly across branches
|
||||
- Predictable length (configurable)
|
||||
|
||||
## How Hashes Work
|
||||
|
||||
IDs are generated from:
|
||||
- Issue title
|
||||
- Creation timestamp
|
||||
- Random salt
|
||||
|
||||
```bash
|
||||
# Create issue - ID assigned automatically
|
||||
bd create "Fix authentication bug"
|
||||
# Returns: bd-7x2f
|
||||
|
||||
# The ID is deterministic for same content+timestamp
|
||||
```
|
||||
|
||||
## Hierarchical IDs
|
||||
|
||||
For epics and subtasks:
|
||||
|
||||
```bash
|
||||
# Parent epic
|
||||
bd create "Auth System" -t epic
|
||||
# Returns: bd-a3f8e9
|
||||
|
||||
# Children auto-increment
|
||||
bd create "Design UI" --parent bd-a3f8e9 # bd-a3f8e9.1
|
||||
bd create "Backend" --parent bd-a3f8e9 # bd-a3f8e9.2
|
||||
bd create "Tests" --parent bd-a3f8e9 # bd-a3f8e9.3
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Clear parent-child relationship
|
||||
- No namespace collision (parent hash is unique)
|
||||
- Up to 3 levels of nesting
|
||||
|
||||
## ID Configuration
|
||||
|
||||
Configure ID prefix and length:
|
||||
|
||||
```bash
|
||||
# Set prefix (default: bd)
|
||||
bd config set id.prefix myproject
|
||||
|
||||
# Set hash length (default: 4)
|
||||
bd config set id.hash_length 6
|
||||
|
||||
# New issues use new format
|
||||
bd create "Test"
|
||||
# Returns: myproject-a1b2c3
|
||||
```
|
||||
|
||||
## Collision Handling
|
||||
|
||||
While rare, collisions are handled automatically:
|
||||
|
||||
1. On import, if hash collision detected
|
||||
2. Beads appends disambiguator
|
||||
3. Both issues preserved
|
||||
|
||||
```bash
|
||||
# Check for collisions
|
||||
bd info --schema --json | jq '.collision_count'
|
||||
```
|
||||
|
||||
## Working with IDs
|
||||
|
||||
```bash
|
||||
# Partial ID matching
|
||||
bd show a1b2 # Finds bd-a1b2...
|
||||
bd show auth # Fuzzy match by title
|
||||
|
||||
# Full ID required for ambiguous cases
|
||||
bd show bd-a1b2c3d4
|
||||
|
||||
# List with full IDs
|
||||
bd list --full-ids
|
||||
```
|
||||
|
||||
## Migration from Sequential IDs
|
||||
|
||||
If migrating from a system with sequential IDs:
|
||||
|
||||
```bash
|
||||
# Bootstrap from a JSONL export (preserves original IDs in metadata)
|
||||
bd init --from-jsonl old-issues.jsonl
|
||||
|
||||
# View original ID
|
||||
bd show bd-new --json | jq '.original_id'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use short references** - `bd-a1b2` is usually unique enough
|
||||
2. **Use `--json` for scripts** - Parse full ID programmatically
|
||||
3. **Reference by hash in commits** - `Fixed bd-a1b2` in commit messages
|
||||
4. **Let hierarchies form naturally** - Create epics, add children as needed
|
||||
72
docs/core-concepts/index.md
Normal file
72
docs/core-concepts/index.md
Normal file
|
|
@ -0,0 +1,72 @@
|
|||
---
|
||||
title: Core Concepts
|
||||
---
|
||||
|
||||
Understanding the fundamental concepts behind beads.
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
Beads was built with these principles:
|
||||
|
||||
1. **Dolt as source of truth** - Issues stored in a version-controlled SQL database (Dolt), enabling collaboration via Dolt-native replication
|
||||
2. **AI-native workflows** - Hash-based IDs, JSON output, dependency-aware execution
|
||||
3. **Local-first operation** - Dolt database for fast queries, background sync
|
||||
4. **Declarative workflows** - Formulas define repeatable patterns
|
||||
|
||||
## Key Components
|
||||
|
||||
### Issues
|
||||
|
||||
Work items with:
|
||||
- **ID** - Hash-based (e.g., `bd-a1b2`) or hierarchical (e.g., `bd-a1b2.1`)
|
||||
- **Type** - `bug`, `feature`, `task`, `epic`, `chore`
|
||||
- **Priority** - 0 (critical) to 4 (backlog)
|
||||
- **Status** - `open`, `in_progress`, `closed`
|
||||
- **Labels** - Flexible tagging
|
||||
- **Dependencies** - Blocking relationships
|
||||
|
||||
### Dependencies
|
||||
|
||||
Four types of relationships:
|
||||
|
||||
| Type | Description | Affects Ready Queue |
|
||||
|------|-------------|---------------------|
|
||||
| `blocks` | Hard dependency (X blocks Y) | Yes |
|
||||
| `parent-child` | Epic/subtask relationship | No |
|
||||
| `discovered-from` | Track issues found during work | No |
|
||||
| `related` | Soft relationship | No |
|
||||
|
||||
### Dolt Server Mode
|
||||
|
||||
Dolt provides the database backend for beads:
|
||||
- Start with `bd dolt start`
|
||||
- Handles auto-commit and sync
|
||||
- Logs available at `.beads/dolt/sql-server.log`
|
||||
- Check health with `bd doctor`
|
||||
|
||||
### Dolt Sync
|
||||
|
||||
The synchronization mechanism:
|
||||
|
||||
```
|
||||
Dolt DB (.beads/dolt/)
|
||||
↕ dolt commit
|
||||
Local Dolt history
|
||||
↕ dolt push/pull
|
||||
Remote Dolt repository
|
||||
```
|
||||
|
||||
### Formulas
|
||||
|
||||
Declarative workflow templates:
|
||||
- Define steps with dependencies
|
||||
- Variable substitution
|
||||
- Gates for async coordination
|
||||
- Aspect-oriented transformations
|
||||
|
||||
## Navigation
|
||||
|
||||
- [Issues & Dependencies](/core-concepts/issues)
|
||||
- [Dolt Server Mode](#dolt-server-mode)
|
||||
- [Dolt Sync](#dolt-sync)
|
||||
- [Hash-based IDs](/core-concepts/hash-ids)
|
||||
179
docs/core-concepts/issues.md
Normal file
179
docs/core-concepts/issues.md
Normal file
|
|
@ -0,0 +1,179 @@
|
|||
---
|
||||
title: "Issues & Dependencies"
|
||||
---
|
||||
|
||||
Understanding the issue model in beads.
|
||||
|
||||
## Issue Structure
|
||||
|
||||
Every issue has:
|
||||
|
||||
```bash
|
||||
bd show bd-42 --json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "bd-42",
|
||||
"title": "Implement authentication",
|
||||
"description": "Add JWT-based auth",
|
||||
"type": "feature",
|
||||
"status": "open",
|
||||
"priority": 1,
|
||||
"labels": ["backend", "security"],
|
||||
"created_at": "2024-01-15T10:30:00Z",
|
||||
"updated_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Issue Types
|
||||
|
||||
| Type | Use Case |
|
||||
|------|----------|
|
||||
| `bug` | Something broken that needs fixing |
|
||||
| `feature` | New functionality |
|
||||
| `task` | Work item (tests, docs, refactoring) |
|
||||
| `epic` | Large feature with subtasks |
|
||||
| `chore` | Maintenance (dependencies, tooling) |
|
||||
|
||||
## Priorities
|
||||
|
||||
| Priority | Level | Examples |
|
||||
|----------|-------|----------|
|
||||
| 0 | Critical | Security, data loss, broken builds |
|
||||
| 1 | High | Major features, important bugs |
|
||||
| 2 | Medium | Nice-to-have features, minor bugs |
|
||||
| 3 | Low | Polish, optimization |
|
||||
| 4 | Backlog | Future ideas |
|
||||
|
||||
## Creating Issues
|
||||
|
||||
```bash
|
||||
# Basic issue
|
||||
bd create "Fix login bug" -t bug -p 1
|
||||
|
||||
# With description
|
||||
bd create "Add password reset" \
|
||||
--description="Users need to reset forgotten passwords via email" \
|
||||
-t feature -p 2
|
||||
|
||||
# With labels
|
||||
bd create "Update dependencies" -t chore -l "maintenance,security"
|
||||
|
||||
# JSON output for agents
|
||||
bd create "Task" -t task --json
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Blocking Dependencies
|
||||
|
||||
The `blocks` relationship affects the ready queue:
|
||||
|
||||
```bash
|
||||
# Add dependency: bd-2 depends on bd-1
|
||||
bd dep add bd-2 bd-1
|
||||
|
||||
# View dependencies
|
||||
bd dep tree bd-2
|
||||
|
||||
# See blocked issues
|
||||
bd blocked
|
||||
|
||||
# See ready work (not blocked)
|
||||
bd ready
|
||||
```
|
||||
|
||||
### Structural Relationships
|
||||
|
||||
These don't affect the ready queue:
|
||||
|
||||
```bash
|
||||
# Parent-child (epic subtasks)
|
||||
bd create "Epic" -t epic
|
||||
bd create "Subtask" --parent bd-42
|
||||
|
||||
# Discovered-from (found during work)
|
||||
bd create "Found bug" --deps discovered-from:bd-42
|
||||
|
||||
# Related (soft link)
|
||||
bd relate bd-1 bd-2
|
||||
```
|
||||
|
||||
### Dependency Types
|
||||
|
||||
| Type | Description | Ready Queue Impact |
|
||||
|------|-------------|-------------------|
|
||||
| `blocks` | Hard dependency | Yes - blocked items not ready |
|
||||
| `parent-child` | Epic/subtask hierarchy | No |
|
||||
| `discovered-from` | Tracks origin of discovery | No |
|
||||
| `related` | Soft relationship | No |
|
||||
|
||||
## Hierarchical Issues
|
||||
|
||||
For large features, use hierarchical IDs:
|
||||
|
||||
```bash
|
||||
# Create epic
|
||||
bd create "Auth System" -t epic -p 1
|
||||
# Returns: bd-a3f8e9
|
||||
|
||||
# Child tasks auto-number
|
||||
bd create "Design login UI" --parent bd-a3f8e9 # bd-a3f8e9.1
|
||||
bd create "Backend validation" --parent bd-a3f8e9 # bd-a3f8e9.2
|
||||
|
||||
# View hierarchy
|
||||
bd dep tree bd-a3f8e9
|
||||
```
|
||||
|
||||
## Updating Issues
|
||||
|
||||
```bash
|
||||
# Change status
|
||||
bd update bd-42 --claim
|
||||
|
||||
# Change priority
|
||||
bd update bd-42 --priority 0
|
||||
|
||||
# Add labels
|
||||
bd update bd-42 --add-label urgent
|
||||
|
||||
# Multiple changes
|
||||
bd update bd-42 --claim --priority 1 --add-label "in-review"
|
||||
```
|
||||
|
||||
## Closing Issues
|
||||
|
||||
```bash
|
||||
# Simple close
|
||||
bd close bd-42
|
||||
|
||||
# With reason
|
||||
bd close bd-42 --reason "Implemented in PR #123"
|
||||
|
||||
# JSON output
|
||||
bd close bd-42 --json
|
||||
```
|
||||
|
||||
## Searching and Filtering
|
||||
|
||||
```bash
|
||||
# By status
|
||||
bd list --status open
|
||||
bd list --status in_progress
|
||||
|
||||
# By priority
|
||||
bd list --priority 1
|
||||
bd list --priority 0,1 # Multiple
|
||||
|
||||
# By type
|
||||
bd list --type bug
|
||||
bd list --type feature,task
|
||||
|
||||
# By label
|
||||
bd list --label-any urgent,critical
|
||||
bd list --label-all backend,security
|
||||
|
||||
# Combined filters
|
||||
bd list --status open --priority 1 --type bug --json
|
||||
```
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Labels in Beads
|
||||
---
|
||||
title: Labels
|
||||
---
|
||||
|
||||
Labels provide flexible, multi-dimensional categorization for issues beyond the structured fields (status, priority, type). Use labels for cross-cutting concerns, technical metadata, and contextual tagging without schema changes.
|
||||
|
||||
|
|
@ -745,7 +747,7 @@ The `set-state` command atomically:
|
|||
2. Removes the old dimension label if present
|
||||
3. Adds the new dimension:value label (cache)
|
||||
|
||||
See [CLI_REFERENCE.md](CLI_REFERENCE.md#state-labels-as-cache) for full command reference.
|
||||
See [CLI_REFERENCE.md](/cli-reference/set-state) for full command reference.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
|
|
@ -784,6 +786,6 @@ bd doctor
|
|||
|
||||
## See Also
|
||||
|
||||
- [README.md](../README.md) - Main documentation
|
||||
- [AGENTS.md](../AGENTS.md) - AI agent integration guide
|
||||
- [ADVANCED.md](ADVANCED.md) - Advanced features and configuration
|
||||
- [README.md](https://github.com/gastownhall/beads/blob/main/README.md) - Main documentation
|
||||
- [AGENTS.md](https://github.com/gastownhall/beads/blob/main/AGENTS.md) - AI agent integration guide
|
||||
- [ADVANCED.md](/reference/advanced) - Advanced features and configuration
|
||||
|
|
@ -1,11 +1,13 @@
|
|||
# Issue Metadata
|
||||
---
|
||||
title: Issue Metadata
|
||||
---
|
||||
|
||||
The `metadata` field on issues accepts arbitrary JSON. Any valid JSON value is stored as-is.
|
||||
|
||||
Metadata is the preferred extension point for data that is specific to an
|
||||
integration, orchestrator, team workflow, or experimental automation. Before
|
||||
adding first-class fields, commands, or schema changes, check the
|
||||
[Project Charter](../engdocs/PROJECT_CHARTER.md#schema-boundary).
|
||||
[Project Charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md#schema-boundary).
|
||||
|
||||
## Example: Agent Execution Metadata
|
||||
|
||||
|
|
@ -83,5 +85,5 @@ Avoid these prefixes in user-defined keys to prevent conflicts with future Beads
|
|||
|
||||
## Related
|
||||
|
||||
- [Project Charter](../engdocs/PROJECT_CHARTER.md) - Product scope and schema boundary
|
||||
- [Project Charter](https://github.com/gastownhall/beads/blob/main/engdocs/PROJECT_CHARTER.md) - Product scope and schema boundary
|
||||
- [#1416](https://github.com/gastownhall/beads/issues/1416) - Optional schema enforcement (future)
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Sync Concepts
|
||||
---
|
||||
title: Sync Concepts
|
||||
---
|
||||
|
||||
Beads issue data lives in Dolt. The local Dolt database is the source of truth
|
||||
for `bd list`, `bd show`, `bd ready`, and every write command.
|
||||
209
docs/getting-started/ide-setup.md
Normal file
209
docs/getting-started/ide-setup.md
Normal file
|
|
@ -0,0 +1,209 @@
|
|||
---
|
||||
title: IDE Setup
|
||||
---
|
||||
|
||||
Configure your IDE for optimal beads integration.
|
||||
|
||||
## Claude Code
|
||||
|
||||
The recommended approach for Claude Code:
|
||||
|
||||
```bash
|
||||
# Setup Claude Code integration
|
||||
bd setup claude
|
||||
```
|
||||
|
||||
This installs:
|
||||
- **SessionStart hook** - Runs `bd prime` when Claude Code starts
|
||||
- **SessionStart compact refresh** - Runs `bd prime` after context compaction
|
||||
|
||||
**How it works:**
|
||||
1. SessionStart hook runs `bd prime` automatically
|
||||
2. `bd prime` injects ~1-2k tokens of workflow context
|
||||
3. You use `bd` CLI commands directly
|
||||
4. Git hooks refresh exports and legacy fallbacks; Dolt remotes handle sync
|
||||
|
||||
**Verify installation:**
|
||||
```bash
|
||||
bd setup claude --check
|
||||
```
|
||||
|
||||
### Manual Setup
|
||||
|
||||
If you prefer manual configuration, add to your Claude Code hooks:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": ["bd prime"],
|
||||
"SessionStart": ["bd prime"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Cursor IDE
|
||||
|
||||
```bash
|
||||
# Setup Cursor integration
|
||||
bd setup cursor
|
||||
```
|
||||
|
||||
This creates `.cursor/rules/beads.mdc` with beads-aware rules.
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
bd setup cursor --check
|
||||
```
|
||||
|
||||
## Aider
|
||||
|
||||
```bash
|
||||
# Setup Aider integration
|
||||
bd setup aider
|
||||
```
|
||||
|
||||
This creates/updates `.aider.conf.yml` with beads context.
|
||||
|
||||
**Verify:**
|
||||
```bash
|
||||
bd setup aider --check
|
||||
```
|
||||
|
||||
## GitHub Copilot
|
||||
|
||||
For VS Code with GitHub Copilot, use the MCP server:
|
||||
|
||||
```bash
|
||||
# Install MCP server
|
||||
uv tool install beads-mcp
|
||||
```
|
||||
|
||||
Create `.vscode/mcp.json` in your project:
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**For all projects:** Add to VS Code user-level MCP config:
|
||||
|
||||
| Platform | Path |
|
||||
|----------|------|
|
||||
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
|
||||
| Linux | `~/.config/Code/User/mcp.json` |
|
||||
| Windows | `%APPDATA%\Code\User\mcp.json` |
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp",
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Initialize beads and reload VS Code:
|
||||
|
||||
```bash
|
||||
bd init --quiet
|
||||
```
|
||||
|
||||
See [GitHub Copilot Integration](/integrations/github-copilot) for detailed setup.
|
||||
|
||||
## Context Injection with `bd prime`
|
||||
|
||||
All integrations use `bd prime` to inject context:
|
||||
|
||||
```bash
|
||||
bd prime
|
||||
```
|
||||
|
||||
This outputs a compact (~1-2k tokens) workflow reference including:
|
||||
- Available commands
|
||||
- Current project status
|
||||
- Workflow patterns
|
||||
- Best practices
|
||||
- Persistent memories from `bd remember`
|
||||
|
||||
`bd prime` prints memories near the top and starts with a truncation warning. If your host stores the full hook output in a file and only shows a preview, have the agent read the full file before continuing.
|
||||
|
||||
For memory-only hooks:
|
||||
|
||||
```bash
|
||||
bd prime --memories-only
|
||||
```
|
||||
|
||||
**Why context efficiency matters:**
|
||||
- Compute cost scales with tokens
|
||||
- Latency increases with context size
|
||||
- Models attend better to smaller, focused contexts
|
||||
|
||||
## MCP Server (Alternative)
|
||||
|
||||
For MCP-only environments (Claude Desktop, no shell access):
|
||||
|
||||
```bash
|
||||
# Install MCP server
|
||||
pip install beads-mcp
|
||||
```
|
||||
|
||||
Add to Claude Desktop config:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Trade-offs:**
|
||||
- Works in MCP-only environments
|
||||
- Higher context overhead (10-50k tokens for tool schemas)
|
||||
- Additional latency from MCP protocol
|
||||
|
||||
See [MCP Server](/integrations/mcp-server) for detailed configuration.
|
||||
|
||||
## Git Hooks
|
||||
|
||||
Ensure git hooks are installed for export refresh and legacy fallback behavior:
|
||||
|
||||
```bash
|
||||
bd hooks install
|
||||
```
|
||||
|
||||
This installs:
|
||||
- **pre-commit** - Validates changes before commit
|
||||
- **post-merge** - Imports changes after pull
|
||||
- **pre-push** - Ensures sync before push
|
||||
|
||||
**Check hook status:**
|
||||
```bash
|
||||
bd info # Shows warnings if hooks are outdated
|
||||
```
|
||||
|
||||
## Verifying Your Setup
|
||||
|
||||
Run a complete health check:
|
||||
|
||||
```bash
|
||||
# Check version
|
||||
bd version
|
||||
|
||||
# Check project health
|
||||
bd doctor
|
||||
|
||||
# Check hooks
|
||||
bd hooks status
|
||||
|
||||
# Check editor integration
|
||||
bd setup claude --check # or cursor, aider
|
||||
```
|
||||
403
docs/getting-started/installation.md
Normal file
403
docs/getting-started/installation.md
Normal file
|
|
@ -0,0 +1,403 @@
|
|||
---
|
||||
title: Installation
|
||||
---
|
||||
|
||||
Complete installation guide for all platforms.
|
||||
|
||||
## Components Overview
|
||||
|
||||
Beads has several components - here's what they are and when you need them:
|
||||
|
||||
| Component | What It Is | When You Need It |
|
||||
|-----------|------------|------------------|
|
||||
| **bd CLI** | Core command-line tool | Always - this is the foundation |
|
||||
| **Claude Code Plugin** | Slash commands + enhanced UX | Optional - if you want `/beads:ready`, `/beads:create` commands |
|
||||
| **MCP Server (beads-mcp)** | Model Context Protocol interface | Only for MCP-only environments (Claude Desktop, Amp) |
|
||||
|
||||
**How they relate:**
|
||||
- The **bd CLI** is the core - install it first via Homebrew, npm, or script
|
||||
- The **Plugin** enhances Claude Code with slash commands but *requires* the CLI installed
|
||||
- The **MCP server** is an *alternative* to the CLI for environments without shell access
|
||||
|
||||
**Important:** Beads is installed system-wide, not cloned into your project. The `.beads/` directory in your project only contains the issue database.
|
||||
|
||||
**Typical setups:**
|
||||
|
||||
| Environment | What to Install |
|
||||
|-------------|-----------------|
|
||||
| Claude Code, Cursor, Windsurf | bd CLI (+ optional Plugin for Claude Code) |
|
||||
| GitHub Copilot (VS Code) | bd CLI + MCP server |
|
||||
| Claude Desktop (no shell) | MCP server only |
|
||||
| Terminal / scripts | bd CLI only |
|
||||
| CI/CD pipelines | bd CLI only |
|
||||
|
||||
**Are they mutually exclusive?** No - you can have CLI + Plugin + MCP all installed. They don't conflict. But most users only need the CLI.
|
||||
|
||||
## Quick Install (Recommended)
|
||||
|
||||
### Homebrew (macOS/Linux)
|
||||
|
||||
```bash
|
||||
brew install beads
|
||||
```
|
||||
|
||||
Homebrew core's `beads` formula is the supported Homebrew package. If you
|
||||
previously installed the old tap formula as `bd`, see
|
||||
[Migrating from the old Homebrew tap](/getting-started/upgrading#homebrew) to
|
||||
switch to the core formula.
|
||||
|
||||
**Why Homebrew?**
|
||||
- Simple one-command install
|
||||
- Automatic updates via `brew upgrade`
|
||||
- No need to install Go
|
||||
- Handles PATH setup automatically
|
||||
|
||||
### Mise-en-place (macOS/Linux/Windows)
|
||||
|
||||
You can install beads using [mise](https://mise.jdx.dev) from the latest GitHub release:
|
||||
|
||||
```bash
|
||||
mise install github:gastownhall/beads
|
||||
mise use -g github:gastownhall/beads
|
||||
```
|
||||
|
||||
The `-g` enables beads globally. To enable project-specific versions, omit it.
|
||||
|
||||
**Why Mise?**
|
||||
- Same as Homebrew: simple, updates via `mise up`, works without Go, handles PATH
|
||||
- Supports all platforms
|
||||
- Always the latest release
|
||||
- May optionally use a different release version for specific projects
|
||||
|
||||
Mise's Go backend follows the same caveats as `go install`; prefer the release backend above.
|
||||
|
||||
### Quick Install Script (All Platforms)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
The installer will:
|
||||
- Detect your platform (macOS/Linux/FreeBSD, amd64/arm64)
|
||||
- Verify downloaded release archives against release `checksums.txt`
|
||||
- Fall back to the supported `go install` modes if Go is available
|
||||
- Fall back to building from source if needed
|
||||
- Guide you through PATH setup if necessary
|
||||
|
||||
On macOS, the script preserves the downloaded binary signature by default. If you explicitly want ad-hoc local re-signing, opt in:
|
||||
|
||||
```bash
|
||||
BEADS_INSTALL_RESIGN_MACOS=1 curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### Comparison of Installation Methods
|
||||
|
||||
| Method | Best For | Updates | Prerequisites | Notes |
|
||||
|--------|----------|---------|---------------|-------|
|
||||
| **Homebrew** | macOS/Linux users | `brew upgrade beads` | Homebrew | Recommended. Handles everything automatically |
|
||||
| **Mise** | All platforms | `mise up` | mise | Installs the latest GitHub release |
|
||||
| **npm** | JS/Node.js projects | `npm update -g @beads/bd` | Node.js | Convenient if npm is your ecosystem |
|
||||
| **bun** | JS/Bun.js projects | `bun install -g --trust @beads/bd` | Bun.js | Convenient if bun is your ecosystem |
|
||||
| **Install script** | Quick setup, CI/CD | Re-run script | curl, bash | Good for automation and one-liners |
|
||||
| **go install (nocgo)** | Go developers, simplest install | Re-run command | Go 1.24+ | **Server-mode only** (no embedded Dolt) |
|
||||
| **go install (cgo)** | Go developers wanting embedded mode | Re-run command | Go 1.24+, C compiler | Full embedded-Dolt support |
|
||||
| **From source** | Contributors only | `git pull && go build` | Go, git | Full control, can modify code |
|
||||
| **AUR (Arch)** | Arch Linux users | `yay -Syu` | yay/paru | Community-maintained |
|
||||
|
||||
**TL;DR:** Use Homebrew if available. Use npm if you're in a Node.js environment. Use the script for quick one-off installs or CI.
|
||||
|
||||
## Go Install and Build Dependencies
|
||||
|
||||
Use Homebrew, npm, or the install script if you do not specifically need `go install`.
|
||||
|
||||
`go install` has two supported modes that give different capabilities:
|
||||
|
||||
- **Server-mode only (nocgo, simplest):** `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest`. Works on any machine with a Go toolchain, no C compiler needed. Produces a server-mode-only binary — you must run an external `dolt sql-server` and use `bd init --server`. See [Dolt](/architecture/dolt) for server-mode setup.
|
||||
- **Embedded-capable (cgo):** `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest`. Requires a C compiler (gcc/clang on Unix, MinGW on Windows). Produces a binary with the default embedded-Dolt backend — `bd init` Just Works.
|
||||
|
||||
ICU headers are not required. The embedded-capable command uses `gms_pure_go` so go-mysql-server uses Go's stdlib regexp instead of ICU.
|
||||
|
||||
Use the `github.com/steveyegge/beads` path for `go install`. The repository now lives under `gastownhall/beads`, but released Go modules still declare `github.com/steveyegge/beads` for compatibility.
|
||||
|
||||
If you don't have a preference, `brew install beads` or the install script give you the embedded-capable build with no fuss.
|
||||
|
||||
### Build Dependencies (Contributors Only)
|
||||
|
||||
<Note>
|
||||
These dependencies are only needed if you build from source. If you installed via Homebrew, npm, or the install script, skip this section entirely.
|
||||
</Note>
|
||||
|
||||
Building from source requires a C compiler (for CGO / embedded Dolt). ICU is
|
||||
not required — all builds use the `gms_pure_go` tag which selects Go's
|
||||
stdlib `regexp` instead of ICU regex. See
|
||||
[ICU-POLICY.md](https://github.com/gastownhall/beads/blob/main/engdocs/ICU-POLICY.md)
|
||||
for details.
|
||||
|
||||
macOS (Homebrew):
|
||||
```bash
|
||||
brew install zstd
|
||||
```
|
||||
|
||||
Linux (Debian/Ubuntu):
|
||||
```bash
|
||||
sudo apt-get install -y libzstd-dev
|
||||
```
|
||||
|
||||
Linux (Fedora/RHEL):
|
||||
```bash
|
||||
sudo dnf install -y libzstd-devel
|
||||
```
|
||||
|
||||
For maintainers only: if you intentionally need to run
|
||||
[scripts/test-icu-path.sh](https://github.com/gastownhall/beads/blob/main/scripts/test-icu-path.sh)
|
||||
(which exercises the leftover ICU code path), install ICU headers:
|
||||
`brew install icu4c` (macOS) or `sudo apt-get install -y libicu-dev` (Linux).
|
||||
This is not needed for normal development.
|
||||
|
||||
## Platform-Specific Installation
|
||||
|
||||
### macOS
|
||||
|
||||
**Via Homebrew** (recommended):
|
||||
```bash
|
||||
brew install beads
|
||||
```
|
||||
|
||||
**Via go install** (server-mode only):
|
||||
```bash
|
||||
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
**Via go install** (embedded-capable):
|
||||
```bash
|
||||
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
**From source**:
|
||||
```bash
|
||||
git clone https://github.com/gastownhall/beads
|
||||
cd beads
|
||||
make build
|
||||
sudo mv bd /usr/local/bin/
|
||||
```
|
||||
|
||||
### Linux
|
||||
|
||||
**Via Homebrew** (works on Linux too):
|
||||
```bash
|
||||
brew install beads
|
||||
```
|
||||
|
||||
**Arch Linux** (AUR):
|
||||
```bash
|
||||
# Install from AUR
|
||||
yay -S beads-git
|
||||
# or
|
||||
paru -S beads-git
|
||||
```
|
||||
|
||||
**Via go install** (server-mode only):
|
||||
```bash
|
||||
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
**Via go install** (embedded-capable):
|
||||
```bash
|
||||
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### FreeBSD
|
||||
|
||||
**Via quick install script**:
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
**Via go install** (server-mode only):
|
||||
```bash
|
||||
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### Windows 11
|
||||
|
||||
Beads ships with native Windows support—no MSYS or MinGW required.
|
||||
|
||||
**Prerequisites:**
|
||||
- [Go 1.24+](https://go.dev/dl/) installed (add `%USERPROFILE%\go\bin` to your `PATH`)
|
||||
- Git for Windows
|
||||
|
||||
**Via PowerShell script**:
|
||||
```pwsh
|
||||
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
|
||||
```
|
||||
|
||||
The script installs a prebuilt Windows release if available. Go is only required for `go install` or building from source.
|
||||
|
||||
**Via go install** (server-mode only):
|
||||
```pwsh
|
||||
$env:CGO_ENABLED="0"; go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
**Via go install** (embedded-capable):
|
||||
```pwsh
|
||||
$env:CGO_ENABLED="1"; $env:GOFLAGS="-tags=gms_pure_go"; go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
## IDE and Editor Integrations
|
||||
|
||||
### CLI + Hooks (Recommended)
|
||||
|
||||
The recommended approach for Claude Code, Cursor, Windsurf, and other editors with shell access:
|
||||
|
||||
```bash
|
||||
# 1. Install bd CLI (see Quick Install above)
|
||||
brew install beads
|
||||
|
||||
# 2. Initialize in your project
|
||||
cd your-project
|
||||
bd init --quiet
|
||||
|
||||
# 3. Setup editor integration (choose one)
|
||||
bd setup claude # Claude Code - installs SessionStart hooks
|
||||
bd setup cursor # Cursor IDE - creates .cursor/rules/beads.mdc
|
||||
bd setup aider # Aider - creates .aider.conf.yml
|
||||
bd setup codex # Codex CLI - installs Beads skill, AGENTS.md guidance, and native hooks
|
||||
bd setup factory # Factory.ai Droid - creates/updates AGENTS.md
|
||||
bd setup mux # Mux - creates/updates AGENTS.md
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
- `bd init` creates or updates `AGENTS.md` and installs project Claude/Codex integrations by default unless you use `--skip-agents` or `--stealth`
|
||||
- Editor hooks/rules inject `bd prime` automatically on session start
|
||||
- Codex 0.129.0+ uses native `/hooks` for startup and compaction-aware context refresh
|
||||
- `bd prime` provides ~1-2k tokens of workflow context
|
||||
- You use `bd` CLI commands directly
|
||||
- Git hooks (installed by `bd init`) refresh exports and legacy fallbacks; `bd dolt push/pull` syncs the database
|
||||
- `bd onboard` prints the small manual snippet for unsupported agents or custom instruction files
|
||||
|
||||
**Why this is recommended:**
|
||||
- **Context efficient** - ~1-2k tokens vs 10-50k for MCP tool schemas
|
||||
- **Lower latency** - Direct CLI calls, no MCP protocol overhead
|
||||
- **Universal** - Works with any editor that has shell access
|
||||
|
||||
### MCP Server (Alternative)
|
||||
|
||||
Use MCP only when CLI is unavailable (Claude Desktop, Sourcegraph Amp without shell):
|
||||
|
||||
```bash
|
||||
# Using uv (recommended)
|
||||
uv tool install beads-mcp
|
||||
|
||||
# Or using pip
|
||||
pip install beads-mcp
|
||||
```
|
||||
|
||||
**Configuration for Claude Desktop** (macOS):
|
||||
|
||||
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Verifying Installation
|
||||
|
||||
After installing, verify bd is working:
|
||||
|
||||
```bash
|
||||
bd version
|
||||
bd help
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `bd: command not found`
|
||||
|
||||
bd is not in your PATH:
|
||||
|
||||
```bash
|
||||
# Check if installed
|
||||
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
|
||||
|
||||
# Add Go bin to PATH (add to ~/.bashrc or ~/.zshrc)
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
|
||||
# Or reinstall with the recommended installer
|
||||
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### `zsh: killed bd` or crashes on macOS
|
||||
|
||||
This is typically caused by CGO/SQLite compatibility issues:
|
||||
|
||||
```bash
|
||||
# Install an embedded-capable build
|
||||
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
## Updating bd
|
||||
|
||||
Upgrade checklist:
|
||||
|
||||
1. With your current `bd`, sync remote-backed databases before installing the
|
||||
new binary:
|
||||
`bd dolt push`
|
||||
`bd dolt pull`
|
||||
2. Back up before migration:
|
||||
`bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl`
|
||||
3. Upgrade using the command for your install method below.
|
||||
4. After upgrading:
|
||||
`bd info --whats-new`
|
||||
`bd hooks install`
|
||||
`bd version`
|
||||
5. If crossing a schema migration on a remote-backed database, only the
|
||||
designated migrator runs:
|
||||
`bd migrate --force`
|
||||
`bd dolt push`
|
||||
|
||||
Other clones should install the new binary and run `bd bootstrap`, not
|
||||
independently migrate. For the full procedure, see [Upgrading](/getting-started/upgrading).
|
||||
|
||||
### Quick install script (macOS/Linux/FreeBSD)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### PowerShell installer (Windows)
|
||||
|
||||
```pwsh
|
||||
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
|
||||
```
|
||||
|
||||
### Homebrew
|
||||
|
||||
```bash
|
||||
brew upgrade beads
|
||||
```
|
||||
|
||||
### go install
|
||||
|
||||
```bash
|
||||
# Server-mode only
|
||||
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
|
||||
# Embedded-capable
|
||||
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
For post-upgrade steps (hooks, migrations), see [Upgrading](/getting-started/upgrading).
|
||||
|
||||
## Next Steps
|
||||
|
||||
After installation:
|
||||
|
||||
1. **Initialize a project**: `cd your-project && bd init`
|
||||
2. **Learn the basics**: See [Quick Start](/getting-started/quickstart)
|
||||
3. **Configure your agent**: See [IDE Setup](/getting-started/ide-setup), or run `bd setup --list`
|
||||
367
docs/getting-started/quickstart.md
Normal file
367
docs/getting-started/quickstart.md
Normal file
|
|
@ -0,0 +1,367 @@
|
|||
---
|
||||
title: Quick Start
|
||||
---
|
||||
|
||||
Get up and running with Beads in a few minutes.
|
||||
|
||||
## Why Beads?
|
||||
|
||||
Flat issue trackers (GitHub Issues, Jira, etc.) show you a list of open items. You pick one. But if that item depends on something else that isn't done yet, you've wasted time. Multiply this across a team of AI agents and humans, and you get thrashing.
|
||||
|
||||
Beads tracks **dependencies between issues** and computes a **ready queue** — only items with no active blockers appear. Here's the difference:
|
||||
|
||||
**Flat tracker (GitHub Issues):**
|
||||
```
|
||||
Open issues: Set up database, Create API, Add authentication
|
||||
→ An agent picks "Add authentication" and gets stuck immediately
|
||||
```
|
||||
|
||||
**Beads:**
|
||||
```bash
|
||||
$ bd ready
|
||||
1. [P1] [task] bd-1: Set up database
|
||||
|
||||
$ bd ready --explain --json | jq '.blocked[0]'
|
||||
{
|
||||
"id": "bd-3",
|
||||
"title": "Add authentication",
|
||||
"blocked_by": [{"id": "bd-2", "title": "Create API", "status": "open"}]
|
||||
}
|
||||
```
|
||||
|
||||
The agent picks the right task every time. No wasted cycles.
|
||||
|
||||
## Installation
|
||||
|
||||
Install `bd` using [the full installation guide](/getting-started/installation) (Homebrew, install script, npm, or `go install`).
|
||||
|
||||
**Developing in a clone of this repository:** use `make install` so the binary gets correct build metadata and a consistent install path. Avoid ad-hoc `go build` / `go install` without the Makefile unless you know what you are doing — see the repository `README` and `AGENTS.md`.
|
||||
|
||||
```bash
|
||||
bd --help
|
||||
```
|
||||
|
||||
## Initialize
|
||||
|
||||
First time in a repository:
|
||||
|
||||
```bash
|
||||
# Basic setup (prompts for contributor mode)
|
||||
bd init
|
||||
|
||||
# For AI agents (non-interactive)
|
||||
bd init --quiet
|
||||
|
||||
# OSS contributor (fork workflow with separate planning repo)
|
||||
bd init --contributor
|
||||
|
||||
# Team member (branch workflow for collaboration)
|
||||
bd init --team
|
||||
|
||||
# Protected main branch (GitHub/GitLab)
|
||||
# Note: Dolt stores data under refs/dolt/data, separate from
|
||||
# Git refs, so no --branch flag is needed.
|
||||
```
|
||||
|
||||
The wizard will:
|
||||
- Create `.beads/` directory and embedded Dolt database
|
||||
- **Prompt for your role** (maintainer or contributor) unless a flag is provided
|
||||
- Import existing issues from git (if any)
|
||||
- Prompt to install git hooks (recommended)
|
||||
- Prompt to configure git merge driver (recommended)
|
||||
|
||||
Notes:
|
||||
- Dolt is the default (and only) storage backend. Data is stored in `.beads/embeddeddolt/`.
|
||||
- By default, Dolt runs in **embedded mode** (in-process, no server needed).
|
||||
- For multi-writer setups, use `bd init --server` to connect to a `dolt sql-server` instead.
|
||||
- To import issues from an older installation, run `bd init --from-jsonl`.
|
||||
|
||||
### Role configuration
|
||||
|
||||
During `bd init`, you'll be asked: "Contributing to someone else's repo? [y/N]"
|
||||
|
||||
- Answer **Y** if you're contributing to a fork (runs contributor wizard)
|
||||
- Answer **N** if you're the maintainer or have push access
|
||||
|
||||
This sets `git config beads.role` which determines how beads routes issues:
|
||||
|
||||
| Role | Use case | Issue storage |
|
||||
|------|----------|---------------|
|
||||
| `maintainer` | Repo owner, team with push access | In-repo `.beads/` |
|
||||
| `contributor` | Fork contributor, OSS contributor | Separate planning repo |
|
||||
|
||||
You can also configure manually:
|
||||
|
||||
```bash
|
||||
# Set as contributor
|
||||
git config beads.role contributor
|
||||
|
||||
# Set as maintainer
|
||||
git config beads.role maintainer
|
||||
|
||||
# Check current role
|
||||
git config --get beads.role
|
||||
```
|
||||
|
||||
**Note:** If `beads.role` is not configured, beads falls back to URL-based detection (deprecated). Run `bd doctor` to check configuration status.
|
||||
|
||||
## Your first issues
|
||||
|
||||
```bash
|
||||
# Create a few issues
|
||||
bd create "Set up database" -p 1 -t task
|
||||
bd create "Create API" -p 2 -t feature
|
||||
bd create "Add authentication" -p 2 -t feature
|
||||
|
||||
# List them
|
||||
bd list
|
||||
```
|
||||
|
||||
**Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently.
|
||||
|
||||
## Hierarchical issues (epics)
|
||||
|
||||
For large features, use hierarchical IDs to organize work:
|
||||
|
||||
```bash
|
||||
# Create epic (generates parent hash ID)
|
||||
bd create "Auth System" -t epic -p 1
|
||||
# Returns: bd-a3f8e9
|
||||
|
||||
# Create child tasks (use --parent to attach to the epic)
|
||||
bd create "Design login UI" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.1
|
||||
bd create "Backend validation" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.2
|
||||
bd create "Integration tests" -p 1 --parent bd-a3f8e9 # bd-a3f8e9.3
|
||||
|
||||
# View hierarchy
|
||||
bd dep tree bd-a3f8e9
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Dependency tree for bd-a3f8e9:
|
||||
|
||||
> bd-a3f8e9: Auth System [epic] [P1] (open)
|
||||
> bd-a3f8e9.1: Design login UI [P1] (open)
|
||||
> bd-a3f8e9.2: Backend validation [P1] (open)
|
||||
> bd-a3f8e9.3: Integration tests [P1] (open)
|
||||
```
|
||||
|
||||
## Add dependencies
|
||||
|
||||
```bash
|
||||
# API depends on database
|
||||
bd dep add bd-2 bd-1
|
||||
|
||||
# Auth depends on API
|
||||
bd dep add bd-3 bd-2
|
||||
|
||||
# View the tree
|
||||
bd dep tree bd-3
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Dependency tree for bd-3:
|
||||
|
||||
> bd-3: Add authentication [P2] (open)
|
||||
> bd-2: Create API [P2] (open)
|
||||
> bd-1: Set up database [P1] (open)
|
||||
```
|
||||
|
||||
**Dependency visibility:** `bd list` shows blocking dependencies inline:
|
||||
```
|
||||
○ bd-a1b2 [P1] [task] - Set up database
|
||||
○ bd-f14c [P2] [feature] - Create API (blocked by: bd-a1b2)
|
||||
○ bd-g25d [P2] [feature] - Add authentication (blocked by: bd-f14c)
|
||||
```
|
||||
|
||||
## Find ready work
|
||||
|
||||
```bash
|
||||
bd ready
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Ready work (1 issues with no blockers):
|
||||
|
||||
1. [P1] bd-1: Set up database
|
||||
```
|
||||
|
||||
Only bd-1 is ready because bd-2 and bd-3 are blocked.
|
||||
|
||||
**Understanding why:** Use `--explain` to see the full graph reasoning:
|
||||
|
||||
```bash
|
||||
bd ready --explain
|
||||
```
|
||||
|
||||
Output:
|
||||
```
|
||||
Ready Work Explanation
|
||||
|
||||
● Ready (1 issues):
|
||||
|
||||
bd-1 [P1] Set up database
|
||||
Reason: no blocking dependencies
|
||||
Unblocks: 1 issue(s)
|
||||
|
||||
● Blocked (2 issues):
|
||||
|
||||
bd-2 [P2] Create API
|
||||
← blocked by bd-1: Set up database [open]
|
||||
|
||||
bd-3 [P2] Add authentication
|
||||
← blocked by bd-2: Create API [open]
|
||||
|
||||
─ Summary: 1 ready, 2 blocked
|
||||
```
|
||||
|
||||
**Note:** `bd ready` is not the same as `bd list --status open`. The `list` command shows all open issues regardless of blockers. The `ready` command computes the dependency graph and only shows truly unblocked work.
|
||||
|
||||
## Work the queue
|
||||
|
||||
```bash
|
||||
# Start working on bd-1
|
||||
bd update bd-1 --claim
|
||||
|
||||
# Complete it
|
||||
bd close bd-1 --reason "Database setup complete"
|
||||
|
||||
# Check ready work again
|
||||
bd ready
|
||||
```
|
||||
|
||||
Now bd-2 is ready.
|
||||
|
||||
## Track progress
|
||||
|
||||
```bash
|
||||
# See blocked issues
|
||||
bd blocked
|
||||
|
||||
# View statistics
|
||||
bd stats
|
||||
```
|
||||
|
||||
## Team sync
|
||||
|
||||
Share issues with your team using Dolt remotes. Dolt stores data under `refs/dolt/data` on the same Git remote, separate from standard Git refs. In repos with `origin`, `bd init` configures that Dolt remote automatically.
|
||||
|
||||
```bash
|
||||
# Verify the remote, or add one if the repo had no origin during init
|
||||
bd dolt remote list
|
||||
bd dolt remote add origin git+ssh://git@github.com/org/repo.git # if needed
|
||||
|
||||
# Push your issues
|
||||
bd dolt push
|
||||
|
||||
# Pull teammates' changes
|
||||
bd dolt pull
|
||||
```
|
||||
|
||||
When a teammate clones the repo, `bd bootstrap` auto-detects the existing database on `refs/dolt/data`, clones it, and wires `origin` for future `bd dolt push` / `bd dolt pull`.
|
||||
|
||||
See [`bd dolt`](/cli-reference/dolt) for CLI details. For remote configuration and federation, see the repository docs [DOLT.md](https://github.com/gastownhall/beads/blob/main/docs/DOLT.md) and [FEDERATION-SETUP.md](https://github.com/gastownhall/beads/blob/main/FEDERATION-SETUP.md).
|
||||
|
||||
## Optional: Notion sync
|
||||
|
||||
If you keep project issues in Notion, save an integration token first:
|
||||
|
||||
```bash
|
||||
bd config set notion.token <your-token>
|
||||
```
|
||||
|
||||
Then either create a new Beads database under a parent page or connect to an existing target:
|
||||
|
||||
```bash
|
||||
bd notion init --parent <page-id>
|
||||
# or
|
||||
bd notion connect --url <notion-database-or-data-source-url>
|
||||
```
|
||||
|
||||
The same auth value can also come from `NOTION_TOKEN`. Directly setting `notion.data_source_id` remains available as an escape hatch for advanced setups.
|
||||
|
||||
Check which auth source is active and whether the target schema is ready:
|
||||
|
||||
```bash
|
||||
bd notion status
|
||||
bd notion status --json
|
||||
```
|
||||
|
||||
Preview or run sync:
|
||||
|
||||
```bash
|
||||
bd notion sync --dry-run
|
||||
bd notion sync
|
||||
bd notion sync --pull
|
||||
bd notion sync --push
|
||||
```
|
||||
|
||||
## Database location
|
||||
|
||||
By default (embedded mode), data is stored in `.beads/embeddeddolt/` within your repository.
|
||||
In server mode, data is managed by the external `dolt sql-server`.
|
||||
|
||||
## Migrating databases
|
||||
|
||||
After upgrading bd, use `bd migrate` to check for and migrate old database files:
|
||||
|
||||
```bash
|
||||
# Inspect migration plan (AI agents)
|
||||
bd migrate --inspect --json
|
||||
|
||||
# Check schema and config
|
||||
bd info --schema --json
|
||||
|
||||
# Preview migration changes
|
||||
bd migrate --dry-run
|
||||
|
||||
# Migrate old databases to beads.db
|
||||
bd migrate
|
||||
|
||||
# Migrate and clean up old files
|
||||
bd migrate --cleanup --yes
|
||||
```
|
||||
|
||||
**AI agents:** Use `--inspect` to analyze migration safety before running. The system verifies required config keys and data integrity invariants.
|
||||
|
||||
## Database maintenance
|
||||
|
||||
As your project accumulates closed issues, the database grows. Manage size with these commands:
|
||||
|
||||
```bash
|
||||
# View compaction statistics
|
||||
bd admin compact --stats
|
||||
|
||||
# Preview compaction candidates (30+ days closed)
|
||||
bd admin compact --analyze --json
|
||||
|
||||
# Apply agent-generated summary
|
||||
bd admin compact --apply --id bd-42 --summary summary.txt
|
||||
|
||||
# Immediately delete closed issues (CAUTION: permanent!)
|
||||
bd admin cleanup --force
|
||||
```
|
||||
|
||||
**When to compact:**
|
||||
- Database file > 10MB with many old closed issues
|
||||
- After major project milestones when old issues are no longer relevant
|
||||
- Before archiving a project phase
|
||||
|
||||
**Note:** Compaction is permanent graceful decay. Original content is discarded but viewable via `bd restore <id>` from git history.
|
||||
|
||||
## Next steps
|
||||
|
||||
- Add labels: `bd create "Task" -l "backend,urgent"`
|
||||
- Filter ready work: `bd ready --priority 1`
|
||||
- Explain the graph: `bd ready --explain`
|
||||
- Check graph integrity: `bd graph check`
|
||||
- Search issues: `bd list --status open`
|
||||
- Detect cycles: `bd dep cycles`
|
||||
- Gates for PR/CI sync: [`bd gate`](/cli-reference/gate)
|
||||
- More sync scenarios: [`bd dolt`](/cli-reference/dolt)
|
||||
- Full command list: [CLI Reference](/cli-reference/index)
|
||||
|
||||
See the [repository README](https://github.com/gastownhall/beads/blob/main/README.md) for an overview and links to deeper docs.
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Sync Setup Guide
|
||||
---
|
||||
title: Sync Setup Guide
|
||||
---
|
||||
|
||||
Set up beads with Dolt sync so your issues follow you across computers.
|
||||
|
||||
|
|
@ -8,7 +10,7 @@ You need two tools installed on every machine:
|
|||
|
||||
| Tool | Minimum Version | Install |
|
||||
|------|-----------------|---------|
|
||||
| **bd** (beads CLI) | 0.59.0+ | See [INSTALLING.md](INSTALLING.md) |
|
||||
| **bd** (beads CLI) | 0.59.0+ | See [INSTALLING.md](/getting-started/installation) |
|
||||
| **Dolt** | 2.1.10+ | `brew install dolt` or [dolt install script](https://github.com/dolthub/dolt/releases/latest/download/install.sh) |
|
||||
|
||||
Verify both are installed:
|
||||
|
|
@ -276,10 +278,10 @@ bd dolt start
|
|||
|
||||
## See Also
|
||||
|
||||
- [SYNC_CONCEPTS.md](SYNC_CONCEPTS.md) — The conceptual model behind this setup (why Dolt is the source of truth, what JSONL is for)
|
||||
- [QUICKSTART.md](QUICKSTART.md) — Getting started with beads
|
||||
- [DOLT.md](DOLT.md) — Dolt backend details, server modes, federation, remote types, and sync modes
|
||||
- [INSTALLING.md](INSTALLING.md) — Installation for all platforms
|
||||
- [SYNC_CONCEPTS.md](/core-concepts/sync-concepts) — The conceptual model behind this setup (why Dolt is the source of truth, what JSONL is for)
|
||||
- [QUICKSTART.md](/getting-started/quickstart) — Getting started with beads
|
||||
- [DOLT.md](/architecture/dolt) — Dolt backend details, server modes, federation, remote types, and sync modes
|
||||
- [INSTALLING.md](/getting-started/installation) — Installation for all platforms
|
||||
|
||||
## Attribution
|
||||
|
||||
368
docs/getting-started/upgrading.md
Normal file
368
docs/getting-started/upgrading.md
Normal file
|
|
@ -0,0 +1,368 @@
|
|||
---
|
||||
title: Upgrading
|
||||
---
|
||||
|
||||
How to upgrade bd and keep your projects in sync.
|
||||
|
||||
## Checking for Updates
|
||||
|
||||
```bash
|
||||
# Current version
|
||||
bd version
|
||||
|
||||
# What's new in recent versions
|
||||
bd info --whats-new
|
||||
bd info --whats-new --json # Machine-readable
|
||||
```
|
||||
|
||||
## Short Version
|
||||
|
||||
1. With your current `bd`, sync remote-backed databases before installing the
|
||||
new binary:
|
||||
`bd dolt push`
|
||||
`bd dolt pull`
|
||||
2. Back up before migration:
|
||||
`bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl`
|
||||
3. Upgrade using the command that matches your install method.
|
||||
4. After upgrading:
|
||||
`bd info --whats-new`
|
||||
`bd hooks install`
|
||||
`bd version`
|
||||
5. If crossing a schema migration on a remote-backed database, only the
|
||||
designated migrator runs:
|
||||
`bd migrate --force`
|
||||
`bd dolt push`
|
||||
|
||||
Other clones should install the new binary and run `bd bootstrap`, not
|
||||
independently migrate. The full procedure is below.
|
||||
|
||||
## Upgrading
|
||||
|
||||
Use the command that matches your install method.
|
||||
|
||||
| Install method | Platforms | Command |
|
||||
|---|---|---|
|
||||
| Quick install script | macOS, Linux, FreeBSD | `curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh \| bash` |
|
||||
| PowerShell installer | Windows | `irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 \| iex` |
|
||||
| Homebrew | macOS, Linux | `brew upgrade beads` |
|
||||
| go install (server-mode only) | macOS, Linux, FreeBSD, Windows | `CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest` |
|
||||
| go install (embedded-capable) | macOS, Linux, Windows | `CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest` |
|
||||
| npm | macOS, Linux, Windows | `npm update -g @beads/bd` |
|
||||
| bun | macOS, Linux, Windows | `bun install -g --trust @beads/bd` |
|
||||
| From source (Unix shell) | macOS, Linux, FreeBSD | `git pull && make build` |
|
||||
|
||||
### Quick install script (macOS/Linux/FreeBSD)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### PowerShell installer (Windows)
|
||||
|
||||
```pwsh
|
||||
irm https://raw.githubusercontent.com/gastownhall/beads/main/install.ps1 | iex
|
||||
```
|
||||
|
||||
### Homebrew
|
||||
|
||||
```bash
|
||||
brew upgrade beads
|
||||
```
|
||||
|
||||
<!-- Canonical Homebrew tap-migration snippet. The installation page links
|
||||
here; docs/INSTALLING.md mirrors this block. Keep all three in sync. -->
|
||||
If you still have the old tap formula installed as `bd`, switch to the
|
||||
Homebrew core formula:
|
||||
|
||||
```bash
|
||||
brew uninstall bd
|
||||
brew untap gastownhall/beads 2>/dev/null || true
|
||||
brew untap steveyegge/beads 2>/dev/null || true
|
||||
brew install beads
|
||||
```
|
||||
|
||||
### go install
|
||||
|
||||
```bash
|
||||
# Server-mode only
|
||||
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
|
||||
# Embedded-capable
|
||||
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### From Source
|
||||
|
||||
```bash
|
||||
cd beads
|
||||
git pull
|
||||
make build
|
||||
sudo mv bd /usr/local/bin/
|
||||
```
|
||||
|
||||
## After Upgrading
|
||||
|
||||
**Important:** After upgrading, update your hooks:
|
||||
|
||||
```bash
|
||||
# 1. Check what changed
|
||||
bd info --whats-new
|
||||
|
||||
# 2. Update git hooks to match new version
|
||||
bd hooks install
|
||||
|
||||
# 3. Check for any outdated hooks
|
||||
bd info # Shows warnings if hooks are outdated
|
||||
|
||||
# 4. If using Dolt backend, restart the server
|
||||
bd dolt stop && bd dolt start
|
||||
```
|
||||
|
||||
**Why update hooks?** Git hooks are versioned with bd. Outdated hooks may miss export refresh, legacy fallback, or safety fixes.
|
||||
|
||||
## Database Migrations
|
||||
|
||||
After major upgrades, check for database migrations:
|
||||
|
||||
```bash
|
||||
# Inspect migration plan (AI agents)
|
||||
bd migrate --inspect --json
|
||||
|
||||
# Preview migration changes
|
||||
bd migrate --dry-run
|
||||
|
||||
# Apply migrations
|
||||
bd migrate
|
||||
|
||||
# Migrate and clean up old files
|
||||
bd migrate --cleanup --yes
|
||||
```
|
||||
|
||||
### Remote-backed databases and multiple clones
|
||||
|
||||
`bd` refuses to silently apply pending schema migrations to a database that has
|
||||
a Dolt remote configured. Migrating more than one clone of a shared remote
|
||||
independently forks the schema, after which `bd dolt pull` can no longer merge —
|
||||
the break is silent and, across a primary-key-reshaping migration, unrecoverable
|
||||
([#4259](https://github.com/gastownhall/beads/issues/4259)). The supported flow
|
||||
is: one machine migrates and publishes; every other clone re-clones the migrated
|
||||
database.
|
||||
|
||||
This applies to **every** upgrade that crosses a pending migration on a
|
||||
remote-backed database — the same procedure whether you are moving to a
|
||||
prerelease or to a stable release.
|
||||
|
||||
The gate is **state-aware by default**
|
||||
([#4516](https://github.com/gastownhall/beads/issues/4516)): before blocking,
|
||||
`bd` consults the remote's *cached* schema state and
|
||||
|
||||
- **auto-migrates** when the remote is at the same schema version as this
|
||||
clone — no one has migrated yet, so this clone is a safe first-mover
|
||||
(concurrent first-movers converge to identical tables). It reminds you to
|
||||
`bd dolt push` afterwards.
|
||||
- **stops and directs you to adopt** (`bd bootstrap`) when the remote has
|
||||
already been migrated by another clone.
|
||||
- **stops for a human decision** when this clone and the remote applied
|
||||
different content for the same migration (a genuine fork), or when the
|
||||
remote's schema state cannot be read from the cached ref.
|
||||
|
||||
Set `BD_SMART_GATE=0` to opt out and make the gate block unconditionally.
|
||||
The recipes below are the explicit path and work the same in either mode.
|
||||
|
||||
**Important ordering:** once the new binary is installed, a database with
|
||||
pending migrations is gated on **every** open — `bd dolt push` and `bd dolt
|
||||
pull` are refused too, not just `bd migrate`. So do all syncing with your
|
||||
**current** binary, *before* you install the new one.
|
||||
|
||||
**Back up before you migrate.** Schema migrations assume the database matches
|
||||
the shape the previous migrations left behind; real databases sometimes drift
|
||||
(interrupted writes, tooling bugs, very old bootstraps). A JSONL export is
|
||||
cheap, issue-complete, and importable by any bd version:
|
||||
|
||||
```bash
|
||||
bd export --all -o .beads/backup/pre-migrate-$(date +%Y%m%d).jsonl
|
||||
```
|
||||
|
||||
`bd export` captures issues, not Dolt history or config — for a full snapshot
|
||||
also copy the `.beads` directory (or `dolt backup` in server mode) while no
|
||||
`bd` command is running.
|
||||
|
||||
**Single clone (including a solo user with a remote):**
|
||||
|
||||
```bash
|
||||
bd dolt push # 1. CURRENT binary: publish all local work
|
||||
bd export --all -o .beads/backup/pre-migrate.jsonl # 2. backup (see above)
|
||||
# 3. install the new binary (see Upgrading above)
|
||||
bd migrate --force # 4. migrate as the designated migrator
|
||||
bd dolt push # 5. publish the migrated schema
|
||||
bd version # 6. confirm the new version is active
|
||||
```
|
||||
|
||||
`--force` confirms you are the single designated migrator so this run may
|
||||
migrate the remote-backed database. For scripted or CI use,
|
||||
`BD_ALLOW_REMOTE_MIGRATE=1 bd migrate` is the env-var equivalent.
|
||||
|
||||
**Multiple clones sharing one remote:**
|
||||
|
||||
```bash
|
||||
# 1. With your CURRENT (old) binary, on EVERY clone: publish all work and get in
|
||||
# sync, then stop editing until the upgrade is done.
|
||||
bd dolt push
|
||||
bd dolt pull
|
||||
|
||||
# 2. Designated migrator ONLY: back up, install the new binary, then migrate
|
||||
# and publish.
|
||||
bd export --all -o .beads/backup/pre-migrate.jsonl
|
||||
bd migrate --force
|
||||
bd dolt push
|
||||
|
||||
# 3. Every OTHER clone: install the new binary, then ADOPT the migrated database.
|
||||
# (bd dolt pull is refused here — the clone still has pending migrations — so
|
||||
# re-clone instead. Safe because step 1 already pushed all work.)
|
||||
bd bootstrap
|
||||
```
|
||||
|
||||
`bd bootstrap` replaces the local database, so any work not pushed in step 1 is
|
||||
lost — that is why step 1 publishes everything first. If a clone was instead
|
||||
migrated independently and `bd dolt pull` later fails with `cannot merge because
|
||||
table dependencies has different primary keys in its common ancestor`, the
|
||||
schema has already forked — follow the recovery playbook:
|
||||
[RECOVERY.md#pk-fork-refused](https://github.com/gastownhall/beads/blob/main/docs/RECOVERY.md#pk-fork-refused).
|
||||
|
||||
<Note>
|
||||
In **server mode**, `bd doctor` adds a migration-content-skew check that flags a
|
||||
forked schema against the cached remote ref — a useful post-upgrade
|
||||
verification. It is not available in embedded mode; there, confirm the upgrade
|
||||
with `bd version` and a normal read such as `bd ready`.
|
||||
</Note>
|
||||
|
||||
## Cross-era Upgrades
|
||||
|
||||
If you're upgrading from a much older version of bd, your project may use a different storage backend. bd has gone through several storage eras:
|
||||
|
||||
| Era | Versions | Storage |
|
||||
|---|---|---|
|
||||
| SQLite | v0.30–v0.50 | `.beads/beads.db` |
|
||||
| Dolt server | v0.50–v0.58 | `.beads/dolt/` (external server) |
|
||||
| Embedded Dolt (old) | v0.59–v0.63.2 | `.beads/dolt/` (in-process) |
|
||||
| Embedded Dolt (current) | v0.63.3+ | `.beads/embeddeddolt/` |
|
||||
|
||||
### From v0.63.3+ (current era)
|
||||
|
||||
Upgrade the binary and run:
|
||||
|
||||
```bash
|
||||
bd migrate
|
||||
```
|
||||
|
||||
If the project was initialized before `bd init` automatically wired git origin
|
||||
as the Dolt remote, verify the remote after upgrading:
|
||||
|
||||
```bash
|
||||
bd dolt remote list
|
||||
```
|
||||
|
||||
When the list is empty, fix it on the machine whose local database is
|
||||
authoritative:
|
||||
|
||||
```bash
|
||||
bd export -o .beads/issues.pre-remote.jsonl # optional issue audit export
|
||||
bd dolt remote add origin git+ssh://git@github.com/org/repo.git
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
Commit the resulting `.beads/config.yaml` change so other clones can run
|
||||
`bd bootstrap` or `bd dolt pull`.
|
||||
|
||||
### From v0.59–v0.63.2 (old embedded)
|
||||
|
||||
Direct upgrade works automatically:
|
||||
|
||||
```bash
|
||||
# Just use the new binary — it handles the conversion
|
||||
bd list
|
||||
```
|
||||
|
||||
### From v0.50–v0.58 (Dolt server era)
|
||||
|
||||
The old binary used an external Dolt SQL server. The new binary uses an embedded engine.
|
||||
|
||||
```bash
|
||||
# 1. Export your data while the old binary still works
|
||||
bd list --json -n 0 --all > .beads/issues.jsonl
|
||||
|
||||
# 2. Stop the Dolt server
|
||||
dolt sql-server --stop # or kill the process
|
||||
|
||||
# 3. Remove stale server metadata and old storage directories
|
||||
rm -f .beads/metadata.json .beads/config.json
|
||||
rm -rf .beads/dolt .beads/embeddeddolt
|
||||
|
||||
# 4. Initialize with the new binary
|
||||
bd init --from-jsonl --quiet
|
||||
|
||||
# 5. Verify
|
||||
bd list --all
|
||||
```
|
||||
|
||||
### From v0.30–v0.50 (SQLite era)
|
||||
|
||||
The old binary stored data in SQLite. The new binary uses Dolt.
|
||||
|
||||
**Recommended: use the migration script** (requires `sqlite3` and `jq`):
|
||||
|
||||
```bash
|
||||
# Download the script from the beads repo
|
||||
curl -fsSLO https://raw.githubusercontent.com/gastownhall/beads/main/scripts/migrate-sqlite-to-current.sh
|
||||
chmod +x migrate-sqlite-to-current.sh
|
||||
|
||||
# Run it in your project directory
|
||||
./migrate-sqlite-to-current.sh
|
||||
```
|
||||
|
||||
The script exports issues, dependencies, and labels from SQLite, handles type normalization, and imports everything into the new Dolt backend.
|
||||
|
||||
**Alternative: manual export with the old binary.** Old binaries are always available on [GitHub Releases](https://github.com/gastownhall/beads/releases). Download the version that matches your project, then:
|
||||
|
||||
```bash
|
||||
# 1. Export with the old binary
|
||||
./bd-old list --json -n 0 --all > .beads/issues.jsonl
|
||||
|
||||
# 2. Import with the current binary
|
||||
bd init --from-jsonl --quiet
|
||||
|
||||
# 3. Verify
|
||||
bd list --all
|
||||
```
|
||||
|
||||
> **Note:** The manual export preserves issue content but not dependencies or labels. Use the migration script for a more complete transfer.
|
||||
|
||||
## Troubleshooting Upgrades
|
||||
|
||||
### Hooks out of date
|
||||
|
||||
```bash
|
||||
bd hooks install
|
||||
```
|
||||
|
||||
### Database schema changed
|
||||
|
||||
```bash
|
||||
bd migrate --dry-run
|
||||
bd migrate
|
||||
```
|
||||
|
||||
### Recovery after upgrade
|
||||
|
||||
If you need to restore from a backup:
|
||||
|
||||
```bash
|
||||
bd init
|
||||
bd backup restore [path] --force
|
||||
```
|
||||
|
||||
Or pull from a Dolt remote:
|
||||
|
||||
```bash
|
||||
bd dolt pull
|
||||
```
|
||||
4
docs/images/favicon.svg
Normal file
4
docs/images/favicon.svg
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
<svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
|
||||
<rect width="32" height="32" rx="6" fill="#25c2a0"/>
|
||||
<text x="16" y="23" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#ffffff">bd</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 298 B |
4
docs/images/logo.svg
Normal file
4
docs/images/logo.svg
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
<svg width="32" height="32" viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
|
||||
<rect width="32" height="32" rx="6" fill="#25c2a0"/>
|
||||
<text x="16" y="23" text-anchor="middle" font-family="system-ui, -apple-system, sans-serif" font-size="18" font-weight="700" fill="#ffffff">bd</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 298 B |
85
docs/index.md
Normal file
85
docs/index.md
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
---
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
**Beads** (`bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows.
|
||||
|
||||
## Why Beads?
|
||||
|
||||
Traditional issue trackers (Jira, GitHub Issues) weren't designed for AI agents. Beads was built from the ground up for:
|
||||
|
||||
- **AI-native workflows** - Hash-based IDs prevent collisions when multiple agents work concurrently
|
||||
- **Dolt-backed storage** - Issues stored in a version-controlled SQL database, enabling collaboration via Dolt-native replication
|
||||
- **Dependency-aware execution** - `bd ready` shows only unblocked work
|
||||
- **Formula system** - Declarative templates for repeatable workflows
|
||||
- **Multi-agent coordination** - Routing, gates, and molecules for complex workflows
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Install via Homebrew (macOS/Linux)
|
||||
brew install beads
|
||||
|
||||
# Or quick install (macOS/Linux/FreeBSD)
|
||||
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
|
||||
# Initialize in your project
|
||||
cd your-project
|
||||
bd init --quiet
|
||||
|
||||
# Create your first issue
|
||||
bd create "Set up database" -p 1 -t task
|
||||
|
||||
# See ready work
|
||||
bd ready
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
| Concept | Description |
|
||||
|---------|-------------|
|
||||
| **Issues** | Work items with priorities, types, labels, and dependencies |
|
||||
| **Dependencies** | `blocks`, `parent-child`, `discovered-from`, `related` |
|
||||
| **Dolt Server** | Database server for multi-writer access and performance |
|
||||
| **Formulas** | Declarative workflow templates (TOML or JSON) |
|
||||
| **Molecules** | Work graphs with parent-child relationships |
|
||||
| **Gates** | Async coordination primitives (human, timer, GitHub) |
|
||||
|
||||
## For AI Agents
|
||||
|
||||
Beads is optimized for AI coding agents:
|
||||
|
||||
```bash
|
||||
# Always use --json for programmatic access
|
||||
bd list --json
|
||||
bd show bd-42 --json
|
||||
|
||||
# Track discovered work during implementation
|
||||
bd create "Found bug in auth" --description="Details..." \
|
||||
--deps discovered-from:bd-100 --json
|
||||
|
||||
# Push changes at end of session
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
See the [Claude Code integration](/integrations/claude-code) for detailed agent instructions.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Dolt DB (.beads/embeddeddolt/ in embedded mode,
|
||||
.beads/dolt/ in server mode; gitignored)
|
||||
↕ dolt commit
|
||||
Local Dolt history
|
||||
↕ dolt push/pull
|
||||
Remote Dolt repository (shared across machines)
|
||||
```
|
||||
|
||||
The magic is automatic synchronization via Dolt's version-controlled database with built-in replication.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Installation](/getting-started/installation) - Get bd installed
|
||||
- [Quick Start](/getting-started/quickstart) - Create your first issues
|
||||
- [CLI Reference](/cli-reference/index) - All available commands
|
||||
- [Workflows](/workflows/index) - Formulas, molecules, and gates
|
||||
137
docs/integrations/aider.md
Normal file
137
docs/integrations/aider.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
title: Aider
|
||||
---
|
||||
|
||||
How to use beads with Aider.
|
||||
|
||||
[Aider](https://aider.chat/) is a human-in-the-loop AI pair programming tool: unlike autonomous agents such as [Claude Code](/integrations/claude-code), it doesn't run shell commands on its own. The beads integration works with that design — the AI **suggests** `bd` commands, and you confirm each one with aider's `/run` command.
|
||||
|
||||
## Setup
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- beads installed and initialized in your project (see [Installation](/getting-started/installation)); run `bd init` if there's no `.beads/` directory yet
|
||||
- aider installed: `pip install aider-chat` (or `pipx install aider-chat`)
|
||||
|
||||
### Quick Setup
|
||||
|
||||
```bash
|
||||
bd setup aider
|
||||
```
|
||||
|
||||
This creates:
|
||||
|
||||
- `.aider.conf.yml` — tells aider to load the beads instructions
|
||||
- `.aider/BEADS.md` — workflow instructions the AI reads
|
||||
- `.aider/README.md` — quick reference for humans
|
||||
|
||||
### Verify Setup
|
||||
|
||||
```bash
|
||||
bd setup aider --check
|
||||
```
|
||||
|
||||
### Remove the Integration
|
||||
|
||||
```bash
|
||||
bd setup aider --remove
|
||||
```
|
||||
|
||||
This removes `.aider.conf.yml`, `.aider/BEADS.md`, and `.aider/README.md`.
|
||||
|
||||
## Configuration
|
||||
|
||||
The generated `.aider.conf.yml` loads the beads instructions into aider's read-only context:
|
||||
|
||||
```yaml
|
||||
# Beads Issue Tracking Integration for Aider
|
||||
# Auto-generated by 'bd setup aider'
|
||||
|
||||
# Load Beads workflow instructions for the AI
|
||||
read:
|
||||
- .aider/BEADS.md
|
||||
```
|
||||
|
||||
`.aider/BEADS.md` holds the workflow rules the AI follows: track all work in bd (never markdown TODOs), suggest `bd ready` to find work, suggest `bd create` for new issues, suggest `bd dolt push` at end of session — and always *suggest* commands for you to run via `/run`. You can edit it to add project-specific instructions, but rerunning `bd setup aider` regenerates it.
|
||||
|
||||
## Workflow
|
||||
|
||||
### Start Session
|
||||
|
||||
```bash
|
||||
# Aider will have access to issues via .aider.conf.yml
|
||||
aider
|
||||
|
||||
# Or manually inject context
|
||||
bd prime | aider --message-file -
|
||||
```
|
||||
|
||||
### During Work
|
||||
|
||||
Use bd commands alongside aider:
|
||||
|
||||
```bash
|
||||
# In another terminal or after exiting aider
|
||||
bd create "Found bug during work" --deps discovered-from:bd-42 --json
|
||||
bd update bd-42 --claim
|
||||
bd ready
|
||||
```
|
||||
|
||||
### End Session
|
||||
|
||||
```bash
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep issues visible** - Use `bd prime` to inject issue context
|
||||
2. **Push regularly** - Run `bd dolt push` after significant changes
|
||||
3. **Use discovered-from** - Track issues found during work
|
||||
4. **Document context** - Include descriptions in issues
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```bash
|
||||
# 1. Check ready work
|
||||
bd ready
|
||||
|
||||
# 2. Start aider with issue context
|
||||
aider --message "Working on bd-42: Fix auth bug"
|
||||
|
||||
# 3. Work in aider...
|
||||
|
||||
# 4. Create discovered issues
|
||||
bd create "Found related bug" --deps discovered-from:bd-42 --json
|
||||
|
||||
# 5. Complete and push
|
||||
bd close bd-42 --reason "Fixed"
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Config not loading
|
||||
|
||||
```bash
|
||||
# Check config exists
|
||||
cat .aider.conf.yml
|
||||
|
||||
# Regenerate
|
||||
bd setup aider
|
||||
```
|
||||
|
||||
### Issues not visible
|
||||
|
||||
```bash
|
||||
# Use bd prime to inject issue context
|
||||
bd prime | aider --message-file -
|
||||
|
||||
# Or check database health
|
||||
bd doctor
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Claude Code](/integrations/claude-code)
|
||||
- [IDE Setup](/getting-started/ide-setup)
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Azure DevOps (ADO) Integration Configuration
|
||||
---
|
||||
title: Azure DevOps (ADO) Integration Configuration
|
||||
---
|
||||
|
||||
Last reviewed: 2026-05-08
|
||||
|
||||
392
docs/integrations/claude-code-plugin.md
Normal file
392
docs/integrations/claude-code-plugin.md
Normal file
|
|
@ -0,0 +1,392 @@
|
|||
---
|
||||
title: Beads Claude Code Plugin
|
||||
---
|
||||
|
||||
AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple slash commands and MCP tools.
|
||||
|
||||
## What is Beads?
|
||||
|
||||
Beads (`bd`) is an issue tracker designed specifically for AI-supervised coding workflows. It helps AI agents and developers:
|
||||
- Track work with a simple CLI
|
||||
- Discover and link related tasks during development
|
||||
- Maintain context across coding sessions
|
||||
- Sync issues via Dolt remotes for distributed workflows
|
||||
|
||||
## Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Install beads CLI:
|
||||
```bash
|
||||
curl -sSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
2. Install Python and uv (for MCP server):
|
||||
```bash
|
||||
# Install uv (if not already installed)
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
```
|
||||
|
||||
### Install Plugin
|
||||
|
||||
There are two ways to install the beads plugin:
|
||||
|
||||
#### Option 1: From GitHub (Recommended)
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
/plugin marketplace add gastownhall/beads
|
||||
/plugin install beads
|
||||
```
|
||||
|
||||
#### Option 2: Local Development
|
||||
|
||||
```bash
|
||||
# Clone the repository (shell command)
|
||||
git clone https://github.com/gastownhall/beads
|
||||
cd beads
|
||||
```
|
||||
|
||||
Then in Claude Code:
|
||||
|
||||
```
|
||||
# Add local marketplace (Claude Code command)
|
||||
/plugin marketplace add ./beads
|
||||
|
||||
# Install plugin
|
||||
/plugin install beads
|
||||
```
|
||||
|
||||
**Note:** If you want to install the plugin from a different repo, first `cd` to that repo's directory in your terminal, then use `./beads` (or the relative path to the beads directory) in Claude Code.
|
||||
|
||||
### Restart Claude Code
|
||||
|
||||
After installation, restart Claude Code to activate the MCP server.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Initialize beads in your project
|
||||
/beads:init
|
||||
|
||||
# Create your first issue
|
||||
/beads:create "Set up project structure" feature 1
|
||||
|
||||
# See what's ready to work on
|
||||
/beads:ready
|
||||
|
||||
# Show full workflow guide
|
||||
/beads:workflow
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
### Version Management
|
||||
|
||||
- **`/beads:version`** - Check bd CLI, plugin, and MCP server versions
|
||||
|
||||
### Core Workflow Commands
|
||||
|
||||
- **`/beads:ready`** - Find tasks with no blockers, ready to work on
|
||||
- **`/beads:create [title] [type] [priority]`** - Create a new issue interactively
|
||||
- **`/beads:show [issue-id]`** - Show detailed information about an issue
|
||||
- **`/beads:update [issue-id] [status]`** - Update issue status or other fields
|
||||
- **`/beads:close [issue-id] [reason]`** - Close a completed issue
|
||||
|
||||
### Project Management
|
||||
|
||||
- **`/beads:init`** - Initialize beads in the current project
|
||||
- **`/beads:workflow`** - Show the AI-supervised issue workflow guide
|
||||
- **`/beads:stats`** - Show project statistics and progress
|
||||
|
||||
### Agents
|
||||
|
||||
- **`@task-agent`** - Autonomous agent that finds and completes ready tasks
|
||||
|
||||
## MCP Tools Available
|
||||
|
||||
The plugin includes a full-featured MCP server with these tools:
|
||||
|
||||
- **`init`** - Initialize bd in current directory
|
||||
- **`create`** - Create new issue (bug, feature, task, epic, chore)
|
||||
- **`list`** - List issues with filters (status, priority, type, assignee)
|
||||
- **`ready`** - Find tasks with no blockers ready to work on
|
||||
- **`show`** - Show detailed issue info including dependencies
|
||||
- **`update`** - Update issue (status, priority, design, notes, etc)
|
||||
- **`close`** - Close completed issue
|
||||
- **`dep`** - Add dependency (blocks, related, parent-child, discovered-from)
|
||||
- **`blocked`** - Get blocked issues
|
||||
- **`stats`** - Get project statistics
|
||||
|
||||
### MCP Resources
|
||||
|
||||
- **`beads://quickstart`** - Interactive quickstart guide
|
||||
|
||||
## Workflow
|
||||
|
||||
The beads workflow is designed for AI agents but works great for humans too:
|
||||
|
||||
1. **Find ready work**: `/beads:ready`
|
||||
2. **Claim your task**: `/beads:update <id> in_progress`
|
||||
3. **Work on it**: Implement, test, document
|
||||
4. **Discover new work**: Create issues for bugs/TODOs found during work
|
||||
5. **Complete**: `/beads:close <id> "Done: <summary>"`
|
||||
6. **Repeat**: Check for newly unblocked tasks
|
||||
|
||||
## Issue Types
|
||||
|
||||
- **`bug`** - Something broken that needs fixing
|
||||
- **`feature`** - New functionality
|
||||
- **`task`** - Work item (tests, docs, refactoring)
|
||||
- **`epic`** - Large feature composed of multiple issues
|
||||
- **`chore`** - Maintenance work (dependencies, tooling)
|
||||
|
||||
## Priority Levels
|
||||
|
||||
- **`0`** - Critical (security, data loss, broken builds)
|
||||
- **`1`** - High (major features, important bugs)
|
||||
- **`2`** - Medium (nice-to-have features, minor bugs)
|
||||
- **`3`** - Low (polish, optimization)
|
||||
- **`4`** - Backlog (future ideas)
|
||||
|
||||
## Dependency Types
|
||||
|
||||
- **`blocks`** - Hard dependency (issue X blocks issue Y from starting)
|
||||
- **`related`** - Soft relationship (issues are connected)
|
||||
- **`parent-child`** - Epic/subtask relationship
|
||||
- **`discovered-from`** - Track issues discovered during work
|
||||
|
||||
Only `blocks` dependencies affect the ready work queue.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Auto-Approval Configuration
|
||||
|
||||
By default, Claude Code asks for confirmation every time the beads MCP server wants to run a command. This is a security feature, but it can disrupt workflow during active development.
|
||||
|
||||
**Available Options:**
|
||||
|
||||
#### 1. Auto-Approve All Beads Tools (Recommended for Trusted Projects)
|
||||
|
||||
Add to your Claude Code `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledMcpjsonServers": ["beads"]
|
||||
}
|
||||
```
|
||||
|
||||
This auto-approves all beads commands without prompting.
|
||||
|
||||
#### 2. Auto-Approve Project MCP Servers
|
||||
|
||||
Add to your Claude Code `settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"enableAllProjectMcpServers": true
|
||||
}
|
||||
```
|
||||
|
||||
This auto-approves all MCP servers defined in your project's `.mcp.json` file. Useful when working across multiple projects with different MCP requirements.
|
||||
|
||||
#### 3. Manual Approval (Default)
|
||||
|
||||
No configuration needed. Claude Code will prompt for approval on each MCP tool invocation.
|
||||
|
||||
**Security Trade-offs:**
|
||||
|
||||
- **Manual approval (default)**: Maximum safety, but interrupts workflow frequently
|
||||
- **Server-level auto-approval**: Convenient for trusted projects, but allows any beads operation without confirmation
|
||||
- **Project-level auto-approval**: Good balance for multi-project workflows with project-specific trust levels
|
||||
|
||||
**Limitation:** Claude Code doesn't currently support per-tool approval granularity. You cannot auto-approve only read operations (like `bd ready`, `bd show`) while requiring confirmation for mutations (like `bd create`, `bd update`). It's all-or-nothing at the server level.
|
||||
|
||||
**Recommended Configuration:**
|
||||
|
||||
For active development on trusted projects where you're frequently using beads:
|
||||
|
||||
```json
|
||||
{
|
||||
"enabledMcpjsonServers": ["beads"]
|
||||
}
|
||||
```
|
||||
|
||||
For more information, see the [Claude Code settings documentation](https://docs.claude.com/en/docs/claude-code/settings).
|
||||
|
||||
### Environment Variables
|
||||
|
||||
The MCP server supports these environment variables:
|
||||
|
||||
- **`BEADS_PATH`** - Path to bd executable (default: `bd` in PATH)
|
||||
- **`BEADS_DB`** - Path to beads database file (default: auto-discover from cwd)
|
||||
- **`BEADS_ACTOR`** - Actor name for audit trail (default: `$USER`)
|
||||
- **`BEADS_NO_AUTO_FLUSH`** - Disable automatic sync (default: `false`)
|
||||
- **`BEADS_NO_AUTO_IMPORT`** - Disable automatic import (default: `false`)
|
||||
|
||||
To customize, edit your Claude Code MCP settings or the plugin configuration.
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic Task Management
|
||||
|
||||
```bash
|
||||
# Create a high-priority bug
|
||||
/beads:create "Fix authentication" bug 1
|
||||
|
||||
# See ready work
|
||||
/beads:ready
|
||||
|
||||
# Start working on bd-10
|
||||
/beads:update bd-10 in_progress
|
||||
|
||||
# Complete the task
|
||||
/beads:close bd-10 "Fixed auth token validation"
|
||||
```
|
||||
|
||||
### Discovering Work During Development
|
||||
|
||||
```bash
|
||||
# Working on bd-10, found a related bug
|
||||
/beads:create "Add rate limiting to API" feature 2
|
||||
|
||||
# Link it to current work (via MCP tool)
|
||||
# Use `dep` tool: issue="bd-11", depends_on="bd-10", type="discovered-from"
|
||||
|
||||
# Close original task
|
||||
/beads:close bd-10 "Done, discovered bd-11 for rate limiting"
|
||||
```
|
||||
|
||||
### Using the Task Agent
|
||||
|
||||
```bash
|
||||
# Let the agent find and complete ready work
|
||||
@task-agent
|
||||
|
||||
# The agent will:
|
||||
# 1. Find ready work with `ready` tool
|
||||
# 2. Claim a task by updating status
|
||||
# 3. Execute the work
|
||||
# 4. Create issues for discoveries
|
||||
# 5. Close when complete
|
||||
# 6. Repeat
|
||||
```
|
||||
|
||||
## Auto-Sync with Dolt
|
||||
|
||||
Beads automatically commits changes to Dolt history after every write operation. This enables seamless collaboration:
|
||||
|
||||
```bash
|
||||
# Make changes
|
||||
bd create "Add feature" -p 1
|
||||
|
||||
# Changes are automatically committed to Dolt history
|
||||
# Sync with remotes when ready:
|
||||
bd dolt push
|
||||
|
||||
# Pull changes from collaborators:
|
||||
bd dolt pull
|
||||
bd ready # Shows issues ready to work on (with fresh data)
|
||||
```
|
||||
|
||||
## Updating
|
||||
|
||||
The beads plugin has three components that may need updating:
|
||||
|
||||
### 1. Plugin Updates
|
||||
|
||||
Check for plugin updates:
|
||||
```bash
|
||||
/plugin update beads
|
||||
```
|
||||
|
||||
Claude Code will pull the latest version from GitHub. After updating, **restart Claude Code** to apply MCP server changes.
|
||||
|
||||
### 2. bd CLI Updates
|
||||
|
||||
The plugin requires the `bd` CLI to be installed. Update it separately:
|
||||
|
||||
```bash
|
||||
# Quick update
|
||||
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
|
||||
# Or with Go (server-mode only)
|
||||
CGO_ENABLED=0 go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
|
||||
# Or with Go (embedded-capable)
|
||||
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### 3. Version Compatibility
|
||||
|
||||
The MCP server **automatically checks** bd CLI version on startup and will fail with a clear error if your version is too old.
|
||||
|
||||
Check version compatibility manually:
|
||||
```bash
|
||||
/beads:version
|
||||
```
|
||||
|
||||
This will show:
|
||||
- bd CLI version
|
||||
- Plugin version
|
||||
- MCP server status
|
||||
- Compatibility warnings if versions mismatch
|
||||
|
||||
**Recommended update workflow:**
|
||||
1. Check versions: `/beads:version`
|
||||
2. Update bd CLI if needed (see above)
|
||||
3. Update plugin: `/plugin update beads`
|
||||
4. Restart Claude Code
|
||||
5. Verify: `/beads:version`
|
||||
|
||||
### Version Numbering
|
||||
|
||||
Beads follows semantic versioning. The plugin version tracks the bd CLI version:
|
||||
- Plugin 0.9.2 requires bd CLI >= 0.9.0 (checked automatically at startup)
|
||||
- Major version bumps may introduce breaking changes
|
||||
- Check CHANGELOG.md for release notes
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Plugin not appearing
|
||||
|
||||
1. Check installation: `/plugin list`
|
||||
2. Restart Claude Code
|
||||
3. Verify `bd` is in PATH: `which bd`
|
||||
4. Check uv is installed: `which uv`
|
||||
|
||||
### MCP server not connecting
|
||||
|
||||
1. Check MCP server list: `/mcp`
|
||||
2. Look for "beads" server with plugin indicator
|
||||
3. Restart Claude Code to reload MCP servers
|
||||
4. Check logs for errors
|
||||
|
||||
### Commands not working
|
||||
|
||||
1. Make sure you're in a project with beads initialized: `/beads:init`
|
||||
2. Check if database exists: `ls -la .beads/`
|
||||
3. Try direct MCP tool access instead of slash commands
|
||||
4. Check the beads CLI works: `bd --help`
|
||||
|
||||
### MCP tool errors
|
||||
|
||||
1. Verify `bd` executable location: `BEADS_PATH` env var
|
||||
2. Check `bd` works in terminal: `bd stats`
|
||||
3. Review MCP server logs in Claude Code
|
||||
4. Try reinitializing: `/beads:init`
|
||||
|
||||
## Learn More
|
||||
|
||||
- **GitHub**: https://github.com/gastownhall/beads
|
||||
- **Documentation**: See README.md in the repository
|
||||
- **Examples**: Check `examples/` directory for integration patterns
|
||||
- **MCP Server**: See `integrations/beads-mcp/` for server details
|
||||
|
||||
## Contributing
|
||||
|
||||
Found a bug or have a feature idea? Create an issue in the beads repository!
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see LICENSE file in the repository.
|
||||
181
docs/integrations/claude-code.md
Normal file
181
docs/integrations/claude-code.md
Normal file
|
|
@ -0,0 +1,181 @@
|
|||
---
|
||||
title: Claude Code
|
||||
---
|
||||
|
||||
How to use beads with Claude Code.
|
||||
|
||||
## Setup
|
||||
|
||||
### Quick Setup
|
||||
|
||||
```bash
|
||||
bd setup claude
|
||||
```
|
||||
|
||||
This installs:
|
||||
- **SessionStart hook** - Runs `bd prime` on session start
|
||||
- **SessionStart compact refresh** - Runs `bd prime` after context compaction
|
||||
|
||||
### Manual Setup
|
||||
|
||||
Add to your Claude Code hooks configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": ["bd prime"],
|
||||
"SessionStart": ["bd prime"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Verify Setup
|
||||
|
||||
```bash
|
||||
bd setup claude --check
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Session starts** → `bd prime` injects ~1-2k tokens of context
|
||||
2. **You work** → Use `bd` CLI commands directly
|
||||
3. **Session compacts** → `bd prime` refreshes workflow context before compaction
|
||||
4. **Session ends** → Changes synced via git
|
||||
|
||||
## Essential Commands for Agents
|
||||
|
||||
### Creating Issues
|
||||
|
||||
```bash
|
||||
# Always include description for context
|
||||
bd create "Fix authentication bug" \
|
||||
--description="Login fails with special characters in password" \
|
||||
-t bug -p 1 --json
|
||||
|
||||
# Link discovered issues
|
||||
bd create "Found SQL injection" \
|
||||
--description="User input not sanitized in query builder" \
|
||||
--deps discovered-from:bd-42 --json
|
||||
```
|
||||
|
||||
### Working on Issues
|
||||
|
||||
```bash
|
||||
# Find ready work
|
||||
bd ready --json
|
||||
|
||||
# Start work
|
||||
bd update bd-42 --claim --json
|
||||
|
||||
# Complete work
|
||||
bd close bd-42 --reason "Fixed in commit abc123" --json
|
||||
```
|
||||
|
||||
### Querying
|
||||
|
||||
```bash
|
||||
# List open issues
|
||||
bd list --status open --json
|
||||
|
||||
# Show issue details
|
||||
bd show bd-42 --json
|
||||
|
||||
# Check blocked issues
|
||||
bd blocked --json
|
||||
```
|
||||
|
||||
### Syncing
|
||||
|
||||
```bash
|
||||
# ALWAYS run at session end
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Always Use `--json`
|
||||
|
||||
```bash
|
||||
bd list --json # Parse programmatically
|
||||
bd create "Task" --json # Get issue ID from output
|
||||
bd show bd-42 --json # Structured data
|
||||
```
|
||||
|
||||
### Always Include Descriptions
|
||||
|
||||
```bash
|
||||
# Good
|
||||
bd create "Fix auth bug" \
|
||||
--description="Login fails when password contains quotes" \
|
||||
-t bug -p 1 --json
|
||||
|
||||
# Bad - no context for future work
|
||||
bd create "Fix auth bug" -t bug -p 1 --json
|
||||
```
|
||||
|
||||
### Link Related Work
|
||||
|
||||
```bash
|
||||
# When you discover issues during work
|
||||
bd create "Found related bug" \
|
||||
--deps discovered-from:bd-current --json
|
||||
```
|
||||
|
||||
### Push Before Session End
|
||||
|
||||
```bash
|
||||
# ALWAYS run before ending
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
## Plugin (Optional)
|
||||
|
||||
For enhanced UX with slash commands:
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
/plugin marketplace add gastownhall/beads
|
||||
/plugin install beads
|
||||
# Restart Claude Code
|
||||
```
|
||||
|
||||
Adds slash commands:
|
||||
- `/beads:ready` - Show ready work
|
||||
- `/beads:create` - Create issue
|
||||
- `/beads:show` - Show issue
|
||||
- `/beads:update` - Update issue
|
||||
- `/beads:close` - Close issue
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Context not injected
|
||||
|
||||
```bash
|
||||
# Check hook setup
|
||||
bd setup claude --check
|
||||
|
||||
# Manually prime
|
||||
bd prime
|
||||
```
|
||||
|
||||
### Changes not syncing
|
||||
|
||||
```bash
|
||||
# Force push
|
||||
bd dolt push
|
||||
|
||||
# Check system health
|
||||
bd doctor
|
||||
```
|
||||
|
||||
### Database not found
|
||||
|
||||
```bash
|
||||
# Initialize beads
|
||||
bd init --quiet
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [MCP Server](/integrations/mcp-server) - For MCP-only environments
|
||||
- [IDE Setup](/getting-started/ide-setup) - Other editors
|
||||
32
docs/integrations/codex.md
Normal file
32
docs/integrations/codex.md
Normal file
|
|
@ -0,0 +1,32 @@
|
|||
---
|
||||
title: Codex
|
||||
---
|
||||
|
||||
Use Beads with Codex through the `beads` skill, managed `AGENTS.md` guidance, and native Codex hooks.
|
||||
|
||||
```bash
|
||||
bd setup codex
|
||||
bd setup codex --check
|
||||
```
|
||||
|
||||
Project setup writes:
|
||||
|
||||
- `.agents/skills/beads/` for the Beads skill.
|
||||
- `AGENTS.md` with a managed Beads section.
|
||||
- `.codex/config.toml` with `[features].hooks = true`.
|
||||
- `.codex/hooks.json` with the Beads hook fallback.
|
||||
|
||||
`bd init` runs this project setup by default unless `--skip-agents` or `--stealth` is used. Global setup uses `bd setup codex --global` and writes under `$CODEX_HOME` when set, otherwise `~/.codex`.
|
||||
|
||||
Codex 0.129.0+ supports `/hooks`, compact lifecycle hooks, and hook-provided developer context. Beads uses that lifecycle to inject `bd prime` on session start and recover context after compaction. Use `/hooks` to inspect or toggle the installed handlers.
|
||||
|
||||
## Hook Lifecycle
|
||||
|
||||
- `SessionStart` (`startup|resume|clear`) injects full `bd prime` output.
|
||||
- `PreCompact` (`manual|auto`) checks `bd prime --memories-only` and warns if Beads context is unavailable.
|
||||
- `PostCompact` (`manual|auto`) records that the session needs a Beads refresh.
|
||||
- `UserPromptSubmit` injects full `bd prime` once after compaction, then clears the refresh marker.
|
||||
|
||||
`PreCompact` alone does not inject context because Codex ignores plain stdout from compact hooks. The post-compact marker plus first-prompt refresh is the reliable recovery path.
|
||||
|
||||
The Beads Codex plugin stores hooks at `plugins/beads/.codex-plugin/hooks/hooks.json` and declares them as `"hooks": "./hooks/hooks.json"`. Without the plugin, `bd setup codex` installs the same hook config in `.codex/hooks.json` and enables `[features].hooks = true`.
|
||||
18
docs/integrations/cody.md
Normal file
18
docs/integrations/cody.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: Sourcegraph Cody
|
||||
---
|
||||
|
||||
Use Beads with Sourcegraph Cody through a project rules file.
|
||||
|
||||
```bash
|
||||
bd setup cody
|
||||
bd setup cody --check
|
||||
```
|
||||
|
||||
The setup command creates `.cody/rules/beads.md` with Beads workflow guidance.
|
||||
|
||||
## Remove
|
||||
|
||||
```bash
|
||||
bd setup cody --remove
|
||||
```
|
||||
|
|
@ -1,8 +1,10 @@
|
|||
# GitHub Copilot CLI Integration Design
|
||||
---
|
||||
title: GitHub Copilot CLI Integration Design
|
||||
---
|
||||
|
||||
This document explains design decisions for GitHub Copilot CLI integration in beads.
|
||||
|
||||
For **VS Code + MCP**, see [COPILOT_INTEGRATION.md](COPILOT_INTEGRATION.md).
|
||||
For **VS Code + MCP**, see [COPILOT_INTEGRATION.md](/integrations/github-copilot).
|
||||
|
||||
## Integration Approach
|
||||
|
||||
149
docs/integrations/cursor.md
Normal file
149
docs/integrations/cursor.md
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
---
|
||||
title: Cursor
|
||||
---
|
||||
|
||||
Use Beads with Cursor through a project rules file **and** agent lifecycle hooks.
|
||||
The hooks are what keep Beads context alive across compaction — without them,
|
||||
Cursor only sees the static rules file and the agent must remember to run
|
||||
`bd prime` itself (which it often forgets after a context compaction).
|
||||
|
||||
```bash
|
||||
bd setup cursor
|
||||
bd setup cursor --check
|
||||
```
|
||||
|
||||
`bd setup cursor` installs three things:
|
||||
|
||||
- **`.cursor/rules/beads.mdc`** — an always-applied rule with the canonical Beads
|
||||
workflow guidance (the same content every other editor integration uses), so it
|
||||
stays in sync as the workflow evolves. Because it is always applied, Cursor
|
||||
re-includes it every turn, including after a compaction.
|
||||
- **`.agents/skills/beads/SKILL.md`** — the Beads agent skill, which Cursor loads
|
||||
natively from `.agents/skills/` (the same skill the Codex integration installs).
|
||||
It gives the agent an on-demand, progressive-disclosure reference for `bd`.
|
||||
- **`.cursor/hooks.json`** — agent hooks that run the hidden `bd cursor-hook`
|
||||
command at key points in the session. Existing (non-Beads) hooks in this file
|
||||
are preserved.
|
||||
|
||||
The managed hooks are:
|
||||
|
||||
| Event | What it does |
|
||||
|-------|--------------|
|
||||
| `sessionStart` | Injects full `bd prime` output so the agent starts every session already knowing the workflow, ready work, and project memories. |
|
||||
| `preCompact` | Arms a one-shot marker and shows a short reminder that context will be restored. |
|
||||
| `postToolUse` | After a compaction, re-injects `bd prime` exactly once on the next tool call, then no-ops. |
|
||||
|
||||
<Note>
|
||||
**Requirements**
|
||||
Hooks run in the Cursor IDE and in recent `cursor-agent` CLI builds (verified on
|
||||
the 2026.06 line; early-2026 CLI builds only fired shell hooks). After setup,
|
||||
restart Cursor or start a **new** `cursor-agent` session so the hooks load.
|
||||
|
||||
The hook entries call `bd cursor-hook`, which Cursor resolves on `PATH` — exactly
|
||||
like the Claude Code and Codex hooks. **But that `PATH` is not your shell's:**
|
||||
Cursor rebuilds it for hook subprocesses and prepends its own directories, so a
|
||||
stale `bd` earlier in *that* order silently wins and every hook fails with no
|
||||
visible error. The classic case is an old Homebrew `bd` (without the
|
||||
`cursor-hook` command) shadowing a newer build. Make sure the first `bd` Cursor
|
||||
finds is current — `~/.local/bin` and `~/go/bin` sort ahead of Homebrew in
|
||||
Cursor's PATH, so installing or symlinking `bd` there is a reliable way to win
|
||||
resolution.
|
||||
|
||||
In the CLI, the workspace must also be **trusted** — hooks do not run in an
|
||||
untrusted workspace.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
**Auto-installed by `bd init`**
|
||||
You usually don't need to run `bd setup cursor` by hand. `bd init` installs the
|
||||
Cursor integration automatically (the same way it sets up Claude Code and
|
||||
Codex), and stages `.cursor/` so the rules + hooks are committed with your repo.
|
||||
Run `bd setup cursor` only to (re)install into an existing project or to repair
|
||||
drift.
|
||||
</Tip>
|
||||
|
||||
## Global install (all projects)
|
||||
|
||||
To wire the hooks once for every project instead of per-repo:
|
||||
|
||||
```bash
|
||||
bd setup cursor --global # writes ~/.cursor/hooks.json
|
||||
bd setup cursor --check --global
|
||||
bd setup cursor --remove --global
|
||||
```
|
||||
|
||||
Global scope installs the **hooks and the agent skill** (`~/.agents/skills/beads`),
|
||||
but not a rules file. Cursor has no reliable file-based global *rules* location —
|
||||
global rules belong in **Cursor Settings → Rules** — so `.cursor/rules/beads.mdc`
|
||||
is project-scoped. This is fine in practice: the global `sessionStart` hook
|
||||
already injects the full `bd prime` context into every project, which supersedes
|
||||
the static rule.
|
||||
|
||||
## Why these specific hooks
|
||||
|
||||
The Claude Code / Codex integrations recover from compaction with a dedicated
|
||||
post-compaction event plus a prompt-submission hook. Cursor's
|
||||
[hook API](https://cursor.com/docs/hooks) doesn't offer equivalents, so the
|
||||
recovery is built from what Cursor *can* do:
|
||||
|
||||
- Cursor has **no post-compaction hook** — only `preCompact`, which is
|
||||
observational and "cannot block or modify the compaction behavior" (its only
|
||||
output is `user_message`). So `preCompact` just arms a one-shot marker and
|
||||
notifies you.
|
||||
- Only **two** hooks can inject model-visible context (`additional_context`):
|
||||
`sessionStart` and `postToolUse`. `sessionStart` fires only when a new
|
||||
conversation is created — not after a compaction, and not when resuming with
|
||||
`cursor-agent --continue`. `preCompact` and `postToolUse` *do* fire in resumed
|
||||
sessions, so compaction recovery still works under `--continue`; only the
|
||||
one-time start-of-session injection is skipped (the resumed conversation
|
||||
already contains it).
|
||||
- That makes `postToolUse` the only place to re-inject `bd prime` after a
|
||||
compaction — which the docs explicitly support ("Useful for ... injecting
|
||||
context").
|
||||
|
||||
<Warning>
|
||||
**Limitation**
|
||||
Post-compaction recovery fires on the **next tool call**. If you have a
|
||||
purely conversational turn right after a compaction (no tool use), the refresh
|
||||
waits until the next tool runs — no Cursor hook can inject context on a bare
|
||||
prompt. Agent sessions call tools often, so in practice this is quick. You can
|
||||
always run `bd prime` manually to force a refresh.
|
||||
</Warning>
|
||||
|
||||
## Verifying it works (CLI, no hooks pane)
|
||||
|
||||
The `cursor-agent` CLI has no hooks output pane, so verify the hooks directly:
|
||||
|
||||
```bash
|
||||
# sessionStart should return {"continue": true, "additional_context": "...bd prime..."}
|
||||
echo '{"hook_event_name":"sessionStart","workspace_roots":["'"$PWD"'"]}' \
|
||||
| bd cursor-hook sessionStart | jq .
|
||||
|
||||
# In a real session, the agent should know your bd workflow without being told,
|
||||
# and should recover it after a compaction without you running `bd prime`.
|
||||
```
|
||||
|
||||
If `additional_context` is empty, the directory is not a Beads workspace yet
|
||||
(run `bd init`) or `bd` is not on Cursor's `PATH`. Note this command runs *your
|
||||
shell's* `bd`; Cursor may resolve a different one for hooks (see Requirements
|
||||
above), so a passing check here doesn't guarantee Cursor runs the same build.
|
||||
|
||||
`bd doctor` also reports three Cursor checks (under integration diagnostics),
|
||||
paralleling the Claude checks:
|
||||
|
||||
- **Cursor Integration** — flags when Cursor is in use but the hooks aren't installed.
|
||||
- **Cursor Settings Health** — errors if `.cursor/hooks.json` is malformed JSON
|
||||
(which would silently disable every hook).
|
||||
- **Cursor Hook Completeness** — warns if only some of the three managed events
|
||||
are installed (e.g. after a hand-edit), since recovery needs all three.
|
||||
|
||||
## Remove
|
||||
|
||||
```bash
|
||||
bd setup cursor --remove
|
||||
```
|
||||
|
||||
This removes the rules file and the Beads-managed hook entries while leaving any
|
||||
of your own hooks in `.cursor/hooks.json` intact. The shared agent skill
|
||||
(`.agents/skills/beads`) is removed too — unless the Codex integration is still
|
||||
installed, in which case it is kept because both integrations use it.
|
||||
18
docs/integrations/factory.md
Normal file
18
docs/integrations/factory.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: Factory.ai Droid
|
||||
---
|
||||
|
||||
Use Beads with Factory.ai Droid through managed `AGENTS.md` guidance.
|
||||
|
||||
```bash
|
||||
bd setup factory
|
||||
bd setup factory --check
|
||||
```
|
||||
|
||||
The setup command creates or updates `AGENTS.md` with a managed Beads section. Factory Droid reads `AGENTS.md` automatically when it starts a session.
|
||||
|
||||
## Remove
|
||||
|
||||
```bash
|
||||
bd setup factory --remove
|
||||
```
|
||||
34
docs/integrations/gemini.md
Normal file
34
docs/integrations/gemini.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
title: Gemini CLI
|
||||
---
|
||||
|
||||
Use Beads with Gemini CLI through SessionStart hooks and `GEMINI.md` guidance.
|
||||
|
||||
```bash
|
||||
bd setup gemini
|
||||
bd setup gemini --check
|
||||
```
|
||||
|
||||
By default, setup installs global hooks in `~/.gemini/settings.json`. For project-local hooks, use:
|
||||
|
||||
```bash
|
||||
bd setup gemini --project
|
||||
```
|
||||
|
||||
The hook runs `bd prime --hook-json` so Gemini receives compact Beads workflow context at session start. The setup also writes Beads guidance to `GEMINI.md`.
|
||||
|
||||
## Stealth Mode
|
||||
|
||||
For CI or other environments where setup should avoid git operations:
|
||||
|
||||
```bash
|
||||
bd setup gemini --stealth
|
||||
bd setup gemini --project --stealth
|
||||
```
|
||||
|
||||
## Remove
|
||||
|
||||
```bash
|
||||
bd setup gemini --remove
|
||||
bd setup gemini --project --remove
|
||||
```
|
||||
141
docs/integrations/github-copilot.md
Normal file
141
docs/integrations/github-copilot.md
Normal file
|
|
@ -0,0 +1,141 @@
|
|||
---
|
||||
title: GitHub Copilot
|
||||
---
|
||||
|
||||
How to use beads with GitHub Copilot in VS Code.
|
||||
|
||||
## Setup
|
||||
|
||||
### Quick Setup
|
||||
|
||||
1. Install beads-mcp:
|
||||
```bash
|
||||
uv tool install beads-mcp
|
||||
```
|
||||
|
||||
2. Create `.vscode/mcp.json` in your project:
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**For all projects:** Add to VS Code user-level MCP config:
|
||||
|
||||
| Platform | Path |
|
||||
|----------|------|
|
||||
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
|
||||
| Linux | `~/.config/Code/User/mcp.json` |
|
||||
| Windows | `%APPDATA%\Code\User\mcp.json` |
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp",
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. Initialize beads:
|
||||
```bash
|
||||
bd init --quiet
|
||||
```
|
||||
|
||||
4. Reload VS Code
|
||||
|
||||
### Verify Setup
|
||||
|
||||
Ask Copilot Chat: "What beads issues are ready to work on?"
|
||||
|
||||
## Using Natural Language
|
||||
|
||||
With MCP configured, interact naturally:
|
||||
|
||||
```
|
||||
You: Create a bug for the login timeout
|
||||
Copilot: Created bd-42: Login timeout bug
|
||||
|
||||
You: What issues are ready?
|
||||
Copilot: 3 issues ready: bd-42, bd-99, bd-17
|
||||
|
||||
You: Close bd-42, it's fixed
|
||||
Copilot: Closed bd-42
|
||||
```
|
||||
|
||||
## MCP Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `beads_ready` | List unblocked issues |
|
||||
| `beads_create` | Create new issue |
|
||||
| `beads_show` | Show issue details |
|
||||
| `beads_update` | Update issue |
|
||||
| `beads_close` | Close issue |
|
||||
| `beads_dolt_push` | Push to Dolt remote |
|
||||
| `beads_dep_add` | Add dependency |
|
||||
| `beads_dep_tree` | Show dependency tree |
|
||||
|
||||
## Copilot Instructions
|
||||
|
||||
Optionally add `.github/copilot-instructions.md`:
|
||||
|
||||
```markdown
|
||||
## Issue Tracking
|
||||
|
||||
This project uses **bd (beads)** for issue tracking.
|
||||
Run `bd prime` for workflow context.
|
||||
|
||||
Quick reference:
|
||||
- `bd ready` - Find unblocked work
|
||||
- `bd create "Title" --type task --priority 2` - Create issue
|
||||
- `bd close <id>` - Complete work
|
||||
- `bd dolt push` - Push changes to Dolt remote
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Tools not appearing
|
||||
|
||||
1. Check VS Code 1.96+
|
||||
2. Verify mcp.json syntax is valid JSON
|
||||
3. Reload VS Code window
|
||||
4. Check Output panel for MCP errors
|
||||
|
||||
### "beads-mcp not found"
|
||||
|
||||
```bash
|
||||
# Check installation
|
||||
which beads-mcp
|
||||
|
||||
# Reinstall if needed
|
||||
uv tool install beads-mcp --force
|
||||
```
|
||||
|
||||
### No database found
|
||||
|
||||
```bash
|
||||
bd init --quiet
|
||||
```
|
||||
|
||||
## FAQ
|
||||
|
||||
### Do I need to clone beads?
|
||||
|
||||
**No.** Beads is a system-wide CLI tool. Install once, use everywhere. The `.beads/` directory in your project only contains the issue database.
|
||||
|
||||
### What about git hooks?
|
||||
|
||||
Git hooks are optional. They refresh exports and legacy fallback checks, while issue sync uses `bd dolt push` / `bd dolt pull`.
|
||||
|
||||
## See Also
|
||||
|
||||
- [MCP Server](/integrations/mcp-server) - Detailed MCP configuration
|
||||
- [Installation](/getting-started/installation) - Full install guide
|
||||
- [Detailed Copilot Guide](https://github.com/gastownhall/beads/blob/main/docs/COPILOT_INTEGRATION.md) - Comprehensive documentation
|
||||
38
docs/integrations/index.md
Normal file
38
docs/integrations/index.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: Integrations
|
||||
---
|
||||
|
||||
Beads integration pages are based on two sources of support in the repository:
|
||||
|
||||
- Built-in `bd setup` recipes from `internal/recipes/recipes.go`
|
||||
- First-party MCP integrations and editor guides already shipped in the repo
|
||||
|
||||
Run this command to see the built-in setup recipes supported by your installed `bd` binary:
|
||||
|
||||
```bash
|
||||
bd setup --list
|
||||
```
|
||||
|
||||
## Built-in Setup Recipes
|
||||
|
||||
| Recipe | Integration | Primary setup surface |
|
||||
|--------|-------------|-----------------------|
|
||||
| `aider` | [Aider](/integrations/aider) | `.aider.conf.yml` and `.aider/` instructions |
|
||||
| `claude` | [Claude Code](/integrations/claude-code) | Claude hooks and `CLAUDE.md` |
|
||||
| `codex` | [Codex](/integrations/codex) | Beads skill, `AGENTS.md`, and Codex hooks |
|
||||
| `cody` | [Sourcegraph Cody](/integrations/cody) | `.cody/rules/beads.md` |
|
||||
| `cursor` | [Cursor](/integrations/cursor) | `.cursor/rules/beads.mdc` + `.cursor/hooks.json` |
|
||||
| `factory` | [Factory.ai Droid](/integrations/factory) | `AGENTS.md` |
|
||||
| `gemini` | [Gemini CLI](/integrations/gemini) | Gemini hooks and `GEMINI.md` |
|
||||
| `junie` | [Junie](/integrations/junie) | `.junie/guidelines.md` and MCP config |
|
||||
| `kilocode` | [Kilo Code](/integrations/kilocode) | `.kilocode/rules/beads.md` |
|
||||
| `mux` | [Mux](/integrations/mux) | `AGENTS.md`, optional `.mux/AGENTS.md`, and Mux hooks |
|
||||
| `opencode` | [OpenCode](/integrations/opencode) | `AGENTS.md` |
|
||||
| `windsurf` | [Windsurf](/integrations/windsurf) | `.windsurf/rules/beads.md` |
|
||||
|
||||
## MCP-Based Integrations
|
||||
|
||||
These integrations use the Beads MCP server rather than a dedicated `bd setup` recipe:
|
||||
|
||||
- [MCP Server](/integrations/mcp-server)
|
||||
- [GitHub Copilot](/integrations/github-copilot)
|
||||
215
docs/integrations/junie.md
Normal file
215
docs/integrations/junie.md
Normal file
|
|
@ -0,0 +1,215 @@
|
|||
---
|
||||
title: Junie
|
||||
---
|
||||
|
||||
How to use beads with Junie (JetBrains AI Agent).
|
||||
|
||||
## Setup
|
||||
|
||||
### Quick Setup
|
||||
|
||||
```bash
|
||||
bd setup junie
|
||||
```
|
||||
|
||||
This creates:
|
||||
- **`.junie/guidelines.md`** - Agent instructions for beads workflow
|
||||
- **`.junie/mcp/mcp.json`** - MCP server configuration
|
||||
|
||||
### Verify Setup
|
||||
|
||||
```bash
|
||||
bd setup junie --check
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Session starts** → Junie reads `.junie/guidelines.md` for workflow context
|
||||
2. **MCP tools available** → Junie can use beads MCP tools directly
|
||||
3. **You work** → Use `bd` CLI commands or MCP tools
|
||||
4. **Session ends** → Run `bd dolt push` to push changes to Dolt remote
|
||||
|
||||
## Configuration Files
|
||||
|
||||
### Guidelines (`.junie/guidelines.md`)
|
||||
|
||||
Contains workflow instructions that Junie reads automatically:
|
||||
- Core workflow rules
|
||||
- Command reference
|
||||
- Issue types and priorities
|
||||
- MCP tool documentation
|
||||
|
||||
### MCP Config (`.junie/mcp/mcp.json`)
|
||||
|
||||
Configures the beads MCP server:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"beads": {
|
||||
"command": "bd",
|
||||
"args": ["mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## MCP Tools
|
||||
|
||||
With MCP configured, Junie can use these tools directly:
|
||||
|
||||
| Tool | Description |
|
||||
| --- | --- |
|
||||
| `mcp_beads_ready` | Find tasks ready for work |
|
||||
| `mcp_beads_list` | List issues with filters |
|
||||
| `mcp_beads_show` | Show issue details |
|
||||
| `mcp_beads_create` | Create new issues |
|
||||
| `mcp_beads_update` | Update issue status/priority |
|
||||
| `mcp_beads_close` | Close completed issues |
|
||||
| `mcp_beads_dep` | Manage dependencies |
|
||||
| `mcp_beads_blocked` | Show blocked issues |
|
||||
| `mcp_beads_stats` | Get issue statistics |
|
||||
|
||||
## CLI Commands
|
||||
|
||||
You can also use the `bd` CLI directly:
|
||||
|
||||
### Creating Issues
|
||||
|
||||
```bash
|
||||
# Always include description for context
|
||||
bd create "Fix authentication bug" \
|
||||
--description="Login fails with special characters in password" \
|
||||
-t bug -p 1 --json
|
||||
|
||||
# Link discovered issues
|
||||
bd create "Found SQL injection" \
|
||||
--description="User input not sanitized in query builder" \
|
||||
--deps discovered-from:bd-42 --json
|
||||
```
|
||||
|
||||
### Working on Issues
|
||||
|
||||
```bash
|
||||
# Find ready work
|
||||
bd ready --json
|
||||
|
||||
# Start work
|
||||
bd update bd-42 --claim --json
|
||||
|
||||
# Complete work
|
||||
bd close bd-42 --reason "Fixed in commit abc123" --json
|
||||
```
|
||||
|
||||
### Querying
|
||||
|
||||
```bash
|
||||
# List open issues
|
||||
bd list --status open --json
|
||||
|
||||
# Show issue details
|
||||
bd show bd-42 --json
|
||||
|
||||
# Check blocked issues
|
||||
bd blocked --json
|
||||
```
|
||||
|
||||
### Syncing
|
||||
|
||||
```bash
|
||||
# ALWAYS run at session end
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Always Use `--json`
|
||||
|
||||
```bash
|
||||
bd list --json # Parse programmatically
|
||||
bd create "Task" --json # Get issue ID from output
|
||||
bd show bd-42 --json # Structured data
|
||||
```
|
||||
|
||||
### Always Include Descriptions
|
||||
|
||||
```bash
|
||||
# Good
|
||||
bd create "Fix auth bug" \
|
||||
--description="Login fails when password contains quotes" \
|
||||
-t bug -p 1 --json
|
||||
|
||||
# Bad - no context for future work
|
||||
bd create "Fix auth bug" -t bug -p 1 --json
|
||||
```
|
||||
|
||||
### Link Related Work
|
||||
|
||||
```bash
|
||||
# When you discover issues during work
|
||||
bd create "Found related bug" \
|
||||
--deps discovered-from:bd-current --json
|
||||
```
|
||||
|
||||
### Push Before Session End
|
||||
|
||||
```bash
|
||||
# ALWAYS run before ending
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Guidelines not loaded
|
||||
|
||||
```bash
|
||||
# Check setup
|
||||
bd setup junie --check
|
||||
|
||||
# Reinstall if needed
|
||||
bd setup junie
|
||||
```
|
||||
|
||||
### MCP tools not available
|
||||
|
||||
```bash
|
||||
# Verify MCP config exists
|
||||
cat .junie/mcp/mcp.json
|
||||
|
||||
# Test MCP server
|
||||
bd mcp --help
|
||||
```
|
||||
|
||||
### Changes not syncing
|
||||
|
||||
```bash
|
||||
# Force push
|
||||
bd dolt push
|
||||
|
||||
# Check system health
|
||||
bd doctor
|
||||
```
|
||||
|
||||
### Database not found
|
||||
|
||||
```bash
|
||||
# Initialize beads
|
||||
bd init --quiet
|
||||
```
|
||||
|
||||
## Removing Integration
|
||||
|
||||
```bash
|
||||
bd setup junie --remove
|
||||
```
|
||||
|
||||
This removes:
|
||||
- `.junie/guidelines.md`
|
||||
- `.junie/mcp/mcp.json`
|
||||
- Empty `.junie/mcp/` and `.junie/` directories
|
||||
|
||||
## See Also
|
||||
|
||||
- [MCP Server](/integrations/mcp-server) - MCP server details
|
||||
- [Claude Code](/integrations/claude-code) - Similar hook-based integration
|
||||
- [IDE Setup](/getting-started/ide-setup) - Other editors
|
||||
18
docs/integrations/kilocode.md
Normal file
18
docs/integrations/kilocode.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: Kilo Code
|
||||
---
|
||||
|
||||
Use Beads with Kilo Code through a project rules file.
|
||||
|
||||
```bash
|
||||
bd setup kilocode
|
||||
bd setup kilocode --check
|
||||
```
|
||||
|
||||
The setup command creates `.kilocode/rules/beads.md` with Beads workflow guidance.
|
||||
|
||||
## Remove
|
||||
|
||||
```bash
|
||||
bd setup kilocode --remove
|
||||
```
|
||||
182
docs/integrations/mcp-server.md
Normal file
182
docs/integrations/mcp-server.md
Normal file
|
|
@ -0,0 +1,182 @@
|
|||
---
|
||||
title: MCP Server
|
||||
---
|
||||
|
||||
Use beads in MCP-only environments.
|
||||
|
||||
## When to Use MCP
|
||||
|
||||
Use MCP server when CLI is unavailable:
|
||||
- Claude Desktop (no shell access)
|
||||
- Sourcegraph Amp without shell
|
||||
- Other MCP-only environments
|
||||
|
||||
**Prefer CLI + hooks** when shell is available - it's more context efficient.
|
||||
|
||||
## Installation
|
||||
|
||||
### Using uv (Recommended)
|
||||
|
||||
```bash
|
||||
uv tool install beads-mcp
|
||||
```
|
||||
|
||||
### Using pip
|
||||
|
||||
```bash
|
||||
pip install beads-mcp
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Claude Desktop (macOS)
|
||||
|
||||
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Claude Desktop (Windows)
|
||||
|
||||
Add to `%APPDATA%\Claude\claude_desktop_config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Sourcegraph Amp
|
||||
|
||||
Add to MCP settings:
|
||||
|
||||
```json
|
||||
{
|
||||
"beads": {
|
||||
"command": "beads-mcp",
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### VS Code / GitHub Copilot
|
||||
|
||||
Create `.vscode/mcp.json` in your project:
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**For all projects:** Add to VS Code user-level MCP config:
|
||||
|
||||
| Platform | Path |
|
||||
|----------|------|
|
||||
| macOS | `~/Library/Application Support/Code/User/mcp.json` |
|
||||
| Linux | `~/.config/Code/User/mcp.json` |
|
||||
| Windows | `%APPDATA%\Code\User\mcp.json` |
|
||||
|
||||
```json
|
||||
{
|
||||
"servers": {
|
||||
"beads": {
|
||||
"command": "beads-mcp",
|
||||
"args": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Requires VS Code 1.96+ with MCP support enabled.
|
||||
|
||||
See [GitHub Copilot Integration](/integrations/github-copilot) for complete setup guide.
|
||||
|
||||
## Available Tools
|
||||
|
||||
The MCP server exposes these tools:
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `beads_create` | Create new issue |
|
||||
| `beads_list` | List issues |
|
||||
| `beads_show` | Show issue details |
|
||||
| `beads_update` | Update issue |
|
||||
| `beads_close` | Close issue |
|
||||
| `beads_ready` | Show ready work |
|
||||
| `beads_sync` | Sync to git |
|
||||
| `beads_dep_add` | Add dependency |
|
||||
| `beads_dep_tree` | Show dependency tree |
|
||||
|
||||
## Usage
|
||||
|
||||
Once configured, use naturally:
|
||||
|
||||
```
|
||||
Create an issue for fixing the login bug with priority 1
|
||||
```
|
||||
|
||||
The MCP server translates to appropriate `bd` commands.
|
||||
|
||||
## Trade-offs
|
||||
|
||||
| Aspect | CLI + Hooks | MCP Server |
|
||||
|--------|-------------|------------|
|
||||
| Context overhead | ~1-2k tokens | 10-50k tokens |
|
||||
| Latency | Direct calls | MCP protocol |
|
||||
| Setup | Hooks config | MCP config |
|
||||
| Availability | Shell required | MCP environments |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Server won't start
|
||||
|
||||
Check if `beads-mcp` is in PATH:
|
||||
|
||||
```bash
|
||||
which beads-mcp
|
||||
```
|
||||
|
||||
If not found:
|
||||
|
||||
```bash
|
||||
# Reinstall
|
||||
pip uninstall beads-mcp
|
||||
pip install beads-mcp
|
||||
```
|
||||
|
||||
### Tools not appearing
|
||||
|
||||
1. Restart Claude Desktop
|
||||
2. Check MCP config JSON syntax
|
||||
3. Verify server path
|
||||
|
||||
### Permission errors
|
||||
|
||||
```bash
|
||||
# Check directory permissions
|
||||
ls -la .beads/
|
||||
|
||||
# Initialize if needed
|
||||
bd init --quiet
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Claude Code](/integrations/claude-code) - CLI integration
|
||||
- [Installation](/getting-started/installation) - Full install guide
|
||||
38
docs/integrations/mux.md
Normal file
38
docs/integrations/mux.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
---
|
||||
title: Mux
|
||||
---
|
||||
|
||||
Use Beads with Mux through `AGENTS.md`, optional layered Mux instruction files, and Mux hooks.
|
||||
|
||||
```bash
|
||||
bd setup mux
|
||||
bd setup mux --check
|
||||
```
|
||||
|
||||
The default setup writes a managed Beads section to root `AGENTS.md`.
|
||||
|
||||
## Workspace and Global Layers
|
||||
|
||||
Mux also supports workspace and global instruction layers:
|
||||
|
||||
```bash
|
||||
bd setup mux --project
|
||||
bd setup mux --global
|
||||
bd setup mux --project --global
|
||||
```
|
||||
|
||||
Project setup writes `.mux/AGENTS.md` and installs Mux hook files under `.mux/`:
|
||||
|
||||
- `.mux/init`
|
||||
- `.mux/tool_post`
|
||||
- `.mux/tool_env`
|
||||
|
||||
Global setup writes `~/.mux/AGENTS.md`.
|
||||
|
||||
## Remove
|
||||
|
||||
```bash
|
||||
bd setup mux --remove
|
||||
bd setup mux --project --remove
|
||||
bd setup mux --global --remove
|
||||
```
|
||||
18
docs/integrations/opencode.md
Normal file
18
docs/integrations/opencode.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: OpenCode
|
||||
---
|
||||
|
||||
Use Beads with OpenCode through managed `AGENTS.md` guidance.
|
||||
|
||||
```bash
|
||||
bd setup opencode
|
||||
bd setup opencode --check
|
||||
```
|
||||
|
||||
The setup command creates or updates `AGENTS.md` with a managed Beads section. Restart OpenCode after setup if it is already running.
|
||||
|
||||
## Remove
|
||||
|
||||
```bash
|
||||
bd setup opencode --remove
|
||||
```
|
||||
18
docs/integrations/windsurf.md
Normal file
18
docs/integrations/windsurf.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
title: Windsurf
|
||||
---
|
||||
|
||||
Use Beads with Windsurf through a project rules file.
|
||||
|
||||
```bash
|
||||
bd setup windsurf
|
||||
bd setup windsurf --check
|
||||
```
|
||||
|
||||
The setup command creates `.windsurf/rules/beads.md` with Beads workflow guidance.
|
||||
|
||||
## Remove
|
||||
|
||||
```bash
|
||||
bd setup windsurf --remove
|
||||
```
|
||||
153
docs/multi-agent/coordination.md
Normal file
153
docs/multi-agent/coordination.md
Normal file
|
|
@ -0,0 +1,153 @@
|
|||
---
|
||||
title: Agent Coordination
|
||||
---
|
||||
|
||||
Patterns for coordinating work between multiple AI agents.
|
||||
|
||||
## Work Assignment
|
||||
|
||||
### Pinning Work
|
||||
|
||||
Assign work to a specific agent:
|
||||
|
||||
```bash
|
||||
# Pin issue to agent
|
||||
bd pin bd-42 --for agent-1
|
||||
|
||||
# Pin and start work
|
||||
bd pin bd-42 --for agent-1 --start
|
||||
|
||||
# Unpin work
|
||||
bd unpin bd-42
|
||||
```
|
||||
|
||||
### Checking Pinned Work
|
||||
|
||||
```bash
|
||||
# What's on my hook?
|
||||
bd hook
|
||||
|
||||
# What's on agent-1's hook?
|
||||
bd hook --agent agent-1
|
||||
|
||||
# JSON output
|
||||
bd hook --json
|
||||
```
|
||||
|
||||
## Handoff Patterns
|
||||
|
||||
### Sequential Handoff
|
||||
|
||||
Agent A completes work, hands off to Agent B:
|
||||
|
||||
```bash
|
||||
# Agent A
|
||||
bd close bd-42 --reason "Ready for review"
|
||||
bd pin bd-42 --for agent-b
|
||||
|
||||
# Agent B picks up
|
||||
bd hook # Sees bd-42
|
||||
bd update bd-42 --claim
|
||||
```
|
||||
|
||||
### Parallel Work
|
||||
|
||||
Multiple agents work on different issues:
|
||||
|
||||
```bash
|
||||
# Coordinator
|
||||
bd pin bd-42 --for agent-a --start
|
||||
bd pin bd-43 --for agent-b --start
|
||||
bd pin bd-44 --for agent-c --start
|
||||
|
||||
# Each agent works independently
|
||||
# Coordinator monitors progress
|
||||
bd list --status in_progress --json
|
||||
```
|
||||
|
||||
### Fan-Out / Fan-In
|
||||
|
||||
Split work, then merge:
|
||||
|
||||
```bash
|
||||
# Fan-out
|
||||
bd create "Part A" --parent bd-epic
|
||||
bd create "Part B" --parent bd-epic
|
||||
bd create "Part C" --parent bd-epic
|
||||
|
||||
bd pin bd-epic.1 --for agent-a
|
||||
bd pin bd-epic.2 --for agent-b
|
||||
bd pin bd-epic.3 --for agent-c
|
||||
|
||||
# Fan-in: wait for all parts
|
||||
bd dep add bd-merge bd-epic.1 bd-epic.2 bd-epic.3
|
||||
```
|
||||
|
||||
## Agent Discovery
|
||||
|
||||
Find available agents:
|
||||
|
||||
```bash
|
||||
# List known agents (if using agent registry)
|
||||
bd agents list
|
||||
|
||||
# Check agent status
|
||||
bd agents status agent-1
|
||||
```
|
||||
|
||||
## Conflict Prevention
|
||||
|
||||
### File Reservations
|
||||
|
||||
Prevent concurrent edits:
|
||||
|
||||
```bash
|
||||
# Reserve files before editing
|
||||
bd reserve auth.go --for agent-1
|
||||
|
||||
# Check reservations
|
||||
bd reservations list
|
||||
|
||||
# Release when done
|
||||
bd reserve --release auth.go
|
||||
```
|
||||
|
||||
### Issue Locking
|
||||
|
||||
```bash
|
||||
# Lock issue for exclusive work
|
||||
bd lock bd-42 --for agent-1
|
||||
|
||||
# Unlock when done
|
||||
bd unlock bd-42
|
||||
```
|
||||
|
||||
## Communication Patterns
|
||||
|
||||
### Via Comments
|
||||
|
||||
```bash
|
||||
# Agent A leaves note
|
||||
bd comment add bd-42 "Completed API, needs frontend integration"
|
||||
|
||||
# Agent B reads
|
||||
bd show bd-42 --full
|
||||
```
|
||||
|
||||
### Via Labels
|
||||
|
||||
```bash
|
||||
# Mark for review
|
||||
bd update bd-42 --add-label "needs-review"
|
||||
|
||||
# Agent B filters
|
||||
bd list --label-any needs-review
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clear ownership** - Always pin work to specific agent
|
||||
2. **Document handoffs** - Use comments to explain context
|
||||
3. **Use labels for status** - `needs-review`, `blocked`, `ready`
|
||||
4. **Avoid conflicts** - Use reservations for shared files
|
||||
5. **Monitor progress** - Regular status checks
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Federation Setup Guide
|
||||
---
|
||||
title: Federation Setup Guide
|
||||
---
|
||||
|
||||
Federation enables peer-to-peer synchronization of beads databases between
|
||||
multiple workspaces using Dolt remotes. Each workspace maintains its own database
|
||||
|
|
@ -214,7 +216,7 @@ bd doctor --deep
|
|||
|
||||
## Reference
|
||||
|
||||
- Configuration: See [CONFIG.md](CONFIG.md) for all federation settings
|
||||
- Configuration: See [CONFIG.md](/reference/configuration) for all federation settings
|
||||
- Source: `cmd/bd/federation.go`
|
||||
- Storage interfaces: `internal/storage/versioned.go`
|
||||
- Dolt implementation: `internal/storage/dolt/store.go`
|
||||
68
docs/multi-agent/index.md
Normal file
68
docs/multi-agent/index.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
---
|
||||
title: Multi-Agent
|
||||
---
|
||||
|
||||
Beads supports coordination between multiple AI agents and repositories.
|
||||
|
||||
## Overview
|
||||
|
||||
Multi-agent features enable:
|
||||
- **Routing** - Automatic issue routing to correct repositories
|
||||
- **Cross-repo dependencies** - Dependencies across repository boundaries
|
||||
- **Agent coordination** - Work assignment and handoff between agents
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Routes
|
||||
|
||||
Routes define which repository handles which issues:
|
||||
|
||||
```jsonl
|
||||
{"pattern": "frontend/*", "target": "frontend-repo"}
|
||||
{"pattern": "backend/*", "target": "backend-repo"}
|
||||
{"pattern": "*", "target": "main-repo"}
|
||||
```
|
||||
|
||||
### Work Assignment
|
||||
|
||||
Pin work to specific agents:
|
||||
|
||||
```bash
|
||||
bd pin bd-42 --for agent-1 --start
|
||||
bd hook --agent agent-1 # Show pinned work
|
||||
```
|
||||
|
||||
### Cross-repo Dependencies
|
||||
|
||||
Track dependencies across repositories:
|
||||
|
||||
```bash
|
||||
bd dep add bd-42 external:other-repo/bd-100
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ Main Repo │
|
||||
│ (coordinator) │
|
||||
└────────┬────────┘
|
||||
│ routes
|
||||
┌────┴────┐
|
||||
│ │
|
||||
┌───▼───┐ ┌───▼───┐
|
||||
│Frontend│ │Backend│
|
||||
│ Repo │ │ Repo │
|
||||
└────────┘ └────────┘
|
||||
```
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. **Single repo**: Standard beads workflow
|
||||
2. **Multi-repo**: Configure routes and cross-repo deps
|
||||
3. **Multi-agent**: Add work assignment and handoff
|
||||
|
||||
## Navigation
|
||||
|
||||
- [Routing](/multi-agent/routing) - Auto-routing configuration
|
||||
- [Coordination](/multi-agent/coordination) - Agent coordination patterns
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Multi-Repo Migration Guide
|
||||
---
|
||||
title: Multi-Repo Migration Guide
|
||||
---
|
||||
|
||||
This guide helps you adopt beads' multi-repo workflow for OSS contributions, team collaboration, and multi-phase development.
|
||||
|
||||
|
|
@ -10,7 +12,7 @@ This guide helps you adopt beads' multi-repo workflow for OSS contributions, tea
|
|||
- [Multi-Phase Development](#multi-phase-development) - Separate repos per phase
|
||||
- [Multiple Personas](#multiple-personas) - Architect vs. implementer separation
|
||||
|
||||
**New to beads?** See [QUICKSTART.md](QUICKSTART.md) first.
|
||||
**New to beads?** See [QUICKSTART.md](/getting-started/quickstart) first.
|
||||
|
||||
## What is Multi-Repo Mode?
|
||||
|
||||
|
|
@ -396,7 +398,7 @@ bd list --json
|
|||
|
||||
**Problem:** Multiple repos with conflicting changes.
|
||||
|
||||
**Solution:** Dolt handles merge conflicts natively with cell-level merge. See [TROUBLESHOOTING.md](TROUBLESHOOTING.md#merge-conflicts) for details.
|
||||
**Solution:** Dolt handles merge conflicts natively with cell-level merge. See [TROUBLESHOOTING.md](/reference/troubleshooting#merge-conflicts) for details.
|
||||
|
||||
### Discovered issues in wrong repository
|
||||
|
||||
|
|
@ -472,10 +474,10 @@ bd create "Issue" -p 1
|
|||
|
||||
## Next Steps
|
||||
|
||||
- **CLI Reference:** See [README.md](../README.md) for command details
|
||||
- **Configuration Guide:** See [CONFIG.md](CONFIG.md) for all config options
|
||||
- **Troubleshooting:** See [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||
- **Multi-Repo Internals:** See [ROUTING.md#multi-repo-hydration](ROUTING.md#multi-repo-hydration)
|
||||
- **CLI Reference:** See [README.md](https://github.com/gastownhall/beads/blob/main/README.md) for command details
|
||||
- **Configuration Guide:** See [CONFIG.md](/reference/configuration) for all config options
|
||||
- **Troubleshooting:** See [TROUBLESHOOTING.md](/reference/troubleshooting)
|
||||
- **Multi-Repo Internals:** See [ROUTING.md#multi-repo-hydration](/multi-agent/routing#multi-repo-hydration)
|
||||
|
||||
## Related Issues
|
||||
|
||||
112
docs/multi-agent/routing.md
Normal file
112
docs/multi-agent/routing.md
Normal file
|
|
@ -0,0 +1,112 @@
|
|||
---
|
||||
title: Routing
|
||||
---
|
||||
|
||||
Automatic issue routing across repositories.
|
||||
|
||||
## Overview
|
||||
|
||||
Routing enables:
|
||||
- Issues created in one repo routed to another
|
||||
- Pattern-based routing rules
|
||||
- Fallback to default repository
|
||||
|
||||
## Configuration
|
||||
|
||||
Create `.beads/routes.jsonl`:
|
||||
|
||||
```jsonl
|
||||
{"pattern": "frontend/**", "target": "frontend-repo", "priority": 10}
|
||||
{"pattern": "backend/**", "target": "backend-repo", "priority": 10}
|
||||
{"pattern": "docs/**", "target": "docs-repo", "priority": 5}
|
||||
{"pattern": "*", "target": "main-repo", "priority": 0}
|
||||
```
|
||||
|
||||
## Route Fields
|
||||
|
||||
| Field | Description |
|
||||
|-------|-------------|
|
||||
| `pattern` | Glob pattern to match |
|
||||
| `target` | Target repository |
|
||||
| `priority` | Higher = checked first |
|
||||
|
||||
## Pattern Matching
|
||||
|
||||
Patterns match against:
|
||||
- Issue title
|
||||
- Labels
|
||||
- Explicit path prefix
|
||||
|
||||
**Examples:**
|
||||
```jsonl
|
||||
{"pattern": "frontend/*", "target": "frontend"}
|
||||
{"pattern": "*api*", "target": "backend"}
|
||||
{"pattern": "label:docs", "target": "docs-repo"}
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
# Show routing table
|
||||
bd routes list
|
||||
bd routes list --json
|
||||
|
||||
# Test routing
|
||||
bd routes test "Fix frontend button"
|
||||
bd routes test --label frontend
|
||||
|
||||
# Add route
|
||||
bd routes add "frontend/**" --target frontend-repo --priority 10
|
||||
|
||||
# Remove route
|
||||
bd routes remove "frontend/**"
|
||||
```
|
||||
|
||||
## Auto-Routing
|
||||
|
||||
When creating issues, beads checks routes:
|
||||
|
||||
```bash
|
||||
bd create "Fix frontend button alignment" -t bug
|
||||
# Auto-routed to frontend-repo based on title match
|
||||
```
|
||||
|
||||
Override with explicit target:
|
||||
|
||||
```bash
|
||||
bd create "Fix button" --repo backend-repo
|
||||
```
|
||||
|
||||
## Cross-Repo Dependencies
|
||||
|
||||
Track dependencies across repos:
|
||||
|
||||
```bash
|
||||
# In frontend-repo
|
||||
bd dep add bd-42 external:backend-repo/bd-100
|
||||
|
||||
# View cross-repo deps
|
||||
bd dep tree bd-42 --cross-repo
|
||||
```
|
||||
|
||||
## Hydration
|
||||
|
||||
Pull related issues from other repos:
|
||||
|
||||
```bash
|
||||
# Hydrate issues from related repos
|
||||
bd hydrate
|
||||
|
||||
# Preview hydration
|
||||
bd hydrate --dry-run
|
||||
|
||||
# Hydrate specific repo
|
||||
bd hydrate --from backend-repo
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use specific patterns** - Avoid overly broad matches
|
||||
2. **Set priorities** - Ensure specific patterns match first
|
||||
3. **Default fallback** - Always have a `*` pattern with lowest priority
|
||||
4. **Test routes** - Use `bd routes test` before committing
|
||||
59
docs/recovery/circular-dependencies.md
Normal file
59
docs/recovery/circular-dependencies.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
title: Circular Dependencies
|
||||
description: Detect and break dependency cycles
|
||||
---
|
||||
|
||||
This runbook helps you detect and break circular dependency cycles in your issues.
|
||||
|
||||
## Symptoms
|
||||
|
||||
- "circular dependency detected" errors
|
||||
- `bd blocked` shows unexpected results
|
||||
- Issues that should be ready appear blocked
|
||||
|
||||
## Diagnosis
|
||||
|
||||
```bash
|
||||
# Check for blocked issues
|
||||
bd blocked
|
||||
|
||||
# View dependencies for a specific issue
|
||||
bd show <issue-id>
|
||||
|
||||
# List all dependencies
|
||||
bd dep tree
|
||||
```
|
||||
|
||||
## Solution
|
||||
|
||||
**Step 1:** Identify the cycle
|
||||
```bash
|
||||
bd blocked --verbose
|
||||
```
|
||||
|
||||
**Step 2:** Map the dependency chain
|
||||
```bash
|
||||
bd show <issue-a>
|
||||
bd show <issue-b>
|
||||
# Follow the chain until you return to <issue-a>
|
||||
```
|
||||
|
||||
**Step 3:** Determine which dependency to remove
|
||||
Consider: Which dependency is least critical to the workflow?
|
||||
|
||||
**Step 4:** Remove the problematic dependency
|
||||
```bash
|
||||
bd dep remove <dependent-issue> <blocking-issue>
|
||||
```
|
||||
|
||||
**Step 5:** Verify the cycle is broken
|
||||
```bash
|
||||
bd blocked
|
||||
bd ready
|
||||
```
|
||||
|
||||
## Prevention
|
||||
|
||||
- Think "X needs Y" not "X before Y" when adding dependencies
|
||||
- Use `bd blocked` after adding dependencies to check for cycles
|
||||
- Keep dependency chains shallow when possible
|
||||
62
docs/recovery/database-corruption.md
Normal file
62
docs/recovery/database-corruption.md
Normal file
|
|
@ -0,0 +1,62 @@
|
|||
---
|
||||
title: Database Corruption
|
||||
description: Recover from Dolt database corruption
|
||||
---
|
||||
|
||||
This runbook helps you recover from database corruption in Beads.
|
||||
|
||||
## Symptoms
|
||||
|
||||
- Error messages during `bd` commands
|
||||
- "database is locked" errors that persist
|
||||
- Missing issues that should exist
|
||||
- Inconsistent database state
|
||||
|
||||
## Diagnosis
|
||||
|
||||
```bash
|
||||
# Check database integrity
|
||||
bd doctor
|
||||
|
||||
# Check Dolt server health
|
||||
bd dolt show
|
||||
```
|
||||
|
||||
## Solution
|
||||
|
||||
**Step 1:** Stop the Dolt server
|
||||
```bash
|
||||
bd dolt stop
|
||||
```
|
||||
|
||||
**Step 2:** Back up current state
|
||||
```bash
|
||||
cp -r .beads .beads.backup
|
||||
```
|
||||
|
||||
**Step 3:** Preview what doctor would fix
|
||||
```bash
|
||||
bd doctor --dry-run
|
||||
```
|
||||
|
||||
**Step 4:** Rebuild database
|
||||
```bash
|
||||
bd doctor --fix
|
||||
```
|
||||
|
||||
**Step 5:** Verify recovery
|
||||
```bash
|
||||
bd doctor
|
||||
bd list
|
||||
```
|
||||
|
||||
**Step 6:** Restart the Dolt server
|
||||
```bash
|
||||
dolt sql-server
|
||||
```
|
||||
|
||||
## Prevention
|
||||
|
||||
- Let the Dolt server handle synchronization
|
||||
- Use `bd dolt stop` before system shutdown
|
||||
- Run `bd doctor` periodically to catch issues early
|
||||
42
docs/recovery/index.md
Normal file
42
docs/recovery/index.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
---
|
||||
title: Recovery Overview
|
||||
description: Diagnose and resolve common Beads issues
|
||||
---
|
||||
|
||||
This section provides step-by-step recovery procedures for common Beads issues. Each runbook follows a consistent format: Symptoms, Diagnosis, Solution (5 steps max), and Prevention.
|
||||
|
||||
## Common Issues
|
||||
|
||||
| Issue | Symptoms | Runbook |
|
||||
|-------|----------|---------|
|
||||
| Database Corruption | SQLite errors, missing data | [Database Corruption](/recovery/database-corruption) |
|
||||
| Merge Conflicts | Dolt conflicts during sync | [Merge Conflicts](/recovery/merge-conflicts) |
|
||||
| Circular Dependencies | Cycle detection errors | [Circular Dependencies](/recovery/circular-dependencies) |
|
||||
| Sync Failures | `bd dolt push`/`bd dolt pull` errors | [Sync Failures](/recovery/sync-failures) |
|
||||
|
||||
## Quick Diagnostic
|
||||
|
||||
Before diving into specific runbooks, try these quick checks:
|
||||
|
||||
```bash
|
||||
# Check Beads status
|
||||
bd status
|
||||
|
||||
# Verify Dolt server is running
|
||||
bd doctor
|
||||
|
||||
# Check for blocked issues
|
||||
bd blocked
|
||||
```
|
||||
|
||||
<Tip>
|
||||
Most issues can be diagnosed with `bd status`. Start there before following specific runbooks.
|
||||
</Tip>
|
||||
|
||||
## Getting Help
|
||||
|
||||
If these runbooks don't resolve your issue:
|
||||
|
||||
1. Check the [FAQ](/reference/faq)
|
||||
2. Search [existing issues](https://github.com/gastownhall/beads/issues)
|
||||
3. Open a new issue with diagnostic output
|
||||
253
docs/recovery/init-safety.md
Normal file
253
docs/recovery/init-safety.md
Normal file
|
|
@ -0,0 +1,253 @@
|
|||
---
|
||||
title: Recovery Playbooks
|
||||
---
|
||||
|
||||
Last reviewed: 2026-06-09
|
||||
|
||||
Freshness source: `cmd/bd/init.go`, `cmd/bd/init_safety.go`,
|
||||
`cmd/bd/init_safety_test.go`, and `cmd/bd/dolt.go`.
|
||||
|
||||
This document lives next to the ADRs and matches the structure of `bd`'s
|
||||
error messages: each named refusal in `bd init` and `bd dolt push`/`pull`
|
||||
points here to a labeled anchor with step-by-step recovery instructions.
|
||||
|
||||
See also: `bd help init-safety`, and
|
||||
[ADR 0002 — `bd init` safety invariants](https://github.com/gastownhall/beads/blob/main/engdocs/adr/0002-init-safety-invariants.md).
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [init-force-refused — `bd init --force`/`--reinit-local` refused because origin has Dolt history](#init-force-refused)
|
||||
- [init-token-missing — `--discard-remote` refused because `--destroy-token` is missing or wrong](#init-token-missing)
|
||||
- [init-local-exists — `bd init` refused because local data already exists](#init-local-exists)
|
||||
- [pk-fork-refused — `bd dolt pull`/`push` refused because a table has different primary keys in its common ancestor](#pk-fork-refused)
|
||||
|
||||
---
|
||||
|
||||
## init-force-refused
|
||||
|
||||
**Exit code:** `10` (`ExitRemoteDivergenceRefused`)
|
||||
|
||||
**Symptom**
|
||||
|
||||
```
|
||||
bd init refuses: remote 'origin' already has Dolt history (refs/dolt/data).
|
||||
Why: this init mode would create or reuse local history instead of
|
||||
adopting the remote. ...
|
||||
```
|
||||
|
||||
**Why this happens**
|
||||
|
||||
`bd init --force` (or `--reinit-local`) tells `bd` to bypass the local
|
||||
data-safety guard. `bd init --from-jsonl` selects a local JSONL export as
|
||||
the source. But the remote already has project history. Proceeding would
|
||||
create an orphan local Dolt branch with no common ancestor on origin. The
|
||||
next `bd dolt push` would either fail (no common ancestor) or — worse, if
|
||||
force-pushed — destroy the team's data.
|
||||
|
||||
**Recovery paths**
|
||||
|
||||
Pick the one that matches your intent.
|
||||
|
||||
### 1. You want to adopt the remote's history (most common)
|
||||
|
||||
```
|
||||
bd bootstrap
|
||||
```
|
||||
|
||||
This clones the remote's Dolt database into a fresh local `.beads/`.
|
||||
Your local state is ignored; the team's history becomes yours.
|
||||
|
||||
### 2. You want to diagnose what went wrong before deciding
|
||||
|
||||
```
|
||||
bd doctor
|
||||
bd dolt status
|
||||
```
|
||||
|
||||
`bd doctor` walks the local + remote state and names concrete problems.
|
||||
`bd dolt status` shows the Dolt-level view. Neither modifies anything.
|
||||
|
||||
### 3. You intentionally want to overwrite the remote's history (destructive)
|
||||
|
||||
This is a cross-boundary operation that affects every collaborator. You
|
||||
need to pair the local-source init (`--reinit-local` or `--from-jsonl`)
|
||||
with `--discard-remote`. In interactive mode `bd` will prompt for
|
||||
confirmation; in non-interactive mode you must supply a `--destroy-token`.
|
||||
See `bd help init-safety` for the token format.
|
||||
|
||||
After `bd init --reinit-local --discard-remote`, your next
|
||||
`bd dolt push` must be a history-replacing push. Coordinate with your
|
||||
team before doing this.
|
||||
|
||||
---
|
||||
|
||||
## init-token-missing
|
||||
|
||||
**Exit code:** `12` (`ExitDestroyTokenMissing`)
|
||||
|
||||
**Symptom**
|
||||
|
||||
```
|
||||
bd init refuses: --discard-remote requires an explicit destroy-token in non-interactive mode.
|
||||
```
|
||||
|
||||
**Why this happens**
|
||||
|
||||
You're running non-interactively (CI, agent, piped input) and passed
|
||||
`--discard-remote`. Destructive cross-boundary operations cannot be
|
||||
authorized silently.
|
||||
|
||||
**Recovery paths**
|
||||
|
||||
### 1. Run interactively
|
||||
|
||||
Re-run in a TTY. `bd init --reinit-local --discard-remote` will prompt
|
||||
you to type the destroy-token at confirmation time.
|
||||
|
||||
### 2. Supply the token explicitly (CI/automation)
|
||||
|
||||
The token format is `DESTROY-<issue-prefix>`. For a project whose issue
|
||||
prefix is `bd`:
|
||||
|
||||
```
|
||||
bd init --reinit-local --discard-remote --destroy-token=DESTROY-bd
|
||||
```
|
||||
|
||||
Automation should template the token from project state, not from error
|
||||
output. See [ADR 0002 — Invariant 4](https://github.com/gastownhall/beads/blob/main/engdocs/adr/0002-init-safety-invariants.md)
|
||||
for why the token is never echoed in `bd`'s error messages.
|
||||
|
||||
---
|
||||
|
||||
## init-local-exists
|
||||
|
||||
**Exit code:** `11` (`ExitLocalExistsRefused`)
|
||||
|
||||
**Symptom**
|
||||
|
||||
```
|
||||
Refusing to destroy N issues in non-interactive mode.
|
||||
See 'bd help init-safety' for the required --destroy-token format.
|
||||
```
|
||||
|
||||
Or, in interactive mode, you declined the typed `destroy N issues`
|
||||
confirmation.
|
||||
|
||||
**Why this happens**
|
||||
|
||||
Local `.beads/` has existing issues. `bd init --reinit-local` would
|
||||
permanently destroy them.
|
||||
|
||||
**Recovery paths**
|
||||
|
||||
### 1. Export first, then proceed
|
||||
|
||||
```
|
||||
bd export > issue-export.jsonl
|
||||
bd init --reinit-local
|
||||
```
|
||||
|
||||
`issue-export.jsonl` lets you re-import individual issues if needed. It is not
|
||||
a full database backup; use `bd backup` when the Dolt database is healthy
|
||||
enough to create a restorable backup before reinitializing.
|
||||
|
||||
### 2. Investigate why you hit this
|
||||
|
||||
If you did NOT expect `bd init` to be the right command here, run
|
||||
`bd doctor` first — you may be looking at a server config issue that a
|
||||
re-init won't fix.
|
||||
|
||||
---
|
||||
|
||||
## pk-fork-refused
|
||||
|
||||
**Symptom**
|
||||
|
||||
```
|
||||
$ bd dolt pull
|
||||
Error: ... cannot merge because table dependencies has different primary keys in its common ancestor
|
||||
```
|
||||
|
||||
(or the variant without `in its common ancestor`). `bd` follows the error
|
||||
with a short version of the recovery recipe below.
|
||||
|
||||
**Why this happens**
|
||||
|
||||
The two histories being merged disagree about a table's *primary key set* —
|
||||
not about row contents. Dolt can cell-merge rows, but it refuses outright to
|
||||
merge a table whose primary key was reshaped differently on each side (or
|
||||
whose common ancestor had a different primary key than both sides). The
|
||||
refusal happens before any row conflicts materialize, so `bd dolt pull`'s
|
||||
conflict auto-resolver never gets a chance to run. **Retrying never helps**:
|
||||
the histories are permanently un-mergeable.
|
||||
|
||||
The usual cause is upgrading `bd` independently on two clones while un-synced
|
||||
changes existed on both sides, across a release whose schema migrations
|
||||
reshape a primary key. Concretely: the
|
||||
[#4259](https://github.com/gastownhall/beads/issues/4259) incident — clones
|
||||
straddling the `0041`/`0043`/`0050` reshapes of `dependencies` (v1.0.4 →
|
||||
v1.0.6) hit exactly this on the first post-upgrade pull if both sides had
|
||||
unpushed dependency edits.
|
||||
|
||||
The remote-migrate prevention gate (v1.0.6+) exists to stop this from being
|
||||
created: it refuses to auto-migrate a remote-backed database and tells you to
|
||||
designate a single migrator. This playbook is for when the fork already
|
||||
exists.
|
||||
|
||||
**Recovery: bootstrap from one canonical clone**
|
||||
|
||||
The forked histories cannot be merged, so one side must be chosen as
|
||||
canonical and every other clone re-cloned from it. Issue *data* survives via
|
||||
JSONL export/import; only the un-mergeable Dolt *history* is discarded on the
|
||||
non-canonical clones.
|
||||
|
||||
### 1. Pick the canonical clone
|
||||
|
||||
Usually the most complete / most recently active clone. To compare, run on
|
||||
each clone (read-only):
|
||||
|
||||
```
|
||||
bd stats
|
||||
bd dolt status
|
||||
```
|
||||
|
||||
### 2. On the canonical clone: upgrade, migrate, force-push
|
||||
|
||||
```
|
||||
bd version # confirm the new bd binary
|
||||
bd doctor # sanity-check before publishing
|
||||
bd dolt push --force # make the remote authoritative
|
||||
```
|
||||
|
||||
(`bd`'s migration gate may block here; run `bd migrate --force` on the
|
||||
canonical clone — that is exactly the designated-migrator case the gate is
|
||||
asking about. `BD_ALLOW_REMOTE_MIGRATE=1` is the env-var equivalent for
|
||||
scripted use.)
|
||||
|
||||
### 3. On EVERY other clone: save local-only work, re-clone, re-apply
|
||||
|
||||
```
|
||||
bd export --all -o /tmp/beads-local.jsonl # safety net for un-synced work
|
||||
rm -rf .beads/dolt # discard the un-mergeable history
|
||||
bd bootstrap # re-clone from the remote
|
||||
bd import /tmp/beads-local.jsonl # re-apply local-only work
|
||||
```
|
||||
|
||||
`bd import` has upsert semantics: issues that only existed on this clone are
|
||||
re-created, newer local edits are applied, and rows older than what the
|
||||
remote already has are skipped. Spot-check with `bd stats` afterwards.
|
||||
|
||||
### Prevention (upgrades across PK-reshaping migrations)
|
||||
|
||||
- **Sync before upgrading**: `bd dolt push` + `bd dolt pull` on every clone
|
||||
while all clones still run the *old* version, then stop editing. Once the new
|
||||
binary is installed, `bd dolt push`/`bd dolt pull` are gated too, so this must
|
||||
happen first.
|
||||
- **One designated migrator**: upgrade one machine, let it migrate, then
|
||||
`bd dolt push`.
|
||||
- **Every other clone adopts, does not pull**: after the migrator pushes, each
|
||||
other clone upgrades the binary and runs `bd bootstrap` to adopt the migrated
|
||||
database. `bd dolt pull` is *refused* while the clone still has pending
|
||||
migrations, so do not rely on it; the "sync before" step above is what
|
||||
preserves these clones' work, because `bd bootstrap` replaces the local
|
||||
database.
|
||||
54
docs/recovery/merge-conflicts.md
Normal file
54
docs/recovery/merge-conflicts.md
Normal file
|
|
@ -0,0 +1,54 @@
|
|||
---
|
||||
title: Merge Conflicts
|
||||
description: Resolve Dolt merge conflicts
|
||||
---
|
||||
|
||||
This runbook helps you resolve merge conflicts that occur during Dolt sync operations.
|
||||
|
||||
## Symptoms
|
||||
|
||||
- `bd dolt pull` fails with conflict errors
|
||||
- Different issue states between clones
|
||||
|
||||
## Diagnosis
|
||||
|
||||
```bash
|
||||
# Check database health
|
||||
bd doctor
|
||||
|
||||
# Preview what fixes would be applied
|
||||
bd doctor --dry-run
|
||||
```
|
||||
|
||||
## Solution
|
||||
|
||||
**Step 1:** Back up current state
|
||||
```bash
|
||||
cp -r .beads .beads.backup
|
||||
```
|
||||
|
||||
**Step 2:** Check for conflicts
|
||||
```bash
|
||||
bd doctor
|
||||
```
|
||||
|
||||
**Step 3:** Fix to reconcile
|
||||
```bash
|
||||
bd doctor --fix
|
||||
```
|
||||
|
||||
**Step 4:** Verify state
|
||||
```bash
|
||||
bd list
|
||||
bd stats
|
||||
```
|
||||
|
||||
**Step 5:** Push resolved state
|
||||
```bash
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
## Prevention
|
||||
|
||||
- Sync before and after work sessions using `bd dolt pull` / `bd dolt push`
|
||||
- Avoid concurrent modifications from multiple clones without the Dolt server running
|
||||
75
docs/recovery/sync-failures.md
Normal file
75
docs/recovery/sync-failures.md
Normal file
|
|
@ -0,0 +1,75 @@
|
|||
---
|
||||
title: Sync Failures
|
||||
description: Recover from Dolt sync failures
|
||||
---
|
||||
|
||||
This runbook helps you recover from Dolt sync failures.
|
||||
|
||||
## Symptoms
|
||||
|
||||
- `bd dolt push` or `bd dolt pull` hangs or times out
|
||||
- Network-related error messages
|
||||
- "failed to push" or "failed to pull" errors
|
||||
- Dolt server not responding
|
||||
|
||||
## Diagnosis
|
||||
|
||||
```bash
|
||||
# Check Dolt server health
|
||||
bd doctor
|
||||
bd dolt show
|
||||
|
||||
# View Dolt server logs
|
||||
tail -50 .beads/dolt/sql-server.log
|
||||
```
|
||||
|
||||
## Solution
|
||||
|
||||
**Step 1:** Stop the Dolt server
|
||||
```bash
|
||||
bd dolt stop
|
||||
```
|
||||
|
||||
**Step 2:** Check for lock files
|
||||
```bash
|
||||
ls -la .beads/*.lock
|
||||
# Remove stale locks if Dolt server is definitely stopped
|
||||
rm -f .beads/*.lock
|
||||
```
|
||||
|
||||
**Step 3:** Back up and preview fixes
|
||||
```bash
|
||||
cp -r .beads .beads.backup
|
||||
bd doctor --dry-run
|
||||
```
|
||||
|
||||
**Step 4:** Apply fixes if needed
|
||||
```bash
|
||||
bd doctor --fix
|
||||
```
|
||||
|
||||
**Step 5:** Restart the Dolt server
|
||||
```bash
|
||||
dolt sql-server
|
||||
```
|
||||
|
||||
**Step 6:** Verify sync works
|
||||
```bash
|
||||
bd dolt push
|
||||
bd doctor
|
||||
```
|
||||
|
||||
## Common Causes
|
||||
|
||||
| Cause | Solution |
|
||||
|-------|----------|
|
||||
| Network timeout | Retry with better connection |
|
||||
| Stale lock file | Remove lock after stopping Dolt server |
|
||||
| Corrupted state | Back up, then `bd doctor --fix` |
|
||||
| Merge conflicts | See [Merge Conflicts](/recovery/merge-conflicts) |
|
||||
|
||||
## Prevention
|
||||
|
||||
- Ensure stable network before sync
|
||||
- Let sync complete before closing terminal
|
||||
- Use `bd dolt stop` before system shutdown
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Uninstalling Beads
|
||||
---
|
||||
title: Uninstalling
|
||||
---
|
||||
|
||||
This guide explains how to remove beads from a repository or remove the `bd`
|
||||
binary from a machine.
|
||||
193
docs/reference/advanced.md
Normal file
193
docs/reference/advanced.md
Normal file
|
|
@ -0,0 +1,193 @@
|
|||
---
|
||||
title: Advanced Features
|
||||
---
|
||||
|
||||
Advanced beads functionality.
|
||||
|
||||
## Issue Rename
|
||||
|
||||
Rename issues while preserving references:
|
||||
|
||||
```bash
|
||||
bd rename bd-42 bd-new-id
|
||||
bd rename bd-42 bd-new-id --dry-run # Preview
|
||||
```
|
||||
|
||||
Updates:
|
||||
- All dependencies pointing to old ID
|
||||
- All references in other issues
|
||||
- Comments and descriptions
|
||||
|
||||
## Issue Merge
|
||||
|
||||
Merge duplicate issues:
|
||||
|
||||
```bash
|
||||
bd merge bd-42 bd-43 --into bd-41
|
||||
bd merge bd-42 bd-43 --into bd-41 --dry-run
|
||||
```
|
||||
|
||||
What gets merged:
|
||||
- Dependencies → target
|
||||
- Text references updated across all issues
|
||||
- Source issues closed with merge reason
|
||||
|
||||
## Database Compaction
|
||||
|
||||
Reduce database size by compacting old issues:
|
||||
|
||||
```bash
|
||||
# View compaction statistics
|
||||
bd admin compact --stats
|
||||
|
||||
# Preview candidates (30+ days closed)
|
||||
bd admin compact --analyze --json
|
||||
|
||||
# Apply agent-generated summary
|
||||
bd admin compact --apply --id bd-42 --summary summary.txt
|
||||
|
||||
# Immediate deletion (CAUTION!)
|
||||
bd admin cleanup --force
|
||||
```
|
||||
|
||||
**When to compact:**
|
||||
- Database > 10MB with old closed issues
|
||||
- After major milestones
|
||||
- Before archiving project phase
|
||||
|
||||
## Restore from History
|
||||
|
||||
View deleted or compacted issues from git:
|
||||
|
||||
```bash
|
||||
bd restore bd-42 --show
|
||||
bd restore bd-42 --to-file issue.json
|
||||
```
|
||||
|
||||
## Database Inspection
|
||||
|
||||
`bd sql` requires Dolt server mode (`bd dolt start`, see Performance Tuning
|
||||
below); it is not available against the default embedded-mode database.
|
||||
|
||||
```bash
|
||||
# Schema info
|
||||
bd info --schema --json
|
||||
|
||||
# Raw database query (server mode only)
|
||||
bd sql "SELECT * FROM issues LIMIT 5"
|
||||
```
|
||||
|
||||
## Extension Data
|
||||
|
||||
For Dolt-backed projects, keep extension state outside the beads database and
|
||||
connect it to beads through stable CLI surfaces:
|
||||
|
||||
```bash
|
||||
# Query issues for integration workflows
|
||||
bd list --json
|
||||
bd query "status=open AND priority<=2" --json
|
||||
|
||||
# Run direct SQL for inspection (server mode only)
|
||||
bd sql "SELECT id, title, status FROM issues LIMIT 5"
|
||||
```
|
||||
|
||||
Custom tables through direct storage access are a legacy SQLite-only pattern.
|
||||
See the [bd-example-extension-go example](https://github.com/gastownhall/beads/blob/main/examples/bd-example-extension-go/README.md)
|
||||
only if you are maintaining a SQLite-backed extension.
|
||||
|
||||
## Audit Data
|
||||
|
||||
Beads records issue lifecycle events in the database for audit and recovery
|
||||
workflows. There is no standalone `bd events` command; inspect current issue
|
||||
state through JSON output, or query the audit tables directly when needed:
|
||||
|
||||
```bash
|
||||
# Current issue state
|
||||
bd show bd-a1b2 --json
|
||||
|
||||
# Recent stored events for one issue (server mode only)
|
||||
bd sql "SELECT event_type, actor, created_at FROM events WHERE issue_id = 'bd-a1b2' ORDER BY created_at DESC LIMIT 20"
|
||||
```
|
||||
|
||||
Events:
|
||||
- `issue.created`
|
||||
- `issue.updated`
|
||||
- `issue.closed`
|
||||
- `dependency.added`
|
||||
- `sync.completed`
|
||||
|
||||
## Batch Operations
|
||||
|
||||
### Create Multiple
|
||||
|
||||
```bash
|
||||
# Bootstrap a new database from JSONL
|
||||
bd init --from-jsonl issues.jsonl
|
||||
```
|
||||
|
||||
### Update Multiple
|
||||
|
||||
```bash
|
||||
bd list --status open --priority 4 --json | \
|
||||
jq -r '.[].id' | \
|
||||
xargs -I {} bd update {} --priority 3
|
||||
```
|
||||
|
||||
### Close Multiple
|
||||
|
||||
```bash
|
||||
bd list --label "sprint-1" --status open --json | \
|
||||
jq -r '.[].id' | \
|
||||
xargs -I {} bd close {} --reason "Sprint complete"
|
||||
```
|
||||
|
||||
## Integration Access
|
||||
|
||||
Use the CLI as the supported integration boundary:
|
||||
|
||||
```bash
|
||||
# Machine-readable issue data
|
||||
bd show bd-a1b2 --json
|
||||
|
||||
# Ready-work queue for automation
|
||||
bd ready --json
|
||||
|
||||
# Direct SQL inspection against the active Dolt database (server mode only)
|
||||
bd sql "SELECT id, priority, status FROM issues WHERE status != 'closed'"
|
||||
```
|
||||
|
||||
The storage packages under `internal/` are not a public Go API.
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Large Databases
|
||||
|
||||
```bash
|
||||
# Enable WAL mode
|
||||
bd config set database.wal_mode true
|
||||
|
||||
# Increase cache
|
||||
bd config set database.cache_size 10000
|
||||
```
|
||||
|
||||
### Many Concurrent Agents
|
||||
|
||||
Beads uses Dolt server mode to handle concurrent access from multiple agents.
|
||||
The server manages transaction isolation automatically.
|
||||
|
||||
```bash
|
||||
# Start the Dolt server
|
||||
bd dolt start
|
||||
|
||||
# Check server health
|
||||
bd doctor
|
||||
```
|
||||
|
||||
### CI/CD Optimization
|
||||
|
||||
In CI/CD environments, beads uses embedded mode by default (no server required):
|
||||
|
||||
```bash
|
||||
# Just run commands directly — no special flags needed
|
||||
bd list
|
||||
```
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Antivirus False Positives
|
||||
---
|
||||
title: Antivirus False Positives
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
275
docs/reference/configuration.md
Normal file
275
docs/reference/configuration.md
Normal file
|
|
@ -0,0 +1,275 @@
|
|||
---
|
||||
title: Configuration
|
||||
---
|
||||
|
||||
Complete configuration reference for beads.
|
||||
|
||||
beads has two complementary configuration systems:
|
||||
|
||||
1. **Tool-level configuration** (YAML, managed by [Viper](https://github.com/spf13/viper)) — startup flags and tool behavior, stored in `config.yaml` files.
|
||||
2. **Project-level configuration** (managed by `bd config`) — integration credentials, status maps, and project-specific settings, stored in the Dolt database. Some keys are routed to `config.yaml` instead (see [YAML-only keys](#yaml-only-keys-startup-settings) below).
|
||||
|
||||
For a deeper treatment of every namespace and its semantics, see [docs/CONFIG.md](https://github.com/gastownhall/beads/blob/main/docs/CONFIG.md).
|
||||
|
||||
## Configuration Locations
|
||||
|
||||
`config.yaml` is searched in this order, with later files overriding earlier ones:
|
||||
|
||||
1. `~/.beads/config.yaml` (legacy user-level, lowest priority)
|
||||
2. `~/.config/bd/config.yaml` (XDG user-level)
|
||||
3. `<repo>/.beads/config.yaml` (project-level, walked up from the current directory)
|
||||
4. `$BEADS_DIR/config.yaml` (highest priority, when `BEADS_DIR` is set)
|
||||
|
||||
A `config.local.yaml` next to the project `config.yaml` is also merged in last for machine-specific overrides that should not be committed.
|
||||
|
||||
## Precedence
|
||||
|
||||
For Viper-managed (YAML) keys, highest to lowest:
|
||||
|
||||
1. **Command-line flags** (e.g. `--json`, `--db`, `--actor`)
|
||||
2. **Environment variables** (`BD_*`, plus a small set of legacy `BEADS_*` names — see below)
|
||||
3. **`config.yaml`** files (in the order listed above)
|
||||
4. **Built-in defaults**
|
||||
|
||||
Project-level keys written via `bd config set` (Jira, Linear, GitHub, status maps, etc.) live in the Dolt database. They are read at command time and have no env var override.
|
||||
|
||||
## Managing Configuration
|
||||
|
||||
```bash
|
||||
# Set a value (auto-routes to config.yaml or the database)
|
||||
bd config set jira.url "https://company.atlassian.net"
|
||||
bd config set validation.on-create warn # YAML-only key
|
||||
|
||||
# Set many values in one go
|
||||
bd config set-many jira.url=https://example.atlassian.net jira.project=PROJ
|
||||
|
||||
# Get a value
|
||||
bd config get jira.url
|
||||
|
||||
# List all database-stored config (with override warnings)
|
||||
bd config list
|
||||
|
||||
# Show all effective config with provenance (env / config.yaml / default / database)
|
||||
bd config show
|
||||
bd config show --source config.yaml
|
||||
bd config show --json
|
||||
|
||||
# Validate sync-related configuration
|
||||
bd config validate
|
||||
|
||||
# Remove a value
|
||||
bd config unset jira.url
|
||||
```
|
||||
|
||||
`bd config set` automatically routes the write to the right location: keys in the YAML namespace (see below) are written to the project `config.yaml`; everything else is written to the Dolt database. `beads.role` is stored in git config.
|
||||
|
||||
## YAML-only Keys (Startup Settings)
|
||||
|
||||
These keys must live in `config.yaml`, not the database, because they are read before the database is opened. Writing them with `bd config set` automatically updates `config.yaml`.
|
||||
|
||||
The full namespaces routed to YAML are:
|
||||
|
||||
`routing.*`, `sync.*`, `git.*`, `directory.*`, `repos.*`, `external_projects.*`, `validation.*`, `hierarchy.*`, `ai.*`, `backup.*`, `export.*`, `dolt.*`, `federation.*`
|
||||
|
||||
Plus these individual keys:
|
||||
|
||||
`no-db`, `json`, `db`, `actor`, `identity`, `no-push`, `no-git-ops`, `create.require-description`, `github.token`, `linear.api_key`, `linear.oauth_client_id`, `linear.oauth_client_secret`.
|
||||
|
||||
Secrets in this list are refused on git-tracked `config.yaml` files unless you pass `--force-git-tracked`; export the value as an environment variable instead (e.g. `LINEAR_API_KEY`).
|
||||
|
||||
## Tool-Level Settings (config.yaml)
|
||||
|
||||
| Setting | Flag | Env Var | Default | Description |
|
||||
|---|---|---|---|---|
|
||||
| `json` | `--json` | `BD_JSON` | `false` | JSON output for scripting |
|
||||
| `db` | `--db` | `BD_DB` | (auto-discover) | Database path |
|
||||
| `actor` | `--actor` | `BEADS_ACTOR` | `git config user.name` | Actor name for audit trail |
|
||||
| `identity` | `--identity` | `BEADS_IDENTITY` | (git user / hostname) | Sender identity for `bd mail` |
|
||||
| `no-db` | `--no-db` | `BD_NO_DAEMON` (related) | `false` | Run without opening the database |
|
||||
| `no-push` | `--no-push` | — | `false` | Skip pushing to Dolt remote |
|
||||
| `no-git-ops` | — | — | `false` | Disable git ops in `bd prime` close protocol |
|
||||
| `dolt.auto-commit` | `--dolt-auto-commit` | `BD_DOLT_AUTO_COMMIT` | `on` | Create a Dolt history commit after each successful write |
|
||||
| `dolt.auto-push` | — | `BD_DOLT_AUTO_PUSH` | `false` | Auto-push to Dolt remote after writes (opt-in) |
|
||||
| `dolt.shared-server` | `--shared-server` | `BEADS_DOLT_SHARED_SERVER` | `false` | Share one Dolt server at `~/.beads/shared-server/` |
|
||||
| `dolt.max-conns` | — | `BEADS_DOLT_MAX_CONNS` | `10` | Connection pool size |
|
||||
| `git.author` | — | — | (none) | Override commit author for beads commits |
|
||||
| `git.no-gpg-sign` | — | — | `false` | Disable GPG signing for beads commits |
|
||||
| `create.require-description` | — | `BD_CREATE_REQUIRE_DESCRIPTION` | `false` | Require description on `bd create` |
|
||||
| `validation.on-create` | — | `BD_VALIDATION_ON_CREATE` | `none` | Template validation: `none`, `warn`, `error` |
|
||||
| `validation.on-close` | — | `BD_VALIDATION_ON_CLOSE` | `none` | Template validation on close |
|
||||
| `validation.on-sync` | — | `BD_VALIDATION_ON_SYNC` | `none` | Template validation before sync |
|
||||
| `validation.metadata.mode` | — | — | `none` | Metadata schema validation |
|
||||
| `hierarchy.max-depth` | — | — | `3` | Max hierarchical ID nesting depth |
|
||||
| `backup.enabled` | — | `BD_BACKUP_ENABLED` | `false` | Enable periodic Dolt-native backup |
|
||||
| `backup.interval` | — | `BD_BACKUP_INTERVAL` | `15m` | Minimum time between auto-backups |
|
||||
| `backup.git-push` | — | — | `false` | Auto-push backup repo |
|
||||
| `backup.git-repo` | — | `BD_BACKUP_GIT_REPO` | (none) | Backup git repo URL |
|
||||
| `export.auto` | — | — | `false` | Refresh `.beads/issues.jsonl` export after every write; not cross-machine sync |
|
||||
| `export.path` | — | — | `issues.jsonl` | Output filename relative to `.beads/` |
|
||||
| `import.path` | — | — | `issues.jsonl` | Input filename relative to `.beads/` for implied JSONL imports; use relative paths for portability |
|
||||
| `export.interval` | — | — | `60s` | Minimum time between auto-exports |
|
||||
| `export.git-add` | — | — | `false` | Run `git add` on the export file |
|
||||
| `routing.mode` | — | — | (none) | Multi-repo routing: `auto`, `maintainer`, `contributor`, `explicit` |
|
||||
| `routing.default` | — | — | `.` | Default routing target |
|
||||
| `routing.maintainer` | — | — | `.` | Maintainer-routed path |
|
||||
| `routing.contributor` | — | — | `~/.beads-planning` | Contributor-routed path |
|
||||
| `list.limit` | `--limit` / `-n` | `BD_LIST_LIMIT` | `50` | Default limit for `bd list` results |
|
||||
| `directory.labels` | — | — | `{}` | Map directory patterns → labels for monorepos |
|
||||
| `external_projects` | — | — | `{}` | Map project names → paths for cross-project deps |
|
||||
| `federation.remote` | — | `BD_FEDERATION_REMOTE` | (none) | Dolt remote URL (`dolthub://`, `gs://`, `s3://`, `az://`, `file://`) |
|
||||
| `federation.sovereignty` | — | `BD_FEDERATION_SOVEREIGNTY` | (none) | Sovereignty tier: `T1`, `T2`, `T3`, `T4` |
|
||||
| `federation.allowed-remote-patterns` | — | — | `[]` | Glob patterns restricting allowed remote URLs |
|
||||
| `federation.exclude_types` | — | — | `[wisp]` | Issue types excluded from federation push |
|
||||
| `sync.require_confirmation_on_mass_delete` | — | — | `false` | Prompt before pushing >50% issue deletions |
|
||||
| `output.title-length` | — | — | `255` | Title display in feedback (`0` hides); see routing note below |
|
||||
| `ai.model` | — | `BD_AI_MODEL` | `claude-haiku-4-5-20251001` | Default AI model |
|
||||
| `agents.file` | — | — | `AGENTS.md` | Agents instruction filename; see routing note below |
|
||||
|
||||
<Warning>
|
||||
**JSONL export is opt-in**
|
||||
|
||||
`export.auto` and `export.git-add` are disabled unless configured explicitly.
|
||||
`.beads/issues.jsonl` is an optional export for viewers, interchange, and
|
||||
issue-level migration. It is not the canonical source of truth, not
|
||||
cross-machine sync, and not a full database backup.
|
||||
|
||||
Workflows that depend on a fresh, git-staged JSONL file should opt in:
|
||||
|
||||
```bash
|
||||
bd config set export.auto true
|
||||
bd config set export.git-add true
|
||||
```
|
||||
|
||||
Use `bd dolt push` / `bd dolt pull` for sync and `bd backup` for restorable
|
||||
database backups.
|
||||
</Warning>
|
||||
|
||||
Routing note: `output.title-length` and `agents.file` are functionally tool-level settings, but `bd config set` writes them to the Dolt database. They are typically read from `config.yaml` when set there directly.
|
||||
|
||||
`bd config show` is the source of truth for what's currently effective on your machine, including provenance.
|
||||
|
||||
## Project-Level Settings (Database)
|
||||
|
||||
These are written to the Dolt database by `bd config set` and have no env var override. Common namespaces:
|
||||
|
||||
| Namespace | Purpose |
|
||||
|---|---|
|
||||
| `jira.*` | Jira integration (URL, project, status_map, type_map) |
|
||||
| `linear.*` | Linear integration (team_id, state_map, label_type_map, relation_map) |
|
||||
| `github.*` | GitHub integration (org, repo, label_map) |
|
||||
| `ado.*` | Azure DevOps integration (org, project, state_map, type_map) |
|
||||
| `custom.*` | User-defined / custom integrations |
|
||||
| `status.custom` | Comma-separated list of custom statuses |
|
||||
| `types.custom` | Comma-separated list of custom issue types |
|
||||
| `types.infra` | Infra types routed to wisps table |
|
||||
| `import.orphan_handling` | `allow` (default) \| `resurrect` \| `skip` \| `strict` |
|
||||
| `compact_*` | Compaction tuning (see [docs/CONFIG.md](https://github.com/gastownhall/beads/blob/main/docs/CONFIG.md)) |
|
||||
| `issue_id_mode` | `hash` (default) \| `counter` (sequential) |
|
||||
| `min_hash_length`, `max_hash_length` | Adaptive ID bounds (defaults `4` and `8`) |
|
||||
| `max_collision_prob` | Hash ID collision tolerance (default `0.25`) |
|
||||
| `doctor.suppress.*` | Suppress specific `bd doctor` warnings by check slug |
|
||||
|
||||
Issue prefix (`issue_prefix`) is **not** settable via `bd config set` — use `bd init --prefix`, `bd bootstrap`, or `bd rename-prefix`.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
The Viper env prefix is `BD_`. Config keys map to env vars by upper-casing and replacing `.` and `-` with `_` (e.g. `dolt.auto-commit` → `BD_DOLT_AUTO_COMMIT`, `validation.on-create` → `BD_VALIDATION_ON_CREATE`).
|
||||
|
||||
Selected commonly-used variables:
|
||||
|
||||
| Variable | Description |
|
||||
|---|---|
|
||||
| `BD_DB`, `BEADS_DB` | Database path (legacy `BEADS_DB` still honored) |
|
||||
| `BD_JSON` | Force JSON output |
|
||||
| `BD_DOLT_AUTO_COMMIT` | Override `dolt.auto-commit` (`on`/`off`) |
|
||||
| `BD_DOLT_AUTO_PUSH` | Override `dolt.auto-push` |
|
||||
| `BD_BACKUP_ENABLED`, `BD_BACKUP_INTERVAL`, `BD_BACKUP_GIT_REPO` | Override backup settings |
|
||||
| `BD_AI_MODEL` | Override AI model |
|
||||
| `BD_FEDERATION_REMOTE`, `BD_FEDERATION_SOVEREIGNTY` | Override federation settings |
|
||||
| `BD_VALIDATION_ON_CREATE` / `_ON_CLOSE` / `_ON_SYNC` | Override validation modes |
|
||||
| `BD_NO_PAGER`, `BD_PAGER` | Pager behavior |
|
||||
| `BD_NON_INTERACTIVE` | Disable prompts |
|
||||
| `BD_DEBUG` | Enable debug logging |
|
||||
| `BEADS_DIR` | Force the active beads workspace directory |
|
||||
| `BEADS_ACTOR` | Actor identity (preferred over `BD_ACTOR`, which is a deprecated alias) |
|
||||
| `BEADS_IDENTITY` | Sender identity for `bd mail` |
|
||||
| `BEADS_DOLT_SERVER_MODE`, `BEADS_DOLT_SHARED_SERVER`, `BEADS_DOLT_DATA_DIR`, `BEADS_DOLT_PORT`, ... | Embedded/server Dolt overrides |
|
||||
|
||||
Secrets like API tokens follow integration-specific conventions: `LINEAR_API_KEY`, `GITHUB_TOKEN`, `ANTHROPIC_API_KEY`, `AZURE_DEVOPS_PAT`. These are preferred over storing the value in `config.yaml` for git-tracked projects.
|
||||
|
||||
`bd config show` will display the source of every effective key, making overrides explicit.
|
||||
|
||||
## Example `.beads/config.yaml`
|
||||
|
||||
```yaml
|
||||
# Default JSON output for scripting
|
||||
json: true
|
||||
|
||||
# Dolt history & sync
|
||||
dolt:
|
||||
auto-commit: on # Create a Dolt commit after each successful write
|
||||
auto-push: false # Opt-in for single-writer setups
|
||||
|
||||
# Issue creation policies
|
||||
create:
|
||||
require-description: true
|
||||
|
||||
validation:
|
||||
on-create: warn # Warn when creating issues missing required sections
|
||||
on-close: none
|
||||
on-sync: none
|
||||
|
||||
# Git commit signing for beads commits (GH#600)
|
||||
git:
|
||||
author: "beads-bot <beads@example.com>"
|
||||
no-gpg-sign: true
|
||||
|
||||
# Periodic Dolt-native backup to .beads/backup/
|
||||
backup:
|
||||
enabled: true
|
||||
interval: 15m
|
||||
|
||||
# Optional auto-export of issues.jsonl after writes for viewers/interchange
|
||||
export:
|
||||
auto: false
|
||||
path: issues.jsonl
|
||||
interval: 60s
|
||||
git-add: false
|
||||
|
||||
# Optional Dolt federation
|
||||
federation:
|
||||
remote: dolthub://myorg/beads
|
||||
sovereignty: T2
|
||||
|
||||
# Directory-aware label scoping for monorepos (GH#541)
|
||||
directory:
|
||||
labels:
|
||||
packages/maverick: maverick
|
||||
packages/agency: agency
|
||||
|
||||
# Cross-project dependency resolution (bd-h807)
|
||||
external_projects:
|
||||
beads: ../beads
|
||||
other-project: /absolute/path/to/other-project
|
||||
|
||||
output:
|
||||
title-length: 255
|
||||
```
|
||||
|
||||
For machine-specific overrides that should not be committed, drop them in `.beads/config.local.yaml`; it is merged in last.
|
||||
|
||||
## Per-Command Override
|
||||
|
||||
```bash
|
||||
bd --db /tmp/test.db list # Override database for one command
|
||||
bd --json --actor "ci-bot" create "Fix things" # Multiple flags
|
||||
```
|
||||
|
||||
## Viewing Active Configuration
|
||||
|
||||
```bash
|
||||
bd config show # Effective config with provenance
|
||||
bd config show --json # Machine-readable
|
||||
bd config list # Database-stored config
|
||||
bd info --json | jq '.config' # Quick snapshot
|
||||
```
|
||||
154
docs/reference/faq.md
Normal file
154
docs/reference/faq.md
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
---
|
||||
title: FAQ
|
||||
---
|
||||
|
||||
## General
|
||||
|
||||
### Why beads instead of GitHub Issues or Jira?
|
||||
|
||||
Beads was designed specifically for AI-supervised coding workflows:
|
||||
- **Hash-based IDs** prevent collisions with concurrent agents
|
||||
- **Dolt-backed storage** enables branch-based workflows
|
||||
- **Dependency-aware** ready queue for automated work selection
|
||||
- **Formula system** for declarative workflow templates
|
||||
|
||||
### What does "beads" stand for?
|
||||
|
||||
Nothing specific - it's a metaphor for linked work items (like beads on a string).
|
||||
|
||||
### Is beads production-ready?
|
||||
|
||||
Yes, beads is used in production for AI-assisted development. The API is stable with semantic versioning.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Why Dolt instead of plain SQLite?
|
||||
|
||||
- **Dolt** provides a version-controlled SQL database with built-in replication
|
||||
- Git-like branching, diffing, and merging at the database level
|
||||
- No need for a separate sync format -- Dolt handles it natively
|
||||
|
||||
### Why hash-based IDs instead of sequential?
|
||||
|
||||
Sequential IDs (`#1`, `#2`) break when:
|
||||
- Multiple agents create issues simultaneously
|
||||
- Different branches have independent numbering
|
||||
- Forks diverge and merge
|
||||
|
||||
Hash-based IDs are globally unique without coordination.
|
||||
|
||||
### How does the Dolt server work?
|
||||
|
||||
Beads uses Dolt server mode for concurrent access:
|
||||
- Transaction isolation for multiple agents
|
||||
- SQL-based queries for performance
|
||||
- Automatic retry on conflicts
|
||||
|
||||
In CI/CD or single-agent environments, beads uses embedded mode automatically (no server required).
|
||||
|
||||
## Usage
|
||||
|
||||
### How do I sync issues?
|
||||
|
||||
```bash
|
||||
# Push changes to Dolt remote:
|
||||
bd dolt push
|
||||
|
||||
# Pull changes from Dolt remote:
|
||||
bd dolt pull
|
||||
```
|
||||
|
||||
### How do I handle merge conflicts?
|
||||
|
||||
Dolt handles merge conflicts at the database level. If conflicts arise during pull:
|
||||
```bash
|
||||
bd doctor --fix
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
### Can multiple agents work on the same repo?
|
||||
|
||||
Yes! That's what beads was designed for:
|
||||
- Hash IDs prevent collisions
|
||||
- Pin work to specific agents
|
||||
- Track who's working on what
|
||||
|
||||
### How do I use beads in CI/CD?
|
||||
|
||||
```bash
|
||||
# Just run commands directly — beads uses embedded mode in CI
|
||||
bd list
|
||||
```
|
||||
|
||||
## Workflows
|
||||
|
||||
### What are formulas?
|
||||
|
||||
Declarative workflow templates in TOML or JSON. Pour them to create molecules (instances).
|
||||
|
||||
### What are gates?
|
||||
|
||||
Async coordination primitives:
|
||||
- Human gates wait for approval
|
||||
- Timer gates wait for duration
|
||||
- GitHub gates wait for CI/PR events
|
||||
|
||||
### What's the difference between molecules and wisps?
|
||||
|
||||
- **Molecules** persist in `.beads/` and sync with git
|
||||
- **Wisps** are ephemeral in `.beads-wisp/` and don't sync
|
||||
|
||||
## Integration
|
||||
|
||||
### Should I use CLI or MCP?
|
||||
|
||||
**Use CLI + hooks** when shell is available (Claude Code, Cursor, etc.):
|
||||
- Lower context overhead (~1-2k vs 10-50k tokens)
|
||||
- Faster execution
|
||||
- Universal across editors
|
||||
|
||||
**Use MCP** when CLI unavailable (Claude Desktop).
|
||||
|
||||
### How do I integrate with my editor?
|
||||
|
||||
```bash
|
||||
bd setup claude # Claude Code
|
||||
bd setup cursor # Cursor
|
||||
bd setup aider # Aider
|
||||
```
|
||||
|
||||
### Can beads import from GitHub Issues?
|
||||
|
||||
Yes — see the [GitHub integration documentation](https://github.com/gastownhall/beads/blob/main/docs/GITHUB_IMPORT.md) for details.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Why is the Dolt server not starting?
|
||||
|
||||
```bash
|
||||
# Check server status
|
||||
bd doctor
|
||||
|
||||
# Check server logs
|
||||
cat .beads/dolt/sql-server.log
|
||||
|
||||
# Restart the server
|
||||
bd dolt stop
|
||||
bd dolt start
|
||||
```
|
||||
|
||||
### Why aren't my changes syncing?
|
||||
|
||||
```bash
|
||||
# Force push to Dolt remote
|
||||
bd dolt push
|
||||
|
||||
# Check hooks
|
||||
bd hooks status
|
||||
```
|
||||
|
||||
### How do I report a bug?
|
||||
|
||||
1. Check existing issues: https://github.com/gastownhall/beads/issues
|
||||
2. Include: `bd version`, `bd info --json`, reproduction steps
|
||||
3. File at: https://github.com/gastownhall/beads/issues/new
|
||||
127
docs/reference/git-integration.md
Normal file
127
docs/reference/git-integration.md
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
title: Git Integration
|
||||
---
|
||||
|
||||
How beads integrates with git.
|
||||
|
||||
## Overview
|
||||
|
||||
Beads uses git for:
|
||||
- **Project hosting** - Your code repository also hosts beads configuration
|
||||
- **Hooks** - Auto-sync on git operations
|
||||
|
||||
Data storage and sync are handled by Dolt (a version-controlled SQL database).
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
.beads/
|
||||
├── config.yaml # Project config (git-tracked)
|
||||
├── metadata.json # Backend metadata (git-tracked)
|
||||
└── dolt/ # Dolt database and server data (gitignored)
|
||||
```
|
||||
|
||||
## Git Hooks
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
bd hooks install
|
||||
```
|
||||
|
||||
Installs:
|
||||
- **pre-commit** - Triggers Dolt commit
|
||||
- **post-merge** - Triggers Dolt sync after pull
|
||||
- **pre-push** - Ensures Dolt sync before push
|
||||
|
||||
### Status
|
||||
|
||||
```bash
|
||||
bd hooks status
|
||||
```
|
||||
|
||||
### Uninstall
|
||||
|
||||
```bash
|
||||
bd hooks uninstall
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
Dolt handles merge conflicts at the database level using its built-in
|
||||
merge capabilities. When conflicts arise during sync, Dolt identifies
|
||||
conflicting rows and allows resolution through SQL.
|
||||
|
||||
```bash
|
||||
# Check for and fix conflicts
|
||||
bd doctor --fix
|
||||
```
|
||||
|
||||
## Protected Branches
|
||||
|
||||
Dolt stores data under `refs/dolt/data`, separate from Git refs. This means
|
||||
beads data does not conflict with protected Git branches, and no separate
|
||||
`beads-sync` branch or protected-branch exception is needed. On new projects
|
||||
with a Git `origin`, `bd init` configures that origin as the Dolt remote
|
||||
automatically.
|
||||
|
||||
## Git Worktrees
|
||||
|
||||
Beads works in Git worktrees without extra setup. Linked worktrees discover the
|
||||
repository's `.beads` workspace and sync issue data through Dolt:
|
||||
|
||||
```bash
|
||||
# In a linked worktree
|
||||
bd create "Task"
|
||||
bd list
|
||||
bd dolt pull
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
Older beads versions documented a `sync.branch` workflow that created hidden
|
||||
Git worktrees. That workflow has been removed; current sync uses Dolt remotes.
|
||||
|
||||
## Branch Workflows
|
||||
|
||||
### Feature Branch
|
||||
|
||||
```bash
|
||||
git checkout -b feature-x
|
||||
bd create "Feature X" -t feature
|
||||
# Work...
|
||||
bd dolt push
|
||||
git push
|
||||
```
|
||||
|
||||
### Fork Workflow
|
||||
|
||||
```bash
|
||||
# In fork
|
||||
bd init --contributor
|
||||
# Work in separate planning repo...
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
### Team Workflow
|
||||
|
||||
```bash
|
||||
bd init --team
|
||||
# All team members share the Dolt database
|
||||
bd dolt pull # Pull latest changes from Dolt remote
|
||||
bd dolt push # Push your changes to Dolt remote
|
||||
```
|
||||
|
||||
### Duplicate Detection
|
||||
|
||||
After merging branches:
|
||||
|
||||
```bash
|
||||
bd duplicates --auto-merge
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Install hooks** - `bd hooks install`
|
||||
2. **Push regularly** - `bd dolt push` at session end
|
||||
3. **Pull before work** - `bd dolt pull` to get latest issues
|
||||
4. **Use normal Git worktrees** - no sync branch is required
|
||||
207
docs/reference/json-schema.md
Normal file
207
docs/reference/json-schema.md
Normal file
|
|
@ -0,0 +1,207 @@
|
|||
---
|
||||
title: JSON Output Schema Contract
|
||||
---
|
||||
|
||||
Last reviewed: 2026-05-08
|
||||
|
||||
Freshness source: `cmd/bd/output.go`, `cmd/bd/errors.go`, and
|
||||
`cmd/bd/protocol/json_contract_test.go`.
|
||||
|
||||
All `bd` commands that support `--json` output can wrap their response in
|
||||
a uniform envelope by setting `BD_JSON_ENVELOPE=1`. This will become the
|
||||
default format in v2.0.
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Opt in to the envelope format
|
||||
|
||||
```bash
|
||||
export BD_JSON_ENVELOPE=1
|
||||
```
|
||||
|
||||
### Envelope format (BD_JSON_ENVELOPE=1, default in v2.0)
|
||||
|
||||
Every `--json` command wraps output as:
|
||||
|
||||
```json
|
||||
{"schema_version": 1, "data": <original-payload>}
|
||||
```
|
||||
|
||||
The original payload is untouched inside `.data` — no type corruption,
|
||||
no field injection. Works identically for objects, arrays, and maps.
|
||||
|
||||
### Updating consumers
|
||||
|
||||
```bash
|
||||
# Before (legacy):
|
||||
bd list --json | jq '.[0].id'
|
||||
bd show beads-abc --json | jq '.title'
|
||||
|
||||
# After (envelope):
|
||||
bd list --json | jq '.data[0].id'
|
||||
bd show beads-abc --json | jq '.data.title'
|
||||
|
||||
# Version check:
|
||||
bd show beads-abc --json | jq '.schema_version'
|
||||
```
|
||||
|
||||
### Timeline
|
||||
|
||||
- **Current release**: Legacy format is default. Set `BD_JSON_ENVELOPE=1` to opt in.
|
||||
A deprecation notice is printed to stderr when `--json` is used without the env var.
|
||||
- **v2.0**: Envelope becomes the default. `BD_JSON_ENVELOPE=0` available as
|
||||
temporary escape hatch for one release cycle.
|
||||
|
||||
## Schema Version
|
||||
|
||||
Current version: **1**
|
||||
|
||||
The `schema_version` field is an integer that increments when:
|
||||
- Fields are added, renamed, or removed
|
||||
- Output structure changes (e.g., nesting depth)
|
||||
- Field types change (e.g., string to integer)
|
||||
|
||||
Additive changes (new optional fields) do NOT bump the version.
|
||||
|
||||
## Output Formats
|
||||
|
||||
### Envelope mode (BD_JSON_ENVELOPE=1)
|
||||
|
||||
All commands emit a uniform envelope:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"data": {
|
||||
"id": "beads-abc",
|
||||
"title": "Example issue",
|
||||
"status": "open"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Arrays are wrapped the same way:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"data": [
|
||||
{"id": "beads-abc", "title": "First"},
|
||||
{"id": "beads-def", "title": "Second"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Legacy mode (default, until v2.0)
|
||||
|
||||
### Object commands (show, create, close, update, etc.)
|
||||
|
||||
Commands that return a single issue or result emit a JSON object with
|
||||
`schema_version` as a top-level field alongside the data:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"id": "beads-abc",
|
||||
"title": "Example issue",
|
||||
"status": "open",
|
||||
"priority": 1,
|
||||
"issue_type": "task",
|
||||
"created_at": "2026-04-20T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### List commands (list, ready, search, stale, etc.)
|
||||
|
||||
Commands that return multiple items emit a raw JSON array:
|
||||
|
||||
```json
|
||||
[
|
||||
{"id": "beads-abc", "title": "First", ...},
|
||||
{"id": "beads-def", "title": "Second", ...}
|
||||
]
|
||||
```
|
||||
|
||||
### Error output (stderr)
|
||||
|
||||
Errors with `--json` active emit JSON to stderr:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": 1,
|
||||
"error": "issue not found: beads-xyz",
|
||||
"code": "not_found"
|
||||
}
|
||||
```
|
||||
|
||||
## Field Contracts by Command
|
||||
|
||||
### bd list --json
|
||||
|
||||
Required fields per item:
|
||||
- `id` (string): Issue ID (e.g., "beads-abc")
|
||||
- `title` (string): Issue title
|
||||
- `status` (string): open, in_progress, closed, deferred
|
||||
- `priority` (number): 0-4
|
||||
- `issue_type` (string): bug, feature, task, epic, chore
|
||||
- `created_at` (string): RFC3339 timestamp
|
||||
|
||||
Optional fields:
|
||||
- `description`, `owner`, `updated_at`, `closed_at`
|
||||
- `labels` (string[]): Attached labels
|
||||
- `dependencies` (object[]): Dependency records
|
||||
- `dependency_count`, `dependent_count`, `comment_count` (number)
|
||||
- `parent` (string|null): Parent issue ID
|
||||
|
||||
### bd ready --json
|
||||
|
||||
Same schema as `bd list --json`. Items are filtered to unblocked issues only.
|
||||
Each item includes `dependency_count`, `dependent_count`, `comment_count`,
|
||||
and optional `parent` fields.
|
||||
|
||||
### bd blocked --json
|
||||
|
||||
Returns issues that are blocked by unresolved dependencies.
|
||||
Each item includes all standard issue fields plus:
|
||||
- `blocked_by_count` (number): Number of blocking dependencies
|
||||
- `blocked_by` (string[]): IDs of blocking issues
|
||||
|
||||
### bd show --json
|
||||
|
||||
Returns a single object (not wrapped in `items`). Same required fields as list
|
||||
items, plus:
|
||||
- `description` (string)
|
||||
- `acceptance_criteria` (string)
|
||||
- `dependencies` (object[]): Full dependency records
|
||||
- `comments` (object[]): Comment thread
|
||||
|
||||
### `import --json`
|
||||
|
||||
Returns a summary object when `--json` is active:
|
||||
- `source` (string): File path or "stdin"
|
||||
- `created` (number): Issues created
|
||||
- `skipped` (number): Issues skipped (dedup)
|
||||
- `dedup_skipped` (number): Issues skipped by `--dedup` title match
|
||||
- `memories` (number): Memory records imported
|
||||
- `ids` (string[]): IDs of created issues
|
||||
- `dry_run` (boolean): Whether `--dry-run` was active
|
||||
|
||||
### bd export --json
|
||||
|
||||
Outputs JSONL (one JSON object per line), not wrapped in an envelope.
|
||||
Each line is a self-contained issue or memory record. `schema_version`
|
||||
is included per line.
|
||||
|
||||
## Consumer Guidelines
|
||||
|
||||
1. **Check `schema_version`** on object output. If the version is
|
||||
higher than expected, log a warning but attempt to parse anyway
|
||||
(additive changes are backward-compatible).
|
||||
|
||||
2. **For list commands**, parse the output as a JSON array directly.
|
||||
|
||||
3. **Ignore unknown fields**. New fields may be added without bumping
|
||||
the schema version.
|
||||
|
||||
4. **Use `--json` flag**, not `--format json`. The `--json` flag is
|
||||
the stable contract; `--format` is for human-readable variants.
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Observability (OpenTelemetry)
|
||||
---
|
||||
title: Observability (OpenTelemetry)
|
||||
---
|
||||
|
||||
Beads exports metrics via OTLP HTTP. Telemetry is **disabled by default** — zero overhead when no variable is set.
|
||||
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Protected Branches
|
||||
---
|
||||
title: Protected Branches
|
||||
---
|
||||
|
||||
Beads does not need a protected-branch workaround in current releases.
|
||||
|
||||
|
|
@ -115,6 +117,6 @@ bd hooks install
|
|||
|
||||
## See Also
|
||||
|
||||
- [WORKTREES.md](WORKTREES.md) - Git worktree behavior
|
||||
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - general Git integration guide
|
||||
- [RECOVERY.md](RECOVERY.md) - recovery playbooks
|
||||
- [WORKTREES.md](/reference/worktrees) - Git worktree behavior
|
||||
- [GIT_INTEGRATION.md](/reference/git-integration) - general Git integration guide
|
||||
- [RECOVERY.md](/recovery/init-safety) - recovery playbooks
|
||||
221
docs/reference/troubleshooting.md
Normal file
221
docs/reference/troubleshooting.md
Normal file
|
|
@ -0,0 +1,221 @@
|
|||
---
|
||||
title: Troubleshooting
|
||||
---
|
||||
|
||||
Common issues and solutions.
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### `bd: command not found`
|
||||
|
||||
```bash
|
||||
# Check if installed
|
||||
which bd
|
||||
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
|
||||
|
||||
# Add Go bin to PATH
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
|
||||
# Or reinstall with the recommended installer
|
||||
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
|
||||
```
|
||||
|
||||
### `zsh: killed bd` on macOS
|
||||
|
||||
CGO/SQLite compatibility issue:
|
||||
|
||||
```bash
|
||||
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### Permission denied
|
||||
|
||||
```bash
|
||||
chmod +x $(which bd)
|
||||
```
|
||||
|
||||
## Database Issues
|
||||
|
||||
### Database not found
|
||||
|
||||
```bash
|
||||
# Initialize beads
|
||||
bd init --quiet
|
||||
|
||||
# Or specify database
|
||||
bd --db .beads/beads.db list
|
||||
```
|
||||
|
||||
### Database locked
|
||||
|
||||
```bash
|
||||
# Stop the Dolt server if running
|
||||
bd dolt stop
|
||||
|
||||
# Try again
|
||||
bd list
|
||||
```
|
||||
|
||||
### Corrupted database
|
||||
|
||||
```bash
|
||||
# Check and fix database
|
||||
bd doctor --fix
|
||||
|
||||
# Or pull from Dolt remote
|
||||
bd dolt pull
|
||||
|
||||
# Or restore from a backup
|
||||
bd backup restore [path] --force
|
||||
```
|
||||
|
||||
## Dolt Server Issues
|
||||
|
||||
### Server not starting
|
||||
|
||||
```bash
|
||||
# Check server health
|
||||
bd doctor
|
||||
|
||||
# Check server logs
|
||||
cat .beads/dolt/sql-server.log
|
||||
|
||||
# Restart the server
|
||||
bd dolt stop
|
||||
bd dolt start
|
||||
```
|
||||
|
||||
### Version mismatch
|
||||
|
||||
After upgrading bd:
|
||||
|
||||
```bash
|
||||
bd dolt stop
|
||||
bd dolt start
|
||||
```
|
||||
|
||||
## Sync Issues
|
||||
|
||||
### Changes not syncing
|
||||
|
||||
```bash
|
||||
# Force push to Dolt remote
|
||||
bd dolt push
|
||||
|
||||
# Check hooks
|
||||
bd hooks status
|
||||
```
|
||||
|
||||
### Recovery from backup
|
||||
|
||||
```bash
|
||||
# Restore from a Dolt backup
|
||||
bd backup restore [path] --force
|
||||
|
||||
# Or pull from Dolt remote
|
||||
bd dolt pull
|
||||
```
|
||||
|
||||
### Merge conflicts
|
||||
|
||||
```bash
|
||||
# Check for and fix Dolt conflicts
|
||||
bd doctor --fix
|
||||
|
||||
# Re-push
|
||||
bd dolt push
|
||||
```
|
||||
|
||||
## Git Hook Issues
|
||||
|
||||
### Hooks not running
|
||||
|
||||
```bash
|
||||
# Check if installed
|
||||
ls -la .git/hooks/
|
||||
|
||||
# Reinstall
|
||||
bd hooks install
|
||||
```
|
||||
|
||||
### Hook errors
|
||||
|
||||
```bash
|
||||
# Check hook script
|
||||
cat .git/hooks/pre-commit
|
||||
|
||||
# Run manually
|
||||
.git/hooks/pre-commit
|
||||
```
|
||||
|
||||
## Dependency Issues
|
||||
|
||||
### Circular dependencies
|
||||
|
||||
```bash
|
||||
# Detect cycles
|
||||
bd dep cycles
|
||||
|
||||
# Remove one dependency
|
||||
bd dep remove bd-A bd-B
|
||||
```
|
||||
|
||||
### Missing dependencies
|
||||
|
||||
```bash
|
||||
# Check orphan handling
|
||||
bd config get import.orphan_handling
|
||||
|
||||
# Allow orphans
|
||||
bd config set import.orphan_handling allow
|
||||
```
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow queries
|
||||
|
||||
```bash
|
||||
# Check database size
|
||||
ls -lh .beads/beads.db
|
||||
|
||||
# Compact if large
|
||||
bd admin compact --analyze
|
||||
```
|
||||
|
||||
### High memory usage
|
||||
|
||||
```bash
|
||||
# Reduce cache
|
||||
bd config set database.cache_size 1000
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Debug output
|
||||
|
||||
```bash
|
||||
bd --verbose list
|
||||
```
|
||||
|
||||
### Logs
|
||||
|
||||
```bash
|
||||
cat .beads/dolt/sql-server.log
|
||||
```
|
||||
|
||||
### System info
|
||||
|
||||
```bash
|
||||
bd info --json
|
||||
```
|
||||
|
||||
### File an issue
|
||||
|
||||
```bash
|
||||
# Include this info
|
||||
bd version
|
||||
bd info --json
|
||||
uname -a
|
||||
```
|
||||
|
||||
Report at: https://github.com/gastownhall/beads/issues
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# Git Worktrees Guide
|
||||
---
|
||||
title: Git Worktrees Guide
|
||||
---
|
||||
|
||||
Beads works from normal Git worktrees without a separate sync branch. Current
|
||||
beads stores issue data in Dolt under `refs/dolt/data`, so issue sync is
|
||||
|
|
@ -126,6 +128,6 @@ working the same issue concurrently.
|
|||
|
||||
## See Also
|
||||
|
||||
- [PROTECTED_BRANCHES.md](PROTECTED_BRANCHES.md) - protected branch behavior
|
||||
- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - general Git integration guide
|
||||
- [MULTI_REPO_MIGRATION.md](MULTI_REPO_MIGRATION.md) - multi-workspace patterns
|
||||
- [PROTECTED_BRANCHES.md](/reference/protected-branches) - protected branch behavior
|
||||
- [GIT_INTEGRATION.md](/reference/git-integration) - general Git integration guide
|
||||
- [MULTI_REPO_MIGRATION.md](/multi-agent/multi-repo-migration) - multi-workspace patterns
|
||||
|
|
@ -1,8 +1,10 @@
|
|||
# Related Projects
|
||||
---
|
||||
title: Related Projects
|
||||
---
|
||||
|
||||
Adjacent or complementary tools that solve different problems in the
|
||||
same neighborhood as Beads. These are not Beads integrations (see
|
||||
[COMMUNITY_TOOLS.md](COMMUNITY_TOOLS.md) for those) — they are
|
||||
[COMMUNITY_TOOLS.md](/community-tools) for those) — they are
|
||||
independent projects whose users may also find Beads useful, or vice
|
||||
versa.
|
||||
|
||||
248
docs/workflows/formulas.md
Normal file
248
docs/workflows/formulas.md
Normal file
|
|
@ -0,0 +1,248 @@
|
|||
---
|
||||
title: Formulas
|
||||
---
|
||||
|
||||
Formulas are declarative workflow templates.
|
||||
|
||||
## Formula Format
|
||||
|
||||
Formulas can be written in TOML (preferred) or JSON:
|
||||
|
||||
### TOML Format
|
||||
|
||||
```toml
|
||||
formula = "feature-workflow"
|
||||
description = "Standard feature development workflow"
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[vars.feature_name]
|
||||
description = "Name of the feature"
|
||||
required = true
|
||||
|
||||
[[steps]]
|
||||
id = "design"
|
||||
title = "Design {{feature_name}}"
|
||||
type = "human"
|
||||
description = "Create design document"
|
||||
|
||||
[[steps]]
|
||||
id = "implement"
|
||||
title = "Implement {{feature_name}}"
|
||||
needs = ["design"]
|
||||
|
||||
[[steps]]
|
||||
id = "review"
|
||||
title = "Code review"
|
||||
needs = ["implement"]
|
||||
type = "human"
|
||||
|
||||
[[steps]]
|
||||
id = "merge"
|
||||
title = "Merge to main"
|
||||
needs = ["review"]
|
||||
```
|
||||
|
||||
### JSON Format
|
||||
|
||||
```json
|
||||
{
|
||||
"formula": "feature-workflow",
|
||||
"description": "Standard feature development workflow",
|
||||
"version": 1,
|
||||
"type": "workflow",
|
||||
"vars": {
|
||||
"feature_name": {
|
||||
"description": "Name of the feature",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"steps": [
|
||||
{
|
||||
"id": "design",
|
||||
"title": "Design {{feature_name}}",
|
||||
"type": "human"
|
||||
},
|
||||
{
|
||||
"id": "implement",
|
||||
"title": "Implement {{feature_name}}",
|
||||
"needs": ["design"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Formula Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `workflow` | Standard step sequence |
|
||||
| `expansion` | Template for expansion operator |
|
||||
| `aspect` | Cross-cutting concerns |
|
||||
|
||||
## Variables
|
||||
|
||||
Define variables with defaults and constraints:
|
||||
|
||||
```toml
|
||||
[vars.version]
|
||||
description = "Release version"
|
||||
required = true
|
||||
pattern = "^\\d+\\.\\d+\\.\\d+$"
|
||||
|
||||
[vars.environment]
|
||||
description = "Target environment"
|
||||
default = "staging"
|
||||
enum = ["staging", "production"]
|
||||
```
|
||||
|
||||
Use variables in steps:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
title = "Deploy {{version}} to {{environment}}"
|
||||
```
|
||||
|
||||
## Step Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| `task` | Normal work step (default) |
|
||||
| `human` | Requires human action |
|
||||
| `gate` | Async coordination point |
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Sequential
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "step1"
|
||||
title = "First step"
|
||||
|
||||
[[steps]]
|
||||
id = "step2"
|
||||
title = "Second step"
|
||||
needs = ["step1"]
|
||||
```
|
||||
|
||||
### Parallel then Join
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "test-unit"
|
||||
title = "Unit tests"
|
||||
|
||||
[[steps]]
|
||||
id = "test-integration"
|
||||
title = "Integration tests"
|
||||
|
||||
[[steps]]
|
||||
id = "deploy"
|
||||
title = "Deploy"
|
||||
needs = ["test-unit", "test-integration"] # Waits for both
|
||||
```
|
||||
|
||||
## Gates
|
||||
|
||||
Add gates for async coordination:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "approval"
|
||||
title = "Manager approval"
|
||||
type = "human"
|
||||
|
||||
[steps.gate]
|
||||
type = "human"
|
||||
approvers = ["manager"]
|
||||
|
||||
[[steps]]
|
||||
id = "deploy"
|
||||
title = "Deploy to production"
|
||||
needs = ["approval"]
|
||||
```
|
||||
|
||||
## Aspects (Cross-cutting)
|
||||
|
||||
Apply transformations to matching steps:
|
||||
|
||||
```toml
|
||||
formula = "security-scan"
|
||||
type = "aspect"
|
||||
|
||||
[[advice]]
|
||||
target = "*.deploy" # Match all deploy steps
|
||||
|
||||
[advice.before]
|
||||
id = "security-scan-{step.id}"
|
||||
title = "Security scan before {step.title}"
|
||||
```
|
||||
|
||||
## Formula Locations
|
||||
|
||||
Formulas are searched in order:
|
||||
1. `.beads/formulas/` (project-level)
|
||||
2. `~/.beads/formulas/` (user-level)
|
||||
3. Built-in formulas
|
||||
|
||||
## Using Formulas
|
||||
|
||||
```bash
|
||||
# List available formulas
|
||||
bd mol list
|
||||
|
||||
# Pour formula into molecule
|
||||
bd pour <formula-name> --var key=value
|
||||
|
||||
# Preview what would be created
|
||||
bd pour <formula-name> --dry-run
|
||||
```
|
||||
|
||||
## Creating Custom Formulas
|
||||
|
||||
1. Create file: `.beads/formulas/my-workflow.formula.toml`
|
||||
2. Define structure (see examples above)
|
||||
3. Use with: `bd pour my-workflow`
|
||||
|
||||
## Example: Release Formula
|
||||
|
||||
```toml
|
||||
formula = "release"
|
||||
description = "Standard release workflow"
|
||||
version = 1
|
||||
|
||||
[vars.version]
|
||||
required = true
|
||||
pattern = "^\\d+\\.\\d+\\.\\d+$"
|
||||
|
||||
[[steps]]
|
||||
id = "bump-version"
|
||||
title = "Bump version to {{version}}"
|
||||
|
||||
[[steps]]
|
||||
id = "changelog"
|
||||
title = "Update CHANGELOG"
|
||||
needs = ["bump-version"]
|
||||
|
||||
[[steps]]
|
||||
id = "test"
|
||||
title = "Run full test suite"
|
||||
needs = ["changelog"]
|
||||
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build release artifacts"
|
||||
needs = ["test"]
|
||||
|
||||
[[steps]]
|
||||
id = "tag"
|
||||
title = "Create git tag v{{version}}"
|
||||
needs = ["build"]
|
||||
|
||||
[[steps]]
|
||||
id = "publish"
|
||||
title = "Publish release"
|
||||
needs = ["tag"]
|
||||
type = "human"
|
||||
```
|
||||
212
docs/workflows/gates.md
Normal file
212
docs/workflows/gates.md
Normal file
|
|
@ -0,0 +1,212 @@
|
|||
---
|
||||
title: Gates
|
||||
---
|
||||
|
||||
Gates are async coordination primitives for workflow orchestration.
|
||||
|
||||
## What are Gates?
|
||||
|
||||
Gates block step progression until a condition is met:
|
||||
- Human approval
|
||||
- Timer expiration
|
||||
- External event (GitHub PR, CI, etc.)
|
||||
|
||||
## Gate Types
|
||||
|
||||
### Human Gate
|
||||
|
||||
Wait for human approval:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "deploy-approval"
|
||||
title = "Approval for production deploy"
|
||||
type = "human"
|
||||
|
||||
[steps.gate]
|
||||
type = "human"
|
||||
approvers = ["team-lead", "security"]
|
||||
require_all = false # Any approver can approve
|
||||
```
|
||||
|
||||
### Timer Gate
|
||||
|
||||
Wait for a duration:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "cooldown"
|
||||
title = "Wait for cooldown period"
|
||||
|
||||
[steps.gate]
|
||||
type = "timer"
|
||||
duration = "24h"
|
||||
```
|
||||
|
||||
Durations: `30m`, `2h`, `24h`, `7d`
|
||||
|
||||
### GitHub Gate
|
||||
|
||||
Wait for GitHub events:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "wait-for-ci"
|
||||
title = "Wait for CI to pass"
|
||||
|
||||
[steps.gate]
|
||||
type = "github"
|
||||
event = "check_suite"
|
||||
status = "success"
|
||||
```
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "wait-for-merge"
|
||||
title = "Wait for PR merge"
|
||||
|
||||
[steps.gate]
|
||||
type = "github"
|
||||
event = "pull_request"
|
||||
action = "closed"
|
||||
merged = true
|
||||
```
|
||||
|
||||
## Gate States
|
||||
|
||||
| State | Description |
|
||||
|-------|-------------|
|
||||
| `pending` | Waiting for condition |
|
||||
| `open` | Condition met, can proceed |
|
||||
| `closed` | Step completed |
|
||||
|
||||
## Using Gates in Workflows
|
||||
|
||||
### Approval Flow
|
||||
|
||||
```toml
|
||||
formula = "production-deploy"
|
||||
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build production artifacts"
|
||||
|
||||
[[steps]]
|
||||
id = "staging"
|
||||
title = "Deploy to staging"
|
||||
needs = ["build"]
|
||||
|
||||
[[steps]]
|
||||
id = "qa-approval"
|
||||
title = "QA sign-off"
|
||||
needs = ["staging"]
|
||||
type = "human"
|
||||
|
||||
[steps.gate]
|
||||
type = "human"
|
||||
approvers = ["qa-team"]
|
||||
|
||||
[[steps]]
|
||||
id = "production"
|
||||
title = "Deploy to production"
|
||||
needs = ["qa-approval"]
|
||||
```
|
||||
|
||||
### Scheduled Release
|
||||
|
||||
```toml
|
||||
formula = "scheduled-release"
|
||||
|
||||
[[steps]]
|
||||
id = "prepare"
|
||||
title = "Prepare release"
|
||||
|
||||
[[steps]]
|
||||
id = "wait-window"
|
||||
title = "Wait for release window"
|
||||
needs = ["prepare"]
|
||||
|
||||
[steps.gate]
|
||||
type = "timer"
|
||||
duration = "2h"
|
||||
|
||||
[[steps]]
|
||||
id = "deploy"
|
||||
title = "Deploy release"
|
||||
needs = ["wait-window"]
|
||||
```
|
||||
|
||||
### CI Integration
|
||||
|
||||
```toml
|
||||
formula = "ci-gated-deploy"
|
||||
|
||||
[[steps]]
|
||||
id = "create-pr"
|
||||
title = "Create pull request"
|
||||
|
||||
[[steps]]
|
||||
id = "wait-ci"
|
||||
title = "Wait for CI"
|
||||
needs = ["create-pr"]
|
||||
|
||||
[steps.gate]
|
||||
type = "github"
|
||||
event = "check_suite"
|
||||
status = "success"
|
||||
|
||||
[[steps]]
|
||||
id = "merge"
|
||||
title = "Merge PR"
|
||||
needs = ["wait-ci"]
|
||||
type = "human"
|
||||
```
|
||||
|
||||
## Gate Operations
|
||||
|
||||
### Check Gate Status
|
||||
|
||||
```bash
|
||||
bd show bd-xyz.3 # Shows gate state
|
||||
bd show bd-xyz.3 --json | jq '.gate'
|
||||
```
|
||||
|
||||
### Manual Gate Override
|
||||
|
||||
For human gates:
|
||||
|
||||
```bash
|
||||
bd gate approve bd-xyz.3 --approver "team-lead"
|
||||
```
|
||||
|
||||
### Skip Gate (Emergency)
|
||||
|
||||
```bash
|
||||
bd gate skip bd-xyz.3 --reason "Emergency deploy"
|
||||
```
|
||||
|
||||
## waits-for Dependency
|
||||
|
||||
The `waits-for` dependency type creates fan-in patterns:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "test-a"
|
||||
title = "Test suite A"
|
||||
|
||||
[[steps]]
|
||||
id = "test-b"
|
||||
title = "Test suite B"
|
||||
|
||||
[[steps]]
|
||||
id = "integration"
|
||||
title = "Integration tests"
|
||||
waits_for = ["test-a", "test-b"] # Fan-in: waits for all
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use human gates for critical decisions** - Don't auto-approve production
|
||||
2. **Add timeout to timer gates** - Prevent indefinite blocking
|
||||
3. **Document gate requirements** - Make approvers clear
|
||||
4. **Use CI gates for quality** - Block on test failures
|
||||
90
docs/workflows/index.md
Normal file
90
docs/workflows/index.md
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
---
|
||||
title: Workflows
|
||||
---
|
||||
|
||||
Beads provides powerful workflow primitives for complex, multi-step processes.
|
||||
|
||||
## Chemistry Metaphor
|
||||
|
||||
Beads uses a molecular chemistry metaphor:
|
||||
|
||||
| Phase | Storage | Synced | Use Case |
|
||||
|-------|---------|--------|----------|
|
||||
| **Proto** (solid) | Built-in | N/A | Reusable templates |
|
||||
| **Mol** (liquid) | `.beads/` | Yes | Persistent work |
|
||||
| **Wisp** (vapor) | `.beads-wisp/` | No | Ephemeral operations |
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Formulas
|
||||
|
||||
Declarative workflow templates in TOML or JSON:
|
||||
|
||||
```toml
|
||||
formula = "feature-workflow"
|
||||
version = 1
|
||||
type = "workflow"
|
||||
|
||||
[[steps]]
|
||||
id = "design"
|
||||
title = "Design the feature"
|
||||
type = "human"
|
||||
|
||||
[[steps]]
|
||||
id = "implement"
|
||||
title = "Implement the feature"
|
||||
needs = ["design"]
|
||||
```
|
||||
|
||||
### Molecules
|
||||
|
||||
Work graphs with parent-child relationships:
|
||||
- Created by instantiating formulas with `bd pour`
|
||||
- Steps have dependencies (`needs`)
|
||||
- Progress tracked via issue status
|
||||
|
||||
### Gates
|
||||
|
||||
Async coordination primitives:
|
||||
- **Human gates** - Wait for human approval
|
||||
- **Timer gates** - Wait for duration
|
||||
- **GitHub gates** - Wait for PR merge, CI, etc.
|
||||
|
||||
### Wisps
|
||||
|
||||
Ephemeral operations that don't sync to git:
|
||||
- Created with `bd wisp`
|
||||
- Stored in `.beads-wisp/` (gitignored)
|
||||
- Auto-expire after completion
|
||||
|
||||
## Workflow Commands
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `bd pour` | Instantiate formula as molecule |
|
||||
| `bd wisp` | Create ephemeral wisp |
|
||||
| `bd mol list` | List molecules |
|
||||
| `bd pin` | Pin work to agent |
|
||||
| `bd hook` | Show pinned work |
|
||||
|
||||
## Simple Example
|
||||
|
||||
```bash
|
||||
# Create a release workflow
|
||||
bd pour release --var version=1.0.0
|
||||
|
||||
# View the molecule
|
||||
bd mol show release-1.0.0
|
||||
|
||||
# Work through steps
|
||||
bd update release-1.0.0.1 --claim
|
||||
bd close release-1.0.0.1
|
||||
# Next step becomes ready...
|
||||
```
|
||||
|
||||
## Navigation
|
||||
|
||||
- [Molecules](/workflows/molecules) - Work graphs and execution
|
||||
- [Formulas](/workflows/formulas) - Declarative templates
|
||||
- [Gates](/workflows/gates) - Async coordination
|
||||
- [Wisps](/workflows/wisps) - Ephemeral operations
|
||||
156
docs/workflows/molecules.md
Normal file
156
docs/workflows/molecules.md
Normal file
|
|
@ -0,0 +1,156 @@
|
|||
---
|
||||
title: Molecules
|
||||
---
|
||||
|
||||
Molecules are work graphs created from formulas.
|
||||
|
||||
## What is a Molecule?
|
||||
|
||||
A molecule is a persistent instance of a formula:
|
||||
- Contains steps with dependencies
|
||||
- Tracked in `.beads/` (syncs with git)
|
||||
- Steps map to issues with parent-child relationships
|
||||
|
||||
## Creating Molecules
|
||||
|
||||
### From Formula
|
||||
|
||||
```bash
|
||||
# Pour a formula into a molecule
|
||||
bd pour <formula-name> [--var key=value]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
bd pour release --var version=1.0.0
|
||||
```
|
||||
|
||||
This creates:
|
||||
- Parent issue: `bd-xyz` (the molecule root)
|
||||
- Child issues: `bd-xyz.1`, `bd-xyz.2`, etc. (the steps)
|
||||
|
||||
### Listing Molecules
|
||||
|
||||
```bash
|
||||
bd mol list
|
||||
bd mol list --json
|
||||
```
|
||||
|
||||
### Viewing a Molecule
|
||||
|
||||
```bash
|
||||
bd mol show <molecule-id>
|
||||
bd dep tree <molecule-id> # Shows full hierarchy
|
||||
```
|
||||
|
||||
## Working with Molecules
|
||||
|
||||
### Step Dependencies
|
||||
|
||||
Steps have `needs` dependencies:
|
||||
|
||||
```toml
|
||||
[[steps]]
|
||||
id = "implement"
|
||||
title = "Implement feature"
|
||||
needs = ["design"] # Must complete design first
|
||||
```
|
||||
|
||||
The `bd ready` command respects these:
|
||||
|
||||
```bash
|
||||
bd ready # Only shows steps with completed dependencies
|
||||
```
|
||||
|
||||
### Progressing Through Steps
|
||||
|
||||
```bash
|
||||
# Start a step
|
||||
bd update bd-xyz.1 --claim
|
||||
|
||||
# Complete a step
|
||||
bd close bd-xyz.1 --reason "Done"
|
||||
|
||||
# Check what's ready next
|
||||
bd ready
|
||||
```
|
||||
|
||||
### Viewing Progress
|
||||
|
||||
```bash
|
||||
# See blocked steps
|
||||
bd blocked
|
||||
|
||||
# See molecule stats
|
||||
bd stats
|
||||
```
|
||||
|
||||
## Molecule Lifecycle
|
||||
|
||||
```
|
||||
Formula (template)
|
||||
↓ bd pour
|
||||
Molecule (instance)
|
||||
↓ work steps
|
||||
Completed Molecule
|
||||
↓ optional cleanup
|
||||
Archived
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Bond Points
|
||||
|
||||
Formulas can define bond points for composition:
|
||||
|
||||
```toml
|
||||
[compose]
|
||||
[[compose.bond_points]]
|
||||
id = "entry"
|
||||
step = "design"
|
||||
position = "before"
|
||||
```
|
||||
|
||||
### Hooks
|
||||
|
||||
Step-completion hooks are not currently exposed as runnable formula
|
||||
actions. The historical `on_complete.run` example was invalid: `run` is
|
||||
not a formula field, and `on_complete` runtime expansion is tracked
|
||||
separately until it is wired end to end.
|
||||
|
||||
### Pinning Work
|
||||
|
||||
Assign molecules to agents:
|
||||
|
||||
```bash
|
||||
# Pin to current agent
|
||||
bd pin bd-xyz --start
|
||||
|
||||
# Check what's pinned
|
||||
bd hook
|
||||
```
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```bash
|
||||
# 1. Create molecule from formula
|
||||
bd pour feature-workflow --var name="dark-mode"
|
||||
|
||||
# 2. View structure
|
||||
bd dep tree bd-xyz
|
||||
|
||||
# 3. Start first step
|
||||
bd update bd-xyz.1 --claim
|
||||
|
||||
# 4. Complete and progress
|
||||
bd close bd-xyz.1
|
||||
bd ready # Shows next steps
|
||||
|
||||
# 5. Continue until complete
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Formulas](/workflows/formulas) - Creating templates
|
||||
- [Gates](/workflows/gates) - Async coordination
|
||||
- [Wisps](/workflows/wisps) - Ephemeral workflows
|
||||
|
|
@ -1,4 +1,6 @@
|
|||
# TODO Command
|
||||
---
|
||||
title: TODO Command
|
||||
---
|
||||
|
||||
The `bd todo` command provides a lightweight interface for managing TODO items as task-type issues.
|
||||
|
||||
125
docs/workflows/wisps.md
Normal file
125
docs/workflows/wisps.md
Normal file
|
|
@ -0,0 +1,125 @@
|
|||
---
|
||||
title: Wisps
|
||||
---
|
||||
|
||||
Wisps are ephemeral workflows that don't sync to git.
|
||||
|
||||
## What are Wisps?
|
||||
|
||||
Wisps are "vapor phase" molecules:
|
||||
- Stored in `.beads-wisp/` (gitignored)
|
||||
- Don't sync with git
|
||||
- Auto-expire after completion
|
||||
- Perfect for temporary operations
|
||||
|
||||
## Use Cases
|
||||
|
||||
| Scenario | Why Wisp? |
|
||||
|----------|-----------|
|
||||
| Local experiments | No need to pollute git history |
|
||||
| CI/CD pipelines | Ephemeral by nature |
|
||||
| Scratch workflows | Quick throwaway work |
|
||||
| Agent coordination | Local-only coordination |
|
||||
|
||||
## Creating Wisps
|
||||
|
||||
```bash
|
||||
# Create wisp from formula
|
||||
bd wisp create <formula> [--var key=value]
|
||||
|
||||
# Example
|
||||
bd wisp create quick-check --var target=auth-module
|
||||
```
|
||||
|
||||
## Wisp Commands
|
||||
|
||||
```bash
|
||||
# List wisps
|
||||
bd wisp list
|
||||
bd wisp list --json
|
||||
|
||||
# Show wisp details
|
||||
bd wisp show <wisp-id>
|
||||
|
||||
# Delete wisp
|
||||
bd wisp delete <wisp-id>
|
||||
|
||||
# Delete all completed wisps
|
||||
bd wisp cleanup
|
||||
```
|
||||
|
||||
## Wisp vs Molecule
|
||||
|
||||
| Aspect | Molecule | Wisp |
|
||||
|--------|----------|------|
|
||||
| Storage | `.beads/` | `.beads-wisp/` |
|
||||
| Git sync | Yes | No |
|
||||
| Persistence | Permanent | Ephemeral |
|
||||
| Use case | Tracked work | Temporary ops |
|
||||
|
||||
## Phase Control
|
||||
|
||||
Use `bd mol bond` to control phase:
|
||||
|
||||
```bash
|
||||
# Force liquid (persistent molecule)
|
||||
bd mol bond <formula> <target> --pour
|
||||
|
||||
# Force vapor (ephemeral wisp)
|
||||
bd mol bond <formula> <target> --wisp
|
||||
```
|
||||
|
||||
## Example: Quick Check Workflow
|
||||
|
||||
Create a wisp for running checks:
|
||||
|
||||
```toml
|
||||
# .beads/formulas/quick-check.formula.toml
|
||||
formula = "quick-check"
|
||||
description = "Quick local checks"
|
||||
|
||||
[[steps]]
|
||||
id = "lint"
|
||||
title = "Run linter"
|
||||
|
||||
[[steps]]
|
||||
id = "test"
|
||||
title = "Run tests"
|
||||
needs = ["lint"]
|
||||
|
||||
[[steps]]
|
||||
id = "build"
|
||||
title = "Build project"
|
||||
needs = ["test"]
|
||||
```
|
||||
|
||||
Use as wisp:
|
||||
|
||||
```bash
|
||||
bd wisp create quick-check
|
||||
# Work through steps...
|
||||
bd wisp cleanup # Remove when done
|
||||
```
|
||||
|
||||
## Auto-Expiration
|
||||
|
||||
Wisps can auto-expire:
|
||||
|
||||
```toml
|
||||
[wisp]
|
||||
expires_after = "24h" # Auto-delete after 24 hours
|
||||
```
|
||||
|
||||
Or cleanup manually:
|
||||
|
||||
```bash
|
||||
bd wisp cleanup --all # Remove all wisps
|
||||
bd wisp cleanup --completed # Remove only completed
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use wisps for local-only work** - Don't sync to git
|
||||
2. **Clean up regularly** - `bd wisp cleanup`
|
||||
3. **Use molecules for tracked work** - Wisps are ephemeral
|
||||
4. **Consider CI/CD wisps** - Perfect for pipeline steps
|
||||
|
|
@ -22,7 +22,7 @@ DOCS=(
|
|||
"docs/ADO_CONFIG.md|cmd/bd/ado*.go;internal/ado/"
|
||||
"docs/JSON_SCHEMA.md|cmd/bd/output.go;cmd/bd/errors.go;cmd/bd/protocol/json_contract_test.go"
|
||||
"docs/RECOVERY.md|cmd/bd/init.go;cmd/bd/init_safety.go;cmd/bd/init_safety_test.go"
|
||||
"docs/ERROR_HANDLING.md|cmd/bd/*.go;cmd/bd/errors.go"
|
||||
"engdocs/ERROR_HANDLING.md|cmd/bd/*.go;cmd/bd/errors.go"
|
||||
"engdocs/LINTING.md|.golangci.yml"
|
||||
"engdocs/design/otel/otel-data-model.md|internal/telemetry/;internal/storage/dolt/store.go;internal/compact/haiku.go;cmd/bd/find_duplicates.go;internal/hooks/"
|
||||
)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue