Compose the prompt before choosing the agent — worked example

Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.

Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.

Part 1 — Compose first, inspect every launch

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

Source references