# Beads Init

> Initialize beads issue tracking with manual sync workflow for new repositories.

- Skill: `justin-delano/beads-init` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add justin-delano/beads-init`
- Raw SKILL.md: https://api.skillmd.com/api/skills/justin-delano/beads-init/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: justin-delano (https://skillmd.com/u/justin-delano)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/justin-delano/beads-init

---

# Beads initialization

Initialize beads issue tracking in a project with manual control over when issue database changes are staged and committed.

## Initialize without auto-staging hooks

```bash
bd init --skip-hooks -p <prefix> -q
```

Replace `<prefix>` with the project-specific issue prefix (e.g., `INFRA`, `TS`, `CLAN`).

The `--skip-hooks` flag prevents installation of git hooks that would automatically stage `.beads/*.jsonl` files on every commit.
We keep the default merge driver (no `--skip-merge-driver`) since it only activates during merge conflicts and doesn't auto-stage.

For completely invisible beads usage without affecting repository collaborators, consider `--stealth` mode instead (see below).

## Alternative: Stealth mode (invisible beads)

For personal use without affecting repository collaborators:

```bash
bd init --stealth -p <prefix> -q
```

Stealth mode configures beads to be completely invisible to git:
- Adds `.beads/` to `.git/info/exclude` (local gitignore, not committed)
- Sets up Claude Code integration automatically
- Perfect for personal issue tracking without team coordination

With stealth mode, beads changes remain local and never enter git history.

## Post-init cleanup

After `bd init` completes, perform these cleanup steps:

```bash
# Review AGENTS.md - the new auto-generated version is minimal and useful:
# - Points to 'bd onboard' for getting started
# - Contains brief quick reference commands
# - Includes session completion protocol
# Customize if needed, or keep the generated version.

echo "README.md" >> .beads/.gitignore
```

## Manual sync workflow

### Committing beads changes

When you've made changes to issues via `bd` commands, flush the database to JSONL and stage the files manually:

```bash
bd hooks run pre-commit   # flush DB→JSONL + stage .beads/*.jsonl files
git commit -m "chore(issues): <description of changes>"
```

Example commit messages:
- `chore(issues): add epic for CI integration`
- `chore(issues): update story status for authentication module`
- `chore(issues): close completed infrastructure stories`

### Importing after git operations

After any git operation that changes commits (pull, checkout, merge, rebase), import JSONL changes back to the database:

```bash
bd sync --import-only   # JSONL→DB without staging
```

This ensures your local beads database stays synchronized with the JSONL files tracked in git.

## Rationale

Manual sync workflow provides explicit control over when issue tracking state enters git history, allowing you to:

- Batch multiple issue operations into single commits
- Separate issue updates from code changes
- Review staged issue changes before committing
- Avoid automatic staging during experimental work

The merge driver remains enabled to handle merge conflicts in JSONL files during collaborative workflows, but it doesn't auto-stage changes during normal operations.

## Configuring no-git-ops mode

To suppress git commands in AI agent session protocols:

```bash
bd config set no-git-ops true
```

This configures `bd prime` to output stealth mode instructions, ensuring agents only flush to JSONL without attempting git operations.
Useful when you want manual control over when commits happen.

## See also

Additional commands for working with beads:

- `bd onboard` - Display integration snippet for AGENTS.md
- `bd prime` - Show AI-optimized workflow context
- `bd quickstart` - View quick start guide
- `bd setup` - Install AI editor integrations