bd mol

Generated from bd help --doc mol

Manage molecules - work templates for agent workflows.

Protos are template epics with the "template" label. They define a DAG of work that can be spawned to create real issues (molecules).

The molecule metaphor:

A proto is an uninstantiated template (reusable work pattern)
Spawning creates a molecule (real issues) from the proto
Variables ({{key}}) are substituted during spawning
Bonding combines protos or molecules into compounds
Distilling extracts a proto from an ad-hoc epic

Commands: show Show proto/molecule structure and variables pour Instantiate proto as persistent mol (liquid phase) wisp Instantiate proto as ephemeral wisp (vapor phase) bond Polymorphic combine: proto+proto, proto+mol, mol+mol squash Condense molecule to digest burn Discard wisp distill Extract proto from ad-hoc epic

Use "bd formula list" to list available formulas.

bd mol

Aliases: protomolecule

bd mol bond

Bond two protos or molecules to create a compound.

The bond command is polymorphic - it handles different operand types:

formula + formula → cook both, compound proto formula + proto → cook formula, compound proto formula + mol → cook formula, spawn and attach proto + proto → compound proto (reusable template) proto + mol → spawn proto, attach to molecule mol + proto → spawn proto, attach to molecule mol + mol → join into compound molecule

Formula names (e.g., mol-polecat-arm) are cooked inline as ephemeral protos. This avoids needing pre-cooked proto beads in the database.

Bond types: sequential (default) - B runs after A completes parallel - B runs alongside A conditional - B runs only if A fails

Phase control: By default, spawned protos follow the target's phase:

Attaching to mol (Ephemeral=false) → spawns as persistent (Ephemeral=false)
Attaching to ephemeral issue (Ephemeral=true) → spawns as ephemeral (Ephemeral=true)

Override with: --pour Force spawn as liquid (persistent, Ephemeral=false) --ephemeral Force spawn as vapor (ephemeral, Ephemeral=true, excluded from Dolt sync via dolt_ignore)

Dynamic bonding (Christmas Ornament pattern): Use --ref to specify a custom child reference with variable substitution. This creates IDs like "parent.child-ref" instead of random hashes.

Example: bd mol bond mol-worker-arm bd-patrol --ref arm-{{worker_name}} --var worker_name=ace # Creates: bd-patrol.arm-ace (and children like bd-patrol.arm-ace.capture)

Use cases:

Found important bug during patrol? Use --pour to persist it
Need ephemeral diagnostic on persistent feature? Use --ephemeral
Spawning per-worker arms on a patrol? Use --ref for readable IDs

Examples: bd mol bond mol-feature mol-deploy # Compound proto bd mol bond mol-feature mol-deploy --type parallel # Run in parallel bd mol bond mol-feature bd-abc123 # Attach proto to molecule bd mol bond bd-abc123 bd-def456 # Join two molecules bd mol bond mol-critical-bug wisp-patrol --pour # Persist found bug bd mol bond mol-temp-check bd-feature --ephemeral # Ephemeral diagnostic bd mol bond mol-arm bd-patrol --ref arm-{{name}} --var name=ace # Dynamic child ID

bd mol bond <A> <B> [flags]

Aliases: fart

Flags:

      --as string         Custom title for compound proto (proto+proto only)
      --dry-run           Preview what would be created
      --ephemeral         Force spawn as vapor (ephemeral, Ephemeral=true)
      --pour              Force spawn as liquid (persistent, Ephemeral=false)
      --ref string        Custom child reference with {{var}} substitution (e.g., arm-{{polecat_name}})
      --type string       Bond type: sequential, parallel, or conditional (default "sequential")
      --var stringArray   Variable substitution for spawned protos (key=value)

bd mol burn

Burn a molecule, deleting it without creating a digest.

Unlike squash (which creates a permanent digest before deletion), burn completely removes the molecule with no trace. Use this for:

Abandoned patrol cycles
Crashed or failed workflows
Test/debug molecules you don't want to preserve

The burn operation differs based on molecule phase:

Wisp (ephemeral): Direct delete
Mol (persistent): Cascade delete (syncs to remotes)

CAUTION: This is a destructive operation. The molecule's data will be permanently lost. If you want to preserve a summary, use 'bd mol squash'.

Example: bd mol burn bd-abc123 # Delete molecule with no trace bd mol burn bd-abc123 --dry-run # Preview what would be deleted bd mol burn bd-abc123 --force # Skip confirmation bd mol burn bd-a1 bd-b2 bd-c3 # Batch delete multiple wisps

bd mol burn <molecule-id> [molecule-id...] [flags]

Flags:

      --dry-run   Preview what would be deleted
      --force     Skip confirmation prompt

bd mol current

Show where you are in a molecule workflow.

If molecule-id is given, show status for that molecule. If not given, infer from in_progress issues assigned to current agent.

The output shows all steps with status indicators: [done] - Step is complete (closed) [current] - Step is in_progress (you are here) [ready] - Step is ready to start (unblocked) [blocked] - Step is blocked by dependencies [pending] - Step is waiting

For large molecules (>100 steps), a summary is shown instead. Use --limit or --range to view specific steps: bd mol current <id> --limit 50 # Show first 50 steps bd mol current <id> --range 100-150 # Show steps 100-150

bd mol current [molecule-id] [flags]

Flags:

      --for string     Show molecules for a specific agent/assignee
      --limit int      Maximum number of steps to display (0 = auto, use 'all' threshold)
      --range string   Display specific step range (e.g., '1-50', '100-150')

bd mol distill

Distill a molecule by extracting a reusable formula from an existing epic.

This is the reverse of pour: instead of formula → molecule, it's molecule → formula.

The distill command:

Loads the existing epic and all its children
Converts the structure to a .formula.json file
Replaces concrete values with {{variable}} placeholders (via --var flags)

Use cases:

Team develops good workflow organically, wants to reuse it
Capture tribal knowledge as executable templates
Create starting point for similar future work

Variable syntax (both work - we detect which side is the concrete value): --var branch=feature-auth Spawn-style: variable=value (recommended) --var feature-auth=branch Substitution-style: value=variable

Output locations (first writable wins):

<resolved-beads-dir>/formulas/ (project-level, default)
<checkout-root>/.beads/formulas/ (repo-local formulas)
~/.beads/formulas/ (user-level, if project not writable)

Examples: bd mol distill bd-o5xe my-workflow bd mol distill bd-abc release-workflow --var feature_name=auth-refactor

bd mol distill <epic-id> [formula-name] [flags]

Flags:

      --dry-run           Preview what would be created
      --output string     Output directory for formula file
      --var stringArray   Replace value with {{variable}} placeholder (variable=value)

bd mol last-activity

Show the most recent activity timestamp for a molecule.

Returns the timestamp of the most recent change to any step in the molecule, making it easy to detect stale or stuck molecules.

Activity sources: step_closed - A step was closed step_updated - A step was updated (claimed, edited, etc.) molecule_updated - The molecule root itself was updated

Examples: bd mol last-activity hq-wisp-0laki bd mol last-activity hq-wisp-0laki --json

bd mol last-activity <molecule-id>

bd mol pour

Pour a proto into a persistent mol - like pouring molten metal into a mold.

This is the chemistry-inspired command for creating PERSISTENT work from templates. The resulting mol lives in .beads/ (permanent storage) and is synced with git.

Phase transition: Proto (solid) -> pour -> Mol (liquid)

WHEN TO USE POUR vs WISP: pour (liquid): Persistent work that needs audit trail - Feature implementations spanning multiple sessions - Work you may need to reference later - Anything worth preserving in git history

wisp (vapor): Ephemeral work that auto-cleans up - Release workflows (one-time execution) - Operational loops and recurring cycles - Health checks and diagnostics - Any operational workflow without audit value

TIP: Formulas can specify phase:"vapor" to recommend wisp usage. If you pour a vapor-phase formula, you'll get a warning.

Examples: bd mol pour mol-feature --var name=auth # Persistent feature work bd mol pour mol-review --var pr=123 # Persistent code review

bd mol pour <proto-id> [flags]

Flags:

      --assignee string      Assign the root issue to this agent/user
      --attach strings       Proto to attach after spawning (repeatable)
      --attach-type string   Bond type for attachments: sequential, parallel, or conditional (default "sequential")
      --dry-run              Preview what would be created
      --var stringArray      Variable substitution (key=value)

bd mol progress

Show efficient progress summary for a molecule.

This command uses indexed queries to count progress without loading all steps, making it suitable for very large molecules (millions of steps).

If no molecule-id is given, shows progress for any molecule you're working on.

Output includes:

Progress: completed / total (percentage)
Current step: the in-progress step (if any)
Rate: steps/hour based on closure times
ETA: estimated time to completion

Example: bd mol progress bd-hanoi-xyz

bd mol progress [molecule-id]

bd mol ready

Find molecules where a gate has closed and the workflow is ready to resume.

This command discovers molecules waiting at a gate step where:

The molecule has a gate bead that blocks a step
The gate bead is now closed (condition satisfied)
The blocked step is now ready to proceed
No agent currently has this molecule hooked

This enables discovery-based resume without explicit waiter tracking. The patrol system uses this to find and dispatch gate-ready molecules.

Examples: bd mol ready --gated # Find all gate-ready molecules bd mol ready --gated --json # JSON output for automation

bd mol ready --gated

bd mol seed

Verify that a formula is accessible and can be cooked.

The seed command checks formula search paths to ensure a formula exists and can be loaded. This is useful for verifying system health before attempting to spawn work from a formula.

Formula search paths (checked in order):

<resolved-beads-dir>/formulas/ (active project)
<checkout-root>/.beads/formulas/ (repo-local formulas)
~/.beads/formulas/ (user level)
$GT_ROOT/.beads/formulas/ (orchestrator level, if GT_ROOT set)

Examples: bd mol seed mol-feature # Verify specific formula bd mol seed mol-review --var name=test # Verify with variable substitution

bd mol seed <formula-name> [flags]

Flags:

      --var stringArray   Variable substitution for condition filtering (key=value)

bd mol show

Show molecule structure and details.

The --parallel flag highlights parallelizable steps:

Steps with no blocking dependencies can run in parallel
Shows which steps are ready to start now
Identifies parallel groups (steps that can run concurrently)

Example: bd mol show bd-patrol --parallel

bd mol show <molecule-id> [flags]

Flags:

  -p, --parallel   Show parallel step analysis

bd mol squash

Squash a molecule's ephemeral children into a single digest issue.

This command collects all ephemeral child issues of a molecule (Ephemeral=true), generates a summary digest, and promotes the wisps to persistent by clearing their Wisp flag (or optionally deletes them).

The squash operation:

Loads the molecule and all its children
Filters to only wisps (ephemeral issues with Ephemeral=true)
Generates a digest (summary of work done)
Creates a permanent digest issue (Ephemeral=false)
Clears Wisp flag on children (promotes to persistent) OR keeps them with --keep-children (default: delete)

AGENT INTEGRATION: Use --summary to provide an AI-generated summary. This keeps bd as a pure tool - the calling agent (orchestrator worker, Claude Code, etc.) is responsible for generating intelligent summaries. Without --summary, a basic concatenation of child issue content is used.

This is part of the wisp workflow: spawn creates wisps, execution happens, squash compresses the trace into an outcome (digest).

Example: bd mol squash bd-abc123 # Squash and promote children bd mol squash bd-abc123 --dry-run # Preview what would be squashed bd mol squash bd-abc123 --keep-children # Keep wisps after digest bd mol squash bd-abc123 --summary "Agent-generated summary of work done"

bd mol squash <molecule-id> [flags]

Flags:

      --dry-run          Preview what would be squashed
      --keep-children    Don't delete ephemeral children after squash
      --summary string   Agent-provided summary (bypasses auto-generation)

bd mol stale

Detect molecules (epics with children) that are complete but still open.

A molecule is considered stale if:

All children are closed (Completed == Total)
Root issue is still open
Not assigned to anyone (optional, use --unassigned)
Is blocking other work (optional, use --blocking)

By default, shows all complete-but-unclosed molecules.

Examples: bd mol stale # List all stale molecules bd mol stale --json # Machine-readable output bd mol stale --blocking # Only show those blocking other work bd mol stale --unassigned # Only show unassigned molecules bd mol stale --all # Include molecules with 0 children

bd mol stale [flags]

Flags:

      --all          Include molecules with 0 children
      --blocking     Only show molecules blocking other work
      --unassigned   Only show unassigned molecules

bd mol wisp

Create or manage wisps - EPHEMERAL molecules for operational workflows.

When called with a proto-id argument, creates a wisp from that proto. When called with a subcommand (list, gc), manages existing wisps.

Wisps are issues with Ephemeral=true in the main database. They're stored locally but NOT synced via git.

WHEN TO USE WISP vs POUR: wisp (vapor): Ephemeral work that auto-cleans up - Release workflows (one-time execution) - Operational loops and recurring cycles - Health checks and diagnostics - Any operational workflow without audit value

pour (liquid): Persistent work that needs audit trail - Feature implementations spanning multiple sessions - Work you may need to reference later - Anything worth preserving in git history

TIP: Formulas can specify phase:"vapor" to recommend wisp usage. If you use pour on a vapor-phase formula, you'll get a warning.

The wisp lifecycle:

Create: bd mol wisp <proto> or bd create --ephemeral
Execute: Normal bd operations work on wisp issues
Squash: bd mol squash <id> (clears Ephemeral flag, promotes to persistent)
Or burn: bd mol burn <id> (deletes without creating digest)

Examples: bd mol wisp beads-release --var version=1.0 # Release workflow bd mol wisp mol-my-workflow # Ephemeral operational cycle bd mol wisp list # List all wisps bd mol wisp gc # Garbage collect old wisps

Subcommands: list List all wisps in current context gc Garbage collect orphaned wisps

bd mol wisp [proto-id] [flags]

Flags:

      --dry-run           Preview what would be created
      --root-only         Create only the root issue (no child step issues)
      --var stringArray   Variable substitution (key=value)

bd mol wisp create

Create a wisp from a proto - sublimation from solid to vapor.

This is the chemistry-inspired command for creating ephemeral work from templates. The resulting wisp is stored in the main database with Ephemeral=true and NOT synced via git.

Phase transition: Proto (solid) -> Wisp (vapor)

Use wisp for:

Operational loops and recurring cycles
Health checks and monitoring
One-shot orchestration runs
Routine operations with no audit value

The wisp will:

Be stored in main database with Ephemeral=true flag
NOT be synced via git
Either evaporate (burn) or condense to digest (squash)

Examples: bd mol wisp create mol-patrol # Ephemeral patrol cycle bd mol wisp create mol-health-check # One-time health check bd mol wisp create mol-diagnostics --var target=db # Diagnostic run

bd mol wisp create <proto-id> [flags]

Flags:

      --dry-run           Preview what would be created
      --root-only         Create only the root issue (no child step issues)
      --var stringArray   Variable substitution (key=value)

bd mol wisp gc

Garbage collect old or abandoned wisps from the database.

A wisp is considered abandoned if:

It hasn't been updated in --age duration and is not closed

Abandoned wisps are deleted without creating a digest. Use 'bd mol squash' if you want to preserve a summary before garbage collection.

Use --closed to purge ALL closed wisps (regardless of age). This is the fastest way to reclaim space from accumulated wisp bloat. Safe by default: requires --force to actually delete.

Note: This uses time-based cleanup, appropriate for ephemeral wisps. For graph-pressure staleness detection (blocking other work), see 'bd mol stale'.

Examples: bd mol wisp gc # Clean abandoned wisps (default: 1h threshold) bd mol wisp gc --dry-run # Preview what would be cleaned bd mol wisp gc --age 24h # Custom age threshold bd mol wisp gc --all # Also clean closed wisps older than threshold bd mol wisp gc --closed # Preview closed wisp deletion bd mol wisp gc --closed --force # Delete all closed wisps bd mol wisp gc --closed --dry-run # Explicit dry-run (same as no --force) bd mol wisp gc --exclude-type agent,rig # Protect agent and rig wisps from GC bd mol wisp gc --closed --force --exclude-type mol # Delete closed wisps except mol type

bd mol wisp gc [flags]

Flags:

      --age string             Age threshold for abandoned wisp detection (default "1h")
      --all                    Also clean closed wisps older than threshold
      --closed                 Delete all closed wisps (ignores --age threshold)
      --dry-run                Preview what would be cleaned
      --exclude-type strings   Exclude wisps of these types from GC (comma-separated, e.g., agent,rig)
  -f, --force                  Actually delete (default: preview only)

bd mol wisp list

List all wisps (ephemeral molecules) in the current context.

Wisps are issues with Ephemeral=true in the main database. They are stored locally but not synced via git.

The list shows:

ID: Issue ID of the wisp
Title: Wisp title
Status: Current status (open, in_progress, closed)
Started: When the wisp was created
Updated: Last modification time

Old wisp detection:

Old wisps haven't been updated in 24+ hours
Use 'bd mol wisp gc' to clean up old/abandoned wisps

Examples: bd mol wisp list # List all wisps bd mol wisp list --json # JSON output for programmatic use bd mol wisp list --all # Include closed wisps

bd mol wisp list [flags]

Flags:

      --all           Include closed wisps
      --type string   Filter by issue type (e.g., agent, task, patrol)