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
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue