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.
Install prompt-builder and alias it to p. Before it launches anything real, show me exactly what it would run.
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.
I keep a second Codex identity by exporting CODEX_HOME by hand every time. Make it a launch target.
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.
And what would that target actually launch?
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.
I script against my tools. Give me the launch as data, not a string.
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
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?
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.
My fork helper takes flags — --fork-from, --compact. Do those survive?
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.
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.
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.)