# Beads Local DB Ops

> Use Beads (bd) with sync-branch workflow for task tracking across two-clone setup. Use when this capability is needed.

- Skill: `tomevault-io/beads-local-db-ops` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/beads-local-db-ops`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/beads-local-db-ops/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/beads-local-db-ops

---


# Beads Sync-Branch Ops

## Goal

Use Beads with sync-branch model where:

- Local SQLite (`.beads/beads.db`) is a fast cache
- Remote `beads-sync` branch is the shared truth
- Two clones sync via remote rendezvous

## Two-Clone Model (recommended)

- **Clone A:** `/path/to/clone-a/` (secondary working copy)
- **Clone B:** `/path/to/clone-b/` (primary working copy)
- Each clone has its own `.git/`, virtual environment, and `.beads/beads.db`
- Remote repo is the rendezvous point
- **Never assign the same task to both clones concurrently**

## When to use this skill

Use this skill for:

- Session start: sync state from remote
- During work: update issue status locally
- Session end: push state to remote

## Critical Workflow

### Session Start

```bash
# Pull latest state from remote (no push)
bd sync --no-push

# Find available work
bd ready

# Claim an issue
bd update <id> --status in_progress
```

### During Work

```bash
# View issue details
bd show <id>

# Update status
bd update <id> --status in_progress

# Add notes as you learn
bd update <id> --notes "..."
```

### Session End

```bash
# Close completed issues
bd close <id>

# Push state to remote
bd sync
```

## Operational Contract

- Always run `bd sync --no-push` at session start
- Only one clone runs daemon at a time (optional but clean)
- When switching employees, run `bd sync --no-push` before starting new work
- Never work on same issue in both clones concurrently

## Troubleshooting

- If Beads feels slow, ensure you are not in `no-db` mode
- If sync conflicts occur, remote `beads-sync` branch is authoritative
- Local DB is cache; sync operations reconcile with remote truth

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/galeavenworth-personal) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->