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.
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.
Install the composer from the public repo. Keep --locked — the lockfile pins patched crossterm and ratatui revisions, so unlocked installs may behave differently in the terminal.
cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
This compiles from source and can take a few minutes.
Alias the binary to p. For zsh:
echo 'alias p=prompt-builder' >> ~/.zshrc
For 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.toml with 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 add appends to it instead; existing targets are preserved.
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:
pi helloCODEX_HOME=<expanded home>/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hellotarget list shows four targets: pi, codex, claude, work-profile (the last with CODEX_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.
cargo install fails on dependency resolution, you probably dropped --locked. Re-run with it.target add fails with a duplicate-name error, the user already has a work-profile target; pick another name and adjust the success check to match.target add defaults to --kind pi — always pass --kind explicitly when creating codex/claude targets.--dry-run) fail if the pi CLI is not on PATH; that does not affect any step in this file.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.fixit wrapper 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 (?raw required — the bare URL serves an HTML viewer). Install only if your user prefers skills: stage anywhere EXCEPT a dir named skills/ (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.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 file p-wrap.zsh, provided by those pages as a liftable code block. Note: that file does NOT exist in the prompt-builder repo — the repo's examples/ directory ships only fixit.zsh — so copy p-wrap.zsh from the workshop pages, not from the repo. This file remains the canonical machine copy for setup.# 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: ```bash 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 1. Install the composer from the public repo. Keep `--locked` — the lockfile pins patched `crossterm` and `ratatui` revisions, so unlocked installs may behave differently in the terminal. ```bash cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked ``` This compiles from source and can take a few minutes. 2. Alias the binary to `p`. For zsh: ```bash echo 'alias p=prompt-builder' >> ~/.zshrc ``` For other shells, either add the equivalent alias to that shell's rc file, or use a shell-independent symlink: ```bash ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p ``` 3. 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: ```bash prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work' ``` On a fresh machine this writes `~/.prompt-builder/targets.toml` with exactly this content: ```toml [[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 add` appends to it instead; existing targets are preserved. ## Success check Run: ```bash 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 list` shows four targets: `pi`, `codex`, `claude`, `work-profile` (the last with `CODEX_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 install` fails on dependency resolution, you probably dropped `--locked`. Re-run with it. - If `target add` fails with a duplicate-name error, the user already has a `work-profile` target; pick another name and adjust the success check to match. - `target add` defaults to `--kind pi` — always pass `--kind` explicitly when creating codex/claude targets. - The default target is Pi. Real submissions (without `--dry-run`) fail if the `pi` CLI is not on `PATH`; 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 `fixit` wrapper 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` (`?raw` required — the bare URL serves an HTML viewer). Install only if your user prefers skills: stage anywhere EXCEPT a dir named `skills/` (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 file `p-wrap.zsh`, provided by those pages as a liftable code block. Note: that file does NOT exist in the prompt-builder repo — the repo's `examples/` directory ships only `fixit.zsh` — so copy `p-wrap.zsh` from the workshop pages, not from the repo. This file remains the canonical machine copy for setup.