Menu
Managing agents — list, peek, nudge, suspend, drain
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Project conventions for writing, editing, restructuring, or reviewing the Gas City user documentation — the Mintlify site under docs/. Use this whenever you touch anything in docs/ (pages, tutorials, guides, reference, concept pages, diagrams, navigation) or write/edit prose about Gas City, even when the request is just "fix the docs", "write a docs page", "the docs are wrong/confusing", "rename X across the docs", or an edit to a file under docs/. It defines the canonical six-primitive model, required terminology (orchestrator not controller, platform not SDK, formulas v2 as the value), the prose / emphasis / diagram conventions, the information architecture, the rule that generated docs are edited at their source, and the gates to run before docs work is done.
Routing work to agents with gc sling and formulas
Finding, creating, claiming, and closing work items (beads)
API server and web dashboard — config, start, monitor
City lifecycle — status, start, stop, init
Sending and reading messages between agents
| name | gc-agents |
| description | Managing agents — list, peek, nudge, suspend, drain |
Agents are the workers in a Gas City workspace. Each runs in its own session (tmux pane, container, etc).
gc agent add --name <name> # Scaffold agents/<name>/prompt.template.md
gc agent add --name <name> --dir <rig> # Scaffold a rig-scoped agent.toml
gc agent add --name <name> --prompt-template <file>
Every configured template can now spawn sessions directly.
For cities migrating off the old multi-instance model, see
engdocs/archive/migrations/remove-agent-multi-migration.md.
Use the session commands directly:
gc session new <template> # Create and attach to a new session
gc session new <template> --no-attach # Create a detached background session
gc session suspend <id-or-template> # Suspend a session
gc session close <id-or-template> # Close a session permanently
gc session kill <name> # Force-kill an agent session
gc session nudge <name> <message...> # Send text to a running agent session
gc session logs <name> # Show session logs for an agent
When multiple sessions exist for the same template, use the session ID.
Pools still control controller-managed worker capacity. Pool max
limits pool-managed workers, not manually created interactive sessions.
gc agent suspend <name> # Suspend agent (reconciler skips it)
gc agent resume <name> # Resume a suspended agent
gc runtime drain <name> # Signal agent to wind down gracefully
gc runtime undrain <name> # Cancel drain
gc runtime drain-check <name> # Check if agent has been drained
gc runtime drain-ack <name> # Acknowledge drain (agent confirms exit)
gc runtime request-restart # Request graceful restart (reads GC_AGENT env)