feat: add llms.txt standard support for AI agent discoverability (#784)
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
This commit is contained in:
165
website/docs/core-concepts/daemon.md
Normal file
165
website/docs/core-concepts/daemon.md
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
id: daemon
|
||||
title: Daemon Architecture
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Daemon Architecture
|
||||
|
||||
Beads runs a background daemon for auto-sync and performance.
|
||||
|
||||
## Overview
|
||||
|
||||
Each workspace gets its own daemon process:
|
||||
- Auto-starts on first `bd` command
|
||||
- Handles database ↔ JSONL synchronization
|
||||
- Listens on `.beads/bd.sock` (Unix) or `.beads/bd.pipe` (Windows)
|
||||
- Version checking prevents mismatches after upgrades
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
CLI Command
|
||||
↓
|
||||
RPC to Daemon
|
||||
↓
|
||||
Daemon executes
|
||||
↓
|
||||
Auto-sync to JSONL (5s debounce)
|
||||
```
|
||||
|
||||
Without daemon, commands access the database directly (slower, no auto-sync).
|
||||
|
||||
## Managing Daemons
|
||||
|
||||
```bash
|
||||
# List all running daemons
|
||||
bd daemons list
|
||||
bd daemons list --json
|
||||
|
||||
# Check health and version mismatches
|
||||
bd daemons health
|
||||
bd daemons health --json
|
||||
|
||||
# View daemon logs
|
||||
bd daemons logs . -n 100
|
||||
|
||||
# Restart all daemons
|
||||
bd daemons killall
|
||||
bd daemons killall --json
|
||||
```
|
||||
|
||||
## Daemon Info
|
||||
|
||||
```bash
|
||||
bd info
|
||||
```
|
||||
|
||||
Shows:
|
||||
- Daemon status (running/stopped)
|
||||
- Daemon version vs CLI version
|
||||
- Socket location
|
||||
- Auto-sync status
|
||||
|
||||
## Disabling Daemon
|
||||
|
||||
Use `--no-daemon` flag to bypass the daemon:
|
||||
|
||||
```bash
|
||||
bd --no-daemon ready
|
||||
bd --no-daemon list
|
||||
```
|
||||
|
||||
**When to disable:**
|
||||
- Git worktrees (required)
|
||||
- CI/CD pipelines
|
||||
- Resource-constrained environments
|
||||
- Debugging sync issues
|
||||
|
||||
## Event-Driven Mode (Experimental)
|
||||
|
||||
Event-driven mode replaces 5-second polling with instant reactivity:
|
||||
|
||||
```bash
|
||||
# Enable globally
|
||||
export BEADS_DAEMON_MODE=events
|
||||
bd daemons killall # Restart to apply
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Less than 500ms latency (vs 5s polling)
|
||||
- ~60% less CPU usage
|
||||
- Instant sync after changes
|
||||
|
||||
**How to verify:**
|
||||
```bash
|
||||
bd info | grep "daemon mode"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Daemon not starting
|
||||
|
||||
```bash
|
||||
# Check if socket exists
|
||||
ls -la .beads/bd.sock
|
||||
|
||||
# Try direct mode
|
||||
bd --no-daemon info
|
||||
|
||||
# Restart daemon
|
||||
bd daemons killall
|
||||
bd info
|
||||
```
|
||||
|
||||
### Version mismatch
|
||||
|
||||
After upgrading bd:
|
||||
|
||||
```bash
|
||||
bd daemons killall
|
||||
bd info # Should show matching versions
|
||||
```
|
||||
|
||||
### Sync not happening
|
||||
|
||||
```bash
|
||||
# Force sync
|
||||
bd sync
|
||||
|
||||
# Check daemon logs
|
||||
bd daemons logs . -n 50
|
||||
|
||||
# Verify git status
|
||||
git status .beads/
|
||||
```
|
||||
|
||||
### Port/socket conflicts
|
||||
|
||||
```bash
|
||||
# Kill all daemons
|
||||
bd daemons killall
|
||||
|
||||
# Remove stale socket
|
||||
rm -f .beads/bd.sock
|
||||
|
||||
# Restart
|
||||
bd info
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Daemon behavior can be configured:
|
||||
|
||||
```bash
|
||||
# Set sync debounce interval
|
||||
bd config set daemon.sync_interval 10s
|
||||
|
||||
# Disable auto-start
|
||||
bd config set daemon.auto_start false
|
||||
|
||||
# Set log level
|
||||
bd config set daemon.log_level debug
|
||||
```
|
||||
|
||||
See [Configuration](/reference/configuration) for all options.
|
||||
Reference in New Issue
Block a user