The fixit debugger persona
You're an expert debugger who always starts with the $fusion skill. The user will pass a terse bug; investigate the behavior and fix it.
workshop-2026-07-17 · section 04
One terminal composer (p) in front of Pi, Codex, and Claude Code — and the shell-wrapper pattern that turns into mdflow.
prompt-builder (alias p) is a terminal composer that gives your prompt its own tool: $ skill lookup, @ file search, and Ctrl+R cross-agent history in front of Pi, Codex, and Claude Code.p, Tab to Target ‹name›, cycle agents with Space — and inspect any launch first with --dry-run --print-command.🤖 Have your agent set this up — paste this into it:
Fetch https://shiny-bloom-f8hv.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.
# needs a Rust toolchain (rustup); pi/codex/claude CLIs are optional for dry-runs
cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
alias p=prompt-builder
p --dry-run --print-command "hello" # prints the exact launch: pi hello
p # open the composer: $ skills · @ files · Ctrl+R history
You're an expert debugger who always starts with the $fusion skill. The user will pass a terse bug; investigate the behavior and fix it.
Write me a zsh wrapper function that opens prompt-builder in handoff mode and hands my composed prompt to my own shell function. Use this pattern: prompt-builder --handoff-command <cmd> --handoff-arg <arg> passes the prompt as the final argv element with no shell eval. Before wiring in the real command, prove the wrapper with: prompt-builder --submit --dry-run --handoff-command /bin/echo "test" — my prompt must appear verbatim as the final echoed argument. Show me that proof, then swap the real command in. The repeated move I want to wrap: <describe your move>.
Add a prompt-builder launch target for a second Claude Code account: run prompt-builder target add second-account --kind claude --env 'CLAUDE_CONFIG_DIR=~/.claude-second' and then verify it with prompt-builder --dry-run --target second-account --print-command "hello". Show me the printed command so I can read the exact argv before any real launch.
These steps mirror agent.md — the machine copy your agent fetches.
p. Keep --locked: the lockfile pins patched crossterm/ratatui revisions.
cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
echo 'alias p=prompt-builder' >> ~/.zshrc
source ~/.zshrc
prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'
This writes ~/.prompt-builder/targets.toml. On a fresh machine the file now reads exactly:
[[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"
Success check: print the launches without running anything, then list the targets.
prompt-builder --dry-run --print-command "hello"
prompt-builder --dry-run --target work-profile --print-command "hello"
prompt-builder target list
pi hello
CODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello
pi pi bin=pi
codex codex bin=codex
claude claude bin=claude
work-profile codex bin=codex CODEX_HOME=~/.codex-work
In real output the CODEX_HOME path appears expanded to your full home directory. Read the second line closely — that bypass flag is the reason dry-run comes first.
Count where your prompts get written: for most agent-CLI users, all of them live inside one agent's interactive loop. The prompt — the thing that carries your intent — has no home of its own; switch agents and you abandon your history, paste handling, and muscle memory.
prompt-builder is a small Ratatui composer whose only job is composing: skill lookup, file search, slash commands, paste handling, and history that follows you, not the agent — it reads Codex's own ~/.codex/history.jsonl alongside its private file, so prompts from either tool come back with Ctrl+R. The agent is just a selector at the bottom of the screen. Targets are named launch profiles — binary, env vars, model, default args — stored in ~/.prompt-builder/targets.toml; a different CODEX_HOME or CLAUDE_CONFIG_DIR is a different identity.
$ prompt-builder target list
pi pi bin=pi
codex codex bin=codex
claude claude bin=claude
work-profile codex bin=codex CODEX_HOME=~/.codex-work
second-account claude bin=claude CLAUDE_CONFIG_DIR=~/.claude-second
The test for whether this matters: the next time you re-type a prompt into a second agent because the first one stalled, you've found the cost this tool removes.
A tool that launches agents for you earns trust only if you can see exactly what it would run. Every launch path has a dry-run twin: --print-command shows the exact argv; --print-launch-json emits a stable schema_version: 1 manifest for scripts.
$ prompt-builder --dry-run --print-command "hello"
pi hello
$ prompt-builder --dry-run --print-launch-json "hello"
{
"schema_version": 1,
"mode": "pi",
"command": "pi",
"argv": ["pi", "hello"],
"env": {},
"prompt": "hello",
"pi": {"cwd": ".", "session_name": null}
}
Codex and Claude targets launch with permission-bypass flags — only point them at directories where you accept the agent modifying files and running commands (details in the appendix). Before trusting any target you add, run it once with --dry-run --print-command and read the argv aloud.
The interesting move is handoff mode: --handoff-command with repeatable --handoff-arg makes the composer call any command with the submitted prompt as the final argv element — passed as data, never through shell eval.
$ prompt-builder --submit --dry-run --handoff-command /bin/echo "hello from handoff"
/bin/echo 'hello from handoff'
$ prompt-builder --submit --dry-run --handoff-command /bin/echo \
--fork-from last --compact "continue"
/bin/echo --fork-from last --compact continue
Those --fork-from/--compact flags render as checkbox toggles in the TUI — the wrapper declares its own UI. Two patterns run daily in the author's shell: fixit bakes a debugger persona into the composer, and p-f composes a prompt, then forks the latest Codex session and resumes it with that prompt. Here is the workshop's copy of both, complete — this page is the file's source (the repo's examples/ ships only fixit.zsh; lift p-wrap.zsh from the block below):
# Wrapping "p" (prompt-builder) with custom tools — the two patterns.
# Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh
# and the p-f/p-c family in your zsh config.
# ── Pattern 1: bake instructions into the composer ─────────────────
# The composer opens normally, but the launch carries your persona/context.
fixit() {
prompt-builder \
--target codex \
-C "$PWD" \
--developer-instructions "You're an expert debugger who always starts with the \$fusion skill. The user will pass a terse bug; investigate the behavior and fix it."
}
# ── Pattern 2: handoff mode — your shell function IS the launcher ──
# prompt-builder composes, then calls your command with the prompt as
# the final argv element (Command::arg, no shell eval).
_p_handoff_zsh() {
local fn="${1:?Usage: _p_handoff_zsh <function> [p-args...]}"
shift
p \
--handoff-command zsh \
--handoff-arg -lc \
--handoff-arg "source \"\$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \
--handoff-arg "$fn" \
"$@"
}
# Compose a prompt, then fork the latest Codex session and resume with it.
p-f() {
local source="${CODEX_FORK_SESSION_ID:-last}"
_p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@"
}
# Same, but compact the forked session before resuming.
p-c() {
local source="${CODEX_FORK_SESSION_ID:-last}"
_p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@"
}
# ── The mdflow lead-in ──────────────────────────────────────────────
# Every wrapper above is: instructions + context + a launch decision.
# Declare that in a markdown file instead of a shell function and you
# get an mdflow flow — reviewable, diffable, evaluable:
#
# flows/fixit.codex.md
# ---
# engine: codex
# ---
# You're an expert debugger. Bug report: {{ _1 }}
#
# prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter
# for the fuzzy picker; flow `_inputs` render as form fields.
To adopt the pattern, write one wrapper for a move you repeat and prove it with --submit --dry-run --handoff-command /bin/echo substituted in: your prompt must appear verbatim as the final echoed argument. When it does, swap the real command back in. (p-f calls the author's private fork helper — supply your own; see the appendix.)
Look at what every wrapper above actually is: instructions, plus context, plus a launch decision. Why is that a shell function and not a file? Shell functions hide in dotfiles; files can be diffed, reviewed, shared, and gated with evals. That's mdflow: each repeatable agent job as a markdown file, run on the CLI engine you already use. The fixit wrapper restated as a flow looks like this:
--- flows/fixit.codex.md ---
engine: codex
---
You're an expert debugger. Bug report: {{ _1 }}
The same job also ships in a third form: an agent skill. The full progression is fixit.zsh (shell wrapper) → flows/fixit.codex.md (mdflow flow) → fixit (SKILL.md) — pick whichever your stack runs on. The skill twin is hosted on this site; install it by staging anywhere except a dir named skills/ (the skills CLI claims that name as its own symlink target and you'd install an empty skill):
mkdir -p skill-src/fixit
curl -fsSL "https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw" -o skill-src/fixit/SKILL.md
npx skills add ./skill-src --skill fixit -y
The bridge already exists in the composer: with the mdflow CLI on PATH, a Flow ‹name› selector appears beside the target selector, Enter opens a fuzzy picker, and a flow's inputs render as form fields. A ⚠ ignores prompt badge warns when a flow never references {{ _1 }}/{{ _prompt }} — mdflow would silently drop your prompt. The promotion rule: when a wrapper survives unchanged for a few weeks, move it into a flow file. If it keeps changing, it isn't ready — keep it in the shell.
--dangerously-bypass-approvals-and-sandbox; Claude targets launch with claude --dangerously-skip-permissions -- <prompt>. Pi targets add no bypass flag and rely on Pi's own trust settings. Only use these launchers in directories where you accept the selected agent modifying files and running commands.review.md, review.claude.md, git diff | explain.md).fixit persona references $fusion, the author's personal skill. Swap in a skill you actually have, or drop that clause.p-f/p-c call _codex_prompt_builder_fork, a private helper in the author's zsh config. The wrappers are printed as evidence of the pattern; to use them, point _p_handoff_zsh at your own function.~/.codex-work for readability; real output expands env paths to your full home directory. Target names work-profile and second-account are genericized stand-ins for the author's personal profiles.PATH, though every --dry-run/print flag works with no agent CLIs installed.Sources: S1 — the prompt-builder README (features, shortcuts, targets, handoff mode, mdflow selector, safety flags) at github.com/johnlindquist/prompt-builder; S2 — the project's shipped examples/fixit.zsh; S3 — wrapper functions (p-f, p-c, _p_handoff_zsh) from the author's working zsh configuration, printed here via the workshop's examples/p-wrap.zsh copy; S4 — live command output regenerated 2026-07-16 from prompt-builder v0.1.0, with personal profile names genericized and home paths shown as ~; S5 — the mdflow README introduction; S6 — the workshop agenda brief, used for framing only. No session identifiers, emails, or credentials appear. JavaScript on this page is one canonical code-copy enhancement (app.js); the page reads fully without it. Published to here.now as "workshop-2026-07-17 04-prompt-builder".