{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-imp-hook-setup",
  "slug": "imp-hook-setup",
  "title": "Install and inspect dash-prefix Imp routing",
  "summary": "Installation and trust-boundary guidance for foreground and forked Imp routing, including helper contracts, hook registration, verification prompts, cmux inspection commands, and troubleshooting.",
  "category": "Execution",
  "tags": [
    "hooks",
    "imps",
    "setup"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/What This Adds",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Install Targets",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Files In This Directory",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Trust Boundary",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Setup Steps",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Verify Single-Dash Route",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Verify Double-Dash Fork Route",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/Inspect A Forked Session",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/hooks/README.md#Imp Hook Setup Examples/If It Goes Wrong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "execution",
  "wordCount": 509,
  "url": "/topics/codex-imp-hook-setup/",
  "markdownUrl": "/markdown/codex-imp-hook-setup.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-imp-hook-setup.json",
  "headings": [
    {
      "id": "what-this-adds",
      "text": "What This Adds",
      "level": 2
    },
    {
      "id": "install-targets",
      "text": "Install Targets",
      "level": 2
    },
    {
      "id": "files-in-this-directory",
      "text": "Files In This Directory",
      "level": 2
    },
    {
      "id": "trust-boundary",
      "text": "Trust Boundary",
      "level": 2
    },
    {
      "id": "setup-steps",
      "text": "Setup Steps",
      "level": 2
    },
    {
      "id": "verify-single-dash-route",
      "text": "Verify Single-Dash Route",
      "level": 2
    },
    {
      "id": "verify-double-dash-fork-route",
      "text": "Verify Double-Dash Fork Route",
      "level": 2
    },
    {
      "id": "inspect-a-forked-session",
      "text": "Inspect A Forked Session",
      "level": 2
    },
    {
      "id": "if-it-goes-wrong",
      "text": "If It Goes Wrong",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Install and inspect dash-prefix Imp routing\n\nThese files show a common local setup for dash-prefix Imp routing.\n\nThey are examples, not trusted universal dotfiles. Review paths, Codex flags, cmux binary location, and logging before installing.\n\n## What This Adds\n\n```text\n-<imp> task\n-> foreground route\n-> hook adds Imp command/path/description/task/cwd\n-> main Codex turn continues\n\n--<imp> task\n-> fork route\n-> hook opens a cmux pane\n-> hook starts `codex fork <session> -- '-<imp> task'`\n-> hook blocks the current prompt\n```\n\n## Install Targets\n\n```text\n~/.codex/hooks/imp-user-prompt-submit.py\n~/.codex/hooks.json\n~/.local/bin/cmux-run-surface\n```\n\n## Files In This Directory\n\n| File | Purpose |\n| --- | --- |\n| `imp-user-prompt-submit.py.template` | UserPromptSubmit hook example for dash-prefix Imp routing |\n| `hooks.json.example` | minimal hook registration example |\n| `cmux-run-surface.example` | helper contract for opening a focused cmux pane and printing a receipt |\n| `cmux-codex-session-registry.py.example` | redacted contract for resolving a cmux surface id to a Codex session id |\n\n## Trust Boundary\n\nHooks run during prompt submission. They can block prompts, launch local commands, open cmux panes, and write logs.\n\nBefore installing:\n\n```bash\npython3 -m py_compile hooks/imp-user-prompt-submit.py.template\npython3 -m json.tool hooks/hooks.json.example >/dev/null\nrg -n \"<your-secret-patterns>\" hooks\n```\n\n## Setup Steps\n\nCopy only after review:\n\n```bash\nmkdir -p ~/.codex/hooks ~/.local/bin\ncp hooks/imp-user-prompt-submit.py.template ~/.codex/hooks/imp-user-prompt-submit.py\ncp hooks/cmux-run-surface.example ~/.local/bin/cmux-run-surface\nchmod +x ~/.codex/hooks/imp-user-prompt-submit.py ~/.local/bin/cmux-run-surface\n```\n\nMerge `hooks/hooks.json.example` into `~/.codex/hooks.json`. Do not overwrite an existing hooks file blindly.\n\nIf you use helpers that fork the focused Codex conversation from a cmux surface,\nreview `hooks/cmux-codex-session-registry.py.example` and install an equivalent\nregistry implementation at:\n\n```text\n~/.codex/hooks/cmux-codex-session-registry.py\n```\n\n## Verify Single-Dash Route\n\nInside a Codex session with the hook enabled:\n\n```text\n-gmail draft a short email about this conversation\n```\n\nExpected:\n\n- main prompt continues\n- hook context resolves `imp-gmail`\n- hook context includes executable path, description, task text, and cwd\n- main agent does not rediscover the Imp with `which`, `where`, `find`, or broad search\n\n## Verify Double-Dash Fork Route\n\nInside a Codex session with cmux available:\n\n```text\n--gmail draft a short email about this conversation\n```\n\nExpected:\n\n- current prompt blocks\n- new cmux pane opens\n- fork receives normalized prompt `-gmail draft a short email about this conversation`\n- block message includes workspace, pane, surface, and window\n- block message includes read-screen, top, and focus-pane commands\n\n## Inspect A Forked Session\n\nUse the ids printed by the hook:\n\n```bash\ncmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80\ncmux top --workspace workspace:<id> --processes --flat --format tsv\ncmux focus-pane --workspace workspace:<id> --pane pane:<id>\n```\n\n## If It Goes Wrong\n\nCheck the roster and health:\n\n```bash\nimp -l\nimp --which \"your task\"\nimps doctor\n```\n\nCheck cmux:\n\n```bash\ncmux rpc workspace.current\ncommand -v cmux-run-surface\ntail -n 40 ~/Library/Logs/cmux-run-surface.log\n```\n\nCheck hook output:\n\n```bash\ntail -n 20 ~/.codex/logs/imp-user-prompt-submit.jsonl\n```\n\nDo 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 ...'`.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
