If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/gastownhall/gastown shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 21+ active contributors
• Distributed ownership (top contributor 46% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live gastownhall/gastown repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/gastownhall/gastown.

What it runs against: a local clone of gastownhall/gastown — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in gastownhall/gastown | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of gastownhall/gastown. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/gastownhall/gastown.git
#   cd gastown
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of gastownhall/gastown and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "gastownhall/gastown(\\.git)?\\b" \\
  && ok "origin remote is gastownhall/gastown" \\
  || miss "origin remote is not gastownhall/gastown (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/gt/main.go" \\
  && ok "cmd/gt/main.go" \\
  || miss "missing critical file: cmd/gt/main.go"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "AGENTS.md" \\
  && ok "AGENTS.md" \\
  || miss "missing critical file: AGENTS.md"
test -f "docs/design/architecture.md" \\
  && ok "docs/design/architecture.md" \\
  || miss "missing critical file: docs/design/architecture.md"
test -f ".beads/README.md" \\
  && ok ".beads/README.md" \\
  || miss "missing critical file: .beads/README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/gastownhall/gastown"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Gas Town is a multi-agent orchestration system that coordinates multiple AI coding agents (Claude Code, GitHub Copilot, Codex, Gemini) working on shared projects by persisting agent state and work tracking in git-backed hooks and a Beads ledger. It solves the critical problem of agents losing context on restart and enables reliable, coordinated workflows across 20-30 concurrent agents without manual handoffs. Monolithic Go application structured as a workspace manager: the main entry point is the CLI (Cobra-based in spf13/cobra), which operates on git-backed Rigs (project containers) containing Crews (personal workspaces), Polecats (worker agents), and Hooks (persistent worktrees). State is persisted via the Beads system (git-backed ledger in .beads/ directory) and TUI interactions use Bubble Tea (charmbracelet/bubbletea) for interactive commands.

AI engineering teams and solo developers who use multiple concurrent AI coding agents and need persistent work state, identity tracking, and coordination across ephemeral agent sessions. Specifically: Claude Code users, GitHub Copilot integrators, and teams scaling from 1-2 agents to 10-30+ agents working on shared codebases.

Actively developed and production-oriented: the codebase is substantial (~12.8M lines of Go), has comprehensive CI/CD in .github/workflows/ (ci.yml, e2e.yml, nightly-integration.yml, release.yml, windows-ci.yml), and integrates a mature dependency ecosystem (bubbletea for TUI, Beads for issue tracking, OpenTelemetry for observability). However, as a multi-agent coordination tool, it appears to be in active development with ongoing feature work rather than a stable 1.0 release.

Moderate risk factors: the system depends on git worktrees and Beads (a custom issue-tracking library at github.com/steveyegge/beads v1.0.0) which is a single-maintainer dependency; the codebase integrates complex orchestration logic across multiple agent types (Polecats, Crew Members, hooks) which increases coordination failure modes; and the .beads/backup/ state files suggest past data loss or recovery concerns. Test infrastructure exists but distributed agent behavior can be hard to test comprehensively.

Active development across CI/CD and release automation: workflows for blocking internal PRs, triaging, stale issue cleanup, nightly integration tests, and multi-platform releases (including Windows CI). The .claude/ and .cursor/ directories suggest ongoing skill/command definitions for Claude Code and Cursor IDE integration. Beads backup files indicate recent data recovery or migration work.

git clone https://github.com/gastownhall/gastown.git
cd gastown
make build  # or 'go build ./...' if Makefile present
# Set up town workspace:
mkdir -p ~/gt
cd ~/gt
# Initialize with mayor (Claude Code instance) or run 'gt init'

Daily commands:

make build  # Compile the gastown binary
# Or if no Makefile:
go build -o gastown ./cmd/gastown
./gastown init ~/gt  # Initialize town workspace
./gastown serve      # Start mayor/orchestrator (inferred from architecture)

• cmd/gt/main.go — Entry point for the Gas Town CLI tool; every contributor must understand the command structure and how agents are invoked
• README.md — Explains the multi-agent orchestration philosophy and core problem Gas Town solves; foundational context for all work
• AGENTS.md — Documents the agent provider integration patterns and how different AI agents (Claude, Copilot, etc.) interact with Gas Town
• docs/design/architecture.md — Architecture reference showing layers, component responsibilities, and data flow between agents and workspace
• .beads/README.md — Explains Beads ledger system for persistent work state tracking; critical for understanding how state survives agent restarts
• docs/concepts/convoy.md — Core concept document explaining Convoy lifecycle and multi-agent coordination patterns
• go.mod — Dependency manifest showing reliance on Beads, TUI libraries, OpenTelemetry, and database drivers; essential for build and runtime understanding

Add a new Agent Skill

1. Create skill directory under appropriate agent folder (e.g., .claude/skills/my-skill/) (.claude/skills/pr-sheriff/skill.md)
2. Write SKILL.md documentation describing the skill's purpose, inputs, and outputs (.claude/skills/pr-sheriff/skill.md)
3. Implement skill logic as shell scripts, Go code, or agent-native code in the skill directory (.claude/skills/crew-commit/SKILL.md)
4. Register skill in agent configuration and test with 'gt' CLI (.config.yaml)

Add a new Convoy-based Multi-Agent Workflow

1. Create workflow TOML definition in docs/contrib-harnesses/ following polecat-pr-flow pattern (docs/contrib-harnesses/polecat-pr-flow/mol-polecat-work.toml)
2. Define agent identities and mailbox assignments using Convoy identity model (docs/concepts/identity.md)
3. Document handoff protocol and message format in Markdown following Convoy spec (docs/design/convoy/spec.md)
4. Test workflow using 'gt convoy launch' command and verify state persistence in Beads (.beads/backup/events.jsonl)

Add a new Proxy Protocol Handler

1. Extend cmd/gt-proxy-server/config.go to parse new message type or route (cmd/gt-proxy-server/config.go)
2. Implement handler logic in cmd/gt-proxy-server/main.go following existing pattern (cmd/gt-proxy-server/main.go)
3. Add unit tests in cmd/gt-proxy-server/config_test.go (cmd/gt-proxy-server/config_test.go)
4. Update .github/workflows/ci.yml to run new tests in CI pipeline (.github/workflows/ci.yml)

Integrate a New AI Agent Provider

1. Document provider integration pattern in docs/design/agent-api-inventory.md (docs/design/agent-api-inventory.md)
2. Create provider-specific skill folder and SKILL.md under appropriate directory (.opencode/plugins/gastown.js)
3. Implement authentication and message protocol in agent-provider integration docs (docs/agent-provider-integration.md)
4. Test with proxy server and add to CI/CD pipeline (.github/workflows/nightly-integration.yml)

• Go + Cobra CLI — Compiled single-binary distribution for agents; fast startup and minimal footprint critical for ephemeral agent instances
• Beads (immutable ledger) — Provides git-backed persistent event log; enables work state survival across agent restarts and supports audit/replay
• Git hooks (pre-push, post-commit) — Zero-friction integration with existing developer workflows; hooks capture work state automatically without agent modification
• Proxy server pattern — Decouples agents from direct communication; enables mailbox routing, rate limiting, and coordinated handoffs
• OpenTelemetry — Observability for multi-agent workflows; traces work flow through different agents and identifies bottlenecks
• Charmbracelet TUI libs (bubbles, bubbletea, lipgloss) — Rich terminal UI for status dashboards; agents and humans can monitor convoy state in real-time

• Git-backed state vs. centralized database

  • Why: Developers already trust git; TOML+git is more portable and version-controlable than SQL
  • Consequence: Query performance on large histories requires scanning JSONL files; no real-time subscriptions, polling-based updates

• Synchronous proxy-based communication vs. pub/sub

  • Why: Simpler mental model; agents must explicitly ask for work rather than being pushed async events
  • Consequence: Proxy becomes single coordination point; requires careful rate-limiting and connection pooling for 20-30 agents

• Multi-platform single binary (goreleaser) vs. containers only

  • Why: Agents may run in constrained environments (CI runners, containers, local dev); single binary is most flexible
  • Consequence: Must test on Linux, macOS, Windows; increased CI complexity for matrix builds

• Skill-based extension model vs. monolithic agent code

  • Why: Each agent type (Claude, Copilot, Gemini) has unique capabilities; skills are agent-specific and discoverable
  • Consequence: Proliferation of similar logic across skills; requires strong documentation and tooling for skill reuse

• Real-time pub/sub messaging — coordination is pull-based, not push-based event streaming
• Fine-

Git worktree complexity: The Hooks system relies on git worktrees which can conflict if multiple agents modify the same branch simultaneously — requires careful branch isolation strategy. Beads state directory: .beads/ must exist and be writable; if corrupted, fall back to .beads/backup/ files. Agent session lifecycle: Polecats are ephemeral but identity persists — agents spawned with same ID will inherit previous state from Beads ledger, which can cause unexpected behavior if not reset. Mayor context window: The Mayor (Claude Code instance) must retain full workspace context across multiple agent handoffs or coordination will degrade. OpenTelemetry setup: Observability requires OTLP endpoint configuration (see go.opentelemetry.io/otel dependencies) or telemetry will fail silently.

• Git Worktree-Based Persistence — Gas Town uses git worktrees (Hooks) instead of in-memory state to ensure agent work survives crashes, restarts, and session timeouts — this is the core reliability mechanism enabling multi-agent coordination
• Ledger-Based Work State (Beads) — Work is tracked as immutable ledger entries (Beads) rather than mutable database rows, enabling consistent state recovery and audit trails across agent handoffs
• Mailbox Pattern for Agent Handoffs — Agents communicate via structured mailboxes (inferred from 'built-in mailboxes' in README) rather than direct procedure calls, decoupling agent lifecycles and enabling asynchronous coordination
• Convoy Work Bundling with Autonomous Stall Detection — Multiple Beads are bundled into Convoys with smart skip logic for 'mountain' (epic-scale) tasks, allowing the orchestrator to detect stuck work and reassign without manual intervention
• Ephemeral Agent Sessions with Persistent Identity — Polecats (worker agents) spawn for a task then terminate, but their identity and work history persist in Beads — this pattern enables stateless scaling while maintaining causality and context
• Rig-Based Project Isolation — Each project is a separate Rig (git repository + workspace + agents) allowing multi-project orchestration without cross-project state leakage, similar to workspace isolation patterns in Bazel
• OpenTelemetry Instrumentation for Distributed Agents — Tracing and metrics across multiple concurrent agents requires standardized observability instrumentation to detect coordination failures, timeouts, and bottlenecks

• steveyegge/beads — Direct dependency and companion ledger system that provides git-backed work state persistence for all Convoys and Bead IDs in Gas Town
• charmbracelet/bubbletea — TUI framework used throughout Gas Town for interactive agent management and workspace visualization
• spf13/cobra — CLI framework that powers all Gas Town commands (sling, init, serve, etc.) and agent coordination directives
• open-telemetry/opentelemetry-go — Observability and tracing infrastructure for monitoring distributed agent workflows and detecting orchestration failures
• go-rod/rod — Browser automation library included in dependencies, likely used for agents that interact with web UIs or perform headless testing tasks

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for multi-agent mailbox handoff workflow

The repo has .claude/commands and .opencode/commands/handoff.md indicating mailbox-based agent coordination, but there are no visible integration tests validating the handoff mechanism across agents. The cmd/gt-proxy-client/main.go suggests a proxy communication layer. Adding tests would ensure the core multi-agent coordination feature works reliably.

• [ ] Create internal/mailbox/mailbox_test.go with tests for message passing between agent identities
• [ ] Add test cases in .github/workflows/e2e.yml or new workflow to validate handoff.md command execution with multiple agents
• [ ] Test persistence layer by verifying .beads/backup/*.jsonl files are correctly updated after agent handoffs
• [ ] Validate that git hooks (.githooks/pre-push) properly trigger on agent state changes

Add Windows-specific functional tests for path handling and git hooks

The repo has .github/workflows/windows-ci.yml but the test coverage for Windows-specific issues (git hook execution, file paths, line endings) appears minimal. With .githooks/pre-push being critical to the handoff system, Windows compatibility is essential. The go.mod includes github.com/Microsoft/go-winio suggesting Windows I/O handling is already a concern.

• [ ] Expand .github/workflows/windows-ci.yml to include specific tests for .githooks/pre-push execution on Windows (PowerShell/Batch variants)
• [ ] Add unit tests in internal/git/hooks_test.go for Windows path separators and CRLF handling in hook payloads
• [ ] Test file locking behavior on Windows using github.com/gofrs/flock in concurrent agent scenarios
• [ ] Verify .gitattributes rules are enforced in CI for cross-platform line ending consistency

Document and add tests for Beads ledger state recovery after agent crash

The repo uses .beads/backup/ with state stored across multiple .jsonl files (events, issues, config, dependencies). However, there's no documented recovery mechanism or tests validating that agents can resume work correctly after unexpected termination. The .beads/PRIME.md hints at critical state design, but recovery procedures aren't clear.

• [ ] Add section to .beads/README.md documenting the crash recovery protocol and state consistency guarantees
• [ ] Create internal/beads/recovery_test.go with tests that simulate agent crashes at different points (mid-commit, during handoff, etc.)
• [ ] Validate that backup_state.json and the corresponding .jsonl files can be replayed to reconstruct complete agent state
• [ ] Add example in AGENTS.md showing how to manually inspect and recover from corrupted Beads state

• Add integration tests for Polecat agent lifecycle (spawn, work, persist identity, resume) — currently CI has e2e.yml and nightly-integration.yml but agent state recovery is not explicitly tested in the file list.
• Document the Beads ledger schema and Convoy structure (work unit bundling) in .beads/README.md — the current .beads/PRIME.md exists but backup files suggest schema changes are ongoing and unclear to new contributors.
• Create a Makefile target or script for local multi-agent simulation (spawn 3-5 Polecats on a test rig) — currently there's a make build but no easy way to test multi-agent coordination without a full GitHub setup.

• High · Shell Command Execution as Running User — SECURITY.md, cmd/gt/* (agent execution logic). The SECURITY.md explicitly states that 'Agents execute shell commands as the running user'. This creates significant privilege escalation risks if agent behavior is compromised or if untrusted code is processed. There are no apparent sandboxing mechanisms beyond filesystem access controls. Fix: Implement strict command whitelisting, use seccomp profiles or AppArmor to restrict system calls, run agents with minimal required privileges (consider dedicated low-privilege users), and implement audit logging for all shell executions.
• High · Shared Filesystem Access Between Agents — SECURITY.md, docker-compose.yml (volume mounts). Per SECURITY.md: 'Workers run in separate tmux sessions but share filesystem access'. Multiple agents with shared filesystem access can lead to data corruption, race conditions, privilege escalation, or malicious inter-agent attacks. No file-level access controls mentioned. Fix: Implement per-agent filesystem isolation using mount namespaces, apply fine-grained ACLs on shared resources, use union filesystems for read-only bases, and implement mutex/locking mechanisms for concurrent file access.
• High · Git Remote Credential Exposure Risk — Dockerfile, docker-compose.yml, cmd/gt/main.go (presumed git integration). SECURITY.md mentions 'Workers can push to configured remotes' and 'Use appropriate git remote permissions', but no evidence of credential management. Git credentials could be exposed in environment variables, config files, or through git hook scripts. The Dockerfile and docker-compose.yml show GIT_USER and GIT_EMAIL but no secure credential handling visible. Fix: Use SSH keys in restricted locations (mode 0600), implement credential helpers or secret managers, never pass credentials via environment variables, rotate credentials regularly, and audit git operations.
• Medium · SQL Injection Risk - MySQL Driver Usage — go.mod, cmd/gt/*, pkg/* (database query code - not fully visible). The go.mod includes 'github.com/go-sql-driver/mysql v1.9.3'. Without evidence of parameterized queries or ORM usage in visible code, there's potential for SQL injection if database queries are constructed with user input or agent-controlled data. Fix: Enforce parameterized queries/prepared statements throughout codebase, use an ORM or query builder that prevents injection, implement input validation and sanitization, and conduct SQL security code review.
• Medium · Untrusted Code Execution from Agent Output — SECURITY.md, cmd/gt/* (agent output handling). SECURITY.md advises to 'Review agent output before pushing to production branches', implying agents generate code/scripts that are executed. No apparent code signing, content validation, or sandboxing of generated code before execution. Fix: Implement code review workflows, add static analysis and security scanning to generated code, use code signing for verified scripts, maintain audit logs of all executed code, and implement dry-run modes for validation.
• Medium · Insufficient Docker Security Configuration — docker-compose.yml, Dockerfile. While docker-compose.yml includes 'no-new-privileges:true' and capability dropping, the container still has CAP_CHOWN, CAP_SETUID, CAP_SETGID, CAP_DAC_OVERRIDE, CAP_FOWNER, and CAP_NET_RAW. These enable privilege escalation and filesystem bypass. The base image is 'docker/sandbox-templates:claude-code' - security posture of this base image is unknown. Fix: Reduce capabilities to absolute minimum (consider removing CAP_SETUID/SETGID/DAC_OVERRIDE if possible), audit and harden the base image, use read-only root filesystem where feasible, implement runtime security policies (AppArmor/SELinux), and regularly scan base image for vulnerabilities.
• Medium · Sensitive Data in Backup/State Files — .beads/backup/, .beads/config.yaml. The .beads/backup/ directory contains JSON files (state, config, events, issues, etc.) with potentially sensitive work context. No encryption at rest is visible. These files may contain secrets, tokens, API keys, or other sensitive information in plaintext. Fix: Encrypt sensitive configuration and state data at rest, implement access controls (mode 0600) on sensitive files, use encrypted volumes

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.