Compose the prompt before choosing the agent — questions and tradeoffs

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

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

The questions, in the order the room asks them

I already compose prompts inside Claude Code. Why does the prompt need a separate tool?

Because the prompt is the actual work product, and right now it lives inside someone else's REPL. Switch agents and you abandon your history, your paste handling, your muscle memory. p decouples them: $ for skill lookup, @ for file search, Ctrl+R for history that follows you — it reads Codex's own ~/.codex/history.jsonl alongside its private file, so prompts from either tool come back. The agent is just a selector at the bottom of the screen.

# 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

It launches agents for me. How do I know what it's actually going to run?

Every launch path has a dry-run twin. --print-command shows the exact argv; --print-launch-json emits a stable manifest for scripts. Nothing is hidden behind the TUI:

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

Before trusting any target you add, run it once with --dry-run --print-command and read the argv aloud.

I did read the argv aloud. It says --dangerously-bypass-approvals-and-sandbox. Isn't that terrifying?

It should give you pause — the flag says so out loud, and this page won't hide it:

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

Explicit Codex targets launch with that bypass flag; Claude targets launch with --dangerously-skip-permissions; Pi targets add no bypass flag and rely on Pi's own trust settings. The rule: only point p at directories where you accept the selected agent modifying files and running commands. Dry-run first is not a suggestion — it's the whole trust model.

I have a work account and a personal account. Do I need two installs?

No — a different CODEX_HOME or CLAUDE_CONFIG_DIR is a different identity, and identities are just targets in ~/.prompt-builder/targets.toml:

prompt-builder target add second-account --kind claude --env 'CLAUDE_CONFIG_DIR=~/.claude-second'
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

In the composer that's Tab to Target ‹name›, Space to cycle. Same prompt, different agent, different account.

My launcher isn't an agent at all — it's a zsh function that forks my last Codex session. Can p drive that?

That's handoff mode, and it's the interesting move of this whole section: --handoff-command makes the composer call any command with your submitted prompt as the final argv element — passed as data, never through shell eval. Here are the two wrapper patterns that run daily, complete:

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

p-f composes a prompt, then forks the latest Codex session and resumes it with that prompt. One caveat, same as the section guide: it calls a private fork helper — point _p_handoff_zsh at your own function.

How do I write one of those wrappers without wrecking my shell config?

You don't hand-write it — you make your agent prove it first with the /bin/echo substitution test: your prompt has to appear verbatim as the final echoed argument before any real command gets wired in. This is the prompt to paste into your agent:

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

Bonus: wrapper flags like --fork-from and --compact render as checkbox toggles in the TUI — the wrapper declares its own UI.

This is turning into a lot of shell functions. Where does it end?

Look at what every wrapper actually is: instructions + context + a launch decision. That's a file format begging to exist. Shell functions hide in dotfiles; files can be diffed, reviewed, shared, and gated with evals. The fixit wrapper restated as a flow:

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

That's mdflow, and the bridge already exists in the composer: with the mdflow CLI on PATH, a Flow ‹name› selector appears beside the target selector, and a flow's inputs render as form fields — with a ignores prompt badge if the flow would silently drop your prompt. The promotion rule: when a wrapper survives unchanged for a few weeks, move it into a flow file. That's the next section.

Source references