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
- State the core sentence.
- Compare regular Codex vs Imp.
- Run
imp -l,imps doctor,imp --which. - Show
-rg find TODOs in srcas a foreground route. - Show
--rg find TODOs in srcas a fork route only if cmux is working. - Use the cmux check commands from the block message.
- 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 --whichis 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-for resume helper paths. Use directcodex 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.