claude-imps

Port status: non-interactive runs use the Claude Agent SDK, with warm startup() prewarm by default. Interactive CLI mode still uses the Codex compatibility bridge until later port steps. Public package bins are claude-imp, claude-imps, and claude-imp-*; source profile files still live under imps/imp-*.

Single-purpose, isolated Claude Agent SDK CLI agents — imps — for common CLI tools. An imp is small, fast, and bound to exactly one tool. Non-interactive paths use Claude; interactive mode is still a labeled Codex compatibility bridge while the port is in progress.

Public bins start with claude-imp-; source profile files still use imps/imp-* during the port.

Where is all this headed? VISION.md — the perfect future we're building toward and the creed every change is measured against.

What is an imp?

An imp is a single executable TypeScript file that wraps a CLI tool with an isolated Claude-oriented profile. It:

• Loads zero user-space config (no plugins, skills, hooks, memories, or MCP servers)
• Uses a focused, Oracle-tuned prompt optimized for small tool agents
• Disables unused tool schemas (Gmail, Slack, web, imagegen) via feature flags
• Isolates Claude runtime config with a temporary CLAUDE_CONFIG_DIR and linked/copied Claude credentials when available
• Uses claude-haiku-4-5-20251001 on the Claude cold/warm paths unless CLAUDE_IMP_MODEL, CLAUDE_PROFILE_MODEL, ANTHROPIC_MODEL, or CLAUDE_MODEL is set
• Opens the interactive Codex compatibility TUI by default; --run streams non-interactive output when you want automation
• Clean Ctrl+C — kills the agent, its commands, and cleans up temp files immediately

Install

# Requires Bun (https://bun.sh)
# bun install brings in @anthropic-ai/claude-agent-sdk.
# Authenticate Claude via Claude config credentials or supported Anthropic/Claude env vars.
# Codex CLI is needed only for default/-i interactive compatibility.
git clone https://github.com/johnlindquist/claude-imps
cd claude-imps
bun install
bun link

This symlinks all imps to ~/.bun/bin/. Type claude-imp- then tab to see the public command roster. You can also run imps directly without linking:

bun imps/imp-gh

The imps

Global package bins use the same profile names with a claude- prefix, for example claude-imp-gh; the table lists source profile names because fleet, eval, and benchmark commands target profiles.

Local-only imps run sandboxed to match their promises: imp-rg is read-only; imp-jq, imp-packx, imp-ffmpeg, and imp-imagemagick are workspace-write. The sandbox enforces what the prompt claims.

Usage

Every imp opens the interactive Codex compatibility TUI by default. Pass an initial prompt to seed the session:

# Interactive TUI in this terminal
claude-imp-gh "list my open PRs"

# Non-interactive streaming — shows commands, output, reasoning, and todos
claude-imp-gh --run "list my open PRs"

# Quiet non-interactive mode — buffered, only shows the final answer
claude-imp-gh -q "list my open PRs"

# Explicit interactive flag, equivalent to the default
claude-imp-gh -i

# Help
claude-imp-gh --help

# Ctrl+C to stop at any time — kills agent + commands cleanly

Pipe data in

Piped stdin is saved to a temp file and pointed out to the imp, so imps compose in pipelines:

cat data.json | claude-imp-jq --run "how many users are on the pro plan?"
curl -s https://api.example.com/things | claude-imp-jq --run "group these by status and count"
git log --oneline -30 | claude-imp-git --run "summarize what shipped this week"

Route without thinking: claude-imp

claude-imp picks the right imp from your prompt by deliberate keyword matching (free, instant, predictable — not a model call). When nothing matches or several imps tie, it lists candidates instead of guessing.

claude-imp "what changed in git since yesterday?"     # -> imp-git
claude-imp "trim the first 10s off intro.mp4"         # -> imp-ffmpeg
claude-imp git "what changed?"                        # explicit tool prefix, no guessing
claude-imp --which "list my PRs"                      # print the routing decision only
claude-imp -l                                         # list all routes

Compound prompts route to multiple imps, in order. Strong connectors (;, . , then, after that) split the prompt, and when every segment routes cleanly each imp runs with only its own segment:

claude-imp "find the TODOs in src; then commit everything"
# [1/2] imp-rg: find the TODOs in src
# [2/2] imp-git: commit everything

A bare and never splits ("open a pane and cd into it" is one cmux task), consecutive segments for the same imp merge back into one call, and if any segment is unclear the split is abandoned for whole-prompt routing — splitting can only ever make routing better. A failing step stops the chain. claude-imp --which prints the full plan.

Manage the fleet: claude-imps

claude-imps list                    # roster: every imp, warm status, evolution count
claude-imps ps                      # warm imps: pid, uptime, idle timeout
claude-imps stop imp-gh             # stop one warm imp (or: claude-imps stop --all)
claude-imps evolve                  # which imps have pending evolution suggestions
claude-imps evolve imp-gh           # review one imp's pending suggestions
claude-imp evolve imp-gh            # same review command from the user-facing router
claude-imps evolve imp-gh --applied all
claude-imps evolve imp-gh --dismiss <id>
claude-imps doctor                  # env sanity checks + stale socket cleanup

Warm imps shut themselves down after 30 idle minutes (the next call transparently respawns one). Tune with CLAUDE_IMP_IDLE_MINUTES (0 disables); legacy timeout aliases with the old prefix still work temporarily.

Typed claude-imps "do the thing" when you meant claude-imp? It forwards: anything that isn't a fleet command but looks like a prompt routes via the claude-imp router. Near-miss subcommands (claude-imps lis) still show usage instead of spending a model turn.

Non-Interactive Warm Mode

Non-interactive runs use warm mode by default. The first --run call to any imp auto-starts a warm background copy of itself and routes through it; later --run calls reuse that same warm imp for faster responses. The warm imp keeps one prewarmed Claude Agent SDK startup() spare ready; each prompt claims that one-shot spare and the sidecar immediately prepares the next one.

# First call auto-spawns a warm background imp, answers, and leaves it warm
claude-imp-gh --run "list my open PRs"

# Every later call routes through the warm imp automatically — just faster
claude-imp-gh --run "list my open issues"

# Opt OUT: force a cold Claude Agent SDK run with no warm sidecar
claude-imp-gh --no-warm "list my open PRs"

# Run the warm imp server in the foreground instead (for a supervisor like launchd/systemd)
claude-imp-gh --serve

# Per-prompt reasoning override for interactive compatibility
claude-imp-gh --run --effort minimal "what's my gh auth status"

# Per-prompt warm turn timeout override (default: 5 minutes)
claude-imp-gh --run --timeout-ms 600000 "audit this repo"

The auto-started warm imp is detached and persists after the call returns, so it stays warm for your next non-interactive prompt. Pass --no-warm whenever you want a one-off run that doesn't start or use the warm imp. Warm turn timeout defaults to 300,000 ms and can be changed per call with --timeout-ms / --turn-timeout-ms, or globally with CLAUDE_IMP_TURN_TIMEOUT_MS. Warm startup readiness defaults to 120,000 ms via CLAUDE_IMP_READY_TIMEOUT_MS; startup/prewarm waits default to 180,000 ms via CLAUDE_IMP_START_TIMEOUT_MS. Legacy timeout aliases with the old prefix still work temporarily.

Edits hot-reload automatically. A warm imp holds your imp's code in memory, so editing it would normally have no effect until you killed the process by hand. Instead, every call fingerprints the imp's source — the executable (its instructions, model, env) plus every lib/*.ts module it loads — and compares it to what the running warm imp was started with. If anything changed, the stale process is stopped and a fresh one is spawned before your prompt runs. So you can tweak an imp's internal prompt, swap the model, or change shared lib code and the very next prompt respects the change — no manual restart, no flag.

Evolution suggestions

Imps no longer rewrite their own prompts from command failures. A failed command is usually a Codex/runtime/tooling issue, not proof that the imp should mutate itself.

Instead, each non-interactive invocation records a compact, redacted session log under ~/.claude-imp/sessions/. If the wrapper sees a bad session boundary, such as a timeout, interrupted/failed turn, or no final answer, it appends a reviewable suggestion to ~/.claude-imp/<imp-name>.evolutions.jsonl. Suggestions are transparent and inert until reviewed:

claude-imps evolve                  # list imps with pending suggestions
claude-imps evolve imp-gh           # inspect pending suggestions for one imp
claude-imp evolve imp-gh            # same review command from the user-facing router
claude-imps evolve imp-gh --applied all
claude-imps evolve imp-gh --dismiss <id>

To intentionally mark one non-interactive run for evolution review, prefix the prompt with +reason on the first line. The feedback line is saved as review evidence and stripped before the model sees the task:

claude-imp-rg --run $'+missed the obvious parser helper\nwhere is parseArgs defined?'

When an imp has pending suggestions, its next run prints a terse stderr status line before the turn starts:

🔁 2 evolutions pending

At 3 pending suggestions the runtime writes ~/.claude-imp/<imp-name>.evolve-request.json and the status line changes to evolution review ready. That is the review trigger: it makes the review/apply step visible on the next run without silently rewriting the imp. After you make the prompt or code change, mark the reviewed suggestions with --applied; use --dismiss for noisy suggestions. The status line is deliberately stderr-only so stdout remains safe for pipes.

For automation or debugging:

claude-imps evolve imp-gh --json       # machine-readable pending suggestions
claude-imps evolve imp-gh --debug      # queue/status/trigger paths and env toggles

--effort <none|minimal|low|medium|high|xhigh> is retained for compatibility parsing. Non-interactive Claude warm mode does not currently map it into a verified Claude reasoning option; treat it as an interactive compatibility flag until that port step lands.

Benchmarking Current Claude Paths

No Claude performance numbers are committed here. Collect current measurements locally before publishing claims:

bun bench.ts imp-gh "say hi" --runs 8         # cold Claude via --no-warm
bun bench.ts imp-gh "say hi" --runs 8 --warm  # Claude startup prewarm sidecar

The first warm sample may include sidecar startup/prewarm. Run enough samples and report setup separately before drawing conclusions.

Parity audit and live smoke gates

bun test is model-free. It audits the Claude package surface, runtime boundaries, warm/cold path wiring, legacy Codex quarantine, eval listing, and the refusal behavior for live smoke commands. See docs/PARITY.md for the explicit live smoke commands that may spend model calls.

What you see while streaming

$ gh pr list --author @me --state all --limit 3    ← command (dimmed)
#42 fix login bug  OPEN                            ← command output (dimmed)
#38 add search     MERGED                          ← command output (dimmed)
                                                   
Your 2 most recent PRs:                            ← agent's answer (normal)
1. #42 fix login bug (open)
2. #38 add search (merged)

Reasoning text appears in dim italic. Todo items show with ○/✓ marks. All verbose output goes to stderr, final answer to stdout — so claude-imp-gh --run "list PRs" > prs.txt captures only the clean answer.

Create your own

Option A: Interactive generator

bun run create
# or after global install:
claude-imp-create

Option B: Copy-paste prompt

See docs/PROMPT.md — paste it into any AI agent with your tool's --help output.

Option C: Copy the template

cp imps/imp-minimal imps/imp-my-tool
chmod +x imps/imp-my-tool
# Edit and customize

Prompt design

Prompts should be transport-neutral and Claude-friendly. Key patterns:

• Operating rule first: "Run [tool] with the shell command tool before any final answer. Do not answer from memory."
• Command maps: Explicit IF/THEN mappings instead of vague instructions. Low-reasoning models need literal decision shortcuts.
• Worked examples: 3-5 few-shot examples per imp (user request → numbered exact command sequence → report step). Low-reasoning models imitate examples far better than they follow abstract rules.
• Error recovery maps: exact error text → exact next command, so a failed command never dead-ends the turn.
• Consistent structure: Every imp follows the same section order: Mission → Tool-output trust boundary → Operating rule → Command map → Workflow → Mutation policy → Worked examples → Error recovery → Command rules → Output.
• No --help dumps: Curated command maps are more effective than raw CLI reference for focused tool agents.

How isolation works

Non-interactive imps create isolated Claude runtime state with a temporary CLAUDE_CONFIG_DIR, temp homes under /tmp/claude-imp-*, credential linking/copying from the real Claude config, explicit Claude tool allowlists/disallowlists, and Claude sandbox mapping for read-only, workspace-write, and danger-full-access profiles.

Interactive mode still uses a Codex compatibility TUI with a temporary CODEX_HOME. See docs/ISOLATION.md for the active Claude isolation model and the legacy Codex appendix.

Evals (model-paid behavioral checks)

bun test proves the imps load; evals prove they behave. Each suite in evals/ runs real prompts against a hermetic temp-dir fixture and asserts on the answer and the resulting filesystem (e.g. imp-jq must create users.csv and must NOT touch users.json; imp-git must commit only the named file and leave unrelated dirty files alone). One model turn per case — run after editing an imp's prompt; hot-reload means the very next eval exercises the change.

bun run evals               # all suites
bun evals.ts --list         # list suites/cases without model calls
bun evals.ts imp-jq         # one suite
bun evals.ts imp-git --filter commit --keep   # one case, keep sandbox for post-mortem

Tests

Fast, model-free smoke tests guard against arg-parsing and load regressions:

bun test

test/parseargs.test.ts exhaustively checks flag/prompt parsing (the spot a past --effort bug dropped the first prompt word). test/cli-smoke.test.ts loads every imp binary, checks --help/no-args, and confirms a real prompt survives parsing without paying a model turn.

Push gate: enable the pre-push hook once per clone so failing tests block a push:

git config core.hooksPath .githooks

(Override an individual push with git push --no-verify.)

Requirements

• Bun v1.0+
• Dependencies installed with bun install, including @anthropic-ai/claude-agent-sdk
• Claude authentication through Claude config credentials or supported Anthropic/Claude env vars
• The CLI tool each imp wraps (e.g. gh, bird, cmux)
• Codex CLI only for the interactive compatibility TUI and Codex-specific imp work