improv

Agent task harness for coding agents. Preflight the task. Loop until verified — not self-reported.

improv is not a prompt beautifier. It compiles rough requests into scoped engineering specs, runs real shell judges against agent output, and keeps looping until acceptance criteria pass. No key required. Best with your key.

Works in VS Code, Cursor, Claude Code, Codex, browser chat (Chrome extension), and terminal via @im.

Why

Prompt enhancers rewrite your ask once and hope the agent gets it right. Agents still burn turns rediscovering scope, guessing test commands, and declaring victory without evidence.

improv is the harness around the agent: compile repo context and done-conditions before work starts, then verify with judges after — tightening gameable gates automatically. You get task memory under .improv/tasks/, loop logs, and optional signed attestations when a verified loop completes.

Features

Harness & verification

• Loop until done — preflight → agent implements → run judges → fix & repeat until exit code 0.
• Judge integrity — Goodhart detection, mutation-tested judges, and semantic gates synthesized from spec invariants; baked into every @im run.
• Post-agent verification — @im --verify checks agent reports against acceptance criteria and validation evidence.
• Constraint-graph compiler — typed spec IR with multi-backend rendering (task.md, CLAUDE.md, AGENTS.md, markdown).
• Task lifecycle — lifecycle ids, status tracking, validation commands, and loop logs in .improv/tasks/.
• Signed attestations — optional Ed25519 proof when a judge-verified loop completes.
• Failure memory — local failure embeddings and bisection attribution when judges regress.
• Tournament mode — optional N-worktree candidate runs (ONE_CLICK_IMPROVE_TOURNAMENT=1).

Preflight & routing

• One-click preflight — transform Fix login bug into a routed, scoped engineering task.
• Browser overlay — Chrome extension for ChatGPT, Claude, Gemini, Perplexity, Grok, DeepSeek, Copilot, and Poe with score, improve, diff, and apply-in-place.
• Automatic routing — @im and /im infer VS Code Chat, Cursor, Claude Code, Codex, or terminal and shape output for that surface.
• Harness recommendation — @harness / /harness picks the best skill and route for the work.
• Auto-detected repo context — infer stack, scripts, generated folders, and agent instruction files when no .improv profile exists.
• Weakness analysis — scores prompts (0–100) on clarity, specificity, constraints, success criteria, testing, ambiguity, and architecture.
• Clarify before output — up to 5 clarifying questions so missing context is elicited, not invented.
• Side-by-side diff — review original vs improved, edit inline, then Apply or Copy.
• Prompt templates — /im-bugfix, /im-refactor, /im-a11y (or @im --template bugfix).

Platform & library

• Local-first — default local provider is deterministic, offline, and needs no API key.
• Best with your key — OpenAI, Anthropic, Gemini, Grok, and OpenAI-compatible providers when you want model-backed scoping.
• Skill-driven — rewrite logic in skills/improve-prompt/SKILL.md; sync to .claude, .cursor, .agents, .github skills.
• Self-improving library — daily autoresearch discovers and adopts harnesses/skills into the bundled corpus powering @im.
• Pipe-friendly CLI — @im --json emits schema v1 with analysis, compiled spec, and savings estimates for CI/scripts.

When to use local vs model-backed

No key is required. Add a provider key when the rough ask needs stronger scoping than offline structure can infer.

Getting started

1. Install the extension (see below).
2. Open the improv view from the Activity Bar, or select a prompt in the editor and press Cmd+Alt+I / Ctrl+Alt+I.
3. Type or paste your prompt, optionally answer the clarifying questions, then click Improve.
4. Apply to editor or Copy the result.
5. After the coding agent finishes, paste its final report into Post-agent verification to check evidence against the preflight task.

Installation

Browser extension (ChatGPT, Claude, Gemini, and more)

For everyone (after a release is published):

curl -fsSL https://improv.sh/install-browser.sh | bash

Then in Chrome: Load unpacked → select the printed folder (~/.local/share/one-click-improve/browser-extension).

From source (developers):

npm run build:browser

Then Extensions → Developer mode → Load unpacked → browser/. See browser/README.md.

Chrome Web Store (one-click, no dev mode): see browser/CHROME_STORE.md.

From the VS Code Marketplace

Search for improv in the Extensions view, or:

code --install-extension improv.one-click-improve

Install on VS Marketplace →

One-line install (from a released .vsix)

The same command is shown at https://improv.sh for quick copy/paste:

curl -fsSL https://improv.sh/install.sh | bash

This downloads the latest release .vsix, installs it into VS Code and/or Cursor when their CLIs are detected on PATH or in standard macOS app bundles, creates the terminal shortcut at ~/.local/bin/@im, installs global /im command files for Cursor and Claude Code, and syncs the bundled skill into user-level harness folders.

At the end of an interactive install, the script asks whether you want to configure an optional provider key for terminal @im. You can skip it. If you say yes, it saves a private terminal config at ~/.config/one-click-improve/env and the generated terminal wrappers load it automatically. VS Code and Cursor extension keys are still managed inside the editor with improv: Set Provider API Key so they can use SecretStorage.

Cursor

Cursor loads VS Code extensions. Use the same .vsix with:

cursor --install-extension one-click-improve-<version>.vsix

Commands

Chat

In VS Code Chat, mention @im before a rough prompt to rewrite it in place. Template-specific participants are also available:

@im Fix login bug
@im-bugfix login fails on Safari
@im-refactor split dashboard loader
@im-a11y modal trap focus

Cursor's native Agent @ menu is Cursor-owned context routing, so the extension cannot force @im into that menu. Use the project command in .cursor/commands/im.md instead:

/im Fix login bug

If your Cursor build exposes VS Code chat participants, @im may appear there too, but /im is the reliable Cursor Chat shortcut.

The one-line installer also writes a global Cursor command to ~/.cursor/commands/im.md, so /im can be available outside this repo. That /im command automatically uses the Cursor-aware route.

Terminal

The package also ships a local CLI that uses the same offline rewrite engine:

@im "Fix login bug"
echo "Fix login bug" | @im --json --provider local
@im --template bugfix "login fails on Safari"
@im --template refactor "split dashboard loader"
@im --template a11y "modal trap focus"
@im --variant safe "Change billing retry behavior"
@im --variant test-heavy "Add tests for session timeout"
@im --score "Fix login bug"
@im --templates
@im --explain "Refactor dashboard loading in Codex"
@im --tasks
@im --verify --task task_123 "Agent final response and tests run"
@harness "I am working in Claude Code on auth tests"

@im --json writes schema version 1 to stdout with analysis, improved, estimates, and stable exit codes (0 success, 1 error, 2 missing prompt). Use /im-bugfix, /im-refactor, or /im-a11y in Cursor and Claude Code, or @im --template <name> in the terminal. In VS Code Chat, use @im-bugfix, @im-refactor, or @im-a11y.

This makes the workflow usable from terminal agents such as Claude Code and Codex: run @im, then paste or pipe the improved prompt into the agent session you are using. The CLI stores recent task lifecycle records locally at ~/.config/one-click-improve/tasks.json without sending prompt content to telemetry.

Use prompt-improve or one-click-improve if a shell, package manager, or corporate policy rejects command names beginning with @. The one-line installer creates all three shortcuts when Node.js is available.

Variants let the same prompt compile into a different execution posture without adding more commands:

• balanced is the default.
• safe emphasizes low-risk, reversible changes.
• fast emphasizes the smallest useful verified change.
• deep emphasizes architecture, call sites, and tradeoffs.
• test-heavy emphasizes test matrix and regression coverage.

Add --no-project-context when you want terminal @im to ignore local .improv project/team settings for a single run.

After an agent finishes, verify the final report against the most recent tracked task:

agent ... | @im --verify
@im --verify --task task_abc "Changed files: ... Tests: npm test passed ..."
@im --tasks

Provider Keys

No key is required:

@im "Fix login bug"

For best results in VS Code or Cursor, run improv: Set Provider API Key, choose a provider, then set oneClickImprove.provider to that provider or to auto. Keys are stored in VS Code SecretStorage.

For terminal @im, the one-line installer asks about optional provider setup at the end. If configured, the wrappers load ~/.config/one-click-improve/env automatically.

For terminal use, add a provider key and opt in per command or through your shell environment:

OPENAI_API_KEY=sk-... @im --provider openai "Fix login bug"
ANTHROPIC_API_KEY=sk-ant-... @im --provider anthropic "Create a speech practice app for children"
GEMINI_API_KEY=... GEMINI_MODEL=your-model-id @im --provider gemini "Improve this product spec"
GROK_API_KEY=... GROK_MODEL=your-model-id @im --provider grok "Tighten this Codex task"
ONE_CLICK_IMPROVE_PROVIDER=auto @im "Refactor dashboard loading"

auto checks configured providers and falls back to local when no key is available. That means /im and @im --provider auto stay usable on fresh machines.

OpenAI-compatible providers are supported without extra packages:

ONE_CLICK_IMPROVE_API_KEY=...
ONE_CLICK_IMPROVE_BASE_URL=https://your-provider.example/v1
ONE_CLICK_IMPROVE_MODEL=your-model-id
@im --provider openai-compatible "Add streaming support"

Provider aliases are also available for openrouter, groq, mistral, deepseek, gemini, grok, and xai. Set that provider's API key plus a model env var, or pass --model:

OPENROUTER_API_KEY=... OPENROUTER_MODEL=openai/gpt-4o-mini @im --provider openrouter "Tighten auth tests"
GROQ_API_KEY=... GROQ_MODEL=your-model-id @im --provider groq "Improve loading states"
XAI_API_KEY=... XAI_MODEL=your-model-id @im --provider xai "Rewrite this agent task"

Run this to see the current provider modes:

@im --providers

For Claude Code interactive sessions, the installer writes ~/.claude/commands/im.md, so /im Fix login bug can use the same command-style workflow there too. That /im command automatically uses the Claude Code-aware route.

Skills And Automatic Routing

The source skill lives at skills/improve-prompt/SKILL.md, and host discovery metadata lives at skills/skills_index.json with a JSON schema in skills/schemas/.

Publicly, there are only two ways to invoke agent preflight:

• @im in VS Code Chat or a terminal.
• /im in Cursor and Claude Code command surfaces.

Template-specific routes:

• @im-bugfix, @im-refactor, @im-a11y in VS Code Chat.
• /im-bugfix, /im-refactor, /im-a11y in Cursor and Claude Code.

Current inventory:

• 1 canonical skill.
• 5 bundled skill copies across the root skill and harness folders.
• 3 prompt templates: bugfix, refactor, a11y.
• 2 command libraries: .cursor/commands and .claude/commands.
• 4 terminal aliases: @im, @harness, prompt-improve, and one-click-improve.

Internally, improv syncs the same skill into .claude, .cursor, .agents, and .github, then automatically routes each request through the right surface profile. The metadata-only prompt/tool corpus generated from research/system-prompts-and-models-of-ai-tools informs routing and validation without exposing raw third-party prompt text in normal output.

Run this whenever the source skill changes:

npm run skills:sync

That regenerates the same skill bundle into:

.claude/skills/improve-prompt/SKILL.md
.cursor/skills/improve-prompt/SKILL.md
.agents/skills/improve-prompt/SKILL.md
.github/skills/improve-prompt/SKILL.md

Each harness folder also gets its own skills_index.json and schema copy, so the bundles are self-contained. The extension and CLI load improve-prompt through the root skills_index.json at runtime and reject unsafe skill paths, missing licenses, oversized skill bodies, and absolute tool references.

Benchmarks

npm run benchmark:savings
npm run benchmark:preflight

benchmark:savings writes research/benchmark-results.md from 30 rough prompts. benchmark:preflight writes benchmarks/prompt-preflight.md from the preflight lifecycle corpus.

Project Context

improv uses project context automatically. If a .improv/config.json or .improv.md profile exists, that explicit team profile wins. If it does not, the CLI and editor extension infer context from repository files such as package.json, tsconfig.json, lockfiles, language manifests, generated directories, and agent instruction files like AGENTS.md, CLAUDE.md, .cursorrules, or .cursor/rules.

Add .improv/config.json or .improv.md when you want to pin team policy, preferred agent, test commands, release checklist, or security rules.

Example .improv/config.json:

{
  "name": "Prompt Improve",
  "preferredAgent": "codex-cli",
  "stack": ["TypeScript", "VS Code extension", "Preact"],
  "testCommands": ["npm test", "npm run typecheck", "npm run build"],
  "forbiddenFiles": ["dist/**"],
  "forbiddenActions": ["reset git state", "rewrite public APIs"],
  "securityRules": ["Keep prompt content out of telemetry."],
  "releaseChecklist": ["Run tests and build before release."],
  "teamPhrasingStyle": "Concise, direct engineering prose."
}

The panel exposes this as a profile selector, and terminal @im uses configured or auto-detected context unless --no-project-context is passed.

Reproducible Benchmarks

Prompt quality now has regression fixtures in test/promptEval.test.ts. Each fixture checks:

• rough prompt
• target surface
• expected sections
• route expectations
• safety signals
• validation signals
• before/after readiness score

Run it with the normal test suite:

npm test

Generate the published local benchmark report:

npm run benchmarks:prompts

That writes:

benchmarks/prompt-preflight.json
benchmarks/prompt-preflight.md

Corpus-derived lessons live in src/core/corpusLessons.generated.ts. They are original summaries mined from local metadata and pattern analysis; raw third-party prompt content remains under research/.

@im preflight regression (automatic)

Maintainers get a second regression layer that shells out to the same dist/cli.js binary as terminal @im and project /im commands. It runs automatically — end users never need to invoke it.

• npm test — includes Vitest fixtures plus the promptfoo matrix (12 cases today)
• GitHub CI — same npm test gate on every PR

The matrix checks:

• Preflight regression — auto-generated from PROMPT_EVAL_FIXTURES (sections, routes, safety, validation, scores) via @im --json --provider local
• Savings smoke — vague prompts must still compile with positive token-savings heuristics
• Template profiles — /im-bugfix, /im-refactor, /im-a11y overlays via --template

Config: evals/promptfoo/promptfooconfig.yaml. Assertions reuse evaluatePreflightOutput from src/core/promptEval.ts, so Vitest and the @im CLI path cannot drift.

Maintainers can inspect results after npm test with npm run eval:promptfoo:view (opens the promptfoo UI from .promptfoo/ — run npm test first so results exist).

Autoresearch Discovery

The repo ships a reproducible savings benchmark over 30 rough prompts:

npm run benchmark:savings

This writes research/benchmark-results.json and research/benchmark-results.md using @im --json --provider local and a clarification-turn heuristic. Use it to sanity-check marketing claims, not as a live-agent trace.

Maintainer: autoresearch (autonomous)

The autoresearch loop runs daily with no human review gate:

npm run research:harnesses

It discovers GitHub harness/skill candidates, auto-adopts high-scoring metadata into research/adopted-registry.json, regenerates src/core/corpusLessons.generated.ts for runtime @im rewrites, and publishes site/assets/autoresearch-stats.json for the improv.sh hero counter. Candidate repository code is never executed.

Replay all historical discovery runs from git into the registry and volume counters:

npm run research:backfill

How It Works In Practice

improv is an explicit agent-preflight step. You invoke it from the panel, VS Code Chat, Cursor Chat, Claude Code, or the terminal; it does not silently rewrite every message you type. It is not just a wording enhancer: it loads the bundled improve-prompt skill, automatically infers the target surface, folds in configured or detected repo context, and writes a prompt with enough context, constraints, and validation detail to execute cleanly.

Without improv, a rough request like Fix login bug usually forces the agent to ask basic questions or guess the missing context. With improv, the same request becomes a structured task with objective, context, constraints, deliverables, acceptance criteria, and validation steps before the agent starts work. The local provider now detects broad request types and domain signals such as auth/session work, product/app creation, UI/accessibility, backend/API changes, dashboard loading states, and child speech-support safety needs. Model-backed providers can go further by using your selected model's reasoning over the same embedded skill.

1. You enter a rough request like Fix login bug.
2. improv scores the prompt for missing context, constraints, success criteria, testing, and ambiguity.
3. In the panel, it can ask clarifying questions before rewriting. In chat and terminal shortcuts, it rewrites immediately.
4. It returns a structured prompt you can send to Codex, Claude Code, Cursor Agent, Copilot Chat, or another coding agent.

Example 1: VS Code Chat

User types:

@im Fix login bug

Improved prompt:

## Objective
Fix the login bug.

## Context
Original request: "Fix login bug".

## Constraints
No explicit constraints were provided.
- Assumption: Preserve the existing tech stack, code style, and public APIs unless the implementation proves a change is required.

## Deliverables
- The code change that fixes the login bug.
- New or updated tests covering the failing login path.
- Notes for any user-visible behavior change.

## Acceptance Criteria
- A user can complete the affected login flow successfully.
- Existing login, logout, and session behavior do not regress.
- The fix handles the edge case that caused the bug.

## Validation Steps
- Run the relevant unit or integration tests for authentication.
- Run the project test suite and linter.
- Manually verify the login flow that previously failed.

Example 2: Cursor Chat

User types:

/im Add tests for session timeout in src/auth/session.ts

Improved prompt:

## Objective
Add test coverage for session timeout behavior in `src/auth/session.ts`.

## Context
The requested scope is `src/auth/session.ts`. The implementation should focus on the existing session timeout logic and avoid unrelated auth refactors.

## Constraints
- Keep the existing public API and session behavior intact unless a test exposes a real bug.
- Follow the repository's current test framework and naming conventions.

## Deliverables
- New or updated tests for active sessions, expired sessions, and timeout boundary behavior.
- Any minimal fixture or mock updates needed for deterministic timeout tests.

## Acceptance Criteria
- The tests fail against a broken timeout implementation and pass against the correct behavior.
- Timeout edge cases are covered without making the suite flaky.
- No unrelated auth tests regress.

## Validation Steps
- Run the targeted auth/session tests.
- Run the broader test suite if the timeout helpers are shared.

Example 3: Terminal And Claude Code

User runs:

@im "Refactor dashboard data loading so it stops flashing a blank screen"

Improved prompt:

## Objective
Refactor dashboard data loading so refreshes no longer flash a blank screen.

## Context
The dashboard currently appears to clear visible content while data is loading. Preserve the existing dashboard behavior, but improve the loading state so users keep useful context during refreshes.

## Constraints
- Avoid broad UI redesigns.
- Preserve existing data-fetching contracts and public component APIs unless a small internal change is necessary.
- Keep accessibility states for loading and error UI intact.

## Deliverables
- The dashboard loading-state refactor.
- Tests or component coverage for initial load, refresh load, success, and error states.
- Any small documentation or comments needed to explain the loading-state behavior.

## Acceptance Criteria
- Existing dashboard data remains visible during background refreshes.
- A loading indicator is still shown when appropriate.
- Initial empty loading, refresh loading, and error states are visually and functionally distinct.
- Existing dashboard tests continue to pass.

## Validation Steps
- Run the dashboard/component test suite.
- Manually verify initial load, refresh, slow network, and error scenarios.
- Confirm there is no blank-screen flash during refresh.

Answering clarifying questions in the panel can make the output even sharper because the answers are inserted into the final prompt instead of being guessed.

Settings

Architecture

Clean architecture with independent, replaceable modules:

• src/adapters/* — pluggable transform providers (local, openai, anthropic, Gemini, Grok/xAI, and OpenAI-compatible providers); the engine is swappable.
• src/services/* — model client, SecretStorage, opt-in telemetry.
• src/ui/* + webview/* — the panel host, typed message bridge, and Preact webview components.
• skills/improve-prompt/SKILL.md — the rewrite logic, editable without code changes.
• .claude/skills, .cursor/skills, .agents/skills, .github/skills — generated harness copies of the same source skill.

Development

npm install
npm run build      # bundle extension + webview + CLI
npm test           # unit tests + @im preflight regression matrix
npm run eval:prompts
npm run test:webview
npm run test:integration
npm run lint       # lint
npm run skills:sync
npm run benchmark:savings

Press F5 to launch the Extension Development Host.

Packaging

npm run package    # produces one-click-improve-<version>.vsix

Landing Page

The static landing page lives in site/index.html and is configured for Cloudflare Pages at https://improv.sh/. The current page uses an IDE-style hero over a local pointillist placeholder image, animates rough prompts into structured specs, keeps the static same-prompt comparison, and includes a no-hash scroll guard so fresh visits anchor at the hero. Replace site/assets/pointillist-placeholder.svg with properly licensed artwork before production use.

npm run site:serve     # preview with Wrangler on localhost:4173
npm run site:deploy    # deploy site/ to the improv-sh Cloudflare Pages project

For first-time Cloudflare setup, create the Pages project with:

npm run site:project:create

Then attach the custom domain in Cloudflare Dashboard > Workers & Pages > improv-sh > Custom domains and add improv.sh. If Cloudflare does not create the DNS record automatically, add this record in Cloudflare DNS:

Type: CNAME
Name: @
Target: improv-sh.pages.dev
Proxy status: Proxied
TTL: Auto

The repo also ships site/_redirects, so www.improv.sh can redirect to the apex after you attach www.improv.sh and add a matching www CNAME to improv-sh.pages.dev.

Privacy

The local provider never makes network requests. Model providers send your prompt to the selected service only when explicitly enabled through VS Code settings or CLI flags/environment. Telemetry is off by default and, when enabled, records event names and counts only — never prompt content.

The panel stores recent prompt history locally in VS Code global state so you can reuse recent rewrites. Telemetry records only numeric activation and workflow counters such as provider mode, route surface, before/after score, variant, copy/apply/send events, and failure counts.

License

MIT