​

Exec Session Provider — Script Protocol

​

Usage

# Absolute path
export GC_SESSION=exec:/path/to/gc-session-screen

# PATH lookup
export GC_SESSION=exec:gc-session-screen

​

Calling Convention

<script> <operation> <session-name> [args...]

​

Exit Codes

​

Operations

​

Start Config (JSON on stdin)

{
  "work_dir": "/path/to/working/directory",
  "command": "claude --dangerously-skip-permissions",
  "env": {"GC_AGENT": "mayor", "GC_CITY": "/home/user/bright-lights"},
  "process_names": ["claude", "node"],
  "nudge": "initial prompt text",
  "pre_start": ["mkdir -p /workspace", "git clone repo /workspace"]
}

​

Startup Hints

• process_names — the tmux adapter polls for these process names to appear in the session’s process tree (30s timeout) before considering the agent “started.” A script can implement this by polling its backend’s process tree after session creation, or ignore it for fire-and-forget behavior (like the subprocess provider does).
• nudge — text that the tmux adapter types into the session after the agent is ready. Scripts that support interactive input can handle this in start (type the text after session creation) or leave it to the separate nudge operation which gc calls after start returns.
• pre_start — array of shell commands to run on the target filesystem before the session is created. Used for directory preparation, worktree creation, or other setup that must exist before the agent starts. Scripts should execute each command in the target environment before creating the tmux session. Non-fatal: warn on stderr if a command fails, but don’t abort start.
• session_setup — array of shell commands to run on the target filesystem after the session is created and ready, before returning. Scripts should execute each command inside the session environment (e.g. kubectl exec -- sh -c '<cmd>' for K8s, docker exec -- sh -c '<cmd>' for Docker, or plain sh -c '<cmd>' for local providers). Non-fatal: warn on stderr if a command fails, but don’t abort start.
• session_setup_script — path to a script on the controller filesystem, run after session_setup commands. For remote providers (K8s, Docker), read the file locally and pipe its contents into the session (e.g. kubectl exec -i -- sh < script). For local providers, run directly via sh -c. Non-fatal like session_setup.

• ready_prompt_prefix — prompt prefix for readiness detection (gc polls via peek after start returns)
• ready_delay_ms — fixed delay fallback (gc sleeps after start returns)
• emits_permission_warning — bypass-permissions dialog handling
• fingerprint_extra — config change detection metadata

​

Conventions

• stdin for values: set-meta, nudge, and start pass data on stdin to avoid shell quoting and argument length limits.
• stdout for results: is-running, process-alive return true/false. get-meta returns the value or empty for unset. list-running returns one name per line.
• Idempotent stop: stop must succeed (exit 0) even if the session doesn’t exist.
• Best-effort interrupt/nudge: Return 0 even if the session doesn’t exist.
• Empty = unsupported: get-last-activity returning empty stdout means the backend doesn’t support activity tracking (zero time in Go).

​

Writing Your Own Script

1. Start with contrib/session-scripts/gc-session-screen as a template.
2. Implement the operations your backend supports.
3. Return exit 2 for operations you don’t support.
4. Test with GC_SESSION=exec:./your-script gc start <city>.

​

Minimal script (start/stop/is-running only)

#!/bin/sh
op="$1"
name="$2"
case "$op" in
  start)     cat > /dev/null; my-mux new "$name" ;;
  stop)      my-mux kill "$name" 2>/dev/null; exit 0 ;;
  is-running) my-mux list | grep -q "^${name}$" && echo true || echo false ;;
  *)         exit 2 ;;
esac

​

Environment Variables

​

Shipped Scripts

• gc-session-screen — GNU screen backend. Dependencies: screen, jq, bash.