Compose the prompt before choosing the agent

A cross-agent composer, named launch profiles, exact argv previews, and safe handoff patterns.

A cross-agent composer, named launch profiles, exact argv previews, and safe handoff patterns.

TL;DR

  • prompt-builder (alias p) is a terminal composer that gives your prompt its own tool: $ skill lookup, @ file search, and Ctrl+R cross-agent history in front of Pi, Codex, and Claude Code.
  • You walk away with a compose-first loop: one composer, your own launch targets, and shell functions promoted to launch targets via handoff mode.
  • The one move: compose in p, Tab to Target ‹name›, cycle agents with Space — and inspect any launch first with --dry-run --print-command.

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.

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 the recorded snapshot 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.

Operating practice

Compose only the evidence the task needs

What to notice

Build a prompt packet from text, files, images, and fresh state without smuggling in an entire stale session.

Try this

List the minimum sources needed to decide, act, and verify; remove everything that cannot change one of those steps.

“How can I consolidate that into something that's gonna manage it for me?”

John Lindquist · 02:37:56

Concept

Input is a task plus evidence. Output is a result with a named check. The tradeoff is simple: extra context can add capability, but it also hides contradictions and consumes review attention.

Reflection

A large packet is not automatically a complete packet. Prefer relevant, current, and inspectable evidence.

Recording evidence: listen at 02:34:33.

“I usually spend the most amount of time preparing that initial prompt.”

John Lindquist · 02:39:00

Open Prompt Builder

Watch chapter

Source references