Complete reusable prompts, setup recipes, success checks, and caveats for compose the prompt before choosing the agent.
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
- Agent: Codex, launched through
p --target codex --developer-instructions "…" - Working directory: the project with the bug
- Expected result: 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
- Agent: any coding agent (Claude Code, Codex, Pi)
- Working directory: wherever your shell config lives
- Expected result: 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
- Agent: any coding agent with shell access
- Working directory: anywhere
- Expected result: a new target in
targets.tomland a printed launch command carryingCLAUDE_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)
-
Install the composer and alias it to
p. Keep--locked: the lockfile pins patchedcrossterm/ratatuirevisions.cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked echo 'alias p=prompt-builder' >> ~/.zshrc source ~/.zshrc -
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.
Complete reusable setup contract
Prompt Builder (p) — agent setup guide
Following this file sets up: the prompt-builder terminal composer, aliased to p, with one custom launch target, verified end-to-end with dry-run flags (no agent is ever launched by these steps).
Placeholders used below: ~ = the user's home directory. All other paths are literal.
Prerequisites
Check each before starting:
cargo --version
Expected: a Rust toolchain from rustup (the repo pins Rust 1.95.0; any recent stable cargo can build it). If cargo is missing, stop and tell your user to install rustup from https://rustup.rs — do not proceed.
The Pi, Codex, and Claude Code CLIs are NOT required for these steps: every verification below uses --dry-run/print flags, which work with no agent CLIs installed.
Steps
-
Install the composer from the public repo. Keep
--locked— the lockfile pins patchedcrosstermandratatuirevisions, so unlocked installs may behave differently in the terminal.cargo install --git https://github.com/johnlindquist/prompt-builder.git --lockedThis compiles from source and can take a few minutes.
-
Alias the binary to
p. For zsh:echo 'alias p=prompt-builder' >> ~/.zshrcFor other shells, either add the equivalent alias to that shell's rc file, or use a shell-independent symlink:
ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p -
Add one launch target (a named launch profile: binary + env vars + default args). This example creates a Codex profile with its own
CODEX_HOME, i.e. a separate identity:prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'On a fresh machine this writes
~/.prompt-builder/targets.tomlwith exactly this content:[[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"If the user already has a
targets.toml,target addappends to it instead; existing targets are preserved.
Success check
Run:
prompt-builder --dry-run --print-command "hello"
prompt-builder --dry-run --target work-profile --print-command "hello"
prompt-builder target list
Expected observable result:
- Line 1 prints exactly:
pi hello - Line 2 prints:
CODEX_HOME=<expanded home>/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello target listshows four targets:pi,codex,claude,work-profile(the last withCODEX_HOME=~/.codex-work)
Report to your user: what you installed, the exact printed launch commands, and — importantly — that the Codex line contains --dangerously-bypass-approvals-and-sandbox. Real (non-dry-run) Codex and Claude launches use permission-bypass flags, so p should only be pointed at directories where the user accepts the agent modifying files and running commands.
Notes for agents
- If
cargo installfails on dependency resolution, you probably dropped--locked. Re-run with it. - If
target addfails with a duplicate-name error, the user already has awork-profiletarget; pick another name and adjust the success check to match. target adddefaults to--kind pi— always pass--kindexplicitly when creating codex/claude targets.- The default target is Pi. Real submissions (without
--dry-run) fail if thepiCLI is not onPATH; that does not affect any step in this file. - The composer's interactive features ($ skills, @ files, Ctrl+R history, Tab to the
Target ‹name›selector) need a real TTY; don't try to drive the TUI from a non-interactive shell. Verify with the print flags above instead. - Full docs and updates: https://github.com/johnlindquist/prompt-builder (page version of this guide: https://shiny-bloom-f8hv.here.now/)
- The guide's
fixitwrapper also ships as a skills.sh-format agent skill hosted on this site (same job, third form of the wrapper: zsh function → mdflow flow → SKILL.md). Machine-fetch URL:https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw(?rawrequired — the bare URL serves an HTML viewer). Install only if your user prefers skills: stage anywhere EXCEPT a dir namedskills/(the skills CLI claims that name and you'd install an empty skill), e.g.mkdir -p skill-src/fixit && curl -fsSL "<url above>" -o skill-src/fixit/SKILL.md && npx skills add ./skill-src --skill fixit -y. - Two presentation pages accompany the guide, for humans walking through the section: https://shiny-bloom-f8hv.here.now/replay.html (Session Replay — the annotated transcript of the sessions that set up and wrapped
p) and https://shiny-bloom-f8hv.here.now/dialogue.html (Socratic Dialogue — attendee questions driving the same material). They contain the same commands plus the complete wrapper filep-wrap.zsh, provided by those pages as a liftable code block. Note: that file does NOT exist in the prompt-builder repo — the repo'sexamples/directory ships onlyfixit.zsh— so copyp-wrap.zshfrom the workshop pages, not from the repo. This file remains the canonical machine copy for setup.