workshop-2026-07-17 · section 04

Prompt Builder: Compose First, Launch Anywhere

One terminal composer (p) in front of Pi, Codex, and Claude Code — and the shell-wrapper pattern that turns into mdflow.

TL;DR

🤖 Have your agent set this up — paste this into it:

Fetch https://shiny-bloom-f8hv.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.

Quick start

# needs a Rust toolchain (rustup); pi/codex/claude CLIs are optional for dry-runs
cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
alias p=prompt-builder
p --dry-run --print-command "hello"    # prints the exact launch: pi hello
p                                      # open the composer: $ skills · @ files · Ctrl+R history

Prompt library

The fixit debugger persona

Codex, launched through p --target codex --developer-instructions "…" the project with the bug the composer opens; whatever terse bug you type launches Codex carrying this persona

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.

Have your agent write you a handoff wrapper

any coding agent (Claude Code, Codex, Pi) wherever your shell config lives a new shell function whose launch is proven with the /bin/echo substitution test before anything real runs

Write me a zsh wrapper function that opens prompt-builder in handoff mode and hands my composed prompt to my own shell function. Use this pattern: prompt-builder --handoff-command <cmd> --handoff-arg <arg> passes the prompt as the final argv element with no shell eval. Before wiring in the real command, prove the wrapper with: prompt-builder --submit --dry-run --handoff-command /bin/echo "test" — my prompt must appear verbatim as the final echoed argument. Show me that proof, then swap the real command in. The repeated move I want to wrap: <describe your move>.

Add a second-account launch target

any coding agent with shell access anywhere a new target in targets.toml and a printed launch command carrying CLAUDE_CONFIG_DIR

Add a prompt-builder launch target for a second Claude Code account: run prompt-builder target add second-account --kind claude --env 'CLAUDE_CONFIG_DIR=~/.claude-second' and then verify it with prompt-builder --dry-run --target second-account --print-command "hello". Show me the printed command so I can read the exact argv before any real launch.

Set it up (agent guide)

These steps mirror agent.md — the machine copy your agent fetches.

  1. Install the composer and alias it to p. Keep --locked: the lockfile pins patched crossterm/ratatui revisions.
    cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
    echo 'alias p=prompt-builder' >> ~/.zshrc
    source ~/.zshrc
  2. Add one launch target for an agent or account you already switch to by hand.
    prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'
    This writes ~/.prompt-builder/targets.toml. On a fresh machine the file 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"

Success check: print the launches without running anything, then list the targets.

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

In real output the CODEX_HOME path appears expanded to your full home directory. Read the second line closely — that bypass flag is the reason dry-run comes first.

One composer in front of every agent

Count where your prompts get written: for most agent-CLI users, all of them live inside one agent's interactive loop. The prompt — the thing that carries your intent — has no home of its own; switch agents and you abandon your history, paste handling, and muscle memory.

prompt-builder is a small Ratatui composer whose only job is composing: skill lookup, file search, slash commands, paste handling, and history that follows you, not the agent — it reads Codex's own ~/.codex/history.jsonl alongside its private file, so prompts from either tool come back with Ctrl+R. The agent is just a selector at the bottom of the screen. Targets are named launch profiles — binary, env vars, model, default args — stored in ~/.prompt-builder/targets.toml; a different CODEX_HOME or CLAUDE_CONFIG_DIR is a different identity.

$ prompt-builder target list
pi              pi      bin=pi
codex           codex   bin=codex
claude          claude  bin=claude
work-profile    codex   bin=codex   CODEX_HOME=~/.codex-work
second-account  claude  bin=claude  CLAUDE_CONFIG_DIR=~/.claude-second

The test for whether this matters: the next time you re-type a prompt into a second agent because the first one stalled, you've found the cost this tool removes.

Every launch is inspectable before it runs

A tool that launches agents for you earns trust only if you can see exactly what it would run. Every launch path has a dry-run twin: --print-command shows the exact argv; --print-launch-json emits a stable schema_version: 1 manifest for scripts.

$ prompt-builder --dry-run --print-command "hello"
pi hello

$ 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}
}

Codex and Claude targets launch with permission-bypass flags — only point them at directories where you accept the agent modifying files and running commands (details in the appendix). Before trusting any target you add, run it once with --dry-run --print-command and read the argv aloud.

Handoff mode turns shell functions into launch targets

The interesting move is handoff mode: --handoff-command with repeatable --handoff-arg makes the composer call any command with the submitted prompt as the final argv element — passed as data, never through shell eval.

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

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

Those --fork-from/--compact flags render as checkbox toggles in the TUI — the wrapper declares its own UI. Two patterns run daily in the author's shell: fixit bakes a debugger persona into the composer, and p-f composes a prompt, then forks the latest Codex session and resumes it with that prompt. Here is the workshop's copy of both, complete — this page is the file's source (the repo's examples/ ships only fixit.zsh; lift p-wrap.zsh from the block below):

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

To adopt the pattern, write one wrapper for a move you repeat and prove it with --submit --dry-run --handoff-command /bin/echo substituted in: your prompt must appear verbatim as the final echoed argument. When it does, swap the real command back in. (p-f calls the author's private fork helper — supply your own; see the appendix.)

A wrapper is a file format waiting to happen

Look at what every wrapper above actually is: instructions, plus context, plus a launch decision. Why is that a shell function and not a file? Shell functions hide in dotfiles; files can be diffed, reviewed, shared, and gated with evals. That's mdflow: each repeatable agent job as a markdown file, run on the CLI engine you already use. The fixit wrapper restated as a flow looks like this:

--- flows/fixit.codex.md ---
engine: codex
---
You're an expert debugger. Bug report: {{ _1 }}

The same job also ships in a third form: an agent skill. The full progression is fixit.zsh (shell wrapper) → flows/fixit.codex.md (mdflow flow) → fixit (SKILL.md) — pick whichever your stack runs on. The skill twin is hosted on this site; install it by staging anywhere except a dir named skills/ (the skills CLI claims that name as its own symlink target and you'd install an empty skill):

mkdir -p skill-src/fixit
curl -fsSL "https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw" -o skill-src/fixit/SKILL.md
npx skills add ./skill-src --skill fixit -y

The bridge already exists in the composer: with the mdflow CLI on PATH, a Flow ‹name› selector appears beside the target selector, Enter opens a fuzzy picker, and a flow's inputs render as form fields. A ⚠ ignores prompt badge warns when a flow never references {{ _1 }}/{{ _prompt }} — mdflow would silently drop your prompt. The promotion rule: when a wrapper survives unchanged for a few weeks, move it into a flow file. If it keeps changing, it isn't ready — keep it in the shell.

Appendix

Limits & caveats
  • Permission bypass: explicit Codex targets launch with --dangerously-bypass-approvals-and-sandbox; Claude targets launch with claude --dangerously-skip-permissions -- <prompt>. Pi targets add no bypass flag and rely on Pi's own trust settings. Only use these launchers in directories where you accept the selected agent modifying files and running commands.
  • The flow file shown in the last story section is a constructed illustration, not a file shipped by either project — that's why it carries the "example — don't paste" badge. mdflow's own README shows the same shape (review.md, review.claude.md, git diff | explain.md).
  • The fixit persona references $fusion, the author's personal skill. Swap in a skill you actually have, or drop that clause.
  • p-f/p-c call _codex_prompt_builder_fork, a private helper in the author's zsh config. The wrappers are printed as evidence of the pattern; to use them, point _p_handoff_zsh at your own function.
  • Success-check outputs show ~/.codex-work for readability; real output expands env paths to your full home directory. Target names work-profile and second-account are genericized stand-ins for the author's personal profiles.
  • All output was captured 2026-07-16 from prompt-builder v0.1.0; TUI details may drift in later versions. Claude targets currently ignore conversation names and Codex-only options with a warning; Claude fork/resume orchestration is future work — that's exactly what handoff wrappers cover today.
  • Claims about mdflow are limited to its README introduction. The "wrappers are proto-flows" promotion rule is the author's editorial inference, not something either README states.
  • The default target is Pi; real submissions fail without the Pi CLI on PATH, though every --dry-run/print flag works with no agent CLIs installed.
Provenance

Sources: S1 — the prompt-builder README (features, shortcuts, targets, handoff mode, mdflow selector, safety flags) at github.com/johnlindquist/prompt-builder; S2 — the project's shipped examples/fixit.zsh; S3 — wrapper functions (p-f, p-c, _p_handoff_zsh) from the author's working zsh configuration, printed here via the workshop's examples/p-wrap.zsh copy; S4 — live command output regenerated 2026-07-16 from prompt-builder v0.1.0, with personal profile names genericized and home paths shown as ~; S5 — the mdflow README introduction; S6 — the workshop agenda brief, used for framing only. No session identifiers, emails, or credentials appear. JavaScript on this page is one canonical code-copy enhancement (app.js); the page reads fully without it. Published to here.now as "workshop-2026-07-17 04-prompt-builder".