Understanding the Two-Level Beads System in Gas Town

The two-level beads system in Gas Town isolates organizational coordination from project-specific work by storing issue-tracking objects at both town-wide and rig-specific scopes, enabling fast cross-rig messaging while maintaining consistent global state.

The gastownhall/gastown repository implements a unique two-level beads system that separates global town operations from individual project workflows. This architecture stores beads—issue-tracking objects—at distinct scopes to ensure agents can exchange messages and manage town-wide operations without polluting project-specific issue spaces.

Architecture of the Two-Level Beads System

Town-Level Beads (Global Scope)

Town-level beads reside in ~/gt/.beads/ and use the hq-* prefix (e.g., hq-mayor, hq-deacon). These beads contain global coordination objects such as the Mayor, Deacon, role definitions, Convoy batch jobs, and town-wide escalation routes. Because this directory sits at the town root, every rig in the town can access these beads for cross-rig communication and global state management.

Rig-Level Beads (Project Scope)

Rig-level beads live in <rig>/mayor/rig/.beads/ and use project-specific prefixes such as gt-* or bd-*. These beads track implementation work for a single rig—bugs, merge requests, and per-project molecules. This isolation ensures that project-specific issues remain separate from global coordination concerns while still remaining accessible via the unified routing system.

Design Rationale for Two-Level Separation

Separation of Concerns

The two-level design enforces strict separation between global and local concerns. Town-level beads hold objects like hq-mayor and hq-deacon that manage cross-rig coordination, allowing agents to exchange messages and manage escalation routes without cluttering project-specific issue spaces. Rig-level beads contain only project-specific work, keeping implementation details isolated from town-wide operations.

Scalable Routing via routes.jsonl

The routing layer uses a routes.jsonl file located in the town root (~/gt/.beads/routes.jsonl) to map each prefix to the appropriate rig directory. When a command like bd show gt-xyz executes from anywhere in the town, the system automatically resolves the prefix and redirects the request to the canonical rig-level beads directory (<rig>/mayor/rig/.beads). Set BD_DEBUG_ROUTING=1 to verify the resolved path during debugging.

Shared Storage Layer

All beads persist in a single Dolt SQL Server per town located at ~/gt/.dolt-data/. Because both town-level and rig-level beads use this shared storage, updates become instantly visible across all agents without requiring per-rig git clones of the bead database. This centralized approach eliminates synchronization delays while maintaining data consistency across the entire town.

Redirect-Based Worktrees

Rig worktrees (Polecats, Refinery, Crew) do not contain their own .beads directories. Instead, they contain a .beads/redirect file that points back to the canonical location (../../mayor/rig/.beads). The resolver follows this redirect chain (maximum depth of 3) to guarantee that every agent in a rig shares the same bead view, ensuring consistency across worktrees without duplicating the database.

Implementation Examples

Create a town-level bead for global coordination:

bd create --type=issue --title="Upgrade City-wide Dolt schema" \
    --prefix=hq- --agent=mayor

Debug the routing resolution for a rig-level bead:

BD_DEBUG_ROUTING=1 bd show gt-abc

Inspect a worktree's redirect file:

cat polecats/alpha/.beads/redirect

# Output: ../../mayor/rig/.beads

Configure the routing table in ~/gt/.beads/routes.jsonl:

{"prefix":"hq-","path":"."}
{"prefix":"gt-","path":"gastown/mayor/rig"}
{"prefix":"bd-","path":"beads/mayor/rig"}

Key Source Files

• docs/design/architecture.md – Complete description of the two-level model, routing logic, and storage architecture.
• internal/beads/beads.go – Core implementation of bead-type structures and helper functions.
• internal/beads/beads_rig.go – Logic that resolves rig-level bead IDs and interacts with the routing table.
• internal/beads/beads_redirect.go – Handles .beads/redirect resolution and circular-reference safety.
• internal/doctor/beads_check.go – Health check validation for town-level and rig-level bead integrity.

Summary

• The two-level beads system separates global coordination (hq-* prefixes) from project work (gt-*, bd-* prefixes) to maintain clean separation of concerns.
• Town-level beads reside in ~/gt/.beads/ while rig-level beads live in <rig>/mayor/rig/.beads/, with both using the same Dolt SQL Server at ~/gt/.dolt-data/.
• The routes.jsonl file enables automatic prefix-based routing across the entire town, allowing commands to resolve correctly regardless of the current working directory.
• Worktrees use .beads/redirect files to share canonical bead databases without duplication, ensuring all agents maintain a consistent view of project state.

Frequently Asked Questions

What is the difference between town-level and rig-level beads?

Town-level beads use the hq-* prefix and store global coordination objects such as the Mayor, Deacon, and role definitions that are visible to every rig. Rig-level beads use project-specific prefixes like gt-* or bd-* and contain implementation work such as bugs and merge requests isolated to individual projects.

How does Gas Town route bead queries to the correct location?

The system reads .beads/routes.jsonl in the town root to map prefixes to rig directories, automatically redirecting commands like bd show gt-xyz to the appropriate <rig>/mayor/rig/.beads path. Setting the BD_DEBUG_ROUTING environment variable displays the resolved path for debugging purposes.

Why don't worktrees contain their own bead databases?

Worktrees use .beads/redirect files that point back to the canonical location (../../mayor/rig/.beads) to ensure all agents in a rig share the same bead view. This design eliminates the need for separate database instances while maintaining consistency across different worktrees like Polecats, Refinery, and Crew.

Where are beads actually stored in the Gas Town architecture?

All beads persist in a single Dolt SQL Server per town located at ~/gt/.dolt-data/, with both town-level beads (in ~/gt/.beads/) and rig-level beads (in <rig>/mayor/rig/.beads/) accessing this shared storage layer for instant visibility across agents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}