workshop-2026-07-17 · section 04 · session replay

Watch the sessions that wrapped p

An annotated transcript: install the composer, prove every launch with dry-run, promote a second identity to a target, then hand the prompt to your own shell functions.

Part 1 — Compose first, inspect every launch

Replayed from the working sessions behind this section, condensed to the beats that matter. Every command and output below is the real capture (2026-07-16, prompt-builder v0.1.0) — regenerate any of them with the project's demo.sh; all of it is dry-run safe.

You

Install prompt-builder and alias it to p. Before it launches anything real, show me exactly what it would run.

Agent

Installed from the public repo — --locked matters, the lockfile pins patched crossterm/ratatui revisions — then asked for the launch without running it:

cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
alias p=prompt-builder
prompt-builder --dry-run --print-command "hello"
pi hello

The first beat of every session with this tool: --dry-run --print-command. Nothing is hidden behind the TUI — the exact argv is printable before anything runs.

You

I keep a second Codex identity by exporting CODEX_HOME by hand every time. Make it a launch target.

Agent

One command; it appends to the targets file and preserves whatever is already there:

prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'

On a fresh machine ~/.prompt-builder/targets.toml now reads exactly:

[[targets]]
name = "pi"
kind = "pi"

[[targets]]
name = "codex"
kind = "codex"

[[targets]]
name = "claude"
kind = "claude"

[[targets]]
name = "work-profile"
kind = "codex"

[targets.env]
CODEX_HOME = "~/.codex-work"

A target is a named launch profile — binary + env + default args. A different CODEX_HOME or CLAUDE_CONFIG_DIR is a different identity; in the TUI it's just Tab to Target ‹name›, Space to cycle.

You

And what would that target actually launch?

Agent
prompt-builder --dry-run --target work-profile --print-command "hello"
CODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello

Read that line closely: explicit Codex targets launch with a permission-bypass flag. That is the reason dry-run comes first.

The safety beat, verbatim from the session: only point p at directories where you accept the selected agent modifying files and running commands. In real output the env path expands to your full home directory.

You

I script against my tools. Give me the launch as data, not a string.

Agent
prompt-builder --dry-run --print-launch-json "hello"
{
  "schema_version": 1,
  "mode": "pi",
  "command": "pi",
  "argv": ["pi", "hello"],
  "env": {},
  "prompt": "hello",
  "pi": {"cwd": ".", "session_name": null}
}

A stable schema_version: 1 manifest — the same launch the TUI would perform, consumable by scripts. This is what "the composer is inspectable" means in practice.

Part 2 — Handoff: your shell functions become launch targets

You

Composer-to-agent is fine. But my daily move is a shell function — fork my latest Codex session and resume it. Can p hand the composed prompt to any command?

Agent

That's handoff mode. Proof with /bin/echo substituted in as the "launcher":

prompt-builder --submit --dry-run --handoff-command /bin/echo "hello from handoff"
/bin/echo 'hello from handoff'

The substitution proof: the composed prompt appears verbatim as the final argv element — passed as data (Command::arg), never through shell eval. Run this before wiring in any real command.

You

My fork helper takes flags — --fork-from, --compact. Do those survive?

Agent
prompt-builder --submit --dry-run --handoff-command /bin/echo --fork-from last --compact "continue"
/bin/echo --fork-from last --compact continue

They pass through — and in the interactive TUI they render as checkbox toggles.

The wrapper declares its own UI: --fork-from / --compact / --launch-option become toggles in the composer. Your function's flags are now form controls.

You

Now wrap it for real: bake my debugger persona into one function, and make another that composes a prompt, forks my latest Codex session, and resumes with it.

Agent

Both patterns landed in one file — pattern 1 bakes instructions into the composer; pattern 2 makes your shell function the launcher:

# Wrapping "p" (prompt-builder) with custom tools — the two patterns.
# Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh
# and the p-f/p-c family in your zsh config.

# ── Pattern 1: bake instructions into the composer ─────────────────
# The composer opens normally, but the launch carries your persona/context.
fixit() {
  prompt-builder \
    --target codex \
    -C "$PWD" \
    --developer-instructions "You're an expert debugger who always starts with the \$fusion skill. The user will pass a terse bug; investigate the behavior and fix it."
}

# ── Pattern 2: handoff mode — your shell function IS the launcher ──
# prompt-builder composes, then calls your command with the prompt as
# the final argv element (Command::arg, no shell eval).
_p_handoff_zsh() {
  local fn="${1:?Usage: _p_handoff_zsh <function> [p-args...]}"
  shift
  p \
    --handoff-command zsh \
    --handoff-arg -lc \
    --handoff-arg "source \"\$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \
    --handoff-arg "$fn" \
    "$@"
}

# Compose a prompt, then fork the latest Codex session and resume with it.
p-f() {
  local source="${CODEX_FORK_SESSION_ID:-last}"
  _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@"
}

# Same, but compact the forked session before resuming.
p-c() {
  local source="${CODEX_FORK_SESSION_ID:-last}"
  _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@"
}

# ── The mdflow lead-in ──────────────────────────────────────────────
# Every wrapper above is: instructions + context + a launch decision.
# Declare that in a markdown file instead of a shell function and you
# get an mdflow flow — reviewable, diffable, evaluable:
#
#   flows/fixit.codex.md
#   ---
#   engine: codex
#   ---
#   You're an expert debugger. Bug report: {{ _1 }}
#
# prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter
# for the fuzzy picker; flow `_inputs` render as form fields.

File landed. fixit runs daily; p-f is compose → fork → resume in one keystroke family.

Read the tail of that file again: every wrapper is instructions + context + a launch decision. Declare that in a markdown file instead of a shell function and you've invented mdflow — which is exactly where section 05 picks up. (p-f calls a private fork helper — supply your own; the pattern is the point.)