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:
Steve Yegge
120
website/docs/integrations/aider.md
Normal file
120
website/docs/integrations/aider.md
Normal file
@@ -0,0 +1,120 @@
|
||||
---
|
||||
id: aider
|
||||
title: Aider
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Aider Integration
|
||||
|
||||
How to use beads with Aider.
|
||||
|
||||
## Setup
|
||||
|
||||
### Quick Setup
|
||||
|
||||
```bash
|
||||
bd setup aider
|
||||
```
|
||||
|
||||
This creates/updates `.aider.conf.yml` with beads context.
|
||||
|
||||
### Verify Setup
|
||||
|
||||
```bash
|
||||
bd setup aider --check
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The setup adds to `.aider.conf.yml`:
|
||||
|
||||
```yaml
|
||||
# Beads integration
|
||||
read:
|
||||
- .beads/issues.jsonl
|
||||
|
||||
# Optional: Auto-run bd prime
|
||||
auto-commits: false
|
||||
```
|
||||
|
||||
## 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 --status in_progress
|
||||
bd ready
|
||||
```
|
||||
|
||||
### End Session
|
||||
|
||||
```bash
|
||||
bd sync
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep issues visible** - Aider reads `.beads/issues.jsonl`
|
||||
2. **Sync regularly** - Run `bd sync` 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 sync
|
||||
bd close bd-42 --reason "Fixed"
|
||||
bd sync
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Config not loading
|
||||
|
||||
```bash
|
||||
# Check config exists
|
||||
cat .aider.conf.yml
|
||||
|
||||
# Regenerate
|
||||
bd setup aider
|
||||
```
|
||||
|
||||
### Issues not visible
|
||||
|
||||
```bash
|
||||
# Check JSONL exists
|
||||
ls -la .beads/issues.jsonl
|
||||
|
||||
# Export if missing
|
||||
bd export
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Claude Code](/integrations/claude-code)
|
||||
- [IDE Setup](/getting-started/ide-setup)
|
||||
186
website/docs/integrations/claude-code.md
Normal file
186
website/docs/integrations/claude-code.md
Normal file
@@ -0,0 +1,186 @@
|
||||
---
|
||||
id: claude-code
|
||||
title: Claude Code
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Claude Code Integration
|
||||
|
||||
How to use beads with Claude Code.
|
||||
|
||||
## Setup
|
||||
|
||||
### Quick Setup
|
||||
|
||||
```bash
|
||||
bd setup claude
|
||||
```
|
||||
|
||||
This installs:
|
||||
- **SessionStart hook** - Runs `bd prime` on session start
|
||||
- **PreCompact hook** - Runs `bd sync` before context compaction
|
||||
|
||||
### Manual Setup
|
||||
|
||||
Add to your Claude Code hooks configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": ["bd prime"],
|
||||
"PreCompact": ["bd sync"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 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 sync` saves work to git
|
||||
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 --status in_progress --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 sync
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
### Sync Before Session End
|
||||
|
||||
```bash
|
||||
# ALWAYS run before ending
|
||||
bd sync
|
||||
```
|
||||
|
||||
## Plugin (Optional)
|
||||
|
||||
For enhanced UX with slash commands:
|
||||
|
||||
```bash
|
||||
# In Claude Code
|
||||
/plugin marketplace add steveyegge/beads
|
||||
/plugin install beads
|
||||
# Restart Claude Code
|
||||
```
|
||||
|
||||
Adds slash commands:
|
||||
- `/bd-ready` - Show ready work
|
||||
- `/bd-create` - Create issue
|
||||
- `/bd-show` - Show issue
|
||||
- `/bd-update` - Update issue
|
||||
- `/bd-close` - Close issue
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Context not injected
|
||||
|
||||
```bash
|
||||
# Check hook setup
|
||||
bd setup claude --check
|
||||
|
||||
# Manually prime
|
||||
bd prime
|
||||
```
|
||||
|
||||
### Changes not syncing
|
||||
|
||||
```bash
|
||||
# Force sync
|
||||
bd sync
|
||||
|
||||
# Check daemon
|
||||
bd info
|
||||
bd daemons health
|
||||
```
|
||||
|
||||
### 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
|
||||
149
website/docs/integrations/mcp-server.md
Normal file
149
website/docs/integrations/mcp-server.md
Normal file
@@ -0,0 +1,149 @@
|
||||
---
|
||||
id: mcp-server
|
||||
title: MCP Server
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# 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": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user