Install and inspect dash-prefix Imp routing

Installation and trust-boundary guidance for foreground and forked Imp routing, including helper contracts, hook registration, verification prompts, cmux inspection commands, and troubleshooting.

These files show a common local setup for dash-prefix Imp routing.

They are examples, not trusted universal dotfiles. Review paths, Codex flags, cmux binary location, and logging before installing.

What This Adds

-<imp> task
-> foreground route
-> hook adds Imp command/path/description/task/cwd
-> main Codex turn continues

--<imp> task
-> fork route
-> hook opens a cmux pane
-> hook starts `codex fork <session> -- '-<imp> task'`
-> hook blocks the current prompt

Install Targets

~/.codex/hooks/imp-user-prompt-submit.py
~/.codex/hooks.json
~/.local/bin/cmux-run-surface

Files In This Directory

File Purpose
imp-user-prompt-submit.py.template UserPromptSubmit hook example for dash-prefix Imp routing
hooks.json.example minimal hook registration example
cmux-run-surface.example helper contract for opening a focused cmux pane and printing a receipt
cmux-codex-session-registry.py.example redacted contract for resolving a cmux surface id to a Codex session id

Trust Boundary

Hooks run during prompt submission. They can block prompts, launch local commands, open cmux panes, and write logs.

Before installing:

python3 -m py_compile hooks/imp-user-prompt-submit.py.template
python3 -m json.tool hooks/hooks.json.example >/dev/null
rg -n "<your-secret-patterns>" hooks

Setup Steps

Copy only after review:

mkdir -p ~/.codex/hooks ~/.local/bin
cp hooks/imp-user-prompt-submit.py.template ~/.codex/hooks/imp-user-prompt-submit.py
cp hooks/cmux-run-surface.example ~/.local/bin/cmux-run-surface
chmod +x ~/.codex/hooks/imp-user-prompt-submit.py ~/.local/bin/cmux-run-surface

Merge hooks/hooks.json.example into ~/.codex/hooks.json. Do not overwrite an existing hooks file blindly.

If you use helpers that fork the focused Codex conversation from a cmux surface, review hooks/cmux-codex-session-registry.py.example and install an equivalent registry implementation at:

~/.codex/hooks/cmux-codex-session-registry.py

Verify Single-Dash Route

Inside a Codex session with the hook enabled:

-gmail draft a short email about this conversation

Expected:

  • main prompt continues
  • hook context resolves imp-gmail
  • hook context includes executable path, description, task text, and cwd
  • main agent does not rediscover the Imp with which, where, find, or broad search

Verify Double-Dash Fork Route

Inside a Codex session with cmux available:

--gmail draft a short email about this conversation

Expected:

  • current prompt blocks
  • new cmux pane opens
  • fork receives normalized prompt -gmail draft a short email about this conversation
  • block message includes workspace, pane, surface, and window
  • block message includes read-screen, top, and focus-pane commands

Inspect A Forked Session

Use the ids printed by the hook:

cmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80
cmux top --workspace workspace:<id> --processes --flat --format tsv
cmux focus-pane --workspace workspace:<id> --pane pane:<id>

If It Goes Wrong

Check the roster and health:

imp -l
imp --which "your task"
imps doctor

Check cmux:

cmux rpc workspace.current
command -v cmux-run-surface
tail -n 40 ~/Library/Logs/cmux-run-surface.log

Check hook output:

tail -n 20 ~/.codex/logs/imp-user-prompt-submit.jsonl

Do not route dash-prefix fork prompts through helpers that create a fork id and then resume it with the dash-starting prompt. A prompt like -gmail ... can be parsed as options. Use direct codex fork <source-session> -- '-gmail ...'.

Source references