> ## Documentation Index > Fetch the complete documentation index at: https://beads.gascity.com/llms.txt > Use this file to discover all available pages before exploring further. # bd mol > Molecule commands (work templates) 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 [command] ``` **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 [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...] [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 \ --limit 50 # Show first 50 steps bd mol current \ --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: 1. Loads the existing epic and all its children 2. Converts the structure to a .formula.json file 3. 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): 1. \/formulas/ (project-level, default) 2. \/.beads/formulas/ (repo-local formulas) 3. \~/.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 [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 [flags] ``` ## 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 is stored as persistent beads in the issue database and syncs like any other bead (bd dolt push / pull). 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 [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] [flags] ``` ## 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: 1. The molecule has a gate bead that blocks a step 2. The gate bead is now closed (condition satisfied) 3. The blocked step is now ready to proceed 4. 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 [flags] ``` **Flags:** ``` --gated Find molecules ready for gate-resume dispatch (always on for this subcommand) ``` ## 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): 1. \/formulas/ (active project) 2. \/.beads/formulas/ (repo-local formulas) 3. \~/.beads/formulas/ (user level) 4. \$GT\_ROOT/.beads/formulas/ (shared workspace root, 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 [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 [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: 1. Loads the molecule and all its children 2. Filters to only wisps (ephemeral issues with Ephemeral=true) 3. Generates a digest (summary of work done) 4. Creates a permanent digest issue (Ephemeral=false) 5. 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 [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: 1. All children are closed (Completed == Total) 2. Root issue is still open 3. Not assigned to anyone (optional, use --unassigned) 4. 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: 1. Create: bd mol wisp \ or bd create --ephemeral 2. Execute: Normal bd operations work on wisp issues 3. Squash: bd mol squash \ (clears Ephemeral flag, promotes to persistent) 4. Or burn: bd mol burn \ (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] bd mol wisp [command] ``` **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 [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) ```