# Understanding the Two-Level Beads System in Gas Town

> Discover the two-level beads system in Gas Town. Isolate coordination and project work, enable fast messaging, and maintain global state. Learn how it works.

- Repository: [Gas Town Hall/gastown](https://github.com/gastownhall/gastown)
- Tags: deep-dive
- Published: 2026-07-07

---

**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:

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

```

Debug the routing resolution for a rig-level bead:

```bash
BD_DEBUG_ROUTING=1 bd show gt-abc

```

Inspect a worktree's redirect file:

```bash
cat polecats/alpha/.beads/redirect

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

```

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

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

```

## Key Source Files

- [`docs/design/architecture.md`](https://github.com/gastownhall/gastown/blob/main/docs/design/architecture.md) – Complete description of the two-level model, routing logic, and storage architecture.
- [`internal/beads/beads.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/beads.go) – Core implementation of bead-type structures and helper functions.
- [`internal/beads/beads_rig.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/beads_rig.go) – Logic that resolves rig-level bead IDs and interacts with the routing table.
- [`internal/beads/beads_redirect.go`](https://github.com/gastownhall/gastown/blob/main/internal/beads/beads_redirect.go) – Handles `.beads/redirect` resolution and circular-reference safety.
- [`internal/doctor/beads_check.go`](https://github.com/gastownhall/gastown/blob/main/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.