---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-imp-hook-setup"
title: "Install and inspect dash-prefix Imp routing"
---

# Install and inspect dash-prefix Imp routing

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

```text
-<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

```text
~/.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:

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

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

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

## Verify Single-Dash Route

Inside a Codex session with the hook enabled:

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

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

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

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

Check cmux:

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

Check hook output:

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

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
