Puff

Overview

Use this skill to launch Codex Cloud tasks without blocking the local CLI session. Use run_puff_tool to run the Zig puff CLI, submit work, detach status watchers, and retain logs/results for later diff/apply actions.

Zig CLI Iteration Repos

When iterating on the Zig-backed puff helper CLI path, use these two repos:

skills-zig (/Users/tk/workspace/tk/skills-zig): source for the puff Zig binary, build/test wiring, and release tags.
homebrew-tap (/Users/tk/workspace/tk/homebrew-tap): Homebrew formula updates/checksum bumps for released puff binaries.

Quick Start

run_puff_tool() {
  install_puff_direct() {
    local repo="${SKILLS_ZIG_REPO:-$HOME/workspace/tk/skills-zig}"
    if ! command -v zig >/dev/null 2>&1; then
      echo "zig not found. Install Zig from https://ziglang.org/download/ and retry." >&2
      return 1
    fi
    if [ ! -d "$repo" ]; then
      echo "skills-zig repo not found at $repo." >&2
      echo "clone it with: git clone https://github.com/tkersey/skills-zig \"$repo\"" >&2
      return 1
    fi
    if ! (cd "$repo" && zig build -Doptimize=ReleaseSafe); then
      echo "direct Zig build failed in $repo." >&2
      return 1
    fi
    if [ ! -x "$repo/zig-out/bin/puff" ]; then
      echo "direct Zig build did not produce $repo/zig-out/bin/puff." >&2
      return 1
    fi
    mkdir -p "$HOME/.local/bin"
    install -m 0755 "$repo/zig-out/bin/puff" "$HOME/.local/bin/puff"
  }

  local os="$(uname -s)"
  if command -v puff >/dev/null 2>&1 && puff --help 2>&1 | grep -q "puff.zig"; then
    puff "$@"
    return
  fi

  if [ "$os" = "Darwin" ]; then
    if ! command -v brew >/dev/null 2>&1; then
      echo "homebrew is required on macOS: https://brew.sh/" >&2
      return 1
    fi
    if ! brew install tkersey/tap/puff; then
      echo "brew install tkersey/tap/puff failed." >&2
      return 1
    fi
  elif ! (command -v puff >/dev/null 2>&1 && puff --help 2>&1 | grep -q "puff.zig"); then
    if ! install_puff_direct; then
      return 1
    fi
  fi

  if command -v puff >/dev/null 2>&1 && puff --help 2>&1 | grep -q "puff.zig"; then
    puff "$@"
    return
  fi
  echo "puff binary missing or incompatible after install attempt." >&2
  if [ "$os" = "Darwin" ]; then
    echo "expected install path: brew install tkersey/tap/puff" >&2
  else
    echo "expected direct path: SKILLS_ZIG_REPO=<skills-zig-path> zig build -Doptimize=ReleaseSafe" >&2
  fi
  return 1
}

Workflow

Ensure ChatGPT auth is present. codex login
Run readiness checks. run_puff_tool doctor --env <env-id-or-label> Optional: print manual environment-creation instructions. run_puff_tool create
Launch cloud work with a detached watcher. run_puff_tool launch --env <env-id-or-label> --prompt "Implement X" Optional: launch the cloud Join operator prompt (seq -> join) for PR patch routing. run_puff_tool join-operator --env <env-id-or-label> --repo <owner/repo> --patch-inbox <locator> Canary mode (single bounded cycle): run_puff_tool join-operator --env <env-id-or-label> --repo <owner/repo> --patch-inbox <locator> --canary
Inspect running and completed watcher jobs. run_puff_tool jobs
Tail watcher logs when needed. tail -f <watch_log_path>
Inspect or apply result when ready. codex cloud diff <task-id> codex cloud apply <task-id>

Command Selection

Use launch for async/background execution. launch runs doctor by default; pass --skip-doctor to bypass pre-checks. Use create when you need formatted manual environment-creation instructions only. Use submit when only task id/url is needed (it executes a cloud task). Use doctor for explicit auth/environment readiness checks. Use watch for blocking foreground polling. Use jobs and stop to manage detached watchers. Use join-operator to generate and launch the cloud join loop prompt that enforces manifest-first routing and seq -> join execution. Use join-operator --max-cycles <n> for bounded runs; --canary is shorthand for one cycle.

Interop With `$cas`

Use $cas when orchestration requirements exceed simple cloud task lifecycle control. Use $puff for fast cloud kickoff and lifecycle polling. Use $cas directly for app-server smoke checks, thread/turn orchestration, multi-instance routing, or swarm conformance around $st claims and $mesh reconciliation.

Notes

Pass either environment id or unique environment label to --env. Treat READY and APPLIED as successful terminal states in watch loops. Treat ERROR as terminal failure and inspect with codex cloud status <task-id> and codex cloud diff <task-id>. Runtime bootstrap policy for puff mirrors seq/cas/lift: use the Zig puff binary only, default to Homebrew install on macOS, and fallback to direct Zig install from skills-zig on non-macOS.

Resources

puff binary: create/submit/watch/launch/jobs/stop wrapper around codex cloud.
references/commands.md: command map including optional $cas pairing.

puff