docs: Guide users to Mayor session in quickstart
- Change tmux from "optional" to "recommended for the full experience" - Add "Enter the Mayor's office" step after gt rig add - Explain Mayor role upfront in Core Concepts - Reorder workflows to put Full Stack (Recommended) first - Add example of conversational interaction with Mayor - Document gt agents for session navigation Closes #21 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
57
README.md
57
README.md
@@ -16,7 +16,7 @@ Multi-agent orchestrator for Claude Code. Track work with convoys; sling to agen
|
||||
- **Go 1.23+** - [go.dev/dl](https://go.dev/dl/)
|
||||
- **Git 2.25+** - for worktree support
|
||||
- **beads (bd)** - [github.com/steveyegge/beads](https://github.com/steveyegge/beads) - required for issue tracking
|
||||
- **tmux 3.0+** - for full stack mode (optional for minimal mode)
|
||||
- **tmux 3.0+** - recommended for the full experience (the Mayor session is the primary interface)
|
||||
- **Claude Code CLI** - [claude.ai/code](https://claude.ai/code)
|
||||
|
||||
## Quick Start
|
||||
@@ -31,24 +31,39 @@ gt install ~/gt
|
||||
# Add a project
|
||||
gt rig add myproject https://github.com/you/repo.git
|
||||
|
||||
# Create a convoy and sling work (standard workflow)
|
||||
# Enter the Mayor's office (recommended)
|
||||
cd ~/gt && gt prime
|
||||
```
|
||||
|
||||
Once inside the Mayor session, you're talking to Claude with full town context. Just tell it what you want:
|
||||
|
||||
> "Help me fix the authentication bug in myproject"
|
||||
|
||||
The Mayor will create convoys, dispatch workers, and coordinate everything. You can also run CLI commands directly:
|
||||
|
||||
```bash
|
||||
# Create a convoy and sling work (CLI workflow)
|
||||
gt convoy create "Feature X" issue-123 issue-456 --notify --human
|
||||
gt sling issue-123 myproject
|
||||
gt sling issue-456 myproject
|
||||
|
||||
# Track progress on dashboard
|
||||
# Track progress
|
||||
gt convoy list
|
||||
|
||||
# Switch between agent sessions
|
||||
gt agents
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
**The Mayor** is your AI coordinator. It's Claude Code with full context about your workspace, projects, and agents. The Mayor session (`gt prime`) is the primary way to interact with Gas Town - just tell it what you want to accomplish.
|
||||
|
||||
```
|
||||
Town (~/gt/) Your workspace
|
||||
├── Mayor Your AI coordinator (start here)
|
||||
├── Rig (project) Container for a git project + its agents
|
||||
│ ├── Polecats Workers (ephemeral, spawn → work → disappear)
|
||||
│ ├── Witness Monitors workers, handles lifecycle
|
||||
│ └── Refinery Merge queue processor
|
||||
└── Mayor Global coordinator
|
||||
```
|
||||
|
||||
**Hook**: Each agent has a hook where work hangs. On wake, run what's on your hook.
|
||||
@@ -57,6 +72,26 @@ Town (~/gt/) Your workspace
|
||||
|
||||
## Workflows
|
||||
|
||||
### Full Stack (Recommended)
|
||||
|
||||
The primary Gas Town experience. Agents run in tmux sessions with the Mayor as your interface.
|
||||
|
||||
```bash
|
||||
gt start # Start Gas Town (daemon + Mayor session)
|
||||
cd ~/gt && gt prime # Enter Mayor session
|
||||
|
||||
# Inside Mayor session, just ask:
|
||||
# "Create a convoy for issues 123 and 456 in myproject"
|
||||
# "What's the status of my work?"
|
||||
# "Show me what the witness is doing"
|
||||
|
||||
# Or use CLI commands:
|
||||
gt convoy create "Feature X" issue-123 issue-456
|
||||
gt sling issue-123 myproject # Spawns polecat automatically
|
||||
gt convoy list # Dashboard view
|
||||
gt agents # Navigate between sessions
|
||||
```
|
||||
|
||||
### Minimal (No Tmux)
|
||||
|
||||
Run individual Claude Code instances manually. Gas Town just tracks state.
|
||||
@@ -68,18 +103,6 @@ claude --resume # Agent reads mail, runs work
|
||||
gt convoy list # Check progress
|
||||
```
|
||||
|
||||
### Full Stack (Tmux)
|
||||
|
||||
Agents run in tmux sessions. Daemon manages lifecycle.
|
||||
|
||||
```bash
|
||||
gt daemon start # Start lifecycle manager
|
||||
gt convoy create "Feature X" issue-123 issue-456
|
||||
gt sling issue-123 myproject # Spawns polecat automatically
|
||||
gt sling issue-456 myproject # Another worker
|
||||
gt convoy list # Dashboard view
|
||||
```
|
||||
|
||||
### Pick Your Roles
|
||||
|
||||
Gas Town is modular. Run what you need:
|
||||
|
||||
Reference in New Issue
Block a user