Gas Town

https://gastown.dev/
Admin
Gas Town is a workspace manager that lets you coordinate multiple coding agents working on different...
Tokens:142,399
Snippets:656
Trust Score:2.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### End-to-End Setup Guide

Source: https://gastown.dev/docs/proxy-server

Provides a step-by-step guide for setting up the gt-proxy server and client, including issuing certificates and installing the client binary.

```APIDOC
## End-to-End Setup

### Step 1: Start the server on the host

```bash
# Installs the CA on first run
gt-proxy-server --listen 0.0.0.0:9876

# The CA cert is now at ~/gt/.runtime/ca/ca.crt
```

### Step 2: Issue a polecat certificate

Use the Go API or a helper tool:

```go
ca, _ := proxy.LoadOrGenerateCA("~/gt/.runtime/ca")
certPEM, keyPEM, _ := ca.IssuePolecat("gt-MyRig-rust", 365*24*time.Hour)
```

Save the output files:

```
~/gt/.runtime/polecats/rust/
  polecat.crt   ← client certificate for this polecat
  polecat.key   ← client private key for this polecat
```

### Step 3: Install the client binary in the container

**Option A: Copy the binary twice**

```bash
cp gt-proxy-client /usr/local/bin/gt
cp gt-proxy-client /usr/local/bin/bd
```

**Option B: Copy once and symlink**

```bash
cp gt-proxy-client /usr/local/bin/gt-proxy-client
ln -s gt-proxy-client /usr/local/bin/gt
ln -s gt-proxy-client /usr/local/bin/bd
```

**If the real `gt` binary should be accessible as a fallback:**

```bash
mv /usr/local/bin/gt.original /usr/local/bin/gt.real
```

```

--------------------------------

### Run Hooks Install

Source: https://gastown.dev/docs/design/agent-api-inventory

Installs hooks from a registry into worktrees by loading, merging, and writing settings.json. Requires Go.

```go
func runHooksInstall() {
  // ... implementation details ...
}
```

```go
func installHookTo(path string) {
  // ... implementation details ...
}
```

--------------------------------

### Start Gas Town Proxy Server

Source: https://gastown.dev/docs/proxy-server

Example command to initialize the proxy server with specific network, CA, and command allowlist configurations.

```shell
gt-proxy-server \
  --listen 0.0.0.0:9876 \
  --ca-dir ~/gt/.runtime/ca \
  --allowed-cmds gt,bd \
  --town-root ~/gt
```

--------------------------------

### Initialize and Start Gas Town Services

Source: https://gastown.dev/docs/INSTALLING

Enables Gas Town system-wide, initializes a Git repository for the HQ, and starts all associated services. This is a crucial step for running Gas Town and its agents.

```shell
cd ~/gt

gt enable              # enable Gas Town system-wide
gt git-init            # initialize a git repo for your HQ
gt up                  # Start all services. Use gt down or gt shutdown for stopping.
```

--------------------------------

### Daytona Devcontainer Setup Script

Source: https://gastown.dev/docs/design/sandboxed-polecat-execution

Shell script to set up the devcontainer environment by installing Node.js tools, the `gt` proxy client, and Git.

```shell
set -e  
npm install -g @anthropic-ai/claude-code  
curl -fsSL https://releases.gastown.dev/gt-proxy-client/latest/linux-amd64 -o /usr/local/bin/gt  
chmod +x /usr/local/bin/gt  
ln -sf /usr/local/bin/gt /usr/local/bin/bd  
apt-get install -y git  
```

--------------------------------

### Quick Start: Manage Convoys

Source: https://gastown.dev/docs/concepts/convoy

Provides essential commands for creating, checking status, and listing convoys. Useful for quickly getting started with convoy tracking.

```bash
# Create a convoy tracking some issues
gt convoy create "Feature X" gt-abc gt-def --notify overseer

# Check progress
gt convoy status hq-cv-abc

# List active convoys (the dashboard)
gt convoy list

# See all convoys including landed ones
gt convoy list --all
```

--------------------------------

### Testing Agent Launch via CLI

Source: https://gastown.dev/docs/agent-provider-integration

Demonstrates how to configure and start an agent using the Gas Town CLI. These commands verify that the agent is correctly registered and capable of handling prime content and nudges.

```bash
# Set your agent as default for a rig
gt config set agent your-agent --rig <rigname>

# Or test with a one-off override
gt crew start jack --agent your-agent
```

--------------------------------

### Install Proxy Client Binary

Source: https://gastown.dev/docs/proxy-server

Provides instructions for installing the proxy client binary into a container, including symlinking and setting up the fallback path for the original binary.

```bash
# Option A: Copy the binary twice
cp gt-proxy-client /usr/local/bin/gt
cp gt-proxy-client /usr/local/bin/bd

# Option B: Copy once and symlink
cp gt-proxy-client /usr/local/bin/gt-proxy-client
ln -s gt-proxy-client /usr/local/bin/gt
ln -s gt-proxy-client /usr/local/bin/bd

# If the real gt binary should be accessible as a fallback:
mv /usr/local/bin/gt.original /usr/local/bin/gt.real
```

--------------------------------

### Install Beads CLI using Go

Source: https://gastown.dev/docs/INSTALLING

Installs the Beads CLI tool, which is an issue tracker, using the Go programming language's install command. Ensure Go is installed and your GOPATH/bin is in your PATH.

```go
go install github.com/steveyegge/beads/cmd/bd@latest
```

--------------------------------

### Startup Command Wrapping Examples

Source: https://gastown.dev/docs/design/sandboxed-polecat-execution

Demonstrates how the ExecWrapper field in RuntimeConfig modifies startup commands for different environments like local, exitbox, and daytona.

```shell
# Local (no wrapper):  
exec env GT_RIG=gastown GT_POLECAT=furiosa ... claude --mode=direct  
  
# exitbox:  
exec env GT_RIG=gastown GT_POLECAT=furiosa ... \  
    exitbox run --profile=gastown-polecat -- claude --mode=direct  
  
# daytona:  
exec env GT_RIG=gastown GT_POLECAT=furiosa ... \  
    daytona exec furiosa-ws -- claude --mode=direct  

```

--------------------------------

### Agent Preset Configuration Example (JSON)

Source: https://gastown.dev/docs/agent-provider-integration

An example JSON configuration for the 'kiro' agent preset. This demonstrates the structure and common fields used to define an agent's behavior, including its command, arguments, environment variables, and non-interactive settings.

```json
{
  "version": 1,
  "agents": {
    "kiro": {
      "name": "kiro",
      "command": "kiro",
      "args": ["--autonomous"],
      "process_names": ["kiro", "node"],
      "session_id_env": "KIRO_SESSION_ID",
      "resume_flag": "--resume",
      "resume_style": "flag",
      "prompt_mode": "arg",
      "ready_prompt_prefix": "> ",
      "ready_delay_ms": 5000,
      "instructions_file": "AGENTS.md",
      "non_interactive": {
        "prompt_flag": "-p",
        "output_flag": "--json"
      }
    }
  }
}
```

--------------------------------

### Install Gas Town Proxy Binaries

Source: https://gastown.dev/docs/proxy-server

Commands to build and install the proxy server and client binaries from the Gas Town repository using Go.

```shell
go install github.com/steveyegge/gastown/cmd/gt-proxy-server@latest
go install github.com/steveyegge/gastown/cmd/gt-proxy-client@latest
```

--------------------------------

### Rig Settings Configuration Example (JSON)

Source: https://gastown.dev/docs/agent-provider-integration

Example JSON for configuring a specific rig to use the 'kiro' agent. This file is typically located in `~/gt/<rig>/settings/config.json` and specifies which agent to use for that rig.

```json
{
  "type": "rig-settings",
  "version": 1,
  "agent": "kiro"
}
```

--------------------------------

### Install Gas Town CLI using Go

Source: https://gastown.dev/docs/INSTALLING

Installs the Gas Town CLI tool, a multi-agent orchestrator, using the Go programming language's install command. Ensure Go is installed and your GOPATH/bin is in your PATH.

```go
go install github.com/steveyegge/gastown/cmd/gt@latest
```

--------------------------------

### gt-proxy-server POST /v1/exec API Example

Source: https://gastown.dev/docs/design/sandboxed-polecat-execution

Shows an example of a POST request to the /v1/exec endpoint of the gt-proxy-server, including the request body and a sample response.

```json
POST /v1/exec  
  body:     {"argv": ["gt", "mail", "inbox", "--json"]}  
  response: {"stdout": "...", "stderr": "...", "exitCode": 0}  

```

--------------------------------

### Verify Telemetry Setup

Source: https://gastown.dev/docs/design/otel/otel-architecture

Run the 'gt prime' command and check for a 'prime' event in the configured backend.

```bash
gt prime
```

--------------------------------

### Workflow B Example

Source: https://gastown.dev/docs/design/convoy/roadmap

Illustrates the sequence of commands and expected outcomes for Workflow B, from design to epic closure.

```bash
/design-to-beads PRD.md
gt convoy stage <root-epic-id>
→ see tree view + wave view
→ see warnings (missing integration branch, parked rigs, etc.)
gt convoy launch <convoy-id>
→ Wave 1 tasks dispatched automatically
→ subsequent waves fed by daemon as tasks close
→ epic statuses update as children progress
→ convoy closes when root epic closes
```

--------------------------------

### Record Session Start Event

Source: https://gastown.dev/docs/design/otel/otel-architecture

Records the start of a new session, marking the beginning of a user interaction or process.

```go
RecordSessionStart / session.start event
```

--------------------------------

### Install Required Packages with APT (Debian/Ubuntu)

Source: https://gastown.dev/docs/INSTALLING

Installs Git using the APT package manager on Debian/Ubuntu systems. It also includes steps for installing Go from a downloaded tarball, which is recommended over the potentially outdated APT version, and optionally installs tmux.

```shell
# Required  
sudo apt update  
sudo apt install -y git  

# Install Go (apt version may be outdated, use official installer)  
wget https://go.dev/dl/go1.24.12.linux-amd64.tar.gz  
sudo rm -rf /usr/local/go && sudo tar -C /usr/local -xzf go1.24.12.linux-amd64.tar.gz  
echo 'export PATH=$PATH:/usr/local/go/bin:$HOME/go/bin' >> ~/.bashrc  
source ~/.bashrc  

# Install Dolt: see https://github.com/dolthub/dolt?tab=readme-ov-file#installation  

# Optional (for full stack mode)  
sudo apt install -y tmux  
```

--------------------------------

### Initialize Telemetry Instruments

Source: https://gastown.dev/docs/design/otel/otel-architecture

Initializes all necessary telemetry instruments. This function is called once during telemetry setup.

```go
initInstruments() -- all instruments initialized here
```

--------------------------------

### Query Example for Run ID Correlation

Source: https://gastown.dev/docs/design/otel/otel-architecture

This query example demonstrates how to retrieve all events for a single session run using the 'run.id' field, which is correlated via the GT_RUN environment variable.

```text
run.id:uuid-1234
```

--------------------------------

### Verify Gas Town Prerequisites

Source: https://gastown.dev/docs/INSTALLING

Checks the installed versions of key prerequisites for Gas Town, including Go, Git, Dolt, and optionally tmux. This command helps ensure that all dependencies meet the minimum version requirements.

```shell
# Check all prerequisites  
go version        # Should show go1.24 or higher  
git --version     # Should show 2.20 or higher  
dolt version      # Should show 1.82.4 or higher  
tmux -V           # (Optional) Should show 3.0 or higher  
```

--------------------------------

### GET /v1/git/<rig>/info/refs

Source: https://gastown.dev/docs/proxy-server

Retrieves the Git smart-HTTP capability advertisement for a specific repository rig.

```APIDOC
## GET /v1/git/<rig>/info/refs

### Description
Fetches the git capability advertisement (pkt-line) for the specified repository rig.

### Method
GET

### Endpoint
/v1/git/<rig>/info/refs?service=<svc>

### Parameters
#### Path Parameters
- **rig** (string) - Required - The name of the repository rig.

#### Query Parameters
- **service** (string) - Required - The git service type (e.g., git-receive-pack, git-upload-pack).

### Response
#### Success Response (200)
- **body** (stream) - The pkt-line formatted capability advertisement.
```

--------------------------------

### Restart Rigs with Cleanup

Source: https://gastown.dev/docs/CLEANUP

Use `gt rig restart <rig>...` to stop and then start one or more rigs. The stop phase of this operation includes cleanup.

```bash
gt rig restart <rig>...
```

--------------------------------

### Daytona Devcontainer Configuration

Source: https://gastown.dev/docs/design/sandboxed-polecat-execution

Defines the devcontainer setup for a Gastown Polecat, including the image and an onCreateCommand script for installing necessary tools.

```json
{
  "name": "GasTown Polecat",
  "image": "ubuntu:24.04",
  "onCreateCommand": "bash .devcontainer/gastown-polecat/setup.sh",
  "remoteUser": "vscode"
}
```

--------------------------------

### Implement Dual-Signal and Self-Transition

Source: https://gastown.dev/docs/design/polecat-self-managed-completion

Code snippets for the migration phases, demonstrating the transition from witness-based notifications to direct refinery nudges.

```go
// Phase 1: gt done sends BOTH signals
nudgeWitness(rigName, fmt.Sprintf("POLECAT_DONE %s", name))
nudgeRefinery(rigName, fmt.Sprintf("MERGE_READY %s", mrID)) // NEW
```

```go
// Phase 2: gt done: self-manage
setAgentState(agentBeadID, "idle")
nudgeRefinery(rigName, fmt.Sprintf("MERGE_READY %s", mrID))
// Witness nudge: optional, for observability only
```

--------------------------------

### Full Provisioning Sequence with gt sling

Source: https://gastown.dev/docs/design/sandboxed-polecat-execution

This sequence outlines the steps for provisioning a workspace using `gt sling`. Step 3 is the longest, while steps 1-2 are instantaneous. For production, workspaces can be pre-provisioned, changing step 3 to `daytona start`.

```bash
gt sling <bead> --daytona  
  │  
  ├─ 1. Create polecat branch (host, instant):  
  │       git -C ~/gt/<rig>/.repo.git fetch origin  
  │       git -C ~/gt/<rig>/.repo.git branch polecat/<name>-<ts> origin/main  
  │  
  ├─ 2. Issue polecat mTLS cert (host, instant)  
  │  
  ├─ 3. Provision daytona workspace (slow: 30–120s):  
  │       daytona create https://<host>:9876/v1/git/<rig>  
  │         --name gt-<rig>-<polecat>  
  │         --branch polecat/<name>-<ts>  
  │         --devcontainer-path .devcontainer/gastown-polecat  
  │       (clones from proxy → .repo.git; runs onCreateCommand)  
  │  
  ├─ 4. Inject cert into workspace:  
  │       daytona exec gt-<rig>-<polecat> -- mkdir -p /run/gt-proxy  
  │       daytona exec gt-<rig>-<polecat> -- tee /run/gt-proxy/client.crt < <cert>  
  │       daytona exec gt-<rig>-<polecat> -- tee /run/gt-proxy/client.key < <key>  
  │       daytona exec gt-<rig>-<polecat> -- tee /run/gt-proxy/ca.crt < <ca>  
  │  
  ├─ 5. Post-create setup:  
  │       daytona exec gt-<rig>-<polecat> -- gt prime --write-prime-md  
  │       daytona exec gt-<rig>-<polecat> -- [overlay files, setup hooks]  
  │  
  ├─ 6. Register agent bead via proxy:  
  │       (proxy client calls bd create/update with state=spawning)  
  │  
  └─ 7. Start tmux pane:  
          tmux new-window -n <polecat>  
          tmux send-keys "daytona exec gt-<rig>-<polecat> \  
            --env GT_RIG=<rig> --env GT_POLECAT=<name> \  
            --env GT_PROXY_URL=... --env GT_PROXY_CERT=... \  
            --env GT_PROXY_KEY=... --env GIT_SSL_CERT=... \  
            --env GIT_SSL_KEY=... --env GIT_SSL_CAINFO=... \  
            -- claude --mode=direct" Enter  
```

--------------------------------

### Town Settings Default Agent Configuration Example (JSON)

Source: https://gastown.dev/docs/agent-provider-integration

Example JSON for setting a default agent for the entire town. This file, typically `~/gt/settings/config.json`, defines the fallback agent when no specific rig or role configuration is present.

```json
{
  "type": "town-settings",
  "version": 1,
  "default_agent": "kiro"
}
```

--------------------------------

### Town Settings Role-Specific Agent Configuration Example (JSON)

Source: https://gastown.dev/docs/agent-provider-integration

Example JSON for assigning specific agents to roles within the town. This allows for cost optimization by directing certain roles (e.g., 'witness', 'polecat') to use a particular agent like 'kiro'.

```json
{
  "type": "town-settings",
  "version": 1,
  "default_agent": "claude",
  "role_agents": {
    "witness": "kiro",
    "polecat": "kiro"
  }
}
```

--------------------------------

### Register HookInstallerFunc in Go

Source: https://gastown.dev/docs/agent-provider-integration

Demonstrates the Go function signature and registration process for writing agent-specific settings files during runtime initialization.

```go
type HookInstallerFunc func(settingsDir, workDir, role, hooksDir, hooksFile string) error

config.RegisterHookInstaller("kiro", func(settingsDir, workDir, role, hooksDir, hooksFile string) error {
    return kiro.EnsureSettingsForRoleAt(settingsDir, role, hooksDir, hooksFile)
})
```

--------------------------------

### Distributed Tracing Setup with OTel

Source: https://gastown.dev/docs/design/otel/otel-architecture

Implements distributed tracing using the OpenTelemetry Traces SDK. This involves setting up a tracer provider and exporter, and propagating trace context via W3C `traceparent` headers. Requires `go.opentelemetry.io/otel/trace`.

```go
import (
	"go.opentelemetry.io/otel/sdk/trace"
	"go.opentelemetry.io/otel/trace"
)

// ... setup tracer provider and exporter ...

// Example of creating a root span for a session:
tr := trace.NewTracer("gastown/polecat")
ctx, span := tr.Start(ctx, "gt.session")
defer span.End()

// ... child spans for bd.call, mail, sling, done ...

// GT_RUN propagation becomes W3C traceparent header injection
```

--------------------------------

### TypeScript Project Build Pipeline Configuration

Source: https://gastown.dev/docs/concepts/integration-branches

Example configuration for a TypeScript project's build pipeline within the merge queue settings. It includes commands for setup, type checking, linting, testing, and building.

```json
{
  "merge_queue": {
    "setup_command": "pnpm install",
    "typecheck_command": "tsc --noEmit",
    "lint_command": "eslint .",
    "test_command": "pnpm test:unit",
    "build_command": "pnpm build"
  }
}
```

--------------------------------

### Witness Session Initialization Logic

Source: https://gastown.dev/docs/design/witness-at-team-lead

This pseudo-code outlines the startup sequence for a Witness session managed by a daemon. It covers hook execution, work discovery via mail and bead checks, AT team spawning, and the monitoring loop for task management.

```pseudo-code
Witness session starts (managed by daemon)
    │
    ├── SessionStart hook: gt prime --hook
    │   └── Loads role context, checks hook
    │
    ├── Check for work:
    │   ├── gt mail inbox (convoy dispatch, priority changes)
    │   ├── bd ready (unblocked issues)
    │   └── gt hook (hooked work)
    │
    ├── If work available:
    │   │
    │   ├── Create AT team:
    │   │   Teammate({ operation: "spawnTeam", team_name: "<rig>-work" })
    │   │
    │   ├── Create AT tasks from beads issues:
    │   │   For each issue: TaskCreate({ subject, description, metadata: { bead_id } })
    │   │   Set dependencies: TaskUpdate({ addBlockedBy: [...] })
    │   │
    │   ├── Create worktrees for polecats:
    │   │   For each polecat: git worktree add ...
    │   │
    │   ├── Spawn polecat teammates:
    │   │   For each (up to max_teammates):
    │   │     Task({ subagent_type: "polecat", team_name: "...", name: "..." })
    │   │
    │   └── Enter monitoring loop:
    │       ├── Watch AT task list for completions
    │       ├── Handle teammate crashes (SubagentStop)
    │       ├── Relay gt mail ↔ AT messages
    │       ├── Check for new convoy arrivals
    │       └── When all tasks done: cleanup and report
    │
    └── If no work:
        └── Stop hook checks for queued work periodically
            └── If work arrives: wake and create team
```

--------------------------------

### Manual Bead Creation and Batch Sling Workflow

Source: https://gastown.dev/docs/design/convoy/roadmap

Demonstrates the standard pattern for creating tasks and batch slinging them to a target branch.

```bash
bd create --type=task "Fix auth timeout"       → sh-task-1  
bd create --type=task "Add validation"         → sh-task-2  
bd create --type=task "Integration tests"      → sh-task-3  
bd dep add sh-task-2 sh-task-1 --type=blocks  
gt sling sh-task-1 sh-task-2 sh-task-3 gastown  
```

--------------------------------

### Install Homebrew Package Manager

Source: https://gastown.dev/docs/INSTALLING

Installs the Homebrew package manager on macOS using a script downloaded from GitHub. Homebrew is used to install other development tools and dependencies.

```shell
# Install Homebrew if needed  
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

--------------------------------

### Discover Target Settings Files

Source: https://gastown.dev/docs/design/agent-api-inventory

Locates all relevant settings files for different agent roles and rigs. Requires Go.

```go
func DiscoverTargets() []string {
  // ... implementation details ...
  return []string{}
}
```

--------------------------------

### Install Required Packages with DNF (Fedora/RHEL)

Source: https://gastown.dev/docs/INSTALLING

Installs Git and Go using the DNF package manager on Fedora/RHEL systems. It also provides instructions for optionally installing tmux.

```shell
# Required  
sudo dnf install -y git golang  
# Install Dolt: see https://github.com/dolthub/dolt?tab=readme-ov-file#installation  

# Optional  
sudo dnf install -y tmux  
```

--------------------------------

### Install Required and Optional Packages with Homebrew (macOS)

Source: https://gastown.dev/docs/INSTALLING

Installs essential development tools like Go and Git using Homebrew on macOS. It also includes instructions for installing optional tools like tmux for full-stack mode. Note that Dolt installation instructions are external.

```shell
# Required  
brew install go git  
# Install Dolt: see https://github.com/dolthub/dolt?tab=readme-ov-file#installation  

# Optional (for full stack mode)  
brew install tmux  
```

--------------------------------

### Run Prime Functionality

Source: https://gastown.dev/docs/design/agent-api-inventory

Executes the full priming process or a compact/resume path for session initialization. Requires Go.

```go
func runPrime() {
  // ... implementation details ...
}
```

--------------------------------

### Install Formula with Gastown CLI

Source: https://gastown.dev/docs/design/mol-mall-design

Installs a specified formula from a registry. It resolves the formula, displays its metadata, downloads, verifies, and installs it to the local `gt` directory.

```bash
$ gt formula install mol-polecat-code-review  
  
Resolving mol-polecat-code-review...  
  Registry: molmall.gastown.io  
  Version:  1.2.0 (latest)  
  Author:   steve@gastown.io  
  Skills:   code-review, security  
  
Downloading... ████████████████████ 100%  
Verifying checksum... ✓  
  
Installed to: ~/gt/.beads/formulas/mol-polecat-code-review.formula.toml  

```

--------------------------------

### Message Format Examples

Source: https://gastown.dev/docs/design/mail-protocol

Provides examples of valid subject lines and address formats used within the Gastown communication protocol. These examples demonstrate the use of type prefixes, colon separators, and hierarchical addressing.

```text
POLECAT_DONE nux
MERGE_READY greenplace/nux
HELP: Polecat stuck on test failures
🤝 HANDOFF: Schema work in progress

greenplace/witness       # Witness for greenplace rig
beads/refinery           # Refinery for beads rig
greenplace/polecats/nux  # Specific polecat
mayor/                # Town-level Mayor
deacon/               # Town-level Deacon
```

--------------------------------

### Initialize Telemetry Provider

Source: https://gastown.dev/docs/design/otel/otel-architecture

Sets up OpenTelemetry providers for metrics and logs on process startup. Telemetry is best-effort; errors during initialization are logged but do not halt the process. The provider should be shut down when no longer needed.

```go
provider, err := telemetry.Init(ctx, "gastown", version)
if err != nil {
    // Log and continue — telemetry is best-effort
}
defer provider.Shutdown(ctx)
```

--------------------------------

### Install Single File Formula using CLI

Source: https://gastown.dev/docs/design/mol-mall-design

Demonstrates the command-line interface (CLI) command `gt formula install` for installing a single `.formula.toml` file from the Mol Mall.

```bash
gt formula install mol-polecat-code-review
# Downloads mol-polecat-code-review.formula.toml to ~/gt/.beads/formulas/

```

--------------------------------

### Install Formula Bundle using CLI

Source: https://gastown.dev/docs/design/mol-mall-design

Shows the CLI command `gt formula install` for installing a formula bundle. The command extracts the bundle contents, including `formula.toml`, into the appropriate local directory.

```bash
gt formula install mol-deploy-k8s
# Extracts to ~/gt/.beads/formulas/mol-deploy-k8s/
# formula.toml is at mol-deploy-k8s/formula.toml

```

--------------------------------

### Start Proxy Server and Issue Polecat Certificates

Source: https://gastown.dev/docs/proxy-server

Demonstrates initializing the proxy server and using the Go API to generate identity certificates for individual polecats.

```bash
# Installs the CA on first run
gt-proxy-server --listen 0.0.0.0:9876
```

```go
ca, _ := proxy.LoadOrGenerateCA("~/gt/.runtime/ca")
certPEM, keyPEM, _ := ca.IssuePolecat("gt-MyRig-rust", 365*24*time.Hour)
```

--------------------------------

### Pin Formula Version with Gastown CLI

Source: https://gastown.dev/docs/design/mol-mall-design

Installs a specific version of a formula, pinning it to prevent automatic upgrades. The `gt formula list --installed` command can then be used to view all installed and pinned formulas.

```bash
$ gt formula install mol-polecat-work@4.0.0  
  
Installing mol-polecat-work@4.0.0 (pinned)...  
✓ Installed  
  
$ gt formula list --installed  
  mol-polecat-work           4.0.0   [pinned]  
  mol-polecat-code-review    1.2.0   [latest]  

```

--------------------------------

### Hook Installer Registration

Source: https://gastown.dev/docs/design/agent-api-inventory

Registers hook installers for various AI providers including Claude, Gemini, and Copilot. Requires Go.

```go
// hook installer registration for 6 providers: claude, gemini, opencode, copilot, omp, pi
```

--------------------------------

### Teammate Lifecycle: Compaction and Handoff

Source: https://gastown.dev/docs/design/witness-at-team-lead

Illustrates the process of teammate compaction, including context filling, PreCompact hook execution, and the 'gt handoff' command. It details the steps involved in saving molecule state, progress notes, and git branch state before auto-compaction.

```text
Teammate running  
    │  
    ├── Context filling → PreCompact hook fires  
    │   │  
    │   └── gt handoff --reason compaction  
    │       ├── Saves current molecule step to beads  
    │       ├── Saves progress notes  
    │       └── Saves git branch state  
    │  
    ├── Auto-compaction occurs  
    │   │  
    │   └── SessionStart hook fires (source: "compact")  
    │       └── gt prime --compact-resume  
    │           └── Reads beads state, restores context  
    │  
    └── Teammate continues with compressed context  

```

--------------------------------

### Manage Hooks Registry with `gt hooks registry` / `gt hooks install`

Source: https://gastown.dev/docs/HOOKS

Allows browsing and installing hooks from the registry. `gt hooks registry` lists available hooks, while `gt hooks install <hook-id>` adds a specified hook to the base configuration.

```bash
gt hooks registry                  # List available hooks  
gt hooks install <hook-id>         # Install a hook to base config  
```

--------------------------------

### Recursive DAG Walking with Go SDK

Source: https://gastown.dev/docs/design/convoy/stage-launch/prd

Implementation of epic DAG walking using the Go SDK to ensure performance and consistency with existing infrastructure.

```go
func buildDAG(rootID string) (*DAG, error) {
	// Use beads SDK for recursive list to avoid subprocess overhead
	items, err := beads.List(beads.ListOptions{Parent: rootID})
	if err != nil {
		return nil, err
	}
	// ... topological sort and graph construction logic
	return constructGraph(items)
}
```

--------------------------------

### Follow Real-Time Activity Feed (Shell)

Source: https://gastown.dev/docs/why-these-features

Shows how to use the 'bd activity --follow' command to stream real-time updates on agent activities. This is crucial for the Real-Time Activity Feed feature, aiding in debugging and status awareness.

```shell
bd activity --follow  

[14:32:08] + patrol-x7k.arm-ace bonded (5 steps)  
[14:32:09] → patrol-x7k.arm-ace.capture in_progress  
[14:32:10] ✓ patrol-x7k.arm-ace.capture completed  
[14:32:14] ✓ patrol-x7k.arm-ace.decide completed  
[14:32:17] ✓ patrol-x7k.arm-ace COMPLETE  

```

--------------------------------

### Design-to-Beads and Manual Sling Workflow

Source: https://gastown.dev/docs/design/convoy/roadmap

Shows how to generate organizational hierarchy and execution dependencies from a PRD file before slinging.

```bash
/design-to-beads PRD.md  
→ creates: root epic, sub-epics, leaf tasks  
→ adds: parent-child deps (organizational hierarchy)  
→ adds: blocks deps (execution ordering between tasks)  
gt sling <task1> <task2> <task3> gastown  
```

--------------------------------

### Wisp Storage Configuration Example

Source: https://gastown.dev/docs/design/property-layers

An example JSON structure showing how configuration values and blocked settings are stored locally for a Gastown rig in the .beads-wisp/config directory.

```json
{
  "rig": "gastown",
  "values": {
    "status": "parked",
    "priority_adjustment": 10
  },
  "blocked": ["auto_restart"]
}
```

--------------------------------

### Handle Prime Hook Mode

Source: https://gastown.dev/docs/design/agent-api-inventory

Integrates the SessionStart hook, reading and persisting session IDs from stdin JSON. Requires Go.

```go
func handlePrimeHookMode() {
  // ... implementation details ...
}
```

--------------------------------

### Gastown CLI Lock File Structure

Source: https://gastown.dev/docs/design/mol-mall-design

The `.lock.json` file in `~/gt/.beads/formulas/` stores the state of installed formulas, including their versions, pinned status, checksums, installation timestamps, and sources.

```json
{
  "version": 1,
  "formulas": {
    "mol-polecat-work": {
      "version": "4.0.0",
      "pinned": true,
      "checksum": "sha256:abc123...",
      "installed_at": "2026-01-10T00:00:00Z",
      "source": "hop://molmall.gastown.io/formulas/mol-polecat-work@4.0.0"
    },
    "mol-polecat-code-review": {
      "version": "1.3.0",
      "pinned": false,
      "checksum": "sha256:def456...",
      "installed_at": "2026-01-10T12:00:00Z",
      "source": "hop://molmall.gastown.io/formulas/mol-polecat-code-review@1.3.0"
    }
  }
}

```
Tokens:
Raw