Skip to content

Gas City Capability Map — Bluefly

Generated 2026-09-16 from gc --help surface enumeration.
Source dump: gc-command-surface.txt

Classification Key

Label Meaning
✅ ALREADY USED We use this in daily workflow
🔥 USE NOW Native capability we have been replacing with glue — switch immediately
🧪 NEEDS EXPERIMENT Clearly relevant, surface not yet fully understood
🔄 REPLACES CUSTOM GLUE Explicit replacement for something we invented
⬜ NOT RELEVANT YET Low priority for current Bluefly phase

Command Surface

gc agent — Configuration

add · list · resume · suspend

🔥 USE NOW

  • gc agent list = canonical inventory of all configured agents. We have been reading city.toml by hand.
  • gc agent suspend / gc agent resume = per-agent scheduling without editing config. We have been manually commenting out agents.
  • gc agent add = scaffold a new agent. We have been writing agent TOML by hand from memory.

Replaces: manual city.toml grep, ad-hoc agent disabling by config edit.

gc agent-script — Deterministic YAML Execution

--script <path>
Status: experimental

🧪 NEEDS EXPERIMENT

A YAML-driven runner that probes gc hook, selects a turn, and executes configured actions. Gas City owns this runner — repo examples can be tested without external helper binaries.

Replaces (potentially): custom shell glue around formulas, demo scripts, CI integration test helpers.

[!IMPORTANT] lifecycle = "one_shot" in agent config makes the runtime treat clean script exit as work completion, not startup death. We need this for CI-driven formula tests.

gc analyze — Observability Reports

reliability

🔥 USE NOW

  • gc analyze reliability = correlates session-lifecycle events with model/version/rig. This is the native failure-rate and reliability report.

Replaces: manual event log parsing, ad-hoc grep forensics.

gc beads — Beads Topology & Health

city · health · list · show

✅ ALREADY USED (partially — gc bd alias used more often)

  • gc beads city = manages canonical city endpoint topology — this is the authoritative path for setting which Dolt endpoint Beads uses, not manual config edits.
  • gc beads health = structured health check with API-routing and bd fallback. Should be the standard health check in all runbooks.

Replaces: gc-beads-health shell alias (which is a thin wrapper).

gc config — Config Inspection

explain · show

✅ ALREADY USED

  • gc config explain is underused — it shows provenance of every config value. Invaluable for debugging pack composition conflicts.

gc converge — Bounded Iterative Refinement

approve · create · iterate · list · retry · status · stop · test-gate · test-trigger

🧪 NEEDS EXPERIMENT — HIGH VALUE

A convergence loop = root bead + formula + gate that repeats until gate passes or max iterations reached. Controller-driven. This is a native CI-style gate mechanism built into Gas City.

Replaces (potentially): - Manual "run formula → check → re-run" loops - Custom CI polling scripts - The ad-hoc "keep iterating until it works" anti-pattern

test-gate and test-trigger are dry-run commands — safe to run alongside live controller.

gc convoy — Work Topology

add · check · close · control · create · delete · delete-source · land · list · reopen-source · status · stranded · target

✅ ALREADY USED (partially)

High-value underused subcommands: - gc convoy stranded = find convoys with ready work but no workers — the READY_BEADS>0 AND IDLE_AGENTS>0 = FAILURE detector. Should run on every shift start. - gc convoy control = executes control beads or runs the control-dispatcher loop. We have been waking Blu manually. - gc convoy land = land an owned convoy (terminate + cleanup). We have been doing this manually. - gc convoy check = auto-close convoys where all issues are closed. Should be automated via gc order.

gc costs — Usage & Cost Observability

(single command)

🔥 USE NOW

Reads .gc/usage.jsonl, groups by run, shows estimated cost. Zero friction — just run it. We have no current cost visibility.

gc doctor — Workspace Health

--fix · --verbose · --json · --explain-postgres-auth

🔥 USE NOW

This is the canonical remediation path: - Checks config validity, binary deps (tmux, git, bd, dolt), controller status, zombie/orphan sessions, bead stores, Dolt server health, event log integrity. - gc doctor --fix = safe mechanical auto-repair including legacy-to-current pack rewrites. - gc doctor --verbose for investigation.

We should run gc doctor before every major deployment and after every merge to release.

gc event — Emit Events

emit

🧪 NEEDS EXPERIMENT

gc event emit = write an event to the city event log from agent code or scripts. This is the native observability injection point. Useful for custom milestone events, audit trails from scripts.

gc events — Event Stream

rotate
Flags: --follow · --watch · --type · --since · --payload-match · --after-cursor

✅ ALREADY USED (via gc-events-follow alias)

Significantly underused flags: - --payload-match key=value = filter events by payload field without grep. - --watch --type <event> = block until a specific event type arrives. This is a native event-driven wait — replaces polling loops. - --after-cursor = resume event stream from a cursor. Enables reliable event replay.

Replaces: sleep+poll loops waiting for state transitions.

gc extmsg — External Conversation Binding

bind · handoff · unbind

🧪 NEEDS EXPERIMENT

Binds Telegram/Discord/external conversations to agent sessions. Bindings survive session restarts — inbound messages cold-wake the agent. handoff rebinds a conversation to a specialist (front-desk pattern).

This is the native external messaging integration. We have been considering building this ourselves.

gc formula — Formula Management

cook · list · show · version-check

✅ ALREADY USED (partially)

Underused: - gc formula version-check <bead> = checks if a bead's formula matches current on-disk version. Safety check before re-running formulas on existing beads. - gc formula show = dump compiled recipe. Useful for debugging formula composition.

gc graph — Dependency Visualization

--tree · --mermaid · --json

🔥 USE NOW

gc graph <convoy-id> --mermaid produces a Mermaid.js flowchart. Direct paste into docs/markdown. We have been drawing dependency graphs by hand.

gc graph <bead-ids> --tree for Unicode tree view in terminal.

gc handoff — Context Handoff

--target · --auto · --hook-format

🧪 NEEDS EXPERIMENT — IMPORTANT

  • Self-handoff: sends mail to self + requests controller restart. Native context compaction handoff for controller-restartable sessions.
  • Remote handoff (--target): sends mail to target + kills it for restart with mail waiting. This is the native agent-to-agent handoff mechanism.
  • Auto handoff (--auto): for PreCompact hooks — sends mail without requesting restart.

Replaces: manual gc mail send + gc session kill sequences. This is the correct atomic handoff path.

gc hook — Work Routing

run
Flags: --claim · --drain-ack · --inject

✅ ALREADY USED (agents use this in hooks)

  • gc hook --claim = atomic claim of one routed work item for the current session. This is the correct startup claim protocol, not manual bd update.
  • gc hook run = run a managed hook command with hard timeout. Safer than raw hook scripts.

gc import — Pack Import Management

add · check · credential · install · list · prune · remove · status · upgrade · why

✅ ALREADY USED

Underused: - gc import check = validate installed pack import state. Should run after every gc import install. - gc import why <name> = explain why an import is present. Invaluable for debugging transitive import conflicts. - gc import prune = remove unreferenced clones from global pack cache. Should run periodically. - gc import upgrade = upgrade packs within constraints. We have been doing this manually.

gc mail — Agent Messaging

archive · check · count · delete · inbox · mark-read · mark-unread · peek · read · reply · send · thread

✅ ALREADY USED

Underused: - gc mail check --inject = hook output format for delivering mail notifications into agent prompts. Should be in every agent's startup hook. - gc mail thread <id> = full conversation thread view. - gc mail peek <id> = read without marking read. Useful for inspection without consuming.

gc maintenance — Dolt Store Health

dolt-gc · status

🔥 USE NOW

  • gc maintenance status = shows maintenance loop state and recent runs. We have no current maintenance visibility.
  • gc maintenance dolt-gc = trigger manual Dolt GC run through the governed path — not ad-hoc dolt gc. This is the safe, doltsafety-compliant trigger.

[!CAUTION] Always use gc maintenance dolt-gc, never raw dolt gc. The governed path enforces the storage runway safety check.

gc mcp — MCP Projection Inspection

list
Flags: --agent · --session

🔥 USE NOW

gc mcp list --agent <name> = shows exactly which MCP servers are projected to an agent. We have been guessing at MCP projection by reading config. This is the authoritative view.

gc nudge — Deferred Nudge Inspection

status

🧪 NEEDS EXPERIMENT

Shows queued and dead-letter nudges for a session. Useful for diagnosing "why didn't the agent respond?" — nudges may have been queued but not delivered.

gc order — Scheduled/Event-Driven Dispatch

check · history · list · run · show · sweep-nudge-mail · sweep-tracking
Trigger types: cooldown · cron · condition · event · manual

🔥 USE NOW — HIGH VALUE

This is the native scheduler. Orders live in orders/<name>.toml, pair a trigger with a formula or exec script.

Replaces (immediately): - Any cron jobs we run outside Gas City - Manual periodic maintenance triggers - Custom "run this formula every N hours" scripts

Specific candidates for orders: - gc convoy check → order on cron to auto-close completed convoys - gc order sweep-nudge-mail → already exists, close stale mail/nudge beads - gc import upgrade → weekly order - gc maintenance dolt-gc → weekly order (with storage runway check) - gc doctor → daily health check order

gc order run <name> = manual execution of any order. Useful for one-off triggers.

gc pack — Remote Pack Sources

fetch · list · registry · release

✅ ALREADY USED (partially)

  • gc pack registry = manage pack registries. We have not explored whether Bluefly has a private registry configured.
  • gc pack release = author pack registry release metadata. Relevant when we publish blucity-packs as a consumable pack.

gc prime — Prompt Rendering

--strict · --hook · --hook-format · --json

✅ ALREADY USED

--strict already used in CI. --hook-format for provider-specific formatting not yet explored.

gc prompt — Prompt Authoring

synth

🧪 NEEDS EXPERIMENT

gc prompt synth = invoke the configured LLM in one-shot mode to generate a prompt template for a given role. This is a native prompt-generation tool.

gc reload — Live Config Reload

--soft · --async · --timeout

✅ ALREADY USED

--soft is critical and underused: accepts config drift on open sessions without draining them. Use when editing .gc/settings.json or pack fragments during a live city to avoid disrupting in-flight work.

gc rig — Rig Management

add · list · remove · restart · resume · set-endpoint · status · suspend

✅ ALREADY USED (partially)

  • gc rig set-endpoint = set canonical endpoint ownership for a rig. This is the authoritative path for Dolt per-rig topology — not config file edits.
  • gc rig suspend / gc rig resume = freeze a rig without touching agents. Useful during deployments.
  • gc rig status = per-rig health with agent running state.

gc runtime — Session Lifecycle (Agent-Internal)

check · conformance · drain · drain-ack · drain-check · heartbeat · request-restart · undrain

🧪 NEEDS EXPERIMENT

Designed to be called from within running agent sessions. Key commands: - gc runtime heartbeat = extend idle-timeout during long operations. Prevents premature session kills. - gc runtime request-restart = request controller restart (used by gc handoff). - gc runtime drain / gc runtime undrain = graceful wind-down signaling. - gc runtime check = validate a Runtime Provider Protocol executable — humans and CI use this. - gc runtime conformance = golden RPP conformance suite — native runtime provider testing.

gc service — Workspace Services

doctor · list · restart

🔥 USE NOW

gc service list = see all workspace services (Dolt, API, controller, etc.) without grepping process lists.
gc service doctor = detailed status per service.
gc service restart <name> = targeted service restart without full city restart.

Replaces: manual ps aux | grep dolt, doltwhere, doltstatus aliases.

gc session — Session Management

attach · close · kill · list · logs · new · nudge · peek · pin · prune · rename · reset · submit · suspend · unpin · wait · wake

✅ ALREADY USED (partially)

Underused commands of high value: - gc session logs <id> = session logs without SSH or tmux. - gc session peek <id> = view output without attaching. - gc session pin / gc session unpin = keep a session awake (prevent sleep). - gc session submit <msg> = deliver a message with semantic delivery intent — not just a nudge. - gc session wait = register a dependency wait for a session. Native durable wait mechanism. - gc session prune = close old dormant sessions. Should be in a periodic order.

gc sling — Work Routing

Full flag surface: --formula · --var · --on · --nudge · --merge · --no-convoy · --owned · --scope-kind · --scope-ref · --stdin · --dry-run

✅ ALREADY USED (basic form)

Underused: - --dry-run = show what would be done without executing. Use before any new sling pattern. - --var key=value = variable substitution for formula. We have been hardcoding formula vars. - --stdin = read bead text from stdin. Enables piped workflow construction. - --merge = specify merge strategy (direct, mr, local). We have been using the default. - --on <formula> = attach a wisp from a formula to an existing bead before routing. - --nudge = nudge target after routing. Atomic route + wake.

gc supervisor — Machine-Wide Supervisor

install · logs · reload · run · start · status · stop · uninstall

✅ ALREADY USED (implicitly — supervisor manages all cities)

  • gc supervisor logs = tail supervisor log. We have been navigating to log files manually.
  • gc supervisor reload = trigger immediate reconciliation of all cities. Faster than restart.
  • gc supervisor install = install as platform service. Should be configured for auto-start.

gc trace — Reconciler Trace

cycle · reasons · show · start · status · stop · tail

🔥 USE NOW — FORENSICS

The session reconciler trace stream. Persisted under .gc/runtime/session-reconciler-trace, works even when controller is offline.

  • gc trace start <template> = enable tracing for a session template.
  • gc trace tail = follow trace records live.
  • gc trace reasons = show reason codes observed. This explains why the reconciler is making decisions — why a session was killed, restarted, drained.
  • gc trace cycle <tick-id> = inspect a specific reconciler tick.

Replaces: reading raw controller logs to understand session lifecycle decisions.

gc wait — Durable Session Waits

cancel · inspect · list · ready

🧪 NEEDS EXPERIMENT

Durable waits registered by gc session wait. Inspector for wait state: - gc wait list = see all registered waits. - gc wait ready <id> = manually mark a wait ready (unblock a session). - gc wait inspect <id> = wait details.

Replaces: manual dependency polling or "check if X is done" scripts.

gc whoami — Hosted Account

--at · --token

⬜ NOT RELEVANT YET

For hosted Gas City (gascity.com) auth. Relevant only if/when Bluefly runs a hosted city. Oracle is self-hosted.

What We Should Stop Doing

What we've been doing Use instead
Manually reading city.toml to see agents gc agent list
Commenting out agents in config to disable gc agent suspend
SSH + ps aux to check Dolt/services gc service list, gc service doctor
Manual dolt gc for store cleanup gc maintenance dolt-gc
Sleep+poll loops waiting for events gc events --watch --type <event>
Drawing dependency graphs by hand gc graph <convoy> --mermaid
gc mail send + gc session kill for handoff gc handoff --target <session>
Guessing at MCP projection gc mcp list --agent <name>
Grepping controller logs for session decisions gc trace reasons, gc trace tail
Custom cron outside Gas City gc order with cron trigger
Manual periodic maintenance gc order wrapping gc maintenance dolt-gc
gc convoy stranded never checked Run it on every shift start
gc doctor never used Run before every deployment

Immediate Next Actions (Priority Order)

  1. gc doctor --verbose → baseline health check, see what auto-repair recommends
  2. gc convoy stranded → find any ready work with no workers right now
  3. gc service list → canonical service inventory
  4. gc costs → first look at usage cost
  5. gc analyze reliability → first reliability report
  6. gc trace start organization.mayor → enable reconciler tracing for Mayor
  7. Draft orders for: convoy check, session prune, maintenance dolt-gc, import upgrade
  8. gc converge --help deep dive → test gate/trigger model against the bc-3c4 proof gates
  9. gc agent-script experiment → prototype one deterministic formula test in YAML
  10. gc extmsg → investigate whether external conversation binding replaces planned integration work

Gate 4 Flag (from bc-3c4 proof)

gastown.boot, gastown.deacon, and all gastown.witness agents still registered — this is the Platform Rename Program (du-dj2). These sessions are asleep but still configured. Gate 4 for bc-3c4 needs a decision:

  • Are gastown.* names allowed to coexist with organization.* names during transition?
  • Or must all gastown.* session configs be removed before Gate 4 passes?

This is a bead question, not a blocker — record and continue.