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

  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.

    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:

    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
    
  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:

    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.

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:

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

# 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.