Agent Setup 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
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:
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.
compose -> inspect -> name -> preview launch -> submit deliberately
Files To Inspect
Local helper file:
zsh/conf.d/40-ai.zsh
Inside the Prompt Builder checkout:
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:
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:
- a checkout-flow implementation prompt needs file references and constraints
- a billing webhook fix should fork from the right Codex session
- an auth/session architecture review needs a named thread
- a failing test investigation needs pasted output plus a careful instruction
- a wrapper needs the prompt as the final argument
- you want to inspect the prompt, command, or launch JSON before launch
- routing has selected the right session and you still need to compose the right prompt
- a controlled-variation run needs one deliberate base prompt
Skip it when the prompt is tiny and obvious:
xfl "continue with the smallest safe patch"
Use it when you need time to compose:
p-f
p-c
p-cm
How This Used To Work
What you used to expect:
Typing directly into Codex or a fork command is enough if the idea is clear.
What the workflow gives you now:
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:
The latest Codex session is probably the right one.
What the workflow gives you now:
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.
human intent
-> Prompt Builder composer
-> exact prompt text
-> optional name
-> launch preview
-> direct Codex / named thread / handoff wrapper
Three launch paths matter:
| Mode | What Happens | Use When |
|---|---|---|
| direct Codex | codex ... <prompt> |
no name, no wrapper |
| named thread | create thread, call thread/name/set, resume thread |
you pass --name |
| handoff | call another command with prompt as final argv | p-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:
which -a prompt-builder p
prompt-builder --version
p --version
What to look for:
- both commands resolve
- both resolve to the intended install location
- both report the same version
pis not just an interactive-only alias
If working from a local Prompt Builder checkout, install durably:
cargo install --path . --locked --force
If p is missing but prompt-builder exists:
ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p
which -a prompt-builder p
p --version
Basic Use
Open the interactive composer:
p
Long form:
prompt-builder
Prefill the composer:
p "Debug the checkout flow failing test and propose the smallest safe fix."
Submit noninteractively:
printf 'Debug the billing webhook duplicate-processing bug.\n' | p --submit
Safer first pass:
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.
| Need | Command |
|---|---|
| exact prompt text | p --print-prompt "hello" |
| human-readable command preview | p --dry-run --print-command "hello" |
| script-readable launch manifest | p --print-launch-json "hello" |
| rehearse submit without launch | p --submit --dry-run --print-command "hello" |
Print the prompt:
p --print-prompt \
"Review the checkout flow for saved payment method regressions."
Print the command:
p --dry-run --print-command \
"Review the failing billing webhook test and identify the smallest patch."
What to look for:
- expected command
- expected cwd from
-C - prompt appears as one quoted argument
- no accidental shell splitting
Print launch JSON:
p --print-launch-json \
"Review the auth/session architecture before refresh-token rotation."
Useful fields:
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.
printf 'failing test output here\n' \
| p --stdin --print-prompt \
"Use this test output to debug the checkout flow."
Good software workflow:
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:
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.
p --name "Checkout saved payment methods"
Noninteractive preview:
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:
cwd basename: shop-app
name: Checkout saved payment methods
CODEX_THREAD_NAME: shop-app:Checkout saved payment methods
What to know:
- the name is not just text inside the prompt
- default named launches use Codex app-server
- Prompt Builder creates a thread, calls
thread/name/set, then resumes the thread with the prompt - handoff mode passes
CODEX_THREAD_NAMEto the child command environment
Confirm named mode:
p --print-launch-json \
--name "Auth rotation review" \
"Review auth/session architecture." \
| jq '.mode, .env, .app_server'
What to look for:
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:
p --submit --dry-run --print-command \
--handoff-command /bin/echo \
"hello handoff"
Add static handoff args:
p --submit --dry-run --print-command \
--handoff-command /bin/echo \
--handoff-arg wrapper \
--handoff-arg before-launch \
"hello handoff"
Important rule:
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:
p --print-launch-json \
--handoff-command /bin/echo \
"fix this
and keep \$HOME literal" \
| jq '.mode, .argv'
What to look for:
- mode is
handoff - prompt is the final argv element
$HOMEstays literal inside the prompt value
Handoff Options
These options become wrapper toggles when --handoff-command is present:
--fork-from
--compact
--launch-option
Example:
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:
<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.
| Helper | Use It When |
|---|---|
xfl |
fork now with an already-obvious prompt |
xfc |
fork, compact, and resume now |
p-f |
compose in p, then fork from the selected/current source |
p-c |
compose in p, then fork, compact, and resume |
p-cm |
compose in p, then compact-fork from conversation m |
Confirm the helpers:
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:
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:
p-f
-> p
-> compose prompt
-> handoff to zsh -lc
-> source 40-ai.zsh
-> _codex_prompt_builder_fork --fork-from <source> <prompt>
Compact shape:
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:
`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.
| Action | Behavior |
|---|---|
Enter |
submit |
Shift+Enter |
insert newline |
| bracketed paste | pasted text arrives as a paste event |
| large paste | visible placeholder, full text restored on submit |
Ctrl+C with draft text |
clear current draft |
Ctrl+C on empty draft |
quit |
@ |
file selector |
$ |
skills lookup |
/ at prompt start |
slash command popup |
Tab |
move between Name, Prompt, and options |
Space on an option |
toggle wrapper option |
@ File Selector
Open:
p
Type:
Review @
Select the file instead of typing the path from memory.
Good prompts:
Review @src/checkout/CheckoutForm.tsx for saved payment method regressions.
Use @src/billing/webhook.ts and @tests/billing/webhook.test.ts to debug duplicate invoice processing.
Skills Lookup
Type:
$
Use skills when the prompt should invoke a known local workflow instead of retyping every step.
Example:
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.
/review
/plan
/compact
Ask The Agent This
Debug a checkout-flow prompt before launch:
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:
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:
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:
`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
| Goal | Confirmation |
|---|---|
| correct binary | which -a prompt-builder p shows intended paths |
| version match | prompt-builder --version and p --version match |
| local install updated | cargo install --path . --locked --force succeeds |
| exact prompt saved | p --print-prompt ... > file and test -s file |
| command preview sane | p --dry-run --print-command ... shows expected command |
| launch JSON sane | p --print-launch-json ... has expected mode, argv, env |
| named thread | JSON mode is app-server-named-thread |
| thread name | JSON env includes CODEX_THREAD_NAME |
| handoff safe | JSON mode is handoff and prompt is last argv |
| zsh helpers available | zsh -lc 'source ...40-ai.zsh; whence -w p-f p-c xfl xfc' |
| variation seed ready | saved base prompt is non-empty and has invariants |
If It Goes Wrong
p Is Missing
Check:
which -a prompt-builder p
prompt-builder --version
p --version
Likely causes:
prompt-builderis installed butpsymlink is missingpis only an alias in an interactive shell- PATH changed after install
Fix shape:
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:
which -a prompt-builder p
prompt-builder --version
p --version
If working from the local checkout:
cargo install --path . --locked --force
which -a prompt-builder p
p --version
Wrong Codex Binary Runs
Inspect:
p --dry-run --print-command "hello"
Override for a safe demo:
PROMPT_BUILDER_CODEX_BIN=/bin/echo \
p --submit --dry-run --print-command \
"hello override"
Or pass the binary explicitly:
p --codex-bin /bin/echo --submit --dry-run --print-command "hello"
Empty Prompt Rejected
Check producer output:
producer_command | tee /tmp/prompt-builder-input.txt
test -s /tmp/prompt-builder-input.txt && echo "input:OK"
Then:
p --stdin --print-prompt < /tmp/prompt-builder-input.txt
Named Thread Did Not Happen
Check mode:
p --print-launch-json --name "Demo" "hello" | jq '.mode, .env, .app_server'
What to look for:
app-server-named-thread
CODEX_THREAD_NAME
thread/name/set
Shell Function Handoff Fails
Symptom:
xfc: command not found
Bad shape:
p --handoff-command xfc
Better shape:
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:
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:
p --print-launch-json \
--handoff-command /bin/echo \
"fix checkout
keep \$HOME literal
do not shell-eval this" \
| jq '.argv'
What to look for:
- the prompt is one JSON string
- it is the final argv element
- shell metacharacters remain text
If a wrapper splits the final argument, fix the wrapper.
Fork/Compact Options Do Nothing
Cause:
--fork-from, --compact, and --launch-option only matter in handoff mode.
Check:
p --print-launch-json --fork-from last --compact "continue" | jq '.mode, .argv'
Fix:
p --print-launch-json \
--handoff-command /bin/echo \
--fork-from last \
--compact \
"continue" \
| jq '.mode, .argv'
Variation Seed Prompt
A useful variation seed has:
- a concrete software goal
- invariants that must not change
- one variable dimension
- verification command
- output path or comparison criteria
Example:
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
- Prompt Builder command:
prompt-builder - Prompt Builder repo: https://github.com/johnlindquist/prompt-builder
- Short command:
p - Zsh helper file:
zsh/conf.d/40-ai.zsh - Prompt Builder checkout files:
README.md,src/cli.rs,src/main.rs,src/handoff.rs,src/launch_manifest.rs,src/app_server_launch.rs,src/composer_input.rs - Local install command from Prompt Builder checkout:
cargo install --path . --locked --force - Useful debug env var:
PROMPT_BUILDER_CODEX_BIN - Useful key debug env var:
PROMPT_BUILDER_DEBUG_KEYS