gastown/docs/harness.md

Gas Town Harness

A harness is a Gas Town installation directory - the top-level workspace where all Gas Town components live.

GGT Harness Location

The Go implementation of Gas Town (GGT) uses a separate harness from the Python implementation (PGT):

Implementation	Harness Location	Status
GGT (Go)	~/gt/	Active, canonical
PGT (Python)	~/ai/	Legacy, reference only

Harness Structure

A properly configured GGT harness looks like:

~/gt/                              # HARNESS ROOT
├── CLAUDE.md                      # Mayor role prompting
├── .beads/                        # Town-level beads (gm-* prefix)
│   ├── beads.db                   # Mayor mail, coordination
│   └── config.yaml
│
├── mayor/                         # Mayor's HOME at town level
│   ├── town.json                  # {"type": "town", "name": "..."}
│   ├── rigs.json                  # Registry of managed rigs
│   └── state.json
│
├── gastown/                       # A rig (project container)
│   ├── config.json
│   ├── .beads/ → mayor/rig/.beads # Symlink to canonical beads
│   ├── mayor/rig/                 # Mayor's clone (beads authority)
│   ├── refinery/rig/              # Refinery's clone
│   ├── witness/                   # Witness agent
│   ├── crew/                      # Overseer workspaces
│   └── polecats/                  # Worker directories
│
└── wyvern/                        # Another rig (same structure)

Key Directories

Town Level (~/gt/)

• CLAUDE.md: Mayor role prompting, loaded when Mayor starts
• .beads/: Town-level beads database (prefix: gm-)
  • Contains Mayor mail and cross-rig coordination beads
• mayor/: Mayor's home directory with town configuration

Rig Level (~/gt/<rig>/)

Each rig is a container directory (NOT a git clone) that holds:

• config.json: Rig configuration (git_url, beads prefix)
• .beads/: Symlink to mayor/rig/.beads (canonical beads)
• mayor/rig/: Mayor's git clone, canonical for beads and worktrees
• refinery/rig/: Refinery's clone for merge operations
• witness/: Witness agent state
• crew/: Overseer's personal workspaces
• polecats/: Worker directories (git worktrees)

Historical Context: PGT/GGT Separation

During initial GGT development, both implementations briefly shared ~/ai/:

~/ai/ (legacy mixed harness - DO NOT USE for GGT)
├── gastown/
│   ├── .gastown/          # PGT marker
│   └── mayor/             # OLD GGT clone (deprecated)
├── mayor/                 # PGT Mayor home
└── .beads/redirect        # OLD redirect (deprecated)

This caused confusion because:

• ~/ai/gastown/ contained both PGT markers AND GGT code
• ~/ai/mayor/ was PGT's Mayor home, conflicting with GGT concepts
• The beads redirect pointed at GGT beads from a PGT harness

The separation was completed by creating ~/gt/ as the dedicated GGT harness.

Cleanup Steps for ~/ai/

If you have the legacy mixed harness, clean it up:

# Remove old GGT clone (beads are no longer here)
rm -rf ~/ai/gastown/mayor/

# Remove old beads redirect
rm ~/ai/.beads/redirect

# Keep PGT-specific files:
# - ~/ai/mayor/ (PGT Mayor home)
# - ~/ai/gastown/.gastown/ (PGT marker)

Creating a New Harness

To create a fresh GGT harness:

gt install ~/my-harness

This creates:

• Town-level directories and configuration
• Town-level beads database
• CLAUDE.md for Mayor role

Then add rigs:

cd ~/my-harness
gt rig add myproject https://github.com/user/myproject

Environment Variables

When spawning agents, Gas Town sets:

Variable	Purpose	Example
BEADS_DIR	Point to rig's beads	/path/to/rig/.beads
BEADS_NO_DAEMON	Disable daemon for worktrees	1

See Also

• Architecture - Full system design
• Federation Design - Remote outposts