Section 05

Prompt Builder

Set up Prompt Builder and its zsh helper wiring on this machine. Do setup and verification only; do not modify Prompt Builder source, create new skills, or launch Codex prompts.


setup agent prompt
Set up Prompt Builder and its zsh helper wiring on this machine. Do setup and verification only; do not modify Prompt Builder source, create new skills, or launch Codex prompts.

Step 1: Locate or install Prompt Builder.
If a local checkout of https://github.com/johnlindquist/prompt-builder exists, inspect `README.md`, `src/cli.rs`, `src/handoff.rs`, `src/launch_manifest.rs`, and `src/app_server_launch.rs`, then install from that checkout:
  cargo install --path . --locked --force
If no checkout exists, clone it first. If `cargo` is missing, stop and report that blocker.

Step 2: Verify `prompt-builder` and `p` identity.
Run:
  which -a prompt-builder p
  prompt-builder --version
  p --version
Confirm both commands resolve to the intended install location and report the same version. `p` must be a real executable or symlink, not only an interactive shell alias.
If `prompt-builder` exists but `p` is missing, run:
  ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p
  hash -r 2>/dev/null || true; rehash 2>/dev/null || true
Then repeat the identity and version checks.

Step 3: Verify print, dry-run, and launch inspection modes.
Run:
  p --print-prompt "Review checkout saved payment method regressions."
  p --dry-run --print-command "Review the failing billing webhook test and identify the smallest patch."
  p --print-launch-json "Review auth/session architecture." | jq '.mode, .command, .argv, .env, .prompt'
  p --submit --dry-run --print-command "Verify submit dry-run."
Confirm the prompt is preserved, the command preview is sane, `argv` is structured, and no accidental shell splitting appears.

Step 4: Verify app-server named threads and `CODEX_THREAD_NAME`.
Run:
  p --print-launch-json --name "Auth rotation review" "Review auth/session architecture." | jq '.mode, .env, .app_server'
Confirm `mode` is `app-server-named-thread`, `env` includes `CODEX_THREAD_NAME` with the current directory basename plus the requested name, and the app-server flow includes `thread/name/set`.

Step 5: Verify handoff mode and final argv safety.
Run:
  p --print-launch-json --handoff-command /bin/echo "fix this
keep \$HOME literal" | jq '.mode, .argv'
Confirm `mode` is `handoff`, the composed prompt is the final `argv` element, and `$HOME`, spaces, quotes, semicolons, pipes, and newlines remain literal prompt text. Treat `Command::arg` behavior as the contract; do not add shell eval to wrappers.

Step 6: Verify handoff options only in handoff mode.
Run:
  p --print-launch-json \
    --handoff-command /bin/echo \
    --handoff-arg wrapper \
    --fork-from last \
    --compact \
    --launch-option "trace=--trace-app-server" \
    "continue from here" | jq '.handoff, .argv'
Confirm the ordering is command, static handoff args, enabled toggle args, then final prompt.

Step 7: Wire and verify zsh helpers.
Inspect `zsh/conf.d/40-ai.zsh` and confirm it contains wiring for `p-f`, `p-c`, `p-cm`, `xfl`, `xfc`, `_p_handoff_zsh`, and `_codex_prompt_builder_fork`.
Verify the loaded helper functions:
  zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc'
Each helper should resolve as a function.
Confirm the intended behavior:
  p-f composes in `p`, then forks from the selected or current source.
  p-c composes in `p`, then forks, compacts, and resumes.
  p-cm composes in `p`, then compact-forks from conversation `m`.
  xfl forks immediately with an already-obvious prompt.
  xfc forks, compacts, and resumes immediately.
Use `zsh -lc` with explicit sourcing for handoffs to shell functions because a normal subprocess cannot directly run those functions.

Step 8: Prove one helper handoff shape with a dry run.
Run:
  p --submit --dry-run --print-command \
    --handoff-command zsh \
    --handoff-arg -lc \
    --handoff-arg 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' \
    --handoff-arg xfc \
    "continue from this compact fork"
Confirm the prompt is still the final argv element before the fork runs.

Step 9: Respect privacy boundaries.
Do not print full `env`. Do not copy private shell config, full Codex config, secret helper files, API variables, cookies, tokens, private endpoints, or key-resolving startup output. Use narrow command output only. For safe binary override checks, prefer:
  PROMPT_BUILDER_CODEX_BIN=/bin/echo p --submit --dry-run --print-command "hello override"

Step 10: Report results.
Return a concise setup report with:
  - files inspected or changed
  - resolved paths for `prompt-builder` and `p`
  - matching version output
  - named-thread JSON evidence for `mode`, `CODEX_THREAD_NAME`, and `thread/name/set`
  - handoff JSON evidence that the prompt is the final argv element
  - zsh helper `whence -w` evidence
  - any skipped or failed step with the exact failing command and output

Workflow route

Prompt Builder

Set up Prompt Builder and its zsh helper wiring on this machine. Do setup and verification only; do not modify Prompt Builder source, create new skills, or launch Codex prompts.

Eggo clamps the final argv before launch for the Prompt Builder workflow, making the page's operating move visible.
Intent

Name the software-workflow decision before launching work.

Evidence

Inspect the file, command, log, prompt, or recording that proves the state.

Route

Pick the narrow agent, tool, shell, or council path that matches the problem.

Verify

Confirm the result with output, screenshots, receipts, or saved decisions.

  1. Big Idea
  2. Try This Now
  3. Files To Inspect
  4. When To Reach For This
  5. How This Used To Work
  6. The Mental Model
the launch strip holds steady while unsafe arguments stay out

Big Idea

Prompt Builder is the terminal prompt composer at https://github.com/johnlindquist/prompt-builder. It opens a small TUI for composing, naming, inspecting, and handing a prompt to Codex or a wrapper command.

Use it as the preflight step before a prompt launches Codex, a fork, a compact, or a wrapper command.

Try This Now

Preview one software prompt before launching it: p --print-launch-json "Debug the checkout saved-payment regression and name the first verification command." | jq '.mode, .argv, .prompt' Submit only after the final argv and prompt text match what you intend.

The practical question is:

snippet-1
What exactly am I about to send, where will it run, and what launch shape will it use?

Use Prompt Builder when the prompt needs to be deliberate before the agent gets authority to work in a repo.

snippet-2
compose -> inspect -> name -> preview launch -> submit deliberately

Files To Inspect

Local helper file:

snippet-3
zsh/conf.d/40-ai.zsh

Inside the Prompt Builder checkout:

snippet-4
README.md
src/cli.rs
src/app.rs
src/composer_input.rs
src/file_search.rs
src/skill_popup.rs
src/slash_commands.rs
src/handoff.rs
src/launch_manifest.rs
src/app_server_launch.rs

Main commands:

bash
prompt-builder
p

p is the short command. It should resolve to the same installed binary as prompt-builder.

When To Reach For This

Use Prompt Builder when:

Skip it when the prompt is tiny and obvious:

bash
xfl "continue with the smallest safe patch"

Use it when you need time to compose:

bash
p-f
p-c
p-cm

How This Used To Work

What you used to expect:

snippet-8
Typing directly into Codex or a fork command is enough if the idea is clear.

What the workflow gives you now:

snippet-9
Prompt Builder lets you compose first, inspect the exact prompt and launch
shape, then submit once the request is specific enough to trust.

What you used to expect:

snippet-10
The latest Codex session is probably the right one.

What the workflow gives you now:

snippet-11
Routing chooses the session. Prompt Builder shapes the prompt before the fork,
compact, or wrapper runs.

The Mental Model

Prompt Builder sits between intent and execution.

snippet-12
human intent
-> Prompt Builder composer
-> exact prompt text
-> optional name
-> launch preview
-> direct Codex / named thread / handoff wrapper

Three launch paths matter:

ModeWhat HappensUse When
direct Codexcodex ... <prompt>no name, no wrapper
named threadcreate thread, call thread/name/set, resume threadyou pass --name
handoffcall another command with prompt as final argvp-f, p-c, wrappers

Prompt Builder owns composition and launch metadata. Wrappers own repo-specific behavior such as fork, compact, resume, and cmux tab naming.

Install And Identity Check

Start with the binary check:

bash
which -a prompt-builder p
prompt-builder --version
p --version

What to look for:

If working from a local Prompt Builder checkout, install durably:

bash
cargo install --path . --locked --force

If p is missing but prompt-builder exists:

bash
ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p
which -a prompt-builder p
p --version

Basic Use

Open the interactive composer:

bash
p

Long form:

bash
prompt-builder

Prefill the composer:

bash
p "Debug the checkout flow failing test and propose the smallest safe fix."

Submit noninteractively:

bash
printf 'Debug the billing webhook duplicate-processing bug.\n' | p --submit

Safer first pass:

bash
printf 'Debug the billing webhook duplicate-processing bug.\n' \
  | p --submit --dry-run --print-command

Use --submit only when the prompt has already been composed by you or a trusted script.

Inspection Modes

Use inspection modes before launch.

NeedCommand
exact prompt textp --print-prompt "hello"
human-readable command previewp --dry-run --print-command "hello"
script-readable launch manifestp --print-launch-json "hello"
rehearse submit without launchp --submit --dry-run --print-command "hello"

Print the prompt:

bash
p --print-prompt \
  "Review the checkout flow for saved payment method regressions."

Print the command:

bash
p --dry-run --print-command \
  "Review the failing billing webhook test and identify the smallest patch."

What to look for:

Print launch JSON:

bash
p --print-launch-json \
  "Review the auth/session architecture before refresh-token rotation."

Useful fields:

snippet-24
mode
command
argv
env
prompt

For scripts, prefer JSON over parsing shell-quoted command text.

Stdin Plus Prefill

Prompt Builder can combine prefilled text and stdin.

bash
printf 'failing test output here\n' \
  | p --stdin --print-prompt \
  "Use this test output to debug the checkout flow."

Good software workflow:

bash
pnpm test checkout -- --runInBand 2>&1 \
  | p --stdin --print-prompt \
  "Debug this checkout test failure. Identify the smallest safe fix and the command to confirm it worked."

For a diff review:

bash
git diff -- src/checkout src/billing \
  | p --stdin --print-prompt \
  "Review this diff for bugs, missing tests, and risky behavior changes."

Conversation Naming

Use --name when the work should create a named Codex thread.

bash
p --name "Checkout saved payment methods"

Noninteractive preview:

bash
p --submit --dry-run --name "Checkout saved payment methods" \
  "Plan the first shippable slice."

Prompt Builder prefixes the submitted name with the current working directory basename:

snippet-30
cwd basename: shop-app
name: Checkout saved payment methods
CODEX_THREAD_NAME: shop-app:Checkout saved payment methods

What to know:

Confirm named mode:

bash
p --print-launch-json \
  --name "Auth rotation review" \
  "Review auth/session architecture." \
  | jq '.mode, .env, .app_server'

What to look for:

snippet-32
app-server-named-thread
CODEX_THREAD_NAME
thread/name/set

Handoff Mode

Use handoff mode when Prompt Builder should compose first, then call another command.

Basic handoff preview:

bash
p --submit --dry-run --print-command \
  --handoff-command /bin/echo \
  "hello handoff"

Add static handoff args:

bash
p --submit --dry-run --print-command \
  --handoff-command /bin/echo \
  --handoff-arg wrapper \
  --handoff-arg before-launch \
  "hello handoff"

Important rule:

snippet-35
The composed prompt is passed with Command::arg as the safe final argv element.
It is not shell-evaluated.

Prompt text with spaces, newlines, quotes, $HOME, semicolons, or pipes stays prompt text.

Confirm with JSON:

bash
p --print-launch-json \
  --handoff-command /bin/echo \
  "fix this
and keep \$HOME literal" \
  | jq '.mode, .argv'

What to look for:

Handoff Options

These options become wrapper toggles when --handoff-command is present:

snippet-37
--fork-from
--compact
--launch-option

Example:

bash
p --print-launch-json \
  --handoff-command /bin/echo \
  --handoff-arg wrapper \
  --fork-from last \
  --compact \
  --launch-option "trace=--trace-app-server" \
  "continue from here" \
  | jq '.handoff, .argv'

Expected ordering:

snippet-39
<command> <handoff args> <enabled toggle args> <final prompt>

If --fork-from, --compact, or --launch-option are used without --handoff-command, they are ignored for default Codex launch.

Compose Before Fork Or Compact

Routing gets work to the right Codex session. Prompt Builder composes the prompt before that routed action runs.

HelperUse It When
xflfork now with an already-obvious prompt
xfcfork, compact, and resume now
p-fcompose in p, then fork from the selected/current source
p-ccompose in p, then fork, compact, and resume
p-cmcompose in p, then compact-fork from conversation m

Confirm the helpers:

zsh
zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc'

Inspect the package copy:

bash
rg -n 'p-f|p-c|p-cm|xfl|xfc|_p_handoff_zsh|_codex_prompt_builder_fork' zsh/conf.d/40-ai.zsh

Conceptual shape:

snippet-42
p-f
-> p
-> compose prompt
-> handoff to zsh -lc
-> source 40-ai.zsh
-> _codex_prompt_builder_fork --fork-from <source> <prompt>

Compact shape:

snippet-43
p-c
-> p
-> compose prompt
-> handoff to zsh -lc
-> source 40-ai.zsh
-> _codex_prompt_builder_fork --fork-from <source> --compact <prompt>

Why zsh -lc is there:

snippet-44
`p-f`, `p-c`, `xfl`, and `xfc` are zsh functions in common setups.
A normal subprocess cannot run a shell function unless zsh loads the file that defines it.

Composer Affordances

Prompt Builder mirrors the important parts of the Codex composer so editing habits stay consistent.

ActionBehavior
Entersubmit
Shift+Enterinsert newline
bracketed pastepasted text arrives as a paste event
large pastevisible placeholder, full text restored on submit
Ctrl+C with draft textclear current draft
Ctrl+C on empty draftquit
@file selector
$skills lookup
/ at prompt startslash command popup
Tabmove between Name, Prompt, and options
Space on an optiontoggle wrapper option

@ File Selector

Open:

bash
p

Type:

snippet-46
Review @

Select the file instead of typing the path from memory.

Good prompts:

snippet-47
Review @src/checkout/CheckoutForm.tsx for saved payment method regressions.
snippet-48
Use @src/billing/webhook.ts and @tests/billing/webhook.test.ts to debug duplicate invoice processing.

Skills Lookup

Type:

snippet-49
$

Use skills when the prompt should invoke a known local workflow instead of retyping every step.

Example:

snippet-50
Use $oracle-packx to review the auth/session architecture before refresh-token rotation.

Slash Commands

Slash commands are structured verbs. Put them at the beginning of the prompt.

snippet-51
/review
/plan
/compact

Ask The Agent This

Debug a checkout-flow prompt before launch:

snippet-52
Use Prompt Builder as the preflight boundary.

I want to implement saved payment methods in checkout. Help me compose a prompt
for `p --print-prompt` first. It should reference the likely checkout files,
call out invariants, name tests to run, and ask for the smallest shippable slice.
Do not launch Codex until the prompt and launch shape have been inspected.

Use a named auth review:

snippet-53
Create a Prompt Builder command for an auth/session architecture review.

Use `--name`, show the `--print-launch-json` command, and confirm the launch
mode uses `app-server-named-thread` with `thread/name/set`. The prompt should
ask for risks, migration steps, and verification commands.

Debug handoff quoting:

snippet-54
A Prompt Builder handoff to a wrapper is splitting the prompt.

Inspect the `--print-launch-json` argv. Confirm the prompt is the final argv
element. If the wrapper re-splits it, fix the wrapper rather than adding shell
eval. Use `Command::arg` behavior as the contract.

Connect routed fork:

snippet-55
`Esc+P` routed to the correct Codex session and launched `p-f`.

Inspect how `p-f` uses Prompt Builder, `--handoff-command zsh`, `--handoff-arg`,
`--fork-from`, and `40-ai.zsh`. Show the dry-run command that proves the prompt
will be the final argv element before the fork runs.

What To Confirm / How To Know It Worked

GoalConfirmation
correct binarywhich -a prompt-builder p shows intended paths
version matchprompt-builder --version and p --version match
local install updatedcargo install --path . --locked --force succeeds
exact prompt savedp --print-prompt ... > file and test -s file
command preview sanep --dry-run --print-command ... shows expected command
launch JSON sanep --print-launch-json ... has expected mode, argv, env
named threadJSON mode is app-server-named-thread
thread nameJSON env includes CODEX_THREAD_NAME
handoff safeJSON mode is handoff and prompt is last argv
zsh helpers availablezsh -lc 'source ...40-ai.zsh; whence -w p-f p-c xfl xfc'
variation seed readysaved base prompt is non-empty and has invariants

If It Goes Wrong

p Is Missing

Check:

bash
which -a prompt-builder p
prompt-builder --version
p --version

Likely causes:

Fix shape:

bash
ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p
hash -r 2>/dev/null || true
rehash 2>/dev/null || true
which -a prompt-builder p
p --version

Wrong Version Runs

Check all matches:

bash
which -a prompt-builder p
prompt-builder --version
p --version

If working from the local checkout:

bash
cargo install --path . --locked --force
which -a prompt-builder p
p --version

Wrong Codex Binary Runs

Inspect:

bash
p --dry-run --print-command "hello"

Override for a safe demo:

bash
PROMPT_BUILDER_CODEX_BIN=/bin/echo \
  p --submit --dry-run --print-command \
  "hello override"

Or pass the binary explicitly:

bash
p --codex-bin /bin/echo --submit --dry-run --print-command "hello"

Empty Prompt Rejected

Check producer output:

bash
producer_command | tee /tmp/prompt-builder-input.txt
test -s /tmp/prompt-builder-input.txt && echo "input:OK"

Then:

bash
p --stdin --print-prompt < /tmp/prompt-builder-input.txt

Named Thread Did Not Happen

Check mode:

bash
p --print-launch-json --name "Demo" "hello" | jq '.mode, .env, .app_server'

What to look for:

snippet-66
app-server-named-thread
CODEX_THREAD_NAME
thread/name/set

Shell Function Handoff Fails

Symptom:

snippet-67
xfc: command not found

Bad shape:

bash
p --handoff-command xfc

Better shape:

bash
p \
  --handoff-command zsh \
  --handoff-arg -lc \
  --handoff-arg 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' \
  --handoff-arg xfc

Dry-run:

bash
p --submit --dry-run --print-command \
  --handoff-command zsh \
  --handoff-arg -lc \
  --handoff-arg 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' \
  --handoff-arg xfc \
  "continue from this compact fork"

Quoting Looks Scary

Use launch JSON instead of guessing from shell text:

bash
p --print-launch-json \
  --handoff-command /bin/echo \
  "fix checkout
keep \$HOME literal
do not shell-eval this" \
  | jq '.argv'

What to look for:

If a wrapper splits the final argument, fix the wrapper.

Fork/Compact Options Do Nothing

Cause:

snippet-72
--fork-from, --compact, and --launch-option only matter in handoff mode.

Check:

bash
p --print-launch-json --fork-from last --compact "continue" | jq '.mode, .argv'

Fix:

bash
p --print-launch-json \
  --handoff-command /bin/echo \
  --fork-from last \
  --compact \
  "continue" \
  | jq '.mode, .argv'

Variation Seed Prompt

A useful variation seed has:

Example:

bash
RUN_ID="billing-webhook-variations"
ROOT="artifacts/variations/$RUN_ID"
mkdir -p "$ROOT/prompts" "$ROOT/launch"

p --print-prompt \
  "Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, and rollback risk." \
  > "$ROOT/prompts/base.prompt.md"

p --print-launch-json \
  "Generate three controlled fixes for duplicate billing webhook processing. Keep the provider contract and database schema fixed. Vary only the idempotency strategy. Each option must name files, tests, and rollback risk." \
  > "$ROOT/launch/base.launch.json"

test -s "$ROOT/prompts/base.prompt.md" && echo "base-prompt:OK"
jq '.mode, .prompt' "$ROOT/launch/base.launch.json"

References And Resources