# Gas Town HQ Design The **HQ** (headquarters) is the top-level directory where Gas Town is installed - the workspace that contains all your rigs, agents, and coordination infrastructure. ## What Is an HQ? Think of HQ as the "mount point" for Gas Town. It's the root directory where: - The Mayor operates from - Rigs are registered and managed - Town-level beads coordinate mail and handoffs - The entire workspace is versioned as a git repository An HQ is NOT: - A git clone of any project (rigs contain the clones) - A hidden directory (it's visible and user-controlled) - Tied to any specific project (it can manage multiple rigs) ## HQ Structure ``` ~/gt/ # HQ ROOT ├── .git/ # HQ is a git repo ├── .gitignore # Generated by gt git-init ├── .beads/ # Town-level beads (hq-* prefix) │ ├── beads.db # Mayor mail, coordination, handoffs │ └── config.yaml # Beads config with prefix: hq │ ├── CLAUDE.md # Mayor role context (runs from here) │ ├── mayor/ # Mayor config and state │ ├── town.json # {"type": "town", "name": "..."} │ ├── rigs.json # Registry of managed rigs │ └── state.json # Mayor state │ ├── rigs/ # Managed rig containers │ ├── gastown/ # A rig (project container) │ └── wyvern/ # Another rig │ └── / # OR rigs at HQ root (legacy) ``` ## Creating an HQ Use `gt install` to create a new HQ: ```bash # Create a new HQ gt install ~/gt # Create with git initialization gt install ~/gt --git # Create and push to GitHub gt install ~/gt --github=username/my-gastown --private # Initialize current directory as HQ gt install . --name my-workspace ``` The install command: 1. Creates the directory structure (`mayor/`, `rigs/`) 2. Writes configuration files (`town.json`, `rigs.json`, `state.json`) 3. Generates `CLAUDE.md` with Mayor role context 4. Initializes town-level beads with `hq-` prefix 5. Optionally initializes git with `.gitignore` ## HQ vs Town vs Rig | Concept | Description | Example | |---------|-------------|---------| | **HQ** | Installation directory | `~/gt/` | | **Town** | Logical workspace (same as HQ) | The Gas Town instance | | **Rig** | Project container within HQ | `~/gt/gastown/` | The terms "HQ" and "town" are often used interchangeably. An HQ IS a town. The distinction is physical (HQ = directory) vs logical (town = workspace concept). ## Beads in an HQ An HQ has **two levels** of beads: ### Town-Level Beads Located at `/.beads/` with `hq-` prefix: - Mayor mail and inbox - Cross-rig coordination messages - Session handoff notes ### Rig-Level Beads Each rig has its own `.beads/` with a project-specific prefix: - Work issues (bugs, features, tasks) - Merge requests - Agent-local mail within the rig The Mayor sees both: town beads for mail, rig beads for work coordination. ## Beads Redirect Pattern In complex setups, you may want the HQ root's `.beads/` to redirect to a rig's beads. This is useful when: - Multiple systems share an HQ - You want a single source of truth for beads - Migration scenarios Create a redirect file: ```bash # Instead of .beads/ directory, create .beads/redirect file mkdir .beads echo "path/to/actual/.beads" > .beads/redirect ``` Example from a real setup: ``` # ~/ai/.beads/redirect # Redirect to gastown beads (Mayor workspace) # The Mayor runs in ~/ai but manages gastown issues in mayor/rigs/gastown mayor/rigs/gastown/.beads ``` **When to use redirects:** - When rig beads should be the canonical town beads - Hybrid setups where agents work in different locations ## HQ Configuration Files ### mayor/town.json Identifies this as a Gas Town installation: ```json { "type": "town", "version": 1, "name": "stevey-gastown", "created_at": "2024-01-15T10:30:00Z" } ``` ### mayor/rigs.json Registry of managed rigs: ```json { "version": 1, "rigs": { "gastown": { "git_url": "https://github.com/steveyegge/gastown", "added_at": "2024-01-15T10:30:00Z" }, "wyvern": { "git_url": "https://github.com/steveyegge/wyvern", "added_at": "2024-01-16T09:00:00Z" } } } ``` ### mayor/state.json Mayor agent state: ```json { "role": "mayor", "last_active": "2024-01-17T14:30:00Z" } ``` ## Git for HQs An HQ should be a git repository. This enables: - Versioning of configuration - Beads sync across machines - Session handoff via beads commits - Recovery after failures ### Initialize git ```bash gt git-init # Basic git setup gt git-init --github=user/repo # Create GitHub repo gt git-init --github=user/repo --private # Private repo ``` ### Standard .gitignore The `gt git-init` command creates: ```gitignore # Gas Town HQ gitignore # Agent sessions and logs *.log *.pid /sessions/ # Rig working directories (managed separately) /rigs/*/polecats/*/ /rigs/*/refinery/rig/ /rigs/*/crew/*/ # Sensitive files .env *.key *.pem credentials.json # Editor and OS .DS_Store *.swp *~ .idea/ .vscode/ # Beads daemon .beads/beads.sock .beads/*.pid ``` ## HQ Health Checks Run `gt doctor` to check HQ health: ```bash gt doctor # Check all gt doctor --fix # Auto-fix issues ``` Checks include: - Configuration file validity - Mayor state consistency - Rig registry accuracy - Beads database health - Git state cleanliness ## HQ Templates For organizations wanting consistent Gas Town setups, create a template repository: ```bash # Create template HQ gt install ~/gt-template --git --no-beads # Customize CLAUDE.md, add standard rigs # Push to GitHub as template repo # Users clone template gh repo create my-gastown --template org/gt-template cd my-gastown gt install . --force # Reinitialize with fresh beads ``` ## Migration Between HQs To move Gas Town to a new location: 1. **Export beads state:** ```bash bd export > beads-backup.jsonl ``` 2. **Create new HQ:** ```bash gt install ~/new-hq --git ``` 3. **Add rigs:** ```bash cd ~/new-hq gt rig add gastown https://github.com/user/gastown ``` 4. **Import beads:** ```bash cd ~/new-hq bd import < beads-backup.jsonl ``` ## Summary | Action | Command | |--------|---------| | Create HQ | `gt install ` | | Initialize git | `gt git-init` | | Add rig | `gt rig add ` | | Check health | `gt doctor` | | View status | `gt status` |