Gas Town: A Practical Guide

Gas Town is Steve Yegge’s multi-agent coding workspace manager. He launched it on January 1, 2026, and the latest GitHub release is v1.0.0 on April 3. The idea is to stop treating agent work like disposable chat and start treating it like agentic issue tracking: each worker has an identity, work lives in Beads (think TODOs or tasks with dependencies and priority ordering), and attached work survives restarts through git-backed hooks. (Medium)

Gas Town is best when you want to move fast with multiple agents, context keeps evaporating, and you need a system that can coordinate work across repos, preserve handoffs, and tell you who changed what and why. It is usually the wrong tool if you just want a clean editor and a chat pane. (Gas Town Docs)

What Gas Town Is

Gas Town is a workspace manager and orchestration layer for multiple coding agents. It is vendor-agnostic and can coordinate agentic workflows like Claude Code, Codex, or Gemini, among others. Work persists across sessions via git-backed hooks, instead of vanishing with session restarts. The idea is to turn agent work into structured, attributable, auditable data. (GitHub)

A rig is a project container. A bead is a work item in the Beads system. A convoy tracks related work (the docs explicitly say to use one even for a single issue). A hook is attached work that survives restarts, handoffs, and context compaction. (Gas Town Docs)

The animal names are whimsical, but the roles are not. The Mayor coordinates work across the town. Crew are long-lived named workers. Polecats are transient workers for discrete tasks. Witness manages polecats per rig. Refinery handles merge processing. Deacon and its dogs keep the system healthy (dogs are not for user work). (Gas Town Docs)

Who Built It And Why

Gas Town was created and announced by Steve Yegge, though the current project has a broader community and core team around it. Yegge’s motivation for building it was because running lots of Claude Code instances was tedious and hard to supervise. As a veteran software engineer that spent long stretches at Amazon and then Google, he quickly realized that teams, including agents, need accountability, quality control, and efficient work routing. (Medium)

The other half of the story is Beads, which he built after noticing that agents struggled with working memory and basic task tracking. He describes Beads as a memory system and knowledge graph for coding agents, with work items stored in Git and queryable like a database. Gas Town sits on top of that foundation. (Github)

What It Is For

Gas Town is for serious multi-agent software work. It fits when you want to plan in one place, send execution to multiple workers, preserve state between sessions, and later reconstruct what happened. Convoys give you a persistent view of work in flight, while the dashboard shows progress, last activity, and status across active convoys. (Gas Town Docs)

It is also built for cross-repo work: use a worktree when you want to keep your identity and quickly patch another rig, or dispatch work to the target rig when that team should own the result.

The recommendation is to use Gas Town when the pain is coordination, not code generation.

• You have several active agent tasks and lose track of them.
• Session restarts keep wiping useful context, and you want durable handoffs.
• You need provenance, accountability, or later forensics. gt audit exists for exactly this reason. (Gas Town Docs)
• Work spans repos, teams, or long-running projects. Convoys and cross-rig patterns are first-class concepts in the docs. (Gas Town Docs)
• Your implementation work is discrete enough to hand to transient workers. Polecats are designed for that. (Gas Town Docs)

When Not To Use It

Skip Gas Town, at least for now, if you mostly work in 1 repo with 1 agent, dislike terminals and tmux, or want a polished GUI-first experience. Yegge’s early posts were blunt that launch-era Gas Town demanded hands-on supervision; the v1.0 post says stability is much better now, but the operating model is still the same. You are running an orchestration system, not just opening an editor. (Medium)

Also skip polecats for fuzzy work. The docs and Yegge’s manual line up here: Crew are better for exploratory, review-heavy, design-heavy, or judgment-heavy work. Polecats are better for crisp tasks that should just get done and land. (Gas Town Docs)

If you try it and hate the added machinery, Gas Town has a clean rollback path. gt disable turns the shell hooks into no-ops and lets supported tools run in vanilla mode while preserving the workspace. (Gas Town Docs)

How Gas Town Actually Works

The key primitive is the hook. When work is on a worker’s hook, Gas Town can recover it after restarts, compaction, or handoff. gt handoff -c can collect current state into handoff mail, and the next session restores context via gt prime. That is why Gas Town feels different from plain agent chat. It externalizes state. (Gas Town Docs)

Convoys are the tracking layer. They are persistent records of related work across rigs, while the “swarm” is only the temporary set of workers currently assigned to those issues. The docs recommend creating a convoy even for a single issue because the point is visibility, status, and history, not just batching. Gas Town can also auto-create a convoy on single-issue gt sling if you forget. (Gas Town Docs)

Crew and polecats are different tools. Crew are persistent, human-managed, and good for design, planning, and review. Polecats are transient, Witness-managed, work on branches, and are better for discrete implementation tasks. Dogs are Deacon helpers, not product workers. (Gas Town Docs)

How To Get Started

Start smaller than you think. The best first setup is 1 town, 1 rig, 1 crew member, and Mayor-first orchestration. Yegge’s own manual says Mayor-only mode is a good intro, and the current README starts by attaching to the Mayor after creating a workspace and a crew clone. (Medium)

A conservative first run looks like this. (GitHub)

brew install gastown

gt install ~/gt --git

cd ~/gt

gt rig add myproject https://github.com/you/repo.git

gt crew add yourname --rig myproject

cd myproject/crew/yourname

gt config agent list

gt mayor attach

If you use multiple runtimes or want lighter models for sub-tasks, set aliases early. The install docs show gt config agent set codex-low "codex --thinking low" and gt config default-agent codex-low, with per-command overrides via --agent. (Gas Town Docs)

If you want to test the model before committing to tmux and background services, the README documents a no-tmux mode where you create a convoy, sling work, run claude --resume or codex manually, and inspect progress with gt convoy list. (GitHub)

gt convoy create "Fix bugs" gt-abc12

gt sling gt-abc12 myproject

claude --resume

gt convoy list

When you’re ready for the full stack, gt up starts the daemon, Deacon, Mayor, Witnesses, and Refineries. Use gt down for a reversible pause, and gt shutdown when you’re done and want polecat worktrees cleaned up. (Gas Town Docs)

A Good First Workflow

1. Talk to the Mayor first. Ask it to turn a feature, bug, or idea into a concrete plan and a bead list.
2. Use Crew for thinking. Let a crew member review the plan, tighten the spec, or break the work into better-defined beads. Crew are the right tool for design, planning, and review.
3. Create a convoy and sling only the crisp parts. Even 1 issue should live in a convoy. Then hand 1 or 2 well-specified beads to polecats.
4. Let workers run. Don’t stare at them. Do not watch agents work. Instead, read their summaries when they finish, then make decisions.
5. Handoff after tasks. Use gt handoff, ideally gt handoff -c, so the next shift starts fresh without losing state. (Medium)

That flow teaches the model without dropping you straight into a 15-worker swarm.

Practical Advice That Actually Pays Off

Learn enough tmux to move between sessions, detach and reattach, and copy text cleanly. You do not need to become a tmux monk, but you do need basic competence. Yegge calls this out for a reason. (Tmux Cheat Sheet)

Don’t swarm by default. Gas Town makes parallelism possible, but it does not make serial bottlenecks disappear. Yegge explicitly says it’s normal to run only 1 or 2 active workers while you unblock the next stage. (Medium)

Bring your own workflow. Gas Town does not force 1 canonical process, and Yegge says most of his own workflows change week to week. That is the right mindset. Layer in Mayor, then Crew, then polecats, then Refineries. Do not turn everything on at once just because the nouns exist. (Medium)

The docs list 4 common beginner mistakes: using dogs for user work, confusing crew with polecats, working from the wrong directory, and waiting for extra confirmation after work is hooked. Gas Town uses your current working directory for identity detection, and hooked work should be treated as assigned work, not a tentative suggestion. (Gas Town Docs)

When something breaks, use the built-ins instead of improvising. gt status shows town name, rigs, active polecats, and witness state. gt doctor --fix checks config, missing files, stale sessions, orphan processes, divergence, and more. gt dashboard is the live convoy view. gt audit answers provenance questions. gt orphans finds lost unmerged polecat commits. gt release reopens stuck in-progress issues. gt seance lets you inspect or even question a predecessor session. (Gas Town Docs)

A compact command starter pack looks like this. (GitHub)

gt mayor attach # main interface

gt convoy create ... # track work

gt sling ... # assign work

gt handoff -c # refresh session with collected state

gt status --watch # town health

gt dashboard # convoy view

gt doctor --fix # diagnose and repair

gt audit --actor=... # provenance

gt orphans # recover lost polecat work

gt release ... # reopen stuck work

gt down # pause

gt shutdown # stop and clean up

Plan your budget outside Gas Town for now. gt costs exists, but the docs say cost tracking is currently disabled because Claude Code’s cost data is not exposed in a way Gas Town can capture. If you run many workers, set your own budget guardrails. Gas Town does support multiple Claude Code accounts and per-spawn account selection, which helps if you separate work and personal usage. (Gas Town Docs)

Pros And Cons

Pros

• Durable continuity across restarts and handoffs, because work lives on hooks and in handoff mail rather than only in the agent’s context window.
• Strong provenance. Commits, beads, and town events can all be attributed and queried.
• Good separation between thinking and doing. Crew handle planning and review, polecats handle crisp execution.
• Useful operational surface: diagnostics, dashboards, audits, recovery commands, and full-stack service control.
• Strong cross-repo story through convoys, dispatch, and identity-preserving worktrees.

Cons

• Steep terminology and operational overhead. You have to learn the model, not just the commands.
• Best experience depends on tools many developers do not enjoy: tmux, Git worktrees, Beads, and Dolt.
• Docs and install details still have rough edges. The CLI docs still mention v0.5.0, and the npm install string is inconsistent between sources right now.
• Built-in cost tracking is currently disabled, so budget visibility is weaker than it should be.
• It is overkill for simple single-agent work. Gas Town shines when coordination is the hard part.

What To Watch Right Now

The current v1.0.0 release adds signs of maturity: Windows support, workflow-formula support, GitHub merge queue integration, security hardening, Mayor approval gates for polecat scope expansion, and a rate-limit watchdog. The release history now looks more operational and less improvisational. (GitHub)

At the same time, Yegge is already nudging advanced users toward Gas City if they want to build custom orchestrators. In his v1.0 post, he says Gas City can import Gas Town config and is functionally identical when used as a dev IDE. That does not make Gas Town obsolete. It makes Gas Town look like the ready-made product, while Gas City looks like the platform layer for people who want to build their own orchestration systems. (Medium)

Bottom Line

Gas Town has cute names and serious intent. It is worth learning when your problem is orchestration: too many workers, too much context loss, too many repos, too little traceability. Start with Mayor-only mode, add 1 crew member, run 1 convoy, and only then introduce polecat swarms and background services. Use Crew for messy thinking. Use polecats for crisp execution. Treat hooks, convoys, handoffs, and audits as the real product.

If that model relieves a real pain in your workflow, Gas Town can be excellent. If it doesn’t, disable it and go back to a vanilla agent flow. That is a perfectly good outcome too.