# Cfn Tmux Agents

> Launch and drive subagent CLI sessions in tmux without the fleet roster. Spawn claude/glm/codex workers, send prompts, read output, kill. Use when you want fleet-style parallel sessions without fleet's run-dir, roster, worktree, or claims machinery.

- Skill: `masharratt/cfn-tmux-agents` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx get-skill add masharratt/cfn-tmux-agents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masharratt/cfn-tmux-agents/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: masharratt (https://skillmd.com/u/masharratt)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/masharratt/cfn-tmux-agents

---


# Skill: cfn-tmux-agents

## Overview

Standalone tmux worker launcher: the spawn/send/monitor mechanics of
cfn-fleet with the coordination machinery stripped. One dedicated tmux
socket (default `tmux-agents`), one session per agent, prompts delivered
literally via `send-keys -l`.

Use when you need N parallel subagent CLI sessions (each a full `claude`,
`claude`-via-z.ai, or `codex` process) but do NOT need fleet's roster,
run-dir, worktrees, claims, or land flow. If you need commit isolation or
workstream coordination in one repo, use cfn-fleet instead.

What it keeps from fleet (all measured there):
- per-session env and pane command in a 0600 launch script; only a short `. '<dir>/launch'` is typed (a fresh macOS pty drops typed input past ~1024 bytes) and the script deletes itself before `exec` (`.claude/cfn-scripts/spawn-env.sh`); never `new-session -e`, whose values stay in the tmux server's argv where `ps` shows them to every process. `--dry-run` never prints a secret value
- folder-trust gate, banner gate, post-first-request 401 auth probe
- billing guards: claude workers strip `ANTHROPIC_*` relay vars (subscription
  billing), codex refuses a set `OPENAI_API_KEY` not covered by its unset list
- glm least-privilege unset list: z.ai panes never hold Airtable/Attio/DB/Supabase creds
- send-keys `-l` literal delivery; follow-ups send text, sleep 1, then a
  separate Enter (one-shot send+Enter leaves text unsent mid-turn)

What it drops: roster, run-dir, briefs/handoff templates, worktrees and
branches, claims/commit guard, land, watch loop, spares, dashboard.

## Usage

```bash
A=$HOME/.claude/skills/cfn-tmux-agents/execute.sh

$A spawn review-auth --engine claude-sub --cwd ~/projects/myapp \
   --prompt "review src/auth, write findings to /tmp/auth-findings.md"
$A status review-auth          # alive + last 3 pane lines
$A capture review-auth         # last 40 lines (--lines N)
$A send review-auth "also check the middleware"
$A list                        # sessions on the socket
$A kill review-auth            # one session
$A kill --all                  # whole socket (agent sessions only)
```

Subcommands and flags:

| Command | Args | Notes |
|---|---|---|
| `spawn` | `NAME` | `--engine claude-sub\|glm\|codex`, `--model M`, `--cwd DIR` (default git toplevel), `--prompt TEXT` or `--prompt-file F`, `--socket S`, `--trust-timeout S`, `--banner-timeout S`, `--dry-run`, `--bin`/`--args`/`--banner-regex` (custom engine) |
| `send` | `NAME TEXT...` | follow-up: literal text, 1s, separate Enter |
| `status` | `[NAME]` | alive/DEAD + last lines; all sessions when NAME omitted |
| `capture` | `NAME` | `--lines N` (default 40) |
| `list` | | session names on the socket |
| `kill` | `NAME` or `--all` | `--all` runs `kill-server` on the dedicated socket |

Env knobs: `TMUX_AGENTS_SOCKET` (default `tmux-agents`),
`TMUX_AGENTS_TRUST_TIMEOUT` (15), `TMUX_AGENTS_BANNER_TIMEOUT` (20),
`TMUX_AGENTS_AUTH_TIMEOUT` (12). glm token source:
`TMUX_AGENTS_ZAI_TOKEN`, or existing `FLEET_ZAI_TOKEN` / `ZAI_TOKEN`
(the skill picks those up).

Exit codes: 0 ok, 64 usage, 3 tmux missing, 65 unknown engine/session,
66 env/guard refusal or launch failure (incl. engine binary or its #!
interpreter not found on the launching shell's PATH), 68 banner timeout or
engine died before its banner (session killed; pane text and exit status
printed), 69 prompt typed but never submitted (session left alive).
Prompt submit knobs: `TMUX_AGENTS_SUBMIT_SETTLE` (1), `TMUX_AGENTS_SUBMIT_VERIFY`
(3), `TMUX_AGENTS_SUBMIT_RETRIES` (3).

### Engines

| Engine | Process | Billing/env posture |
|---|---|---|
| `claude-sub` (default; `claude` alias) | `claude --model sonnet --permission-mode bypassPermissions` | unsets all `ANTHROPIC_*` relay vars: subscription billing, never API |
| `glm` | `zai-fence.sh claude --model glm-5.3-flash --permission-mode bypassPermissions` + z.ai base URL/token; the wrapper confines the worker to its repo root (macOS sandbox, fails closed with exit 70) | needs a token var; unsets `ANTHROPIC_API_KEY` + data-system creds (Airtable/Attio/Postgres/Supabase) as least privilege |
| `codex` | `codex --sandbox workspace-write --ask-for-approval never` | unsets `OPENAI_API_KEY` (ChatGPT-plan billing); refuses a set key an engine would not unset; Codex delegation gate: refuses (exit 66) unless the target project's CLAUDE.md carries a literal `codex=true` line |

Registry: the SHARED `~/.claude/cfn-config/engines.env`, the same single
source of truth cfn-fleet reads (via its `templates/engines.env` symlink), so
the two skills can never drift apart. `lib/engines.sh` parses it. No secret
values on disk, only var names.

## Examples

Two parallel reviewers, then collect (thin prompt, fat files):

```bash
A=$HOME/.claude/skills/cfn-tmux-agents/execute.sh
printf 'Review src/auth. Write findings to /tmp/rev-auth.md and stop.\n' > /tmp/brief-auth.md
printf 'Review src/db.  Write findings to /tmp/rev-db.md and stop.\n'  > /tmp/brief-db.md
$A spawn rev-auth --prompt-file /tmp/brief-auth.md
$A spawn rev-db   --prompt-file /tmp/brief-db.md
$A status                  # poll until both panes go quiet
$A kill --all
```

Batch fan-out:

```bash
for t in api cli docs; do
  $A spawn "fix-$t" --engine glm --model glm-5.3 --prompt "fix lint errors in $t/, commit"
done
$A list
```

Codex worker (remember: codex has NO inbound messaging after spawn; the
initial prompt must be self-contained):

```bash
$A spawn impl-x --engine codex --prompt-file /tmp/brief-x.md
```

## Implementation

- `execute.sh` - dispatcher: arg parse, socket pre-scan, subcommands.
- `lib/common.sh` - socket resolution, `pane_wait` poll with noise filter
  (strips CR/blank lines and echoes of the launch command so the poll can
  never match its own send-keys), trust/banner/auth gates, guards,
  literal send helpers.
- `lib/engines.sh` - inline engine registry (7 fields, ` | ` separator),
  `$SOURCE_VAR` resolution at spawn time (exit 66 names the missing var),
  z.ai token prefill from fleet-era exports.
- Spawn order: guards and env resolution run BEFORE any side effect; then
  new-session (with `-e` env), pane command `unset <list>; exec bin args`
  (exec so the pane dies with the engine), startup gates, banner gate
  (timeout kills the session, exit 68), prompt, auth probe.
- Startup gates (one poll, dispatch on match): the codex-cli update modal
  ("Update available ... Press enter to continue") is dismissed with
  `2` then Enter (plain Enter would pick "1. Update now" = surprise
  `npm install -g`); folder-trust prompts get the engine trust_keys.
- Sessions live on a dedicated socket, never the user's default tmux
  server, so `kill --all` cannot touch unrelated sessions.

Prompt conventions (same rule as fleet): thin prompt, fat file. Keep the
in-pane prompt short; put the task body in a file the prompt names. Tell
the worker where to write output and that it should stop when done; there
is no roster heartbeat to signal completion, `status`/`capture` are the
only readback.

## Tests

```bash
$HOME/.claude/skills/cfn-tmux-agents/tests/test-agents.sh
$HOME/.claude/skills/cfn-tmux-agents/tests/test-spawn-path.sh
```

21 assertions against fake engine binaries (`tests/fake-engine.sh`,
`tests/fake-engine-modal.sh`) on a per-run socket: spawn/banner gate,
literal send-keys delivery (no shell expansion), duplicate-name refusal,
banner timeout exit 68, glm missing-token exit 66, unknown-engine/bad-name
usage codes, registry banner regexes match current TUIs, codex update-modal
dismissed with 2 (never Enter), kill and kill --all teardown. No real
claude/codex process is spawned.

Live smoke 2026-09-10: claude-sub, glm, codex all spawned, replied, and
tore down. codex-cli 0.153.4 needed the update-modal gate; the engine
field parser must split on " | " with empty fields surviving (bare-pipe
split shreds banner alternation, sed /g chews the shared space in
" | | ").

