# Gc Agents

> Managing agents — list, peek, nudge, suspend, drain

- Skill: `gastownhall/gc-agents` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gastownhall/gc-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gastownhall/gc-agents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gastownhall (https://skillmd.com/u/gastownhall)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gastownhall/gc-agents

---


# Agent Management

Agents are the workers in a Gas City workspace. Each runs in its own
session (tmux pane, container, etc).

## Adding agents

```
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>
```

## Sessions from templates

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

Pools still control controller-managed worker capacity. Pool `max`
limits pool-managed workers, not manually created interactive sessions.

## Lifecycle

```
gc agent suspend <name>                # Suspend agent (reconciler skips it)
gc agent resume <name>                 # Resume a suspended agent
```

## Runtime

```
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)
```