playbooks

home / skills / tkersey / dotfiles / puff

puff skill

/codex/skills/puff

This skill launches Codex Cloud tasks from the CLI, manages detached watchers, and fetches results for local application.

npx playbooks add skill tkersey/dotfiles --skill puff

Review the files below or copy the command above to add this skill to your agents.

Files (4)
SKILL.md
2.7 KB
---
name: puff
description: Launch and manage Codex Cloud tasks from the CLI, including detached background watchers that track completion. Use when users ask to run coding work in cloud/background agents, queue multiple cloud tasks, poll task status, fetch cloud diffs, apply cloud outputs locally, or pair cloud kickoff with `$cas` orchestration.
---

# Puff

## Overview

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

## Workflow

1. Ensure ChatGPT auth is present.
`codex login`
2. Resolve skill paths (`.codex` primary, `.claude` fallback).
```bash
CODEX_SKILLS_HOME="${CODEX_HOME:-$HOME/.codex}"
CLAUDE_SKILLS_HOME="${CLAUDE_HOME:-$HOME/.claude}"
PUFF_SCRIPT="$CODEX_SKILLS_HOME/skills/puff/scripts/puff.sh"
[ -f "$PUFF_SCRIPT" ] || PUFF_SCRIPT="$CLAUDE_SKILLS_HOME/skills/puff/scripts/puff.sh"
```
3. Run readiness checks.
`"$PUFF_SCRIPT" doctor --env <env-id-or-label>`
Optional: print manual environment-creation instructions.
`"$PUFF_SCRIPT" create`
4. Launch cloud work with a detached watcher.
`"$PUFF_SCRIPT" launch --env <env-id-or-label> --prompt "Implement X"`
5. Inspect running and completed watcher jobs.
`"$PUFF_SCRIPT" jobs`
6. Tail watcher logs when needed.
`tail -f <watch_log_path>`
7. 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.

## Interop With `$cas`

Use `$cas` when orchestration requirements exceed simple cloud task lifecycle control.
Use `$puff` for fast cloud kickoff and lifecycle polling.
Use `$puff` `cas-start` / `cas-stop` to manage the `$cas` proxy lifecycle from the same wrapper.
Use `$cas` for app-server thread/turn orchestration, steering, forwarding server requests, or complex multi-thread routing.

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

## Resources

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

Overview

This skill launches and manages Codex Cloud tasks from the CLI, enabling detached background watchers that track task completion. It provides a small wrapper to submit cloud work, retain logs/results, and later inspect diffs or apply outputs locally without blocking the terminal.

How this skill works

The wrapper runs readiness checks, submits tasks to Codex Cloud, and can spawn detached watcher processes that poll for status and stream logs to files. Completed tasks are preserved so you can run codex cloud diff or codex cloud apply later. It also offers foreground watch, job listing, and stop controls, plus optional integration with a $cas orchestration proxy.

When to use it

  • Kick off coding work in cloud agents without blocking your local shell
  • Queue multiple cloud tasks and let background watchers track each one
  • Poll task status and tail watcher logs independently from submission
  • Fetch diffs and apply cloud-generated changes to the local repository
  • Start or stop a paired $cas proxy when orchestration is needed

Best practices

  • Run codex login before launching tasks to ensure authentication is available
  • Use launch for detached execution; use submit when you only need the task id
  • Let launch run doctor by default to catch environment or auth issues; use --skip-doctor only when safe
  • Treat READY and APPLIED as successful terminals and ERROR as a failure to investigate
  • Store and inspect watcher log files (tail -f) to troubleshoot long-running jobs

Example use cases

  • Submit a feature implementation to Codex Cloud, detach a watcher, and continue local work
  • Queue several refactor tasks, list jobs to track progress, and apply completed changes selectively
  • Run puff doctor to validate environment before mass task submission
  • Pair a rapid cloud kickoff with cas-start to enable complex orchestration for a set of tasks
  • Use codex cloud diff <task-id> to review changes from a finished cloud run before applying

FAQ

What command launches a task in the background?

Use puff launch --env <env-id-or-label> --prompt "..." to run submission with a detached watcher.

How do I inspect or apply a finished task?

Run codex cloud diff <task-id> to inspect and codex cloud apply <task-id> to apply the changes locally.