{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-imp-workflows-team-guide",
  "slug": "imp-workflows-team-guide",
  "title": "Narrow Imp agents and routing: team walkthrough",
  "summary": "Bounded one-tool agent workflow covering routing, direct execution, foreground versus forked dash-prefix prompts, fleet health, warm-mode recovery, isolation, command evidence, and marker-packet handoff. Includes cmux inspection commands, fallback receipt…",
  "category": "Team practice",
  "tags": [
    "imps",
    "routing",
    "isolation",
    "team-guide"
  ],
  "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!/instructor-notes/09-imps.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Presenter Goal",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Timing Options",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Timing Options/10-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Timing Options/20-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Timing Options/35-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Things To Say",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/1. Health",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/2. Routing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/3. Direct Imp",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/4. Dash-Prefix Demo",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/5. Marker Packet Bridge",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Live Demo Script/6. Safety Net",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Cut Path",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Boundaries",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Failure Paths To Preserve",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Presenter Checklist",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/09-imps.md#Instructor Notes: 09. Imps/Closing Line",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "team-practice",
  "wordCount": 920,
  "url": "/topics/codex-imp-workflows-team-guide/",
  "markdownUrl": "/markdown/codex-imp-workflows-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-imp-workflows-team-guide.json",
  "headings": [
    {
      "id": "team-learning-goal",
      "text": "Team Learning Goal",
      "level": 2
    },
    {
      "id": "walkthrough-depth",
      "text": "Walkthrough Depth",
      "level": 2
    },
    {
      "id": "essential-walkthrough",
      "text": "Essential Walkthrough",
      "level": 3
    },
    {
      "id": "expanded-walkthrough",
      "text": "Expanded Walkthrough",
      "level": 3
    },
    {
      "id": "deep-dive-walkthrough",
      "text": "Deep-Dive Walkthrough",
      "level": 3
    },
    {
      "id": "talking-points",
      "text": "Talking Points",
      "level": 2
    },
    {
      "id": "live-demo-script",
      "text": "Live Demo Script",
      "level": 2
    },
    {
      "id": "1-health",
      "text": "1. Health",
      "level": 3
    },
    {
      "id": "2-routing",
      "text": "2. Routing",
      "level": 3
    },
    {
      "id": "3-direct-imp",
      "text": "3. Direct Imp",
      "level": 3
    },
    {
      "id": "4-dash-prefix-demo",
      "text": "4. Dash-Prefix Demo",
      "level": 3
    },
    {
      "id": "5-marker-packet-bridge",
      "text": "5. Marker Packet Bridge",
      "level": 3
    },
    {
      "id": "6-safety-net",
      "text": "6. Safety Net",
      "level": 3
    },
    {
      "id": "minimal-useful-path",
      "text": "Minimal Useful Path",
      "level": 2
    },
    {
      "id": "boundaries",
      "text": "Boundaries",
      "level": 2
    },
    {
      "id": "failure-paths-to-preserve",
      "text": "Failure Paths To Preserve",
      "level": 2
    },
    {
      "id": "team-checklist",
      "text": "Team Checklist",
      "level": 2
    },
    {
      "id": "closing-line",
      "text": "Closing Line",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Narrow Imp agents and routing: team walkthrough\n\n## Team Learning Goal\n\nClose the workshop by showing where bounded, tool-specific packets go next.\n\nThe core idea:\n\n```text\nAn Imp is a narrow tool agent that should run the tool before it talks.\n```\n\nBy the end of this section, the room should understand:\n\n- regular Codex vs Imp\n- when a task is tool-shaped\n- how to route before running\n- direct vs noninteractive vs quiet modes\n- warm mode and fleet management\n- isolation boundaries\n- evolution suggestions as review material\n- how a Section 8 marker packet becomes an Imp task\n- the current dash-prefix workflow:\n\n```text\n-<imp>  -> foreground route with hook-provided context\n--<imp> -> fork current Codex conversation into a cmux pane\n```\n\nThe teaching point is not \"memorize a hook.\" The teaching point is routing: keep broad reasoning in regular Codex, send bounded tool work to an Imp, and fork when the bounded task should run separately.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. State the core sentence.\n2. Compare regular Codex vs Imp.\n3. Run `imp -l`, `imps doctor`, `imp --which`.\n4. Show `-rg find TODOs in src` as a foreground route.\n5. Show `--rg find TODOs in src` as a fork route only if cmux is working.\n6. Use the cmux check commands from the block message.\n7. Close with the 9-section workflow.\n\n### Expanded Walkthrough\n\nAdd:\n\n- compound routing\n- `--run`, `-q`, `--no-warm`, `--serve`\n- fleet commands\n- isolation model table\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- prompt design pattern\n- evolution suggestions\n- failure paths\n- exercises\n\n## Talking Points\n\nOpening:\n\n> An Imp is a narrow tool agent that should run the tool before it talks.\n\nOn narrowness:\n\n> If the request needs broad reasoning, it is not an Imp task yet.\n\nOn routing:\n\n> `imp --which` is the cheap check before spending a turn.\n\nOn isolation:\n\n> The isolation model keeps an Imp from becoming your whole Codex environment.\n\nOn Section 8:\n\n> A marker packet gives us the terms and boundary. The Imp runs the tool-shaped part.\n\n## Live Demo Script\n\n### 1. Health\n\n```bash\nimp -l\nimps list\nimps ps\nimps doctor\n```\n\n### 2. Routing\n\n```bash\nimp --which \"what changed in git since yesterday?\"\nimp --which \"find the TODOs in src; then commit everything\"\n```\n\n### 3. Direct Imp\n\n```bash\nimp-rg --run \"find TODOs in src\"\n```\n\n### 4. Dash-Prefix Demo\n\nForeground route:\n\n```text\n-rg find checkout disabled-state code paths\n```\n\nSay:\n\n> Single dash keeps the main agent responsible. The hook resolves the Imp and gives the agent the path, description, task, and cwd.\n\nFork route:\n\n```text\n--rg find checkout disabled-state code paths\n```\n\nSay:\n\n> Double dash blocks this prompt and opens a fork. The fork receives the normalized single-dash prompt.\n\nInspect the fork with the commands printed by 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### 5. Marker Packet Bridge\n\n```bash\nimp --which \"find code paths related to acceptedTerms, selectedShipping, and checkout disabled\"\n```\n\nThen:\n\n```bash\nimp-rg --run \"Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and exact rg commands used.\"\n```\n\n### 6. Safety Net\n\n```bash\nbun test\n```\n\n## Minimal Useful Path\n\nIf 5 minutes behind, cut:\n\n- evolution suggestions\n- warm app-server internals\n- new Imp design exercise\n- detailed isolation flags\n- live `--<imp>` fork demo if cmux is not working\n\nPreserve:\n\n- core sentence\n- regular Codex vs Imp\n- `imp --which`\n- direct `imp-rg --run`\n- `-<imp>` foreground route\n- fleet health\n- Section 8 marker packet bridge\n\nIf cmux is unavailable, explain the block/fork contract and show the expected receipt shape instead:\n\n```text\ncmux workspace: workspace:<id>\ncmux pane: pane:<id>\ncmux surface: surface:<id>\ncmux window: window:<id>\n```\n\n## Boundaries\n\nDo not turn this into:\n\n- a full source-code tour\n- an implementation session for new Imps\n- broad Codex routing theory\n- a replacement for Section 4 orchestration\n\nKeep the scope:\n\n```text\none tool\none operating rule\none command map\ncommand evidence\nbounded output\n```\n\n## Failure Paths To Preserve\n\nWrong Imp:\n\n> Run `imp --which`, then use an explicit route.\n\nToo broad:\n\n> Send the broad part back to regular Codex.\n\nNo command evidence:\n\n> Strengthen the operating rule and worked examples.\n\nWarm stale:\n\n> `imps ps`, `imps stop <imp>`, `imps doctor`.\n\nEvolution unsafe:\n\n> Treat suggestions as review material, not automatic updates.\n\nDash prompt parsed as option:\n\n> Do not route dash-prefix prompts through stale `p-f` or resume helper paths. Use direct `codex fork <source-session> -- '-imp ...'`.\n\nNo cmux ids:\n\n> Treat the fork as unverified. Check `cmux-run-surface`, `cmux rpc workspace.current`, and the hook log.\n\n## Team Checklist\n\nConfirm the materials include:\n\n```text\nsingle-purpose isolated Codex agents\nnot smaller general agents\none tool\none operating rule\none command map\nreal commands first\nregular Codex vs Imp\nimp -l\nimps list\nimps ps\nimps doctor\nimp --which\nimp-rg\n--run\n-q\n--no-warm\n--serve\n--effort\ncompound routing\nimps stop\nimps evolve\ntemporary CODEX_HOME\nauth.json symlink\nbase instructions replaced\nproject docs disabled\nmemories disabled\nMCP empty\nweb search disabled\napps disabled\nwarm app-server\nsocketPath\nsourceFingerprint\nCODEX_IMP_IDLE_MINUTES\nOperating rule\nCommand map\nWorked examples\nError recovery\nOutput rules\nSection 8 marker packet\nbun test\n```\n\n## Closing Line\n\n```text\nThe workshop starts by packing broad context and ends by shrinking finished evidence into tool-shaped work.\n```\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/)"
}
