Convert gitgram/ and aitimemachine/ from embedded git repos (which showed as opaque submodule gitlinks on GitHub) into fully-tracked first-party content. AITM now merges its 7 vendored repos as first-party engines: - memory: beads (Go task DAG) + context7 (docs SDK), unified into saved_contexts - git: vendored C git (bundled binary) + gitnexus (in-process code intelligence) - agentic: a2a (@a2a-js/sdk) + pal (AITM-managed Python subprocess) Includes the full session's product build: Gitgram web/mobile/backend features, AITM website/CLI/MCP, the unified memory layer, engine build tooling (scripts/build-engines.sh, Dockerfile, CI), docs (README, ENGINES.md, ARCHITECTURE.md), and extensive test suites. Build artifacts, node_modules, external/, and gemini-cli are gitignored. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2.8 KiB
2.8 KiB
id, title, sidebar_position
| id | title | sidebar_position |
|---|---|---|
| troubleshooting | Troubleshooting | 4 |
Troubleshooting
Common issues and solutions.
Installation Issues
bd: command not found
# 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:
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
Permission denied
chmod +x $(which bd)
Database Issues
Database not found
# Initialize beads
bd init --quiet
# Or specify database
bd --db .beads/beads.db list
Database locked
# Stop the Dolt server if running
bd dolt stop
# Try again
bd list
Corrupted database
# 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
# 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:
bd dolt stop
bd dolt start
Sync Issues
Changes not syncing
# Force push to Dolt remote
bd dolt push
# Check hooks
bd hooks status
Recovery from backup
# Restore from a Dolt backup
bd backup restore [path] --force
# Or pull from Dolt remote
bd dolt pull
Merge conflicts
# Check for and fix Dolt conflicts
bd doctor --fix
# Re-push
bd dolt push
Git Hook Issues
Hooks not running
# Check if installed
ls -la .git/hooks/
# Reinstall
bd hooks install
Hook errors
# Check hook script
cat .git/hooks/pre-commit
# Run manually
.git/hooks/pre-commit
Dependency Issues
Circular dependencies
# Detect cycles
bd dep cycles
# Remove one dependency
bd dep remove bd-A bd-B
Missing dependencies
# Check orphan handling
bd config get import.orphan_handling
# Allow orphans
bd config set import.orphan_handling allow
Performance Issues
Slow queries
# Check database size
ls -lh .beads/beads.db
# Compact if large
bd admin compact --analyze
High memory usage
# Reduce cache
bd config set database.cache_size 1000
Getting Help
Debug output
bd --verbose list
Logs
cat .beads/dolt/sql-server.log
System info
bd info --json
File an issue
# Include this info
bd version
bd info --json
uname -a
Report at: https://github.com/gastownhall/beads/issues