---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-imp-workflows-team-guide"
title: "Narrow Imp agents and routing: team walkthrough"
---

# Narrow Imp agents and routing: team walkthrough

## Team Learning Goal

Close the workshop by showing where bounded, tool-specific packets go next.

The core idea:

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

By the end of this section, the room should understand:

- regular Codex vs Imp
- when a task is tool-shaped
- how to route before running
- direct vs noninteractive vs quiet modes
- warm mode and fleet management
- isolation boundaries
- evolution suggestions as review material
- how a Section 8 marker packet becomes an Imp task
- the current dash-prefix workflow:

```text
-<imp>  -> foreground route with hook-provided context
--<imp> -> fork current Codex conversation into a cmux pane
```

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

## Walkthrough Depth

### Essential Walkthrough

1. State the core sentence.
2. Compare regular Codex vs Imp.
3. Run `imp -l`, `imps doctor`, `imp --which`.
4. Show `-rg find TODOs in src` as a foreground route.
5. Show `--rg find TODOs in src` as a fork route only if cmux is working.
6. Use the cmux check commands from the block message.
7. Close with the 9-section workflow.

### Expanded Walkthrough

Add:

- compound routing
- `--run`, `-q`, `--no-warm`, `--serve`
- fleet commands
- isolation model table

### Deep-Dive Walkthrough

Add:

- prompt design pattern
- evolution suggestions
- failure paths
- exercises

## Talking Points

Opening:

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

On narrowness:

> If the request needs broad reasoning, it is not an Imp task yet.

On routing:

> `imp --which` is the cheap check before spending a turn.

On isolation:

> The isolation model keeps an Imp from becoming your whole Codex environment.

On Section 8:

> A marker packet gives us the terms and boundary. The Imp runs the tool-shaped part.

## Live Demo Script

### 1. Health

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

### 2. Routing

```bash
imp --which "what changed in git since yesterday?"
imp --which "find the TODOs in src; then commit everything"
```

### 3. Direct Imp

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

### 4. Dash-Prefix Demo

Foreground route:

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

Say:

> Single dash keeps the main agent responsible. The hook resolves the Imp and gives the agent the path, description, task, and cwd.

Fork route:

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

Say:

> Double dash blocks this prompt and opens a fork. The fork receives the normalized single-dash prompt.

Inspect the fork with the commands printed by 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>
```

### 5. Marker Packet Bridge

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

Then:

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

### 6. Safety Net

```bash
bun test
```

## Minimal Useful Path

If 5 minutes behind, cut:

- evolution suggestions
- warm app-server internals
- new Imp design exercise
- detailed isolation flags
- live `--<imp>` fork demo if cmux is not working

Preserve:

- core sentence
- regular Codex vs Imp
- `imp --which`
- direct `imp-rg --run`
- `-<imp>` foreground route
- fleet health
- Section 8 marker packet bridge

If cmux is unavailable, explain the block/fork contract and show the expected receipt shape instead:

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

## Boundaries

Do not turn this into:

- a full source-code tour
- an implementation session for new Imps
- broad Codex routing theory
- a replacement for Section 4 orchestration

Keep the scope:

```text
one tool
one operating rule
one command map
command evidence
bounded output
```

## Failure Paths To Preserve

Wrong Imp:

> Run `imp --which`, then use an explicit route.

Too broad:

> Send the broad part back to regular Codex.

No command evidence:

> Strengthen the operating rule and worked examples.

Warm stale:

> `imps ps`, `imps stop <imp>`, `imps doctor`.

Evolution unsafe:

> Treat suggestions as review material, not automatic updates.

Dash prompt parsed as option:

> Do not route dash-prefix prompts through stale `p-f` or resume helper paths. Use direct `codex fork <source-session> -- '-imp ...'`.

No cmux ids:

> Treat the fork as unverified. Check `cmux-run-surface`, `cmux rpc workspace.current`, and the hook log.

## Team Checklist

Confirm the materials include:

```text
single-purpose isolated Codex agents
not smaller general agents
one tool
one operating rule
one command map
real commands first
regular Codex vs Imp
imp -l
imps list
imps ps
imps doctor
imp --which
imp-rg
--run
-q
--no-warm
--serve
--effort
compound routing
imps stop
imps evolve
temporary CODEX_HOME
auth.json symlink
base instructions replaced
project docs disabled
memories disabled
MCP empty
web search disabled
apps disabled
warm app-server
socketPath
sourceFingerprint
CODEX_IMP_IDLE_MINUTES
Operating rule
Command map
Worked examples
Error recovery
Output rules
Section 8 marker packet
bun test
```

## Closing Line

```text
The workshop starts by packing broad context and ends by shrinking finished evidence into tool-shaped work.
```

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