# How Rig-Level Beads Are Organized and Prefixed in Gas Town

> Discover how Gas Town organizes rig level beads using configurable prefixes defined in rigs.json. Learn about namespaces isolation and work history.

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

---

**In Gas Town, each rig isolates its issues, mail, and work history in a beads namespace defined by a configurable prefix stored in [`rigs.json`](https://github.com/gastownhall/gastown/blob/main/rigs.json), which defaults to the rig name itself when omitted.**

Rig-level beads in the gastownhall/gastown repository provide isolated workspaces for every logical workstation, from developer laptops to CI runners. Each rig owns a dedicated **beads namespace** that prevents name collisions across machines while maintaining a unified global store. The organization hinges on a **beads prefix** defined in the central configuration file, which determines how bead IDs and tmux sessions are constructed for that specific rig.

## The Beads Prefix Configuration in rigs.json

The prefix is defined in [`rigs.json`](https://github.com/gastownhall/gastown/blob/main/rigs.json) at the repository root. Each rig entry contains a `beads` object with an optional `prefix` field. If omitted, the system uses the rig name itself as the prefix according to the gastownhall/gastown source code.

Example from the stuck-agent-dog test harness:

```json
{
  "gastown": {
    "beads": { "prefix": "gt" }
  }
}

```

*(Source: [`plugins/stuck-agent-dog/run_test.sh`](https://github.com/gastownhall/gastown/blob/main/plugins/stuck-agent-dog/run_test.sh), line 239)*

## How the Prefix Is Applied in Practice

When a **polecat** (agent) initializes a bead, it constructs session names and database IDs using the pattern `<prefix>-<rig>`. This convention appears in the plugin documentation:

```bash
SESSION_NAME="${BEADS_PREFIX}-${RIG}"

```

*(Source: [`plugins/stuck-agent-dog/plugin.md`](https://github.com/gastownhall/gastown/blob/main/plugins/stuck-agent-dog/plugin.md), line 70)*

The same prefix appears in the Git-backed beads database (Dolt repo), ensuring every bead ID carries its origin rig's namespace. This prevents collisions when multiple rigs run identical polecat code, yet allows global queries across all rigs using the unified naming convention.

## Fallback Resolution for rigs.json

If the runtime configuration is missing at `$TOWN_ROOT/rigs.json`, Gas Town falls back to `$TOWN_ROOT/mayor/rigs.json`. This preserves backward compatibility with older repository layouts while maintaining the prefix resolution logic.

*(Source: [`plugins/stuck-agent-dog/plugin.md`](https://github.com/gastownhall/gastown/blob/main/plugins/stuck-agent-dog/plugin.md), lines 63-66)*

## Practical Implementation Examples

### Reading the Prefix for the Current Rig

```bash

# Load the registry

RIGS_JSON="${TOWN_ROOT}/rigs.json"

# Extract the prefix (jq required)

PREFIX=$(jq -r ".${RIG}.beads.prefix // .${RIG}" "$RIGS_JSON")
echo "Beads prefix for $RIG is $PREFIX"

```

### Creating a Bead with Proper Namespacing

```bash

# Assume RIG=gastown, PREFIX=gt

BEAD_TITLE="Fix-database-leak"

# The bead ID will be prefixed automatically by the bd create script

bd create --title "$BEAD_TITLE" --type task --rig "$RIG"

# Internally the bead is stored as gt-gastown-<unique-hash>

```

### Naming tmux Sessions for Polecats

```bash
SESSION="${PREFIX}-${RIG}"
tmux new-session -d -s "$SESSION"
echo "Session $SESSION now hosts the polecat for bead $BEAD_ID"

```

### Resolving a Bead's Origin from Its ID

```bash

# $BEAD_ID looks like gt-gastown-123abc

IFS='-' read -r PREFIX RIG _ <<< "$BEAD_ID"
echo "Bead $BEAD_ID belongs to rig $RIG with prefix $PREFIX"

```

## Summary

- Each rig in Gas Town owns an isolated **beads namespace** controlled by a configurable prefix in [`rigs.json`](https://github.com/gastownhall/gastown/blob/main/rigs.json).
- The prefix defaults to the rig name when not explicitly specified, ensuring consistent namespacing.
- Agent scripts and **polecats** use the `<prefix>-<rig>` pattern to construct tmux session names and bead IDs.
- The system falls back to `$TOWN_ROOT/mayor/rigs.json` if the primary configuration file is missing.
- This architecture prevents name collisions across multiple workstations while supporting global queries against the unified beads database.

## Frequently Asked Questions

### What is the default beads prefix if I don't specify one in rigs.json?

If the `beads.prefix` field is omitted for a rig entry in [`rigs.json`](https://github.com/gastownhall/gastown/blob/main/rigs.json), Gas Town automatically uses the rig name itself as the prefix. For example, a rig named "workstation1" would use "workstation1" as its prefix for all bead IDs and session names.

### How does Gas Town prevent bead ID collisions between different developer machines?

Each rig maintains its own beads namespace through the prefix system. When a bead is created, its ID is prefixed with `<prefix>-<rig>`, ensuring that identical bead names on different machines produce unique global identifiers in the Dolt-backed beads database.

### Where does Gas Town look for the rigs.json configuration file?

The system first attempts to read `$TOWN_ROOT/rigs.json`. If this file does not exist, it automatically falls back to `$TOWN_ROOT/mayor/rigs.json`, maintaining compatibility with older repository layouts while preserving the prefix configuration.

### Can I change the beads prefix for an existing rig without breaking existing bead references?

Changing the prefix for an active rig would alter the namespace for new beads and sessions, but existing bead IDs in the database retain their original prefixed names. You would need to migrate or update existing references to maintain consistency with the new prefix convention.