wisp

A terminal interface for AI coding agents, built on the Agent Client Protocol (ACP).

Wisp launches an ACP-compatible agent as a subprocess, streams the conversation in real time, and gives you built-in git diff viewing, file attachments, session management, and a settings overlay — all without leaving the terminal.

Table of Contents

• Quick start
• How it works
• Keybindings
• Slash commands
• Settings
  • Themes
• Logs
• Documentation

Quick start

cargo install --path packages/wisp
wisp                       # launches the default agent ("aether acp")
wisp --agent "my-agent"    # launch a custom ACP agent

The --agent flag accepts any shell command that speaks ACP over stdio.

How it works

CLI args ──→ RuntimeState (ACP handshake + theme) ──→ App event loop ──→ Renderer
                                                           │
                            ┌──────────────────────────────┼──────────────────┐
                            ▼                              ▼                  ▼
                    terminal events               ACP events (stream)      tick
                    (keys, resize)                (text, tool calls,     (100 ms)
                            │                      plans, thoughts)         │
                            ▼                              ▼                ▼
                        on_event ─────────────────→ on_acp_event ────→ on_tick
                            │                              │                │
                            └──────────────┬───────────────┘                │
                                           ▼                                │
                                    Renderer::render_frame  ◀───────────────┘

1. RuntimeState spawns the agent subprocess, performs the ACP initialize / newSession handshake, and loads the theme.
2. App owns two screens — the conversation and a git diff viewer — plus a settings overlay. It routes terminal events, ACP events, and ticks to the active screen.
3. The tui library's diff-based Renderer turns each frame into minimal ANSI output.

Keybindings

Slash commands

Type / in the input to open the command picker. Built-in commands:

Additional commands may be available from the agent (e.g., /search, /web).

Settings

Wisp has two kinds of settings:

1. Wisp settings (~/.wisp/settings.json) — UI preferences like themes and status-line segments.
2. Agent settings — Model, reasoning effort, MCP servers, etc. These come from the agent and are configured in-app via /settings

Override the Wisp home directory with WISP_HOME environment variable.

Status line

The status line is configurable. Segments like cwd, gitRef, agent, mode, model, reasoning, context, and serverHealth can be reordered or hidden. See the settings reference for details.

Themes

Place .tmTheme files in ~/.wisp/themes/:

mkdir -p ~/.wisp/themes
cp my-theme.tmTheme ~/.wisp/themes/

Then set in ~/.wisp/settings.json:

{
  "theme": { "file": "my-theme.tmTheme" }
}

Remove "file" or set it to null to use the default theme.

Logs

Debug logs are written to /tmp/wisp-logs/wisp.log.YYYY-MM-DD by default. Override with:

wisp --log-dir ~/logs

Documentation

Run cargo doc -p wisp --open for full API docs. Key entry points:

• run_tui — launch wisp with an agent command
• RuntimeState — ACP session bootstrap
• App — main application component
• settings — Wisp and theme configuration