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