These exercises practice routing narrow tool-shaped work to Imps.
Exercise 1: Regular Codex Or Imp?
Choose regular Codex or Imp.
| Task | Choice | Why |
|---|---|---|
| Find every place checkout disabled state is computed. | ||
| Decide which checkout architecture to use. | ||
| Summarize current git dirty state. | ||
| Implement saved payment methods. | ||
| Query JSON for users by plan. | ||
| Trim a video file. | ||
| Explain product risk of auth/session rotation. | ||
| Find GitHub examples of a file pattern. |
Exercise 2: Check Health
Run:
imp -l
imps list
imps ps
imps doctor
Fill out:
# Imp Health
- roster visible? yes/no:
- warm processes:
- doctor status:
- auth status:
- command that failed:
- next check:
Exercise 3: Route Before Running
Run:
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"
Fill out:
# Routing Notes
- prompt:
- chosen Imp:
- compound route? yes/no:
- split points:
- would you run it? yes/no:
- why:
Exercise 4: Run imp-rg
Run:
imp-rg --run "find TODOs in src"
Quiet mode:
imp-rg -q "find TODOs in src"
No warm mode:
imp-rg --no-warm "find TODOs in src"
Fill out:
# imp-rg Notes
- command:
- files searched:
- matches:
- exact command evidence present? yes/no:
- when to use `--run`:
- when to use `-q`:
- when to use `--no-warm`:
Exercise 4A: Single-Dash Hook Route
Submit a foreground Imp prompt from Codex:
-rg find TODOs in src
Fill out:
# Single-Dash Hook Notes
- prompt:
- resolved Imp:
- executable path included? yes/no:
- description included? yes/no:
- task text preserved? yes/no:
- cwd included? yes/no:
- did the main prompt continue? yes/no:
- did the main agent avoid rediscovering the Imp? yes/no:
- command evidence returned:
Exercise 4B: Double-Dash Fork Route
Submit a forked Imp prompt from Codex:
--rg find TODOs in src
Fill out:
# Double-Dash Fork Notes
- original prompt:
- normalized fork prompt:
- did current prompt block? yes/no:
- workspace:
- pane:
- surface:
- window:
- read-screen command:
- top command:
- focus-pane command:
- what output appeared in the fork:
Exercise 4C: Unknown Or Ambiguous Imp
Try an intentionally unclear route:
-g find TODOs in src
Fill out:
# Ambiguous Route Notes
- prompt:
- blocked? yes/no:
- suggested matches:
- would you clarify, use `imp --which`, or create with `imp-create`?
- corrected prompt:
Exercise 5: Section 8 Marker Packet To Imp
Start with a bounded marker packet.
# Marker Packet
- marker id:
- marker label: Checkout button stayed disabled
- marker note:
- nearby evidence terms:
- acceptedTerms
- selectedShipping
- checkout disabled
- privacy boundary:
- storage values exported? no
- request bodies exported? no
- response bodies exported? no
Route:
imp --which "find code paths related to acceptedTerms, selectedShipping, and checkout disabled"
Run:
imp-rg --run "Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and exact rg commands used."
Fill out:
# Marker Packet Imp Run
- marker id:
- chosen Imp:
- exact command:
- file:line evidence:
- what the Imp must not infer:
- next regular Codex task:
Exercise 6: Fleet Management
Run:
imps ps
imps stop imp-rg
imps stop --all
imps doctor
Fill out:
# Fleet Management
- warm imps before:
- stopped:
- warm imps after:
- doctor status:
- when to stop a warm Imp:
Exercise 7: Inspect Evolution Suggestions
Run:
imps evolve
imps evolve imp-rg
Fill out:
# Evolution Review
- suggestion path:
- suggested change:
- safe? yes/no:
- keeps one tool? yes/no:
- keeps command evidence? yes/no:
- accept, edit, or reject:
- why:
Exercise 8: Design A New Imp
Pick one CLI tool.
Examples:
sqlite3
redis-cli
internal search tool
project-specific deploy CLI
Fill out:
# New Imp Design
- name: imp-
- tool:
- sandbox mode:
- why this is single-purpose:
- what this Imp must never do:
- first safe command:
- first verification command:
## Operating Rule
Run <tool> via exec_command before any final answer. Do not answer from memory.
## Command Map
| User Intent | Exact Command |
| --- | --- |
| status | |
| list | |
| inspect | |
| help | |
## Worked Examples
### Example 1
1.
2.
3.
### Example 2
1.
2.
3.
## Error Recovery
| Error Text | Next Command |
| --- | --- |
| command not found | |
| unknown flag | |
| no results | |
## Output Rules
-
-
-
Answer:
# Narrowness Review
- does this use exactly one tool? yes/no:
- does it need broad repo reasoning? yes/no:
- should it be regular Codex instead? yes/no:
- what to split out:
Exercise 9: Failure Path Drill
Choose a recovery for each failure.
| Failure | Recovery |
|---|---|
| router picks the wrong Imp | |
| prompt is too broad for an Imp | |
| Imp answers without showing a command | |
| warm server appears stale | |
| auth.json missing | |
| compound route split wrong | |
| evolution suggestion looks unsafe | |
| marker packet lacks nearby evidence terms | |
| package Imp wants to mutate a pnpm project | |
| ffmpeg Imp would overwrite input |
Recovery options:
run `imp --which`
use an explicit route
split into smaller tool tasks
send broad reasoning back to regular Codex
strengthen Operating rule
add Worked examples
run `imps ps`
run `imps stop <imp>`
run `imps doctor`
rewrite compound prompt with `;` or `then`
dismiss unsafe evolution suggestions
sharpen marker packet
inspect lockfiles
require new output file and no overwrite
run read-only checks only
Fill out one in detail:
# Failure Recovery Detail
- failure:
- likely cause:
- first command:
- recovery:
- how to know it worked:
Exercise 10: Verify The Imp Project Safety Net
From the Imp project checkout, run:
bun test
Fill out:
# Test Check
- command: `bun test`
- pass count:
- fail count:
- test files:
- router covered? yes/no:
- parse args covered? yes/no:
- CLI smoke covered? yes/no:
- hot reload covered? yes/no:
- evolution covered? yes/no:
- would you edit routing without this passing? yes/no:
- why:
Optional focused checks:
bun test test/router.test.ts
bun test test/parseargs.test.ts
bun test test/cli-smoke.test.ts
Hook route checks:
-rg find TODOs in src
--rg find TODOs in src
Fill out:
# Dash Route Check
- can explain `-<imp>`? yes/no:
- can explain `--<imp>`? yes/no:
- can inspect a forked cmux session? yes/no:
- can explain why direct `codex fork ... -- '-imp ...'` is used? yes/no:
Exercise 11: Final Handoff
Write a final handoff file:
mkdir -p receipts
cat > receipts/section9-final-handoff.md <<'EOF'
# Section 9 Final Imp Handoff
- source: Section 8 marker packet
- DebugSession path:
- marker id:
- marker label:
- marker note:
- expected:
- actual:
- nearbyEventIds:
- evidence terms:
-
-
-
- privacy boundary:
- storage values exported?
- request bodies exported?
- response bodies exported?
- target Imp:
- why this target is single-purpose:
- command to run:
- required output:
- command evidence to preserve:
- what the Imp must not invent:
- next handoff after Imp result:
EOF
test -s receipts/section9-final-handoff.md && echo "handoff:OK"
Fill out:
# Final Handoff Review
- handoff file:
- target Imp:
- command:
- route checked with `imp --which`? yes/no:
- marker packet bounded? yes/no:
- expected output clear? yes/no:
- command evidence required? yes/no:
- privacy boundary explicit? yes/no:
- ready to run? yes/no:
Final Check
Run or review:
imp -l
imps list
imps ps
imps doctor
imp --which "find TODOs in src; then summarize git changes"
bun test
Fill out:
# Final Imps Check
- can explain regular Codex vs Imp? yes/no:
- can state the core sentence? yes/no:
- can route before running? yes/no:
- can explain compound routing? yes/no:
- can run direct interactive mode? yes/no:
- can run `--run`? yes/no:
- can run `-q`? yes/no:
- can explain warm mode? yes/no:
- can stop warm imps? yes/no:
- can explain isolation? yes/no:
- can inspect evolution suggestions? yes/no:
- can design a narrow Imp prompt? yes/no:
- can hand a Section 8 marker packet to an Imp? yes/no:
- can decide when to return to regular Codex? yes/no: