{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-imp-workflows-reference",
  "slug": "imp-workflows-reference",
  "title": "Narrow Imp agents and routing: practical reference",
  "summary": "Comprehensive Imp reference covering setup and verification, narrow-agent boundaries, command modes, router and compound routing, foreground/forked dash hooks, cmux inspection, fleet and warm-session management, runtime isolation, prompt templates, bounded…",
  "category": "Execution",
  "tags": [
    "imps",
    "routing",
    "isolation"
  ],
  "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!/cheatsheets/09-imps.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Agent Setup Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Big Idea",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Try This Now",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Files To Inspect",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/When To Reach For This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/How This Used To Work",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Commands First",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Dash-Prefix Imp Routing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Foreground vs Forked Imp Requests",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Hook Setup Files",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Inspect A Forked Imp Session",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Router And Compound Routing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Fleet Management",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Isolation Model",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Warm Mode",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Prompt Design Pattern",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Tool Packet To Imp",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/Ask The Agent This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/What To Confirm / How To Know It Worked",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Router Picks Wrong Imp",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Prompt Is Too Broad",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Imp Answers Without Tool Evidence",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Warm Server Looks Stale",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Auth Missing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Compound Route Split Wrong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Dash Prompt Treated As A Codex Option",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Fork Opens But Cannot Be Found Later",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Hook Blocks Unexpectedly",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Do Not Use Resume-Based Fork Helpers For Dash Prompts",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Evolution Suggestion Looks Unsafe",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/If It Goes Wrong/Tool Packet Too Vague",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/09-imps.md#09. Imps/References And Resources",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "execution",
  "wordCount": 3720,
  "url": "/topics/codex-imp-workflows-reference/",
  "markdownUrl": "/markdown/codex-imp-workflows-reference.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-imp-workflows-reference.json",
  "headings": [
    {
      "id": "agent-setup-prompt",
      "text": "Agent Setup Prompt",
      "level": 2
    },
    {
      "id": "big-idea",
      "text": "Big Idea",
      "level": 2
    },
    {
      "id": "try-this-now",
      "text": "Try This Now",
      "level": 2
    },
    {
      "id": "files-to-inspect",
      "text": "Files To Inspect",
      "level": 2
    },
    {
      "id": "when-to-reach-for-this",
      "text": "When To Reach For This",
      "level": 2
    },
    {
      "id": "how-this-used-to-work",
      "text": "How This Used To Work",
      "level": 2
    },
    {
      "id": "commands-first",
      "text": "Commands First",
      "level": 2
    },
    {
      "id": "dash-prefix-imp-routing",
      "text": "Dash-Prefix Imp Routing",
      "level": 2
    },
    {
      "id": "foreground-vs-forked-imp-requests",
      "text": "Foreground vs Forked Imp Requests",
      "level": 2
    },
    {
      "id": "hook-setup-files",
      "text": "Hook Setup Files",
      "level": 2
    },
    {
      "id": "inspect-a-forked-imp-session",
      "text": "Inspect A Forked Imp Session",
      "level": 2
    },
    {
      "id": "router-and-compound-routing",
      "text": "Router And Compound Routing",
      "level": 2
    },
    {
      "id": "fleet-management",
      "text": "Fleet Management",
      "level": 2
    },
    {
      "id": "isolation-model",
      "text": "Isolation Model",
      "level": 2
    },
    {
      "id": "warm-mode",
      "text": "Warm Mode",
      "level": 2
    },
    {
      "id": "prompt-design-pattern",
      "text": "Prompt Design Pattern",
      "level": 2
    },
    {
      "id": "tool-packet-to-imp",
      "text": "Tool Packet To Imp",
      "level": 2
    },
    {
      "id": "ask-the-agent-this",
      "text": "Ask The Agent This",
      "level": 2
    },
    {
      "id": "what-to-confirm-how-to-know-it-worked",
      "text": "What To Confirm / How To Know It Worked",
      "level": 2
    },
    {
      "id": "if-it-goes-wrong",
      "text": "If It Goes Wrong",
      "level": 2
    },
    {
      "id": "router-picks-wrong-imp",
      "text": "Router Picks Wrong Imp",
      "level": 3
    },
    {
      "id": "prompt-is-too-broad",
      "text": "Prompt Is Too Broad",
      "level": 3
    },
    {
      "id": "imp-answers-without-tool-evidence",
      "text": "Imp Answers Without Tool Evidence",
      "level": 3
    },
    {
      "id": "warm-server-looks-stale",
      "text": "Warm Server Looks Stale",
      "level": 3
    },
    {
      "id": "auth-missing",
      "text": "Auth Missing",
      "level": 3
    },
    {
      "id": "compound-route-split-wrong",
      "text": "Compound Route Split Wrong",
      "level": 3
    },
    {
      "id": "dash-prompt-treated-as-a-codex-option",
      "text": "Dash Prompt Treated As A Codex Option",
      "level": 3
    },
    {
      "id": "fork-opens-but-cannot-be-found-later",
      "text": "Fork Opens But Cannot Be Found Later",
      "level": 3
    },
    {
      "id": "hook-blocks-unexpectedly",
      "text": "Hook Blocks Unexpectedly",
      "level": 3
    },
    {
      "id": "do-not-use-resume-based-fork-helpers-for-dash-prompts",
      "text": "Do Not Use Resume-Based Fork Helpers For Dash Prompts",
      "level": 3
    },
    {
      "id": "evolution-suggestion-looks-unsafe",
      "text": "Evolution Suggestion Looks Unsafe",
      "level": 3
    },
    {
      "id": "tool-packet-too-vague",
      "text": "Tool Packet Too Vague",
      "level": 3
    },
    {
      "id": "references-and-resources",
      "text": "References And Resources",
      "level": 2
    },
    {
      "id": "operational-boundaries",
      "text": "Operational boundaries",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Narrow Imp agents and routing: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet up the local Imp/codex-daemons workflow for narrow, tool-shaped agent work. Act as a setup and verification agent: inspect the local implementation, configure only the required files, prove each piece works, and do not run broad agent work until the setup checks pass.\n\n1. Locate the local Imp/codex-daemons checkout or install source. Before changing anything, inspect the setup-relevant files: `README.md`, `imp.ts`, `imps.ts`, `docs/PROMPT.md`, `docs/ISOLATION.md`, `lib/defaults.ts`, `lib/isolated.ts`, `lib/imp.ts`, `lib/appserver.ts`, `imps/imp-rg`, `imps/imp-git`, `imps/imp-github-examples`, `test/router.test.ts`, `test/parseargs.test.ts`, and `test/cli-smoke.test.ts`.\n\n2. Check current command availability and health:\n   - `command -v imp`\n   - `command -v imps`\n   - `imp -l`\n   - `imps list`\n   - `imps ps`\n   - `imps doctor`\n   - `imp --which \"find checkout disabled-state code paths\"`\n   Report missing commands, stale paths, failed health checks, or auth problems before proceeding.\n\n3. Install or repair the local `imp` and `imps` entrypoints only according to the project's own docs and package scripts. Preserve the one-file Imp command model: each `imp-<tool>` command should stay narrow, own one tool, run that tool before answering, and return command evidence. Do not turn an Imp into a general Codex agent.\n\n4. Verify isolated runtime behavior. Confirm each Imp uses a temporary or narrow `CODEX_HOME`, symlinks only the required `auth.json` for login, replaces broad base instructions with the Imp prompt, disables broad project-doc loading, disables memories, keeps MCP servers empty unless a specific Imp requires one, disables web search unless the Imp owns that behavior, disables broad app/plugin surfaces, and removes unused schemas or unrelated tools. Use `imps doctor` and implementation inspection as evidence.\n\n5. Respect privacy boundaries. Do not copy full private Codex config, secret helper files, provider API variables, cookies, tokens, private endpoints, full `env` output, or full machine-local startup files into reports or isolated homes. If auth is needed, use the project's isolated auth symlink pattern rather than copying secret-bearing config. Summarize sensitive findings without printing secret values.\n\n6. Verify direct Imp commands before hook work:\n   - `imp-rg \"find TODOs in src\"`\n   - `imp-rg --run \"find TODOs in src\"`\n   - `imp-rg -q \"find TODOs in src\"`\n   - `imp-rg --no-warm \"find TODOs in src\"`\n   - `imp-rg --serve` only if a foreground warm-server check is appropriate, then stop it\n   - `imp-rg --run --effort minimal \"find TODOs in src\"`\n   Confirm the output includes exact command evidence and file:line matches where applicable. If an Imp answers from memory or without tool evidence, stop and report it.\n\n7. Verify router and compound routing:\n   - `imp --which \"what changed in git since yesterday?\"`\n   - `imp --which \"find the TODOs in src; then commit everything\"`\n   - `imp --which \"find TODOs in src after that summarize git changes\"`\n   Confirm strong connectors such as `;`, `.`, `then`, `after that`, and `afterwards` split routes correctly. Confirm bare `and` is not treated as a strong splitter unless the current implementation explicitly says otherwise.\n\n8. Verify fleet management and warm mode:\n   - `imps list`\n   - `imps ps`\n   - `imps doctor`\n   - `imps stop imp-rg` if a test warm process exists\n   - `imps stop --all` only if safe for the current local session\n   - `imps evolve`\n   - `imps evolve imp-rg`\n   Treat evolution suggestions as review material only. Do not auto-apply changes that broaden an Imp into a general agent.\n\n9. Set up the `UserPromptSubmit` hook for dash-prefix Imp prompts only after the command and isolation checks pass. Review and adapt these examples before installing:\n   - `hooks/imp-user-prompt-submit.py.template` to `~/.codex/hooks/imp-user-prompt-submit.py`\n   - `hooks/hooks.json.example` merged into `~/.codex/hooks.json`\n   - `hooks/cmux-run-surface.example` to `~/.local/bin/cmux-run-surface`\n   Check existing files first. Review paths, Codex flags, cmux binary location, logging, and current-session lookup before enabling the hook.\n\n10. Verify foreground dash routing. A prompt like `-rg find TODOs in src` should resolve the Imp command, executable path, description, task text, and current cwd, then add route context while letting the main prompt continue. The main agent should use that route context and should not rediscover the Imp with `which`, `where`, `find`, or broad repo search.\n\n11. Verify forked dash routing. A prompt like `--rg find TODOs in src` should block the current prompt, open a forked Codex session in a new cmux pane, normalize the prompt to `-rg find TODOs in src`, and print inspectable cmux ids: workspace, pane, surface, and window. Unknown or ambiguous Imp names should block and ask for a clearer Imp name.\n\n12. Confirm the fork command uses direct Codex fork syntax with `--` before the dash-starting prompt, for example: `codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' --dangerously-bypass-approvals-and-sandbox fork <source-session> -- '-rg find TODOs in src'`. The `--` before the prompt is required so `-rg` is not parsed as a Codex option. Do not use resume-based helpers for dash-starting prompts.\n\n13. Verify fork inspection from the returned ids:\n   - `cmux read-screen --workspace workspace:<id> --surface surface:<id> --scrollback --lines 80`\n   - `cmux top --workspace workspace:<id> --processes --flat --format tsv`\n   - `cmux focus-pane --workspace workspace:<id> --pane pane:<id>`\n\n14. Verify marker-packet handoff with a bounded packet only. Prepare a packet with task, search terms, scope, and required command evidence. Route it with `imp --which`, then run the selected Imp with `--run`. Example: task `find checkout disabled-state code paths`, terms `acceptedTerms`, `selectedShipping`, `canSubmit`, scope `src` and `tests`, required evidence `file:line matches and exact rg commands`. The Imp should return exact commands and evidence only, not product recommendations, file edits, or architecture decisions.\n\n15. Do not run broad product reasoning, code edits, commits, fleet-wide stops, or long-running forked tasks unless the setup checks above pass and the user explicitly asks for that next step.\n\n16. Finish with a concise setup report: files inspected, files changed, commands installed or repaired, hook status, isolation/auth status, warm/fleet status, router and compound-routing results, direct command results, fork inspection result if tested, marker-packet result, privacy-sensitive items skipped, and remaining manual steps.\n```\n\n## Big Idea\n\nPhase: Delegation And Review - hand bounded, tool-shaped work to narrow agents before escalating expensive decisions to council review.\n\nAn Imp is a narrow tool agent that should run the tool before it talks.\n\n## Try This Now\n\nCheck the Imp roster: `imp -l`.\nRoute a narrow search before running it: `imp --which \"find checkout disabled-state code paths\"`.\nUse the foreground dash path when regular Codex should keep the conversation: `-rg find checkout disabled-state code paths`.\nUse the forked dash path when the bounded task should run in a new cmux pane: `--rg find checkout disabled-state code paths`.\nUse the chosen Imp only for command evidence; send broad product reasoning back to regular Codex.\n\nImps are single-purpose, isolated Codex agents for common command-line tools. They are not smaller general agents.\n\n```text\nregular Codex -> broad context, general agent\nImp           -> narrow context, one tool, faster loop\n```\n\nUse regular Codex when the task needs broad reasoning across files, product intent, design, or multiple systems.\n\nUse an Imp when the task is tool-shaped:\n\n- search this repo\n- inspect git state\n- summarize GitHub PRs\n- query JSON\n- trim a video\n- inspect package metadata\n- find examples on GitHub\n\nClosing workflow:\n\n```text\nBounded tool question\n-> choose the right Imp\n-> run the narrow tool\n-> preserve command evidence\n-> return clean results\n-> hand results back to the broader task\n```\n\n## Files To Inspect\n\nImp implementation references:\n\n```text\nREADME.md\nimp.ts\nimps.ts\ndocs/PROMPT.md\ndocs/ISOLATION.md\nlib/defaults.ts\nlib/isolated.ts\nlib/imp.ts\nlib/appserver.ts\nimps/imp-rg\nimps/imp-git\nimps/imp-github-examples\ntest/router.test.ts\ntest/parseargs.test.ts\ntest/cli-smoke.test.ts\n```\n\n## When To Reach For This\n\nUse an Imp when the request maps cleanly to one tool.\n\n| Use An Imp For | Example |\n| --- | --- |\n| repo search | `imp-rg \"find checkout disabled state\"` |\n| git state | `imp-git \"what changed since yesterday?\"` |\n| GitHub examples | `imp-github-examples \"find examples of DESIGN.md\"` |\n| JSON query | `imp-jq --run \"count users by plan\"` |\n| video/file command | `imp-ffmpeg \"trim first 10 seconds\"` |\n| package metadata | `imp-npm \"inspect package scripts\"` |\n\nUse regular Codex when:\n\n- the task spans several tools\n- code edits are likely\n- product intent matters\n- architecture tradeoffs matter\n- the request is still too vague\n- the next move is not tool-shaped yet\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nEvery small tool question needs a full Codex session with broad project context.\n```\n\nWhat the workflow gives you now:\n\n```text\nTool-shaped work can go to a narrow Imp that runs one tool, returns command\nevidence, and leaves broad reasoning to regular Codex.\n```\n\nWhat you used to expect:\n\n```text\nAn agent can infer the right tool and explain from memory.\n```\n\nWhat the workflow gives you now:\n\n```text\nAn Imp has one operating rule and command map. It runs the tool first and\nanswers from the output.\n```\n\n## Commands First\n\nStart with identity and health checks:\n\n```bash\nimp -l\nimps list\nimps ps\nimps doctor\n```\n\nCheck routing without spending a model turn:\n\n```bash\nimp --which \"what changed in git since yesterday?\"\nimp --which \"find the TODOs in src; then commit everything\"\nimp --which \"find examples of DESIGN.md created in the past 2 months\"\n```\n\nExpected routing shape:\n\n```text\nimp-git\nimp-rg                  find the TODOs in src\nimp-git                 commit everything\nimp-github-examples\n```\n\nRun one Imp interactively:\n\n```bash\nimp-rg \"find TODOs in src\"\n```\n\nRun one Imp non-interactively:\n\n```bash\nimp-rg --run \"find TODOs in src\"\n```\n\nQuiet final-answer-only mode:\n\n```bash\nimp-rg -q \"find TODOs in src\"\n```\n\nOpt out of warm mode:\n\n```bash\nimp-rg --no-warm \"find TODOs in src\"\n```\n\nRun a warm server in the foreground:\n\n```bash\nimp-rg --serve\n```\n\nOverride reasoning effort for one prompt:\n\n```bash\nimp-rg --run --effort minimal \"find TODOs in src\"\n```\n\n## Dash-Prefix Imp Routing\n\nA common local setup adds a `UserPromptSubmit` hook for Imp prompts.\n\n| Prompt Shape | Meaning | What Happens |\n| --- | --- | --- |\n| `-<imp> <task>` | foreground Imp route | hook resolves the Imp, adds routing context, and lets the main prompt continue |\n| `--<imp> <task>` | forked Imp route | hook blocks the current prompt, opens a forked Codex session in cmux, and seeds it with `-<imp> <task>` |\n| unknown Imp | unsafe route | hook blocks and asks for a clearer Imp name or a new Imp |\n| ambiguous Imp | unsafe route | hook blocks and shows likely matches |\n\nThe hook should resolve the Imp command, executable path, description, task text, and current cwd before the main agent starts working.\n\nThat means the main agent should not waste a turn rediscovering the Imp with `which`, `where`, `find`, or broad repo search. It should use the hook-provided route.\n\n## Foreground vs Forked Imp Requests\n\nUse single dash when the main agent should stay responsible for the broader conversation.\n\n```text\n-rg find checkout disabled-state code paths\n```\n\nUse double dash when the Imp task should run separately and the current prompt should not continue.\n\n```text\n--rg find checkout disabled-state code paths\n```\n\n| Use | Pick | Why |\n| --- | --- | --- |\n| main agent needs repo or conversation context first | `-<imp>` | hook adds route context; main agent can gather context before invoking the Imp |\n| bounded tool task should run separately | `--<imp>` | hook opens a forked Codex session in a new cmux pane |\n| task may require product judgment | regular Codex | not tool-shaped enough yet |\n| Imp name is unclear | neither | clarify or run `imp --which` |\n\nDouble dash normalizes to a single-dash prompt inside the fork.\n\n```text\n--gmail draft a reply\n-> forked Codex prompt:\n-gmail draft a reply\n```\n\nDouble dash does not mean \"run the Imp harder.\" It means \"fork the current Codex conversation and seed the fork.\"\n\n## Hook Setup Files\n\nCommon local 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\nWorkshop package examples live under:\n\n```text\nhooks/\n```\n\nTreat these as setup examples, not trusted universal dotfiles. Review paths, Codex flags, cmux binary location, and logging before installing.\n\n| File | Install Target | Purpose |\n| --- | --- | --- |\n| `hooks/imp-user-prompt-submit.py.template` | `~/.codex/hooks/imp-user-prompt-submit.py` | parse dash-prefix prompts and route or fork Imps |\n| `hooks/hooks.json.example` | merge into `~/.codex/hooks.json` | register the `UserPromptSubmit` hook |\n| `hooks/cmux-run-surface.example` | `~/.local/bin/cmux-run-surface` | open a cmux pane and print an inspectable receipt |\n\n## Inspect A Forked Imp Session\n\nA successful fork should print cmux ids:\n\n```text\ncmux workspace: workspace:<id>\ncmux pane: pane:<id>\ncmux surface: surface:<id>\ncmux window: window:<id>\n```\n\nUse the printed ids:\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| Command | Use It To |\n| --- | --- |\n| `cmux read-screen ...` | inspect recent fork output |\n| `cmux top ...` | check running processes in the workspace |\n| `cmux focus-pane ...` | jump back to the forked pane |\n\nThe fork path should use direct Codex fork with `--` before the prompt:\n\n```bash\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n  --dangerously-bypass-approvals-and-sandbox \\\n  fork <source-session> -- '-gmail draft ...'\n```\n\nThe `--` before the prompt prevents `-gmail` from being parsed as Codex options.\n\n## Router And Compound Routing\n\nUse the router when you know the request but not the Imp.\n\n```bash\nimp \"what changed in git since yesterday?\"\nimp \"trim the first 10s off intro.mp4\"\nimp git \"what changed?\"\nimp --which \"list my PRs\"\n```\n\nCompound routing splits strong connectors:\n\n```bash\nimp --which \"find the TODOs in src; then commit everything\"\n```\n\nStrong splitters:\n\n```text\n;\n.\nthen\nafter that\nafterwards\n```\n\nBare `and` should not split by itself.\n\n## Fleet Management\n\nList Imps:\n\n```bash\nimps list\n```\n\nSee warm processes:\n\n```bash\nimps ps\n```\n\nStop one:\n\n```bash\nimps stop imp-rg\n```\n\nStop all:\n\n```bash\nimps stop --all\n```\n\nInspect health:\n\n```bash\nimps doctor\n```\n\nInspect evolution suggestions:\n\n```bash\nimps evolve\nimps evolve imp-rg\n```\n\nEvolution suggestions are review material. They are not magic self-modification.\n\n## Isolation Model\n\nEach Imp runs with a narrow isolated runtime.\n\nImportant boundaries:\n\n| Boundary | Meaning |\n| --- | --- |\n| temporary `CODEX_HOME` | isolated runtime folder |\n| symlinked `auth.json` | login works without copying full config |\n| replaced base instructions | Imp prompt owns the behavior |\n| explicit developer instructions | one tool, one operating rule |\n| project docs disabled | no broad repo instruction loading |\n| memories disabled | no broad personal memory context |\n| MCP servers empty | no unrelated tool surface |\n| web search disabled | unless the Imp specifically owns that behavior |\n| apps disabled | no broad app/plugin surface |\n| unused schemas disabled | fewer ways to drift |\n\nThe point is not restriction for its own sake. The point is a clean tool boundary.\n\n## Warm Mode\n\nWarm mode keeps a narrow app-server session ready for faster turns.\n\nConcepts:\n\n```text\nwarm app-server\nsocketPath\nsourceFingerprint\nthread/start\nturn/start\nCODEX_IMP_IDLE_MINUTES\n```\n\nUse warm mode when the same Imp will be called repeatedly.\n\nUse `--no-warm` when you want a fresh one-shot run:\n\n```bash\nimp-rg --no-warm \"find TODOs in src\"\n```\n\nIf warm behavior looks stale:\n\n```bash\nimps ps\nimps stop imp-rg\nimps doctor\n```\n\n## Prompt Design Pattern\n\nA strong Imp prompt has:\n\n```text\nOperating rule\nCommand map\nWorked examples\nError recovery\nOutput rules\n```\n\nTemplate:\n\n~~~markdown\n# imp-<tool>\n\n## Operating Rule\n\nRun `<tool>` via `exec_command` before any final answer. Do not answer from memory.\n\n## Command Map\n\n| User Intent | Exact Command |\n| --- | --- |\n| find text | `<tool> ...` |\n| list status | `<tool> ...` |\n| inspect help | `<tool> --help` |\n\n## Worked Examples\n\n### Example 1\n\nUser request:\n\n```text\nfind checkout disabled state\n```\n\nCommand:\n\n```bash\nrg -n \"disabled|canSubmit|isSubmitting\" src tests\n```\n\n## Error Recovery\n\n| Error Text | Next Command |\n| --- | --- |\n| command not found | inspect install / PATH |\n| no results | broaden terms once |\n| unknown flag | run help |\n\n## Output Rules\n\n- show exact command evidence\n- return file:line matches when available\n- do not invent results\n- say when the tool found nothing\n~~~\n\n## Tool Packet To Imp\n\nStart from a bounded tool packet:\n\n```markdown\n# Imp Tool Packet\n\n- task:\n  - find checkout disabled-state code paths\n- search terms:\n  - acceptedTerms\n  - selectedShipping\n  - checkout disabled\n- scope:\n  - src\n  - tests\n- required verification:\n  - return file:line matches\n  - return exact commands used\n```\n\nRoute it:\n\n```bash\nimp --which \"find code paths related to acceptedTerms, selectedShipping, and checkout disabled\"\n```\n\nRun the narrow tool:\n\n```bash\nimp-rg --run \"Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and the exact rg commands used.\"\n```\n\nGood Imp request:\n\n```text\nHere is a bounded tool packet.\n\nSearch for code paths related to checkout disabled state. Use these terms:\nacceptedTerms, selectedShipping, checkout disabled. Stay inside src and tests.\n\nReturn file:line matches and the exact rg commands used. Do not propose a fix.\n```\n\nBad Imp request:\n\n```text\nFix checkout.\n```\n\n## Ask The Agent This\n\nRoute a tool packet:\n\n```text\nUse Imps for the tool-shaped part of this task.\n\nGiven this bounded tool packet, first run `imp --which` to choose the narrow\nImp. The packet points at checkout disabled state and includes terms\n`acceptedTerms`, `selectedShipping`, and `canSubmit`. Use the chosen Imp to\nreturn command evidence only. Do not edit files.\n```\n\nSearch with `imp-rg`:\n\n```text\nUse `imp-rg`.\n\nFind every place checkout disabled state is computed. Search for `disabled`,\n`canSubmit`, `isSubmitting`, `acceptedTerms`, and `selectedShipping` under\n`src` and `tests`. Return file:line matches and the exact commands used.\n```\n\nInspect git state:\n\n```text\nUse `imp-git`.\n\nSummarize current dirty state and recent commits. Return commands and evidence.\nDo not stage, commit, or modify files.\n```\n\nDesign a new Imp:\n\n```text\nDesign an Imp for a project-specific deploy CLI.\n\nIt must use exactly one tool, run help/status before answering, include a\ncommand map, worked examples, error recovery, and output rules. Explain when\nthis should remain regular Codex instead.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| Imp roster visible | `imp -l` or `imps list` |\n| fleet healthy | `imps doctor` |\n| route checked | `imp --which \"...\"` |\n| direct Imp works | `imp-rg \"find TODOs in src\"` |\n| noninteractive works | `imp-rg --run \"find TODOs in src\"` |\n| quiet mode works | `imp-rg -q \"find TODOs in src\"` |\n| warm state known | `imps ps` |\n| warm server stopped | `imps stop imp-rg` or `imps stop --all` |\n| broad work rejected | task returns to regular Codex when not tool-shaped |\n| command evidence present | Imp output includes exact commands/results |\n| project safety net passes | `bun test` in the Imp project |\n| dash hook installed | `-rg find TODOs` adds Imp route context without blocking |\n| fork hook installed | `--rg find TODOs` blocks current prompt and opens a cmux fork |\n| Imp path resolved | hook context names `imp-<name>` and executable path |\n| no rediscovery needed | main agent does not run `which`, `where`, `find`, or broad search for the Imp |\n| cmux fork inspectable | block message includes workspace, pane, surface, window, and check commands |\n| dash prompt safe | fork uses `codex fork <session> -- '-imp ...'` |\n\n## If It Goes Wrong\n\n### Router Picks Wrong Imp\n\nCheck routing first:\n\n```bash\nimp --which \"your request\"\n```\n\nThen use an explicit route:\n\n```bash\nimp rg \"find TODOs in src\"\n```\n\n### Prompt Is Too Broad\n\nBad:\n\n```text\nfix checkout\n```\n\nBetter:\n\n```text\nUse rg to find checkout disabled-state code paths. Return file:line evidence only.\n```\n\nIf the task still needs product reasoning, send it back to regular Codex.\n\n### Imp Answers Without Tool Evidence\n\nStrengthen the operating rule:\n\n```text\nRun the tool before final answer. Include exact commands and outputs.\n```\n\nAdd worked examples.\n\n### Warm Server Looks Stale\n\nRun:\n\n```bash\nimps ps\nimps stop <imp>\nimps doctor\n```\n\n### Auth Missing\n\nRun:\n\n```bash\nimps doctor\n```\n\nLook for `auth.json` status.\n\n### Compound Route Split Wrong\n\nUse a strong connector:\n\n```bash\nimp --which \"find TODOs in src; then summarize git changes\"\n```\n\nAvoid relying on bare `and`.\n\n### Dash Prompt Treated As A Codex Option\n\nBad shape: any helper that creates a fork id and then resumes it with `-gmail draft ...`.\n\nThe dash-starting prompt can be parsed as command options.\n\nSafer fork shape:\n\n```bash\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"' \\\n  --dangerously-bypass-approvals-and-sandbox \\\n  fork <source-session> -- '-gmail draft ...'\n```\n\nThe `--` matters.\n\n### Fork Opens But Cannot Be Found Later\n\nUse the cmux ids from the block message:\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### Hook Blocks Unexpectedly\n\nLikely causes:\n\n- unknown Imp name\n- ambiguous Imp name\n- missing `imp-` roster\n- missing cmux helper\n- no current Codex session id\n- cmux pane creation failed\n\nRecovery:\n\n```bash\nimp -l\nimp --which \"your task\"\nimps doctor\ncmux rpc workspace.current\ncommand -v cmux-run-surface\n```\n\n### Do Not Use Resume-Based Fork Helpers For Dash Prompts\n\nAvoid helper paths that create a fork id and then resume it with the dash-starting prompt.\n\nUse direct `codex fork <source-session> -- '-imp ...'` for the hook path.\n\n### Evolution Suggestion Looks Unsafe\n\nTreat it as review material:\n\n```bash\nimps evolve imp-rg\n```\n\nDismiss or edit manually. Do not accept broad behavior that makes the Imp a general agent.\n\n### Tool Packet Too Vague\n\nSharpen the packet before choosing an Imp:\n\n```text\ntask:\nsearch terms:\nscope:\nrequired command evidence:\n```\n\n## References And Resources\n\n- Codex Imps project: <https://github.com/johnlindquist/codex-imps>\n- Imp roster: `imp -l`, `imps list`\n- Router: `imp --which \"...\"`\n- Fleet health: `imps doctor`\n- Fleet processes: `imps ps`\n- Stop warm Imps: `imps stop <imp>`, `imps stop --all`\n- Evolution suggestions: `imps evolve`, `imps evolve <imp>`\n- Project safety net: `bun test`\n- Key implementation files: `imp.ts`, `imps.ts`, `lib/isolated.ts`, `lib/imp.ts`, `lib/appserver.ts`\n\n## Operational boundaries\n\n- Configuration isolation is not an operating-system security sandbox. A linked auth file still grants access to authentication material, and the illustrated fork launch explicitly bypasses approval and sandbox protections.\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/)"
}
