Narrow Imp agents and routing: team walkthrough

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…

Team Learning Goal

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

The core idea:

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

imp -l
imps list
imps ps
imps doctor

2. Routing

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

3. Direct Imp

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

4. Dash-Prefix Demo

Foreground route:

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

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

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

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

Then:

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

6. Safety Net

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:

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:

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:

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

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

Source references