{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-prompt-composition-reference",
  "slug": "prompt-composition-reference",
  "title": "Prompt Builder composition and handoff: practical reference",
  "summary": "Prompt Builder setup and reference covering installation and binary identity, interactive and stdin composition, launch inspection, named Codex threads, safe final-argument handoffs, fork/compact wrappers, composer controls, file and skill lookup, slash…",
  "category": "Planning",
  "tags": [
    "prompt-builder",
    "prompts",
    "preflight"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Agent Setup Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Big Idea",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Try This Now",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Files To Inspect",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/When To Reach For This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/How This Used To Work",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/The Mental Model",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Install And Identity Check",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Basic Use",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Inspection Modes",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Stdin Plus Prefill",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Conversation Naming",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Handoff Mode",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Handoff Options",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Compose Before Fork Or Compact",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Composer Affordances",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Composer Affordances/`@` File Selector",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Composer Affordances/Skills Lookup",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Composer Affordances/Slash Commands",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Ask The Agent This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/What To Confirm / How To Know It Worked",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/`p` Is Missing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Wrong Version Runs",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Wrong Codex Binary Runs",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Empty Prompt Rejected",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Named Thread Did Not Happen",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Shell Function Handoff Fails",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Quoting Looks Scary",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/If It Goes Wrong/Fork/Compact Options Do Nothing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/Variation Seed Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/05-prompt-builder.md#05. Prompt Builder/References And Resources",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "planning",
  "wordCount": 3369,
  "url": "/topics/codex-prompt-composition-reference/",
  "markdownUrl": "/markdown/codex-prompt-composition-reference.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-prompt-composition-reference.json",
  "headings": [
    {
      "id": "agent-setup-prompt",
      "text": "Agent Setup Prompt",
      "level": 2
    },
    {
      "id": "big-idea",
      "text": "Big Idea",
      "level": 2
    },
    {
      "id": "try-this-now",
      "text": "Try This Now",
      "level": 2
    },
    {
      "id": "files-to-inspect",
      "text": "Files To Inspect",
      "level": 2
    },
    {
      "id": "when-to-reach-for-this",
      "text": "When To Reach For This",
      "level": 2
    },
    {
      "id": "how-this-used-to-work",
      "text": "How This Used To Work",
      "level": 2
    },
    {
      "id": "the-mental-model",
      "text": "The Mental Model",
      "level": 2
    },
    {
      "id": "install-and-identity-check",
      "text": "Install And Identity Check",
      "level": 2
    },
    {
      "id": "basic-use",
      "text": "Basic Use",
      "level": 2
    },
    {
      "id": "inspection-modes",
      "text": "Inspection Modes",
      "level": 2
    },
    {
      "id": "stdin-plus-prefill",
      "text": "Stdin Plus Prefill",
      "level": 2
    },
    {
      "id": "conversation-naming",
      "text": "Conversation Naming",
      "level": 2
    },
    {
      "id": "handoff-mode",
      "text": "Handoff Mode",
      "level": 2
    },
    {
      "id": "handoff-options",
      "text": "Handoff Options",
      "level": 2
    },
    {
      "id": "compose-before-fork-or-compact",
      "text": "Compose Before Fork Or Compact",
      "level": 2
    },
    {
      "id": "composer-affordances",
      "text": "Composer Affordances",
      "level": 2
    },
    {
      "id": "file-selector",
      "text": "`@` File Selector",
      "level": 3
    },
    {
      "id": "skills-lookup",
      "text": "Skills Lookup",
      "level": 3
    },
    {
      "id": "slash-commands",
      "text": "Slash Commands",
      "level": 3
    },
    {
      "id": "ask-the-agent-this",
      "text": "Ask The Agent This",
      "level": 2
    },
    {
      "id": "what-to-confirm-how-to-know-it-worked",
      "text": "What To Confirm / How To Know It Worked",
      "level": 2
    },
    {
      "id": "if-it-goes-wrong",
      "text": "If It Goes Wrong",
      "level": 2
    },
    {
      "id": "p-is-missing",
      "text": "`p` Is Missing",
      "level": 3
    },
    {
      "id": "wrong-version-runs",
      "text": "Wrong Version Runs",
      "level": 3
    },
    {
      "id": "wrong-codex-binary-runs",
      "text": "Wrong Codex Binary Runs",
      "level": 3
    },
    {
      "id": "empty-prompt-rejected",
      "text": "Empty Prompt Rejected",
      "level": 3
    },
    {
      "id": "named-thread-did-not-happen",
      "text": "Named Thread Did Not Happen",
      "level": 3
    },
    {
      "id": "shell-function-handoff-fails",
      "text": "Shell Function Handoff Fails",
      "level": 3
    },
    {
      "id": "quoting-looks-scary",
      "text": "Quoting Looks Scary",
      "level": 3
    },
    {
      "id": "fork-compact-options-do-nothing",
      "text": "Fork/Compact Options Do Nothing",
      "level": 3
    },
    {
      "id": "variation-seed-prompt",
      "text": "Variation Seed Prompt",
      "level": 2
    },
    {
      "id": "references-and-resources",
      "text": "References And Resources",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Prompt Builder composition and handoff: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet 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.\n\nStep 1: Locate or install Prompt Builder.\nIf 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:\n  cargo install --path . --locked --force\nIf no checkout exists, clone it first. If `cargo` is missing, stop and report that blocker.\n\nStep 2: Verify `prompt-builder` and `p` identity.\nRun:\n  which -a prompt-builder p\n  prompt-builder --version\n  p --version\nConfirm 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.\nIf `prompt-builder` exists but `p` is missing, run:\n  ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\n  hash -r 2>/dev/null || true; rehash 2>/dev/null || true\nThen repeat the identity and version checks.\n\nStep 3: Verify print, dry-run, and launch inspection modes.\nRun:\n  p --print-prompt \"Review checkout saved payment method regressions.\"\n  p --dry-run --print-command \"Review the failing billing webhook test and identify the smallest patch.\"\n  p --print-launch-json \"Review auth/session architecture.\" | jq '.mode, .command, .argv, .env, .prompt'\n  p --submit --dry-run --print-command \"Verify submit dry-run.\"\nConfirm the prompt is preserved, the command preview is sane, `argv` is structured, and no accidental shell splitting appears.\n\nStep 4: Verify app-server named threads and `CODEX_THREAD_NAME`.\nRun:\n  p --print-launch-json --name \"Auth rotation review\" \"Review auth/session architecture.\" | jq '.mode, .env, .app_server'\nConfirm `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`.\n\nStep 5: Verify handoff mode and final argv safety.\nRun:\n  p --print-launch-json --handoff-command /bin/echo \"fix this\nkeep \\$HOME literal\" | jq '.mode, .argv'\nConfirm `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.\n\nStep 6: Verify handoff options only in handoff mode.\nRun:\n  p --print-launch-json \\\n    --handoff-command /bin/echo \\\n    --handoff-arg wrapper \\\n    --fork-from last \\\n    --compact \\\n    --launch-option \"trace=--trace-app-server\" \\\n    \"continue from here\" | jq '.handoff, .argv'\nConfirm the ordering is command, static handoff args, enabled toggle args, then final prompt.\n\nStep 7: Wire and verify zsh helpers.\nInspect `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`.\nVerify the loaded helper functions:\n  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'\nEach helper should resolve as a function.\nConfirm the intended behavior:\n  p-f composes in `p`, then forks from the selected or current source.\n  p-c composes in `p`, then forks, compacts, and resumes.\n  p-cm composes in `p`, then compact-forks from conversation `m`.\n  xfl forks immediately with an already-obvious prompt.\n  xfc forks, compacts, and resumes immediately.\nUse `zsh -lc` with explicit sourcing for handoffs to shell functions because a normal subprocess cannot directly run those functions.\n\nStep 8: Prove one helper handoff shape with a dry run.\nRun:\n  p --submit --dry-run --print-command \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' \\\n    --handoff-arg xfc \\\n    \"continue from this compact fork\"\nConfirm the prompt is still the final argv element before the fork runs.\n\nStep 9: Respect privacy boundaries.\nDo 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:\n  PROMPT_BUILDER_CODEX_BIN=/bin/echo p --submit --dry-run --print-command \"hello override\"\n\nStep 10: Report results.\nReturn a concise setup report with:\n  - files inspected or changed\n  - resolved paths for `prompt-builder` and `p`\n  - matching version output\n  - named-thread JSON evidence for `mode`, `CODEX_THREAD_NAME`, and `thread/name/set`\n  - handoff JSON evidence that the prompt is the final argv element\n  - zsh helper `whence -w` evidence\n  - any skipped or failed step with the exact failing command and output\n```\n\n## Big Idea\n\nPrompt Builder is the terminal prompt composer at <https://github.com/johnlindquist/prompt-builder>.\nIt opens a small TUI for composing, naming, inspecting, and handing a prompt to Codex or a wrapper command.\n\nUse it as the preflight step before a prompt launches Codex, a fork, a compact, or a wrapper command.\n\n## Try This Now\n\nPreview one software prompt before launching it:\n`p --print-launch-json \"Debug the checkout saved-payment regression and name the first verification command.\" | jq '.mode, .argv, .prompt'`\nSubmit only after the final argv and prompt text match what you intend.\n\nThe practical question is:\n\n```text\nWhat exactly am I about to send, where will it run, and what launch shape will it use?\n```\n\nUse Prompt Builder when the prompt needs to be deliberate before the agent gets authority to work in a repo.\n\n```text\ncompose -> inspect -> name -> preview launch -> submit deliberately\n```\n\n## Files To Inspect\n\nLocal helper file:\n\n```text\nzsh/conf.d/40-ai.zsh\n```\n\nInside the Prompt Builder checkout:\n\n```text\nREADME.md\nsrc/cli.rs\nsrc/app.rs\nsrc/composer_input.rs\nsrc/file_search.rs\nsrc/skill_popup.rs\nsrc/slash_commands.rs\nsrc/handoff.rs\nsrc/launch_manifest.rs\nsrc/app_server_launch.rs\n```\n\nMain commands:\n\n```bash\nprompt-builder\np\n```\n\n`p` is the short command. It should resolve to the same installed binary as `prompt-builder`.\n\n## When To Reach For This\n\nUse Prompt Builder when:\n\n- a checkout-flow implementation prompt needs file references and constraints\n- a billing webhook fix should fork from the right Codex session\n- an auth/session architecture review needs a named thread\n- a failing test investigation needs pasted output plus a careful instruction\n- a wrapper needs the prompt as the final argument\n- you want to inspect the prompt, command, or launch JSON before launch\n- routing has selected the right session and you still need to compose the right prompt\n- a controlled-variation run needs one deliberate base prompt\n\nSkip it when the prompt is tiny and obvious:\n\n```bash\nxfl \"continue with the smallest safe patch\"\n```\n\nUse it when you need time to compose:\n\n```bash\np-f\np-c\np-cm\n```\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nTyping directly into Codex or a fork command is enough if the idea is clear.\n```\n\nWhat the workflow gives you now:\n\n```text\nPrompt Builder lets you compose first, inspect the exact prompt and launch\nshape, then submit once the request is specific enough to trust.\n```\n\nWhat you used to expect:\n\n```text\nThe latest Codex session is probably the right one.\n```\n\nWhat the workflow gives you now:\n\n```text\nRouting chooses the session. Prompt Builder shapes the prompt before the fork,\ncompact, or wrapper runs.\n```\n\n## The Mental Model\n\nPrompt Builder sits between intent and execution.\n\n```text\nhuman intent\n-> Prompt Builder composer\n-> exact prompt text\n-> optional name\n-> launch preview\n-> direct Codex / named thread / handoff wrapper\n```\n\nThree launch paths matter:\n\n| Mode | What Happens | Use When |\n| --- | --- | --- |\n| direct Codex | `codex ... <prompt>` | no name, no wrapper |\n| named thread | create thread, call `thread/name/set`, resume thread | you pass `--name` |\n| handoff | call another command with prompt as final argv | `p-f`, `p-c`, wrappers |\n\nPrompt Builder owns composition and launch metadata. Wrappers own repo-specific behavior such as fork, compact, resume, and cmux tab naming.\n\n## Install And Identity Check\n\nStart with the binary check:\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nWhat to look for:\n\n- both commands resolve\n- both resolve to the intended install location\n- both report the same version\n- `p` is not just an interactive-only alias\n\nIf working from a local Prompt Builder checkout, install durably:\n\n```bash\ncargo install --path . --locked --force\n```\n\nIf `p` is missing but `prompt-builder` exists:\n\n```bash\nln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\nwhich -a prompt-builder p\np --version\n```\n\n## Basic Use\n\nOpen the interactive composer:\n\n```bash\np\n```\n\nLong form:\n\n```bash\nprompt-builder\n```\n\nPrefill the composer:\n\n```bash\np \"Debug the checkout flow failing test and propose the smallest safe fix.\"\n```\n\nSubmit noninteractively:\n\n```bash\nprintf 'Debug the billing webhook duplicate-processing bug.\\n' | p --submit\n```\n\nSafer first pass:\n\n```bash\nprintf 'Debug the billing webhook duplicate-processing bug.\\n' \\\n  | p --submit --dry-run --print-command\n```\n\nUse `--submit` only when the prompt has already been composed by you or a trusted script.\n\n## Inspection Modes\n\nUse inspection modes before launch.\n\n| Need | Command |\n| --- | --- |\n| exact prompt text | `p --print-prompt \"hello\"` |\n| human-readable command preview | `p --dry-run --print-command \"hello\"` |\n| script-readable launch manifest | `p --print-launch-json \"hello\"` |\n| rehearse submit without launch | `p --submit --dry-run --print-command \"hello\"` |\n\nPrint the prompt:\n\n```bash\np --print-prompt \\\n  \"Review the checkout flow for saved payment method regressions.\"\n```\n\nPrint the command:\n\n```bash\np --dry-run --print-command \\\n  \"Review the failing billing webhook test and identify the smallest patch.\"\n```\n\nWhat to look for:\n\n- expected command\n- expected cwd from `-C`\n- prompt appears as one quoted argument\n- no accidental shell splitting\n\nPrint launch JSON:\n\n```bash\np --print-launch-json \\\n  \"Review the auth/session architecture before refresh-token rotation.\"\n```\n\nUseful fields:\n\n```text\nmode\ncommand\nargv\nenv\nprompt\n```\n\nFor scripts, prefer JSON over parsing shell-quoted command text.\n\n## Stdin Plus Prefill\n\nPrompt Builder can combine prefilled text and stdin.\n\n```bash\nprintf 'failing test output here\\n' \\\n  | p --stdin --print-prompt \\\n  \"Use this test output to debug the checkout flow.\"\n```\n\nGood software workflow:\n\n```bash\npnpm test checkout -- --runInBand 2>&1 \\\n  | p --stdin --print-prompt \\\n  \"Debug this checkout test failure. Identify the smallest safe fix and the command to confirm it worked.\"\n```\n\nFor a diff review:\n\n```bash\ngit diff -- src/checkout src/billing \\\n  | p --stdin --print-prompt \\\n  \"Review this diff for bugs, missing tests, and risky behavior changes.\"\n```\n\n## Conversation Naming\n\nUse `--name` when the work should create a named Codex thread.\n\n```bash\np --name \"Checkout saved payment methods\"\n```\n\nNoninteractive preview:\n\n```bash\np --submit --dry-run --name \"Checkout saved payment methods\" \\\n  \"Plan the first shippable slice.\"\n```\n\nPrompt Builder prefixes the submitted name with the current working directory basename:\n\n```text\ncwd basename: shop-app\nname: Checkout saved payment methods\nCODEX_THREAD_NAME: shop-app:Checkout saved payment methods\n```\n\nWhat to know:\n\n- the name is not just text inside the prompt\n- default named launches use Codex app-server\n- Prompt Builder creates a thread, calls `thread/name/set`, then resumes the thread with the prompt\n- handoff mode passes `CODEX_THREAD_NAME` to the child command environment\n\nConfirm named mode:\n\n```bash\np --print-launch-json \\\n  --name \"Auth rotation review\" \\\n  \"Review auth/session architecture.\" \\\n  | jq '.mode, .env, .app_server'\n```\n\nWhat to look for:\n\n```text\napp-server-named-thread\nCODEX_THREAD_NAME\nthread/name/set\n```\n\n## Handoff Mode\n\nUse handoff mode when Prompt Builder should compose first, then call another command.\n\nBasic handoff preview:\n\n```bash\np --submit --dry-run --print-command \\\n  --handoff-command /bin/echo \\\n  \"hello handoff\"\n```\n\nAdd static handoff args:\n\n```bash\np --submit --dry-run --print-command \\\n  --handoff-command /bin/echo \\\n  --handoff-arg wrapper \\\n  --handoff-arg before-launch \\\n  \"hello handoff\"\n```\n\nImportant rule:\n\n```text\nThe composed prompt is passed with Command::arg as the safe final argv element.\nIt is not shell-evaluated.\n```\n\nPrompt text with spaces, newlines, quotes, `$HOME`, semicolons, or pipes stays prompt text.\n\nConfirm with JSON:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  \"fix this\nand keep \\$HOME literal\" \\\n  | jq '.mode, .argv'\n```\n\nWhat to look for:\n\n- mode is `handoff`\n- prompt is the final argv element\n- `$HOME` stays literal inside the prompt value\n\n## Handoff Options\n\nThese options become wrapper toggles when `--handoff-command` is present:\n\n```text\n--fork-from\n--compact\n--launch-option\n```\n\nExample:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --handoff-arg wrapper \\\n  --fork-from last \\\n  --compact \\\n  --launch-option \"trace=--trace-app-server\" \\\n  \"continue from here\" \\\n  | jq '.handoff, .argv'\n```\n\nExpected ordering:\n\n```text\n<command> <handoff args> <enabled toggle args> <final prompt>\n```\n\nIf `--fork-from`, `--compact`, or `--launch-option` are used without `--handoff-command`, they are ignored for default Codex launch.\n\n## Compose Before Fork Or Compact\n\nRouting gets work to the right Codex session. Prompt Builder composes the prompt before that routed action runs.\n\n| Helper | Use It When |\n| --- | --- |\n| `xfl` | fork now with an already-obvious prompt |\n| `xfc` | fork, compact, and resume now |\n| `p-f` | compose in `p`, then fork from the selected/current source |\n| `p-c` | compose in `p`, then fork, compact, and resume |\n| `p-cm` | compose in `p`, then compact-fork from conversation `m` |\n\nConfirm the helpers:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc'\n```\n\nInspect the package copy:\n\n```bash\nrg -n 'p-f|p-c|p-cm|xfl|xfc|_p_handoff_zsh|_codex_prompt_builder_fork' zsh/conf.d/40-ai.zsh\n```\n\nConceptual shape:\n\n```text\np-f\n-> p\n-> compose prompt\n-> handoff to zsh -lc\n-> source 40-ai.zsh\n-> _codex_prompt_builder_fork --fork-from <source> <prompt>\n```\n\nCompact shape:\n\n```text\np-c\n-> p\n-> compose prompt\n-> handoff to zsh -lc\n-> source 40-ai.zsh\n-> _codex_prompt_builder_fork --fork-from <source> --compact <prompt>\n```\n\nWhy `zsh -lc` is there:\n\n```text\n`p-f`, `p-c`, `xfl`, and `xfc` are zsh functions in common setups.\nA normal subprocess cannot run a shell function unless zsh loads the file that defines it.\n```\n\n## Composer Affordances\n\nPrompt Builder mirrors the important parts of the Codex composer so editing habits stay consistent.\n\n| Action | Behavior |\n| --- | --- |\n| `Enter` | submit |\n| `Shift+Enter` | insert newline |\n| bracketed paste | pasted text arrives as a paste event |\n| large paste | visible placeholder, full text restored on submit |\n| `Ctrl+C` with draft text | clear current draft |\n| `Ctrl+C` on empty draft | quit |\n| `@` | file selector |\n| `$` | skills lookup |\n| `/` at prompt start | slash command popup |\n| `Tab` | move between Name, Prompt, and options |\n| `Space` on an option | toggle wrapper option |\n\n### `@` File Selector\n\nOpen:\n\n```bash\np\n```\n\nType:\n\n```text\nReview @\n```\n\nSelect the file instead of typing the path from memory.\n\nGood prompts:\n\n```text\nReview @src/checkout/CheckoutForm.tsx for saved payment method regressions.\n```\n\n```text\nUse @src/billing/webhook.ts and @tests/billing/webhook.test.ts to debug duplicate invoice processing.\n```\n\n### Skills Lookup\n\nType:\n\n```text\n$\n```\n\nUse skills when the prompt should invoke a known local workflow instead of retyping every step.\n\nExample:\n\n```text\nUse $oracle-packx to review the auth/session architecture before refresh-token rotation.\n```\n\n### Slash Commands\n\nSlash commands are structured verbs. Put them at the beginning of the prompt.\n\n```text\n/review\n/plan\n/compact\n```\n\n## Ask The Agent This\n\nDebug a checkout-flow prompt before launch:\n\n```text\nUse Prompt Builder as the preflight boundary.\n\nI want to implement saved payment methods in checkout. Help me compose a prompt\nfor `p --print-prompt` first. It should reference the likely checkout files,\ncall out invariants, name tests to run, and ask for the smallest shippable slice.\nDo not launch Codex until the prompt and launch shape have been inspected.\n```\n\nUse a named auth review:\n\n```text\nCreate a Prompt Builder command for an auth/session architecture review.\n\nUse `--name`, show the `--print-launch-json` command, and confirm the launch\nmode uses `app-server-named-thread` with `thread/name/set`. The prompt should\nask for risks, migration steps, and verification commands.\n```\n\nDebug handoff quoting:\n\n```text\nA Prompt Builder handoff to a wrapper is splitting the prompt.\n\nInspect the `--print-launch-json` argv. Confirm the prompt is the final argv\nelement. If the wrapper re-splits it, fix the wrapper rather than adding shell\neval. Use `Command::arg` behavior as the contract.\n```\n\nConnect routed fork:\n\n```text\n`Esc+P` routed to the correct Codex session and launched `p-f`.\n\nInspect how `p-f` uses Prompt Builder, `--handoff-command zsh`, `--handoff-arg`,\n`--fork-from`, and `40-ai.zsh`. Show the dry-run command that proves the prompt\nwill be the final argv element before the fork runs.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| correct binary | `which -a prompt-builder p` shows intended paths |\n| version match | `prompt-builder --version` and `p --version` match |\n| local install updated | `cargo install --path . --locked --force` succeeds |\n| exact prompt saved | `p --print-prompt ... > file` and `test -s file` |\n| command preview sane | `p --dry-run --print-command ...` shows expected command |\n| launch JSON sane | `p --print-launch-json ...` has expected `mode`, `argv`, `env` |\n| named thread | JSON mode is `app-server-named-thread` |\n| thread name | JSON env includes `CODEX_THREAD_NAME` |\n| handoff safe | JSON mode is `handoff` and prompt is last argv |\n| zsh helpers available | `zsh -lc 'source ...40-ai.zsh; whence -w p-f p-c xfl xfc'` |\n| variation seed ready | saved base prompt is non-empty and has invariants |\n\n## If It Goes Wrong\n\n### `p` Is Missing\n\nCheck:\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nLikely causes:\n\n- `prompt-builder` is installed but `p` symlink is missing\n- `p` is only an alias in an interactive shell\n- PATH changed after install\n\nFix shape:\n\n```bash\nln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\nhash -r 2>/dev/null || true\nrehash 2>/dev/null || true\nwhich -a prompt-builder p\np --version\n```\n\n### Wrong Version Runs\n\nCheck all matches:\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nIf working from the local checkout:\n\n```bash\ncargo install --path . --locked --force\nwhich -a prompt-builder p\np --version\n```\n\n### Wrong Codex Binary Runs\n\nInspect:\n\n```bash\np --dry-run --print-command \"hello\"\n```\n\nOverride for a safe demo:\n\n```bash\nPROMPT_BUILDER_CODEX_BIN=/bin/echo \\\n  p --submit --dry-run --print-command \\\n  \"hello override\"\n```\n\nOr pass the binary explicitly:\n\n```bash\np --codex-bin /bin/echo --submit --dry-run --print-command \"hello\"\n```\n\n### Empty Prompt Rejected\n\nCheck producer output:\n\n```bash\nproducer_command | tee /tmp/prompt-builder-input.txt\ntest -s /tmp/prompt-builder-input.txt && echo \"input:OK\"\n```\n\nThen:\n\n```bash\np --stdin --print-prompt < /tmp/prompt-builder-input.txt\n```\n\n### Named Thread Did Not Happen\n\nCheck mode:\n\n```bash\np --print-launch-json --name \"Demo\" \"hello\" | jq '.mode, .env, .app_server'\n```\n\nWhat to look for:\n\n```text\napp-server-named-thread\nCODEX_THREAD_NAME\nthread/name/set\n```\n\n### Shell Function Handoff Fails\n\nSymptom:\n\n```text\nxfc: command not found\n```\n\nBad shape:\n\n```bash\np --handoff-command xfc\n```\n\nBetter shape:\n\n```bash\np \\\n  --handoff-command zsh \\\n  --handoff-arg -lc \\\n  --handoff-arg 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' \\\n  --handoff-arg xfc\n```\n\nDry-run:\n\n```bash\np --submit --dry-run --print-command \\\n  --handoff-command zsh \\\n  --handoff-arg -lc \\\n  --handoff-arg 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; xfc \"$@\"' \\\n  --handoff-arg xfc \\\n  \"continue from this compact fork\"\n```\n\n### Quoting Looks Scary\n\nUse launch JSON instead of guessing from shell text:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  \"fix checkout\nkeep \\$HOME literal\ndo not shell-eval this\" \\\n  | jq '.argv'\n```\n\nWhat to look for:\n\n- the prompt is one JSON string\n- it is the final argv element\n- shell metacharacters remain text\n\nIf a wrapper splits the final argument, fix the wrapper.\n\n### Fork/Compact Options Do Nothing\n\nCause:\n\n```text\n--fork-from, --compact, and --launch-option only matter in handoff mode.\n```\n\nCheck:\n\n```bash\np --print-launch-json --fork-from last --compact \"continue\" | jq '.mode, .argv'\n```\n\nFix:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --fork-from last \\\n  --compact \\\n  \"continue\" \\\n  | jq '.mode, .argv'\n```\n\n## Variation Seed Prompt\n\nA useful variation seed has:\n\n- a concrete software goal\n- invariants that must not change\n- one variable dimension\n- verification command\n- output path or comparison criteria\n\nExample:\n\n```bash\nRUN_ID=\"billing-webhook-variations\"\nROOT=\"artifacts/variations/$RUN_ID\"\nmkdir -p \"$ROOT/prompts\" \"$ROOT/launch\"\n\np --print-prompt \\\n  \"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.\" \\\n  > \"$ROOT/prompts/base.prompt.md\"\n\np --print-launch-json \\\n  \"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.\" \\\n  > \"$ROOT/launch/base.launch.json\"\n\ntest -s \"$ROOT/prompts/base.prompt.md\" && echo \"base-prompt:OK\"\njq '.mode, .prompt' \"$ROOT/launch/base.launch.json\"\n```\n\n## References And Resources\n\n- Prompt Builder command: `prompt-builder`\n- Prompt Builder repo: <https://github.com/johnlindquist/prompt-builder>\n- Short command: `p`\n- Zsh helper file: `zsh/conf.d/40-ai.zsh`\n- 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`\n- Local install command from Prompt Builder checkout: `cargo install --path . --locked --force`\n- Useful debug env var: `PROMPT_BUILDER_CODEX_BIN`\n- Useful key debug env var: `PROMPT_BUILDER_DEBUG_KEYS`\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
