---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-imp-workflows-reference"
title: "Narrow Imp agents and routing: practical reference"
---

# Narrow Imp agents and routing: practical reference

## Agent Setup Prompt

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

1. 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`.

2. Check current command availability and health:
   - `command -v imp`
   - `command -v imps`
   - `imp -l`
   - `imps list`
   - `imps ps`
   - `imps doctor`
   - `imp --which "find checkout disabled-state code paths"`
   Report missing commands, stale paths, failed health checks, or auth problems before proceeding.

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

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

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

6. Verify direct Imp commands before hook work:
   - `imp-rg "find TODOs in src"`
   - `imp-rg --run "find TODOs in src"`
   - `imp-rg -q "find TODOs in src"`
   - `imp-rg --no-warm "find TODOs in src"`
   - `imp-rg --serve` only if a foreground warm-server check is appropriate, then stop it
   - `imp-rg --run --effort minimal "find TODOs in src"`
   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.

7. Verify router and compound routing:
   - `imp --which "what changed in git since yesterday?"`
   - `imp --which "find the TODOs in src; then commit everything"`
   - `imp --which "find TODOs in src after that summarize git changes"`
   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.

8. Verify fleet management and warm mode:
   - `imps list`
   - `imps ps`
   - `imps doctor`
   - `imps stop imp-rg` if a test warm process exists
   - `imps stop --all` only if safe for the current local session
   - `imps evolve`
   - `imps evolve imp-rg`
   Treat evolution suggestions as review material only. Do not auto-apply changes that broaden an Imp into a general agent.

9. 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:
   - `hooks/imp-user-prompt-submit.py.template` to `~/.codex/hooks/imp-user-prompt-submit.py`
   - `hooks/hooks.json.example` merged into `~/.codex/hooks.json`
   - `hooks/cmux-run-surface.example` to `~/.local/bin/cmux-run-surface`
   Check existing files first. Review paths, Codex flags, cmux binary location, logging, and current-session lookup before enabling the hook.

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

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

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

13. Verify fork inspection from the returned ids:
   - `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>`

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

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

16. 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.
```

## Big Idea

Phase: Delegation And Review - hand bounded, tool-shaped work to narrow agents before escalating expensive decisions to council review.

An Imp is a narrow tool agent that should run the tool before it talks.

## Try This Now

Check the Imp roster: `imp -l`.
Route a narrow search before running it: `imp --which "find checkout disabled-state code paths"`.
Use the foreground dash path when regular Codex should keep the conversation: `-rg find checkout disabled-state code paths`.
Use the forked dash path when the bounded task should run in a new cmux pane: `--rg find checkout disabled-state code paths`.
Use the chosen Imp only for command evidence; send broad product reasoning back to regular Codex.

Imps are single-purpose, isolated Codex agents for common command-line tools. They are not smaller general agents.

```text
regular Codex -> broad context, general agent
Imp           -> narrow context, one tool, faster loop
```

Use regular Codex when the task needs broad reasoning across files, product intent, design, or multiple systems.

Use an Imp when the task is tool-shaped:

- search this repo
- inspect git state
- summarize GitHub PRs
- query JSON
- trim a video
- inspect package metadata
- find examples on GitHub

Closing workflow:

```text
Bounded tool question
-> choose the right Imp
-> run the narrow tool
-> preserve command evidence
-> return clean results
-> hand results back to the broader task
```

## Files To Inspect

Imp implementation references:

```text
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
test/cli-smoke.test.ts
```

## When To Reach For This

Use an Imp when the request maps cleanly to one tool.

| Use An Imp For | Example |
| --- | --- |
| repo search | `imp-rg "find checkout disabled state"` |
| git state | `imp-git "what changed since yesterday?"` |
| GitHub examples | `imp-github-examples "find examples of DESIGN.md"` |
| JSON query | `imp-jq --run "count users by plan"` |
| video/file command | `imp-ffmpeg "trim first 10 seconds"` |
| package metadata | `imp-npm "inspect package scripts"` |

Use regular Codex when:

- the task spans several tools
- code edits are likely
- product intent matters
- architecture tradeoffs matter
- the request is still too vague
- the next move is not tool-shaped yet

## How This Used To Work

What you used to expect:

```text
Every small tool question needs a full Codex session with broad project context.
```

What the workflow gives you now:

```text
Tool-shaped work can go to a narrow Imp that runs one tool, returns command
evidence, and leaves broad reasoning to regular Codex.
```

What you used to expect:

```text
An agent can infer the right tool and explain from memory.
```

What the workflow gives you now:

```text
An Imp has one operating rule and command map. It runs the tool first and
answers from the output.
```

## Commands First

Start with identity and health checks:

```bash
imp -l
imps list
imps ps
imps doctor
```

Check routing without spending a model turn:

```bash
imp --which "what changed in git since yesterday?"
imp --which "find the TODOs in src; then commit everything"
imp --which "find examples of DESIGN.md created in the past 2 months"
```

Expected routing shape:

```text
imp-git
imp-rg                  find the TODOs in src
imp-git                 commit everything
imp-github-examples
```

Run one Imp interactively:

```bash
imp-rg "find TODOs in src"
```

Run one Imp non-interactively:

```bash
imp-rg --run "find TODOs in src"
```

Quiet final-answer-only mode:

```bash
imp-rg -q "find TODOs in src"
```

Opt out of warm mode:

```bash
imp-rg --no-warm "find TODOs in src"
```

Run a warm server in the foreground:

```bash
imp-rg --serve
```

Override reasoning effort for one prompt:

```bash
imp-rg --run --effort minimal "find TODOs in src"
```

## Dash-Prefix Imp Routing

A common local setup adds a `UserPromptSubmit` hook for Imp prompts.

| Prompt Shape | Meaning | What Happens |
| --- | --- | --- |
| `-<imp> <task>` | foreground Imp route | hook resolves the Imp, adds routing context, and lets the main prompt continue |
| `--<imp> <task>` | forked Imp route | hook blocks the current prompt, opens a forked Codex session in cmux, and seeds it with `-<imp> <task>` |
| unknown Imp | unsafe route | hook blocks and asks for a clearer Imp name or a new Imp |
| ambiguous Imp | unsafe route | hook blocks and shows likely matches |

The hook should resolve the Imp command, executable path, description, task text, and current cwd before the main agent starts working.

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

## Foreground vs Forked Imp Requests

Use single dash when the main agent should stay responsible for the broader conversation.

```text
-rg find checkout disabled-state code paths
```

Use double dash when the Imp task should run separately and the current prompt should not continue.

```text
--rg find checkout disabled-state code paths
```

| Use | Pick | Why |
| --- | --- | --- |
| main agent needs repo or conversation context first | `-<imp>` | hook adds route context; main agent can gather context before invoking the Imp |
| bounded tool task should run separately | `--<imp>` | hook opens a forked Codex session in a new cmux pane |
| task may require product judgment | regular Codex | not tool-shaped enough yet |
| Imp name is unclear | neither | clarify or run `imp --which` |

Double dash normalizes to a single-dash prompt inside the fork.

```text
--gmail draft a reply
-> forked Codex prompt:
-gmail draft a reply
```

Double dash does not mean "run the Imp harder." It means "fork the current Codex conversation and seed the fork."

## Hook Setup Files

Common local install targets:

```text
~/.codex/hooks/imp-user-prompt-submit.py
~/.codex/hooks.json
~/.local/bin/cmux-run-surface
```

Workshop package examples live under:

```text
hooks/
```

Treat these as setup examples, not trusted universal dotfiles. Review paths, Codex flags, cmux binary location, and logging before installing.

| File | Install Target | Purpose |
| --- | --- | --- |
| `hooks/imp-user-prompt-submit.py.template` | `~/.codex/hooks/imp-user-prompt-submit.py` | parse dash-prefix prompts and route or fork Imps |
| `hooks/hooks.json.example` | merge into `~/.codex/hooks.json` | register the `UserPromptSubmit` hook |
| `hooks/cmux-run-surface.example` | `~/.local/bin/cmux-run-surface` | open a cmux pane and print an inspectable receipt |

## Inspect A Forked Imp Session

A successful fork should print cmux ids:

```text
cmux workspace: workspace:<id>
cmux pane: pane:<id>
cmux surface: surface:<id>
cmux window: window:<id>
```

Use the printed ids:

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

| Command | Use It To |
| --- | --- |
| `cmux read-screen ...` | inspect recent fork output |
| `cmux top ...` | check running processes in the workspace |
| `cmux focus-pane ...` | jump back to the forked pane |

The fork path should use direct Codex fork with `--` before the prompt:

```bash
codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \
  --dangerously-bypass-approvals-and-sandbox \
  fork <source-session> -- '-gmail draft ...'
```

The `--` before the prompt prevents `-gmail` from being parsed as Codex options.

## Router And Compound Routing

Use the router when you know the request but not the Imp.

```bash
imp "what changed in git since yesterday?"
imp "trim the first 10s off intro.mp4"
imp git "what changed?"
imp --which "list my PRs"
```

Compound routing splits strong connectors:

```bash
imp --which "find the TODOs in src; then commit everything"
```

Strong splitters:

```text
;
.
then
after that
afterwards
```

Bare `and` should not split by itself.

## Fleet Management

List Imps:

```bash
imps list
```

See warm processes:

```bash
imps ps
```

Stop one:

```bash
imps stop imp-rg
```

Stop all:

```bash
imps stop --all
```

Inspect health:

```bash
imps doctor
```

Inspect evolution suggestions:

```bash
imps evolve
imps evolve imp-rg
```

Evolution suggestions are review material. They are not magic self-modification.

## Isolation Model

Each Imp runs with a narrow isolated runtime.

Important boundaries:

| Boundary | Meaning |
| --- | --- |
| temporary `CODEX_HOME` | isolated runtime folder |
| symlinked `auth.json` | login works without copying full config |
| replaced base instructions | Imp prompt owns the behavior |
| explicit developer instructions | one tool, one operating rule |
| project docs disabled | no broad repo instruction loading |
| memories disabled | no broad personal memory context |
| MCP servers empty | no unrelated tool surface |
| web search disabled | unless the Imp specifically owns that behavior |
| apps disabled | no broad app/plugin surface |
| unused schemas disabled | fewer ways to drift |

The point is not restriction for its own sake. The point is a clean tool boundary.

## Warm Mode

Warm mode keeps a narrow app-server session ready for faster turns.

Concepts:

```text
warm app-server
socketPath
sourceFingerprint
thread/start
turn/start
CODEX_IMP_IDLE_MINUTES
```

Use warm mode when the same Imp will be called repeatedly.

Use `--no-warm` when you want a fresh one-shot run:

```bash
imp-rg --no-warm "find TODOs in src"
```

If warm behavior looks stale:

```bash
imps ps
imps stop imp-rg
imps doctor
```

## Prompt Design Pattern

A strong Imp prompt has:

```text
Operating rule
Command map
Worked examples
Error recovery
Output rules
```

Template:

~~~markdown
# imp-<tool>

## Operating Rule

Run `<tool>` via `exec_command` before any final answer. Do not answer from memory.

## Command Map

| User Intent | Exact Command |
| --- | --- |
| find text | `<tool> ...` |
| list status | `<tool> ...` |
| inspect help | `<tool> --help` |

## Worked Examples

### Example 1

User request:

```text
find checkout disabled state
```

Command:

```bash
rg -n "disabled|canSubmit|isSubmitting" src tests
```

## Error Recovery

| Error Text | Next Command |
| --- | --- |
| command not found | inspect install / PATH |
| no results | broaden terms once |
| unknown flag | run help |

## Output Rules

- show exact command evidence
- return file:line matches when available
- do not invent results
- say when the tool found nothing
~~~

## Tool Packet To Imp

Start from a bounded tool packet:

```markdown
# Imp Tool Packet

- task:
  - find checkout disabled-state code paths
- search terms:
  - acceptedTerms
  - selectedShipping
  - checkout disabled
- scope:
  - src
  - tests
- required verification:
  - return file:line matches
  - return exact commands used
```

Route it:

```bash
imp --which "find code paths related to acceptedTerms, selectedShipping, and checkout disabled"
```

Run the narrow tool:

```bash
imp-rg --run "Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and the exact rg commands used."
```

Good Imp request:

```text
Here is a bounded tool packet.

Search for code paths related to checkout disabled state. Use these terms:
acceptedTerms, selectedShipping, checkout disabled. Stay inside src and tests.

Return file:line matches and the exact rg commands used. Do not propose a fix.
```

Bad Imp request:

```text
Fix checkout.
```

## Ask The Agent This

Route a tool packet:

```text
Use Imps for the tool-shaped part of this task.

Given this bounded tool packet, first run `imp --which` to choose the narrow
Imp. The packet points at checkout disabled state and includes terms
`acceptedTerms`, `selectedShipping`, and `canSubmit`. Use the chosen Imp to
return command evidence only. Do not edit files.
```

Search with `imp-rg`:

```text
Use `imp-rg`.

Find every place checkout disabled state is computed. Search for `disabled`,
`canSubmit`, `isSubmitting`, `acceptedTerms`, and `selectedShipping` under
`src` and `tests`. Return file:line matches and the exact commands used.
```

Inspect git state:

```text
Use `imp-git`.

Summarize current dirty state and recent commits. Return commands and evidence.
Do not stage, commit, or modify files.
```

Design a new Imp:

```text
Design an Imp for a project-specific deploy CLI.

It must use exactly one tool, run help/status before answering, include a
command map, worked examples, error recovery, and output rules. Explain when
this should remain regular Codex instead.
```

## What To Confirm / How To Know It Worked

| Goal | Confirmation |
| --- | --- |
| Imp roster visible | `imp -l` or `imps list` |
| fleet healthy | `imps doctor` |
| route checked | `imp --which "..."` |
| direct Imp works | `imp-rg "find TODOs in src"` |
| noninteractive works | `imp-rg --run "find TODOs in src"` |
| quiet mode works | `imp-rg -q "find TODOs in src"` |
| warm state known | `imps ps` |
| warm server stopped | `imps stop imp-rg` or `imps stop --all` |
| broad work rejected | task returns to regular Codex when not tool-shaped |
| command evidence present | Imp output includes exact commands/results |
| project safety net passes | `bun test` in the Imp project |
| dash hook installed | `-rg find TODOs` adds Imp route context without blocking |
| fork hook installed | `--rg find TODOs` blocks current prompt and opens a cmux fork |
| Imp path resolved | hook context names `imp-<name>` and executable path |
| no rediscovery needed | main agent does not run `which`, `where`, `find`, or broad search for the Imp |
| cmux fork inspectable | block message includes workspace, pane, surface, window, and check commands |
| dash prompt safe | fork uses `codex fork <session> -- '-imp ...'` |

## If It Goes Wrong

### Router Picks Wrong Imp

Check routing first:

```bash
imp --which "your request"
```

Then use an explicit route:

```bash
imp rg "find TODOs in src"
```

### Prompt Is Too Broad

Bad:

```text
fix checkout
```

Better:

```text
Use rg to find checkout disabled-state code paths. Return file:line evidence only.
```

If the task still needs product reasoning, send it back to regular Codex.

### Imp Answers Without Tool Evidence

Strengthen the operating rule:

```text
Run the tool before final answer. Include exact commands and outputs.
```

Add worked examples.

### Warm Server Looks Stale

Run:

```bash
imps ps
imps stop <imp>
imps doctor
```

### Auth Missing

Run:

```bash
imps doctor
```

Look for `auth.json` status.

### Compound Route Split Wrong

Use a strong connector:

```bash
imp --which "find TODOs in src; then summarize git changes"
```

Avoid relying on bare `and`.

### Dash Prompt Treated As A Codex Option

Bad shape: any helper that creates a fork id and then resumes it with `-gmail draft ...`.

The dash-starting prompt can be parsed as command options.

Safer fork shape:

```bash
codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"' \
  --dangerously-bypass-approvals-and-sandbox \
  fork <source-session> -- '-gmail draft ...'
```

The `--` matters.

### Fork Opens But Cannot Be Found Later

Use the cmux ids from the block message:

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

### Hook Blocks Unexpectedly

Likely causes:

- unknown Imp name
- ambiguous Imp name
- missing `imp-` roster
- missing cmux helper
- no current Codex session id
- cmux pane creation failed

Recovery:

```bash
imp -l
imp --which "your task"
imps doctor
cmux rpc workspace.current
command -v cmux-run-surface
```

### Do Not Use Resume-Based Fork Helpers For Dash Prompts

Avoid helper paths that create a fork id and then resume it with the dash-starting prompt.

Use direct `codex fork <source-session> -- '-imp ...'` for the hook path.

### Evolution Suggestion Looks Unsafe

Treat it as review material:

```bash
imps evolve imp-rg
```

Dismiss or edit manually. Do not accept broad behavior that makes the Imp a general agent.

### Tool Packet Too Vague

Sharpen the packet before choosing an Imp:

```text
task:
search terms:
scope:
required command evidence:
```

## References And Resources

- Codex Imps project: <https://github.com/johnlindquist/codex-imps>
- Imp roster: `imp -l`, `imps list`
- Router: `imp --which "..."`
- Fleet health: `imps doctor`
- Fleet processes: `imps ps`
- Stop warm Imps: `imps stop <imp>`, `imps stop --all`
- Evolution suggestions: `imps evolve`, `imps evolve <imp>`
- Project safety net: `bun test`
- Key implementation files: `imp.ts`, `imps.ts`, `lib/isolated.ts`, `lib/imp.ts`, `lib/appserver.ts`

## Operational boundaries

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

## 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)
