Wisp

A coding agent that stays in sync with you.
Redirect it while it works. Approve what it changes. Inspect everything it did.

Install · Quickstart · Staying in sync · Docs · PyPI · Changelog

What is Wisp?

Most coding agents ask you to choose between watching and working: you either sit and wait, or you walk away and audit a diff afterwards. Wisp is built for the middle — you can redirect it mid-run, you approve anything that touches your machine, and every action it takes is a typed event on an inspectable transcript.

Underneath is a single event-driven runtime. The CLI, the fullscreen TUI, the JSONL RPC process, and the in-process SDK all drive the same command host and agent loop rather than reimplementing it. They share session, tool, approval, and cancellation semantics, while each frontend exposes the controls its input model supports: RPC and SDK clients have live steering and queue APIs, the TUI accepts interactive follow-ups, and print/JSON modes run one prompt without a mid-run input channel.

Install

Wisp is published on PyPI as wisp-ai, installs a wisp command, and requires Python 3.12+. Linux and macOS are supported; Windows is best-effort until it has dedicated CI coverage.

uv tool install "wisp-ai==0.1.0"
wisp --version

To run it without installing: uvx --from "wisp-ai==0.1.0" wisp. If wisp is not on your PATH, run uv tool update-shell once and restart your shell.

See Installation for the update policy and troubleshooting.

Quickstart

Run Wisp from the project you want it to work on:

cd path/to/project
wisp

Wisp defaults to OpenAI Codex subscription access. Type /connect to open the provider panel, pick OpenAI → ChatGPT Plus/Pro, and complete the device-code flow. The same panel accepts masked API keys for OpenAI, xAI, DeepSeek, Anthropic, and Google. Then ask for something:

explain the architecture of this repository

For one-shot prompts and scripts, use print mode — or run entirely offline to try it without credentials:

wisp -p "summarize the current changes"
wisp -p "hello" --provider fake

Staying in sync

This is the part worth knowing before anything else.

Steer without starting over. RPC and SDK clients can queue a course correction for the active run. Wisp injects it at the next safe request boundary without discarding completed tool work or rewriting the transcript. A follow-up waits until the run would otherwise finish. The TUI queues text entered during a run as follow-up work; print and JSON invocations are intentionally one-shot.

Cancel cleanly. Cancellation is cooperative and leaves the session resumable rather than half-written. In-flight tool work is unwound, the JSONL record stays valid, and --continue picks up from the last committed state.

Approve what matters. Tools are classified read, mutating, or command. Reads run directly; writes, edits, and shell commands stop and ask. The decision lives outside the model's reach — no prompt can talk Wisp into skipping it — and print mode blocks unsafe execution entirely unless you pass --yes.

Nothing happens off-screen. Every action is a typed WispEvent in an enforced order, persisted to an append-only JSONL session you can read, resume, branch, or audit long after the run.

→ How it stays in sync

Interfaces

In 0.2.0rc2, wisp, wisp tui, and wisp --mode tui use auto: prefer the Rust frontend on macOS/Linux when the active installation declares its native binary, otherwise use Textual. Native wheels cover macOS arm64/x86_64 and Linux glibc 2.28+ x86_64. Pure/source installs and other platforms keep Textual. Explicit CLI selection takes precedence over WISP_TUI_RENDERER, which takes precedence over auto. WISP_RUST_TUI_BINARY also selects Rust in auto mode on macOS/Linux for source development. Missing or damaged declared binaries and Rust launch/runtime failures report an error; they never silently switch frontends.

Use wisp tui --renderer textual or WISP_TUI_RENDERER=textual for the maintained Python fallback. Textual keeps compatibility and critical fixes; new frontend work prioritizes Rust. Both clients use the same Python runtime, permissions, providers, and saved sessions.

This is the RC2 release policy; stable 0.1.0 and published RC1 retain their existing defaults. See the TUI guide.

The Rust TUI shows context usage in its header. Use /context for budget, usage, cost, and compaction details; during a run, session totals show the last refreshed snapshot. When idle, /context auto on|off changes automatic compaction for the current process, and /compact [instructions] compacts the selected session. Ctrl-C cancels manual compaction.

Use /skills to browse skill descriptions and sources; d shows discovery diagnostics. Enter inserts the selected /skill:name before your draft, ready to edit and submit. Slash completion lists commands followed by skills; /skill: narrows the list to skills. Tab or Enter accepts a suggestion, then Enter submits it. /mcp shows server status, registered tools, and connection errors. Press r in either browser to refresh, and Esc or Ctrl-C to close. Both browsers remain available while a prompt is running.

Press Ctrl-R or use /history to search prompts submitted in the current Rust TUI run, including accepted steering and follow-ups. Search ignores case and repeated whitespace. Enter replaces your draft with the selected prompt without submitting it; Esc, Ctrl-C, or Ctrl-R closes history and preserves your draft. History survives session switches, but is cleared when the TUI exits. It retains up to 100 unique prompts within a 4 MiB text budget; older entries are evicted first. Search covers the first 16,384 normalized characters of each prompt, while restoration keeps the complete original text.

RPC mode and the in-process SDK expose the same command, event, session, trust, and approval contracts the built-in interfaces use. See Interfaces and the Python SDK guide.

External frontends can use the project file discovery RPC for bounded, protected-path-aware file and directory snapshots.

Architecture

One event-driven runtime, shared by every interface:

CLI / JSONL-RPC / SDK adapters → RPC command host → CodingSession → AgentHarness → run_agent_loop

Each layer adds exactly one concern. The provider/tool cycle knows nothing about sessions or frontends; the harness owns in-memory conversation state; the coding session adds persistence and safety policy; interfaces consume typed events. The TUI is an RPC client, not a second agent loop — which is why it cannot drift from the guarantees above.

→ Architecture

Documentation

Contributing

uv sync                                                              # install
uv run ruff format --check . && uv run ruff check . && uv run mypy   # quality gates
uv run pytest tests                                                  # complete suite

The suite runs entirely against deterministic fake and scripted providers, so the agent core, CLI, and JSONL sessions are exercised without API keys or network calls. Run the complete command before considering a change verified, and preserve the layer boundaries described above.

See Contributing for development setup and CI policy. Issues and pull requests are welcome at github.com/whanyu1212/Wisp/issues.

License

MIT — see LICENSE.