Agent Setup Prompt
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.
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:
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:
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:
Every small tool question needs a full Codex session with broad project context.
What the workflow gives you now:
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:
An agent can infer the right tool and explain from memory.
What the workflow gives you now:
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:
imp -l
imps list
imps ps
imps doctor
Check routing without spending a model turn:
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:
imp-git
imp-rg find the TODOs in src
imp-git commit everything
imp-github-examples
Run one Imp interactively:
imp-rg "find TODOs in src"
Run one Imp non-interactively:
imp-rg --run "find TODOs in src"
Quiet final-answer-only mode:
imp-rg -q "find TODOs in src"
Opt out of warm mode:
imp-rg --no-warm "find TODOs in src"
Run a warm server in the foreground:
imp-rg --serve
Override reasoning effort for one prompt:
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.
-rg find checkout disabled-state code paths
Use double dash when the Imp task should run separately and the current prompt should not continue.
--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.
--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:
~/.codex/hooks/imp-user-prompt-submit.py
~/.codex/hooks.json
~/.local/bin/cmux-run-surface
Workshop package examples live under:
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:
cmux workspace: workspace:<id>
cmux pane: pane:<id>
cmux surface: surface:<id>
cmux window: window:<id>
Use the printed 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>
| 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:
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.
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:
imp --which "find the TODOs in src; then commit everything"
Strong splitters:
;
.
then
after that
afterwards
Bare and should not split by itself.
Fleet Management
List Imps:
imps list
See warm processes:
imps ps
Stop one:
imps stop imp-rg
Stop all:
imps stop --all
Inspect health:
imps doctor
Inspect evolution suggestions:
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:
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:
imp-rg --no-warm "find TODOs in src"
If warm behavior looks stale:
imps ps
imps stop imp-rg
imps doctor
Prompt Design Pattern
A strong Imp prompt has:
Operating rule
Command map
Worked examples
Error recovery
Output rules
Template:
# 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:
# 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:
imp --which "find code paths related to acceptedTerms, selectedShipping, and checkout disabled"
Run the narrow tool:
imp-rg --run "Search for acceptedTerms, selectedShipping, and checkout disabled. Return file:line matches and the exact rg commands used."
Good Imp request:
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:
Fix checkout.
Ask The Agent This
Route a tool packet:
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:
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:
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:
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:
imp --which "your request"
Then use an explicit route:
imp rg "find TODOs in src"
Prompt Is Too Broad
Bad:
fix checkout
Better:
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:
Run the tool before final answer. Include exact commands and outputs.
Add worked examples.
Warm Server Looks Stale
Run:
imps ps
imps stop <imp>
imps doctor
Auth Missing
Run:
imps doctor
Look for auth.json status.
Compound Route Split Wrong
Use a strong connector:
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:
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:
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:
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:
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:
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.