# Documentation
Source: https://trywisp.dev/docs/index.md
wisp runs Claude Code, Codex, Cursor, opencode, Antigravity, Grok and Copilot from one place: the desktop app, the
browser, the terminal UI, the command line, your phone, or your own agent. It keeps every task they did next to the
code they wrote. Every guide shows each step four ways: the **Desktop app** (the browser is the same), the **Phone app**, the
**TUI** and the **CLI**.
**Declare**
Your agents, crew, machines, skills, MCP servers, rules and workflows as files in your repo's `.wisp/`
folder. Review them in a pull request like any code.
[Write your setup as code](/docs/concepts/formulas/)
**Run**
Any agent, many at once, each in its own git worktree, on this computer, your other computers or in the
cloud. Follow up, set goals, compare two agents on the same task.
[Run a task](/docs/guides/run/run-and-follow-up/)
**Track**
Every task is a file: what was asked, what the agent said, the code it wrote. `wisp blame` tells you which
task wrote a line and why.
[Track agent work](/docs/guides/track/track-agent-work/)
**Make it yours**
Everything in wisp is a plugin. Add a setting, a pane, a command or a whole channel with the same API the
built-ins use.
[Make wisp your own](/docs/plugins/make-wisp-your-own/)
## For agents
Every page is also plain markdown: add `.md` to its address. [`llms.txt`](/docs/llms.txt) lists them all and
[`llms-full.txt`](/docs/llms-full.txt) holds them in one file.
- [Start with your agent](https://trywisp.dev/docs/guides/agents/claude-code/): Claude Code, Codex, Cursor, opencode, Copilot, Grok or Antigravity.
- [The desktop and phone apps](https://trywisp.dev/docs/guides/apps/desktop-app/): Install the desktop app; join the phone app waitlist.
- [Reference](https://trywisp.dev/docs/reference/cli/): The CLI, every command, setting, MCP tool, answer block and resource kind, generated from the code.
---
# Install wisp
Source: https://trywisp.dev/docs/start/install.md
wisp runs the coding agents you already have. You need at least one of them installed and signed in:
| Agent | Command wisp runs |
| --- | --- |
| [Claude Code](https://claude.com/claude-code) | `claude` |
| [Codex](https://github.com/openai/codex) | `codex` |
| [opencode](https://opencode.ai) | `opencode` |
| [Cursor CLI](https://cursor.com/cli) | `cursor-agent` |
| [Antigravity CLI](https://antigravity.google/docs/cli/headless/) | `agy` |
| [Grok Build](https://x.ai/cli) | `grok` |
| [GitHub Copilot CLI](https://github.com/features/copilot/cli) | `copilot` |
No agent yet? Settings → Agents installs the ones wisp can install for you, and tells you how to get the others.
## Install
Pick one.
```sh
npm install -g wisp-agents # macOS, Windows or Linux, with Node.js 18 or later
curl -fsSL https://trywisp.dev/install.sh | bash # macOS or Linux: checks Node, then installs with npm
brew install wispagents/tap/wisp-agents # Homebrew: the command line and the browser app
brew install --cask wispagents/tap/wisp # Homebrew: the desktop app (macOS 13.3 or later)
```
Or try it without installing: `npx wisp-agents`.
:::note
wisp is in alpha: expect rough edges, and [tell us what breaks](https://github.com/WispAgents/wisp/issues).
:::
The desktop app for macOS, Windows and Linux is on the [latest release](https://github.com/WispAgents/wisp/releases/latest),
with `SHA256SUMS.txt`. The app updates itself: when a new version is out, its top bar says *Update to …*.
## Open it
```sh
wisp # opens the desktop app (or a browser tab when there's no app)
wisp --browser # in the browser: http://localhost:4477
wisp "fix the flaky login test" # starts a task in this folder right away
```
wisp runs a small local server, `wisp serve`, that the app, the browser, the terminal and your phone all talk to.
The first `wisp` starts it for you.
## No computer to keep on?
[wisp Cloud](../../concepts/machines-and-cloud/) gives you your own wisp on a server. Sign in at
[grid.trywisp.dev](https://grid.trywisp.dev) and your agents keep working when your laptop sleeps.
## Next
- [Run your first task](../first-task/)
- [Give your repo a `.wisp/` folder](../your-repo/)
---
# Your first task
Source: https://trywisp.dev/docs/start/first-task.md
A **task** is one piece of work you hand to an agent: "fix the flaky login test", "add a dark mode toggle". wisp
gives it its own copy of your repo (a git worktree), runs the agent there, and shows you what it did.
## Start it
**Desktop app:**
Press **New task** (**N** or **⌘L**), pick the project, type what you want, and press **Enter**. The footer under the
box picks:
- **The mode:** *Plan* only reads and proposes. *Edits* changes files and asks before anything else. *Full auto*
does the whole job without stopping.
- **The agent and model:** Claude Code, Codex, Cursor and the rest, each with its own models and thinking level.
New task keeps your last pick.
- **Where:** *This computer · Worktree* by default: the task works in its own folder and branch, so your checkout
stays as it was and several tasks can run at once.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right). Pick the project, type what you want, and tap
**Send**. The chips under the box pick the mode, the agent and model, and where it runs, the same as on the desktop.
New task keeps your last pick.
**TUI:**
Run `wisp tui` in your repo. Press **n** for a new task, type, and press **Enter**. **Shift-Tab** cycles the mode
(plan → edits → auto).
**CLI:**
In your repo:
```sh
wisp "fix the flaky login test"
wisp "fix the flaky login test" --agent codex --effort high --mode edits
wisp "fix the flaky login test" --no-worktree # work in your checkout instead
```
## Watch it
While it works you see what it's doing right now. When it's done you get its answer as cards: what changed, the
diff, the tests it ran, screenshots, what you might do next. The full transcript is always one click away.
**Desktop app:**
The task opens beside the list. Its state shows on its row: working, needs you, finished. **J** and **K** move to
the next and previous task. **V** opens the full transcript.
**Phone app:**
Tap the task in **Tasks** to open it. The list groups tasks by state: *Needs you*, *Working*, and the rest.
**⋯** (iPhone) or **⋮** (Android) in the task's top bar → **Show ›** has the full transcript.
**TUI:**
**Enter** opens the task. **j** and **k** move between its steps, **Space** opens one, **d** shows the diff.
**CLI:**
```sh
wisp ls # every task and its state
wisp attach last # follow the newest one live, with a reply box after
wisp show last # its latest answer as markdown
```
## Follow up
A follow-up sent while the task works interrupts it, or waits its turn if you queue it.
**Desktop app:**
Press **/** to jump to the reply box under the answer, type, and press **Enter**. If the answer suggested
follow-ups, the first shows faded in the box: press **Tab** to use it. Switch **Queue** on to send it after the
current turn.
**Phone app:**
Type in the reply bar at the bottom of the task and tap **Send**. To send it after the current turn, tap the
options chip in the reply bar and switch on **Queue**.
**TUI:**
Press **i**, type, **Enter**. While a turn runs, **Enter** queues it; **Ctrl-S** sends a queued one now.
**CLI:**
```sh
wisp reply last "also cover the logout path"
wisp reply last "then update the changelog" --queue
```
## Ship it
Shipping commits the task's changes, pushes its branch and opens a pull request. wisp then follows the PR's checks
and reviews on the task.
**Desktop app:**
**Ship** at the top of the task (**S**). *Write it with …* has the task's agent write the PR title and description
from the diff, following your repo's pull request template. When you're happy, **Done** (**E**).
**Phone app:**
Open **⋯** (iPhone) or **⋮** (Android) in the task's top bar → **Ship it…**. When you're happy, **Mark done** in the same
menu, or swipe the task right in the **Tasks** list.
**TUI:**
With the task open, send `/ship ship`. `/ship merge` squash-merges it.
**CLI:**
```sh
wisp ship # commit, push, open the PR (--draft)
wisp merge # squash-merge it and sync your local base branch
```
## Next
- [Give your repo a `.wisp/` folder](../your-repo/), so every task is kept next to the code it wrote.
- [Start with your agent](../../guides/agents/claude-code/): what's special about each one.
- [All the guides](../../guides/).
---
# Your repo's .wisp folder
Source: https://trywisp.dev/docs/start/your-repo.md
`wisp init` gives your repo a `.wisp/` folder. It holds two things:
- **Your agent setup, as code**: which agents, crew, skills, MCP servers, rules and workflows this repo uses
(`*.wisp.yml` files). See [Formulas](../../concepts/formulas/).
- **The tasks that built the code**: one file per task, with what was asked, what the agent answered, its
transcript and the commits it made. See [The .wisp folder](../../concepts/wisp-folder/).
```sh
cd your-repo
wisp init
git add .wisp && git commit -m "chore: wisp setup"
```
`wisp init` writes `.wisp/wisp.yml`, adds a short note to `AGENTS.md` (and `CLAUDE.md` when there is one) so
agents know about the folder, and fetches and locks any modules the setup uses.
## Which tasks the repo keeps
`.wisp/wisp.yml` says it:
```yaml
wisp: 1
history: { track: ask } # auto | ask | manual
```
- `ask` (the default): when a task in this repo is shipped or marked done, its answer offers **Save to repo**.
- `auto`: every such task is saved.
- `manual`: nothing is saved unless you save it, with **Save to repo** or `wisp track `.
A saved task is written to `.wisp/tasks/` for you to commit, scrubbed of secrets and private paths. Commits that
Ship it makes carry a `Wisp-Task:` trailer, so the code and the task point at each other.
## Use it
```sh
wisp log # the tasks that built this repo, newest first
wisp log src/auth # the ones that touched a path
wisp blame src/auth/login.ts:42 # which task wrote that line, and what it was asked
wisp resume # a new task that carries on from where that one stopped
```
Agents can read it too. With `history: { track: ask, inject: true }`, a new task starts with the past tasks on the
files its prompt names (the five most relevant), so it knows the decisions already made there.
## Next
- [Track agent work beside your code](../../guides/track/track-agent-work/)
- [Write your setup as code](../../guides/declare/software-factory-as-code/)
---
# Declare, Run, Track
Source: https://trywisp.dev/docs/concepts/declare-run-track.md
Infrastructure as code put servers in the repo. wisp puts **the way your software gets built** there: who builds
it, how, and what was asked along the way. It does three things.
## Declare
Your agents, your crew, the machines they run on, their skills and MCP servers, your rules and your workflows are
files in `.wisp/` ([formulas](../formulas/)). You change them in a pull request, review them like code, and share
them across repos as modules. Everything you set up in the app can be written back to files with `wisp export`,
and `wisp plan` shows what changed in the app since.
## Run
Any coding agent, many at once, each [task](../tasks/) in its own git worktree, on this computer, your
[other computers or the cloud](../machines-and-cloud/). You drive it from wherever you are: the desktop app, a
browser, the terminal (`wisp`), your phone, Slack or Telegram, your own agent over MCP, or your own code through
the SDK. A [crew](../crew/) of long-lived agents can check in on a schedule and wake on events.
## Track
Every task is a file: what was asked, the agent's answer, its transcript and its commits. The repo keeps the ones
you choose in [`.wisp/tasks`](../wisp-folder/). `wisp blame` tells you which task wrote a line and why,
`wisp resume` carries on an old task on today's code, and `wisp rerun` replays one from the commit it started on.
## One engine, many ways in
The app, the TUI, the CLI, the SDKs, the MCP tools and the chat channels all call the same commands
([reference](../../reference/commands/)), so anything you can do in one you can do in the others. Everything in
wisp, the built-in parts included, is a [plugin](../plugins/).
---
# Tasks
Source: https://trywisp.dev/docs/concepts/tasks.md
A **task** is one piece of work for one agent. It has a prompt, a project (the folder it works in), an agent and
a model, and a mode. It runs in **turns**: your first message is the first turn, each follow-up is another.
## Modes
| Mode | What the agent may do |
| --- | --- |
| Plan | Read and run commands to look around. No file edits. |
| Edits | Change files. Anything else asks you first. |
| Full auto | The whole job, without stopping to ask. |
Change the mode for the next turn from the reply box (Shift+Tab), or `wisp reply --mode edits "…"`.
## The worktree
With **Worktree** on (the default, Settings → Worktrees), a task gets its own git worktree and branch, made from
your project's base branch. Your checkout is never touched, and several tasks can change the same repo at once.
wisp cleans up idle worktrees after a while (7 days by default), but never one that holds changes or commits that
exist nowhere else.
## The answer
An agent wisp runs ends its turn with a short structured report: what it did, the diff, the tests it ran, a live
preview, questions for you, suggested next steps. wisp draws each part as a card
([answer blocks](../../reference/answer-blocks/)), so you read the result, not the whole conversation. The full
transcript is one click away (*Transcript*).
## While it works
- **Follow up** at any time. By default a follow-up interrupts the turn; with *Queue* on, it waits.
- **Ask on the side** (`wisp btw "…"`) without interrupting.
- **Stop** ends the turn. Queued follow-ups stay.
- A task that needs you (a question, a permission, a usage limit) moves to **Needs you** and, if you set it up,
tells your phone.
## Goals
Give a task a **goal** ("all tests pass") and wisp keeps sending it back after each turn until judges agree the
goal is met, or it runs out of rounds and asks you. Judges can be other agents and harnesses. See
[Keep going until it's done](../../guides/run/goals/).
## How it ends
**Ship it** commits, pushes and opens a pull request; **Merge** squash-merges it. **Mark done** closes the task.
In a repo with a `.wisp/` folder, a finished task can be [saved to the repo](../wisp-folder/).
---
# Agents and harnesses
Source: https://trywisp.dev/docs/concepts/agents.md
## Harnesses
A **harness** is a coding agent's own command line: `claude`, `codex`, `opencode`, `cursor-agent`, `agy`, `grok`,
`copilot`. wisp doesn't replace it. It starts it in the task's folder, reads what it does, and shows you the
result. Your sign-in, your plan and your settings stay the harness's own.
Settings → Agents lists the harnesses wisp found, their version and models, and lets you:
- **Sign in** through the harness's own login, or add a key for one that takes keys.
- **Add another account** (Claude Code, Codex): wisp picks the account for each run and skips one that's at its
usage limit.
- **Update** a harness when a newer version is out, the way you installed it.
- **Ask before running a changed harness**: wisp pins each harness's program and holds a run if it changed.
## Agent profiles
An **agent** in a formula is a named way of running a harness: which harness, model and effort, which mode, which
skills and MCP servers, and standing instructions.
```yaml
agents:
reviewer: { harness: codex, effort: high, mode: plan, instructions: "Review for correctness first." }
builder: { harness: claude, model: opus, skills: [testing], connectors: [linear] }
skills:
testing: { description: How this repo tests, body: "Run the tests before you say it's done." }
connectors:
linear: { url: "https://mcp.linear.app/sse", oauth: true }
```
A task, a crew member, a team seat or a goal judge names a profile (`agent: reviewer`) or a harness directly.
## Auto
Pick **Auto** and wisp's router chooses the harness and model for each task from what it is and what you have.
New task shows what Auto would pick before you send. Tune it with a `router:` in your formula.
## Teams
A **team** is a lead agent and the subagents it may hand work to: wisp's own delegates (each a task of its own,
on any harness) and the harness's own subagents (Claude Code's). The task's **Team** tab shows each one live: what
it's doing, then what it came back with.
---
# Crew
Source: https://trywisp.dev/docs/concepts/crew.md
A **crew member** is an agent that stays: it has a name and a face, a role ("reviewer", "release manager"), a
**brief** (standing instructions), a **kit** (skills and notes), and a **notebook** it keeps between jobs. Each job
it does is a task of its own, so you can open it, follow up and ship it like any other.
## Giving it work
- **Hand it a job** from its page, or mention it: `@ada fix the flaky test` in the launcher, a reply box or a chat
channel.
- **Delegate**: a task can hand work to crew members (its Team tab shows them).
- **Check-ins**: `cron: "every weekday at 9"` and it looks at its brief and decides what to do.
- **Wakes**: triggers can wake it on an event (`pr.review_requested`, a CI failure, a chat message).
## Where it works
`cwd` is its folder and `machine` the computer its jobs run on. `sandbox: job` gives each job a worktree of its
own; `sandbox: own` gives the member one of its own. `parallel` says how many of its jobs may run at once, and
`paused` stops check-ins and jobs until you resume it.
```yaml
agents:
reviewer: { harness: codex, effort: high, mode: plan }
crew:
ada:
role: reviewer
agent: reviewer
brief: "Review every PR the crew opens. Request changes, never merge."
cron: "every weekday at 9"
sandbox: job
```
## Sharing
A crew member can be shared as a file (`.crew.json`) or through wisp Cloud, with what it references. See
[Share skills, AGENTS.md and MCP servers](../../guides/declare/share-skills-and-mcps/).
---
# Formulas (your setup as code)
Source: https://trywisp.dev/docs/concepts/formulas.md
A **formula** is your wisp setup written as files. In a repo it's the `.wisp/` folder: wisp reads every
`*.wisp.yml` (or `.json`, `.toml`) in it as one setup, the way Terraform reads every `.tf` in a folder. Split it
however you like: `agents.wisp.yml`, `crew.wisp.yml`, `workflows/release.wisp.yml`.
```yaml
# .wisp/agents.wisp.yml
wisp: 1
agents:
reviewer: { harness: codex, effort: high, mode: plan }
builder: { harness: claude, model: opus }
skills:
testing: { description: How this repo tests, path: docs/testing.md }
connectors:
linear: { url: "https://mcp.linear.app/sse", oauth: true }
```
Every kind and field is in the [resource kinds reference](../../reference/kinds/). `wisp schema` prints the same as
JSON Schema, for your editor.
## Addresses and references
Every resource has an address `.`: `agent.reviewer`, `crew.ada`, `connector.linear`. Any field can
refer to another resource or one of its fields:
```yaml
tasks:
nightly: { prompt: Update the dependencies, agent: "${agent.reviewer}" }
```
References set the order things are created in, and a cycle is refused. `wisp graph` prints them, and
`wisp mv agent.reviewer agent.critic` renames one and rewrites every reference to it.
A field that names another thing takes its bare name too (`agent: reviewer`, `goal: green-build`, `task: nightly`,
`connectors: [linear]`), or the thing inline where the field allows it (`goal: { text: … }`). Either way the name is
checked wherever a formula is read: `wisp validate`, `wisp apply`, a run with `--formula` and the app's Import all refuse
one that names nothing, and say what there is:
```text
✗ tasks.nightly: no agent named reviwer: agents has reviewer (or claude, codex, auto)
✗ crew.ada: team[].crew: a loop: crew.ada → crew.bo → crew.ada
```
An agent field also takes a harness (`codex`) or `auto`; a machine field a computer you added in the app, or `this`; a
task's `project:` a project's name as well as a folder. A module's resources are referenced by their address:
`${module.team.agent.reviewer}`. Every file reads the same way, a `.wisp/` folder, `wisp apply -f one.yml`, a
`--formula` and a task file's formula alike: references, variables, locals, `count` and modules all work in each.
## Variables, locals, outputs, count
```yaml
variables:
model: { type: string, default: opus }
helpers: { type: number, default: 2 }
locals:
harness: claude
agents:
critic: { harness: "${local.harness}", model: "${var.model}" }
helper:
count: ${var.helpers} # helper-0, helper-1
harness: codex
instructions: "helper ${count.index}"
outputs:
critic_model: { value: "${agent.critic.model}" }
```
Set a variable with `-var model=sonnet`, a `--var-file`, or `WISP_VAR_model`. `wisp output` prints the outputs.
**Workspaces** keep one set of variables each: `wisp workspace new prod`, `wisp workspace select prod`, and
`${workspace}` is its name.
## Modules
A module is a formula folder you reuse, with inputs and outputs: a "review team" or a "nightly maintenance" setup
shared across repos.
```yaml
modules:
team: { source: ../shared/review-team, inputs: { model: haiku } }
pack: { source: "git::https://github.com/acme/wisp-modules//pack?ref=v1.2" }
```
`wisp init` fetches them into `.wisp/modules/` and pins them in `.wisp/lock.yml`; `wisp init -upgrade` moves
them. A module's resources are addressed `module.team.agent.reviewer`.
## Plan, apply, export
```sh
wisp validate # schema and checks
wisp plan # what applying .wisp/ would change
wisp apply # do it (asks first; --yes to skip)
wisp destroy # take out everything it declares
wisp export # what's set up here (in the app too), as files
```
wisp's store is the state: `wisp plan` compares your files with what wisp has now, so a change made in the app
shows up as drift. `wisp export` writes it back to files, and `wisp import ` adopts one thing made in the
app into the files.
## One-off overlays
A formula can run one task without being applied: its agents, skills, connectors, teams, projects and goals are that
task's alone, and nothing is left behind. Handy for trying a setup before you apply it.
```sh
wisp "review the diff" --formula f.yml # a task under it (several: --formula f.yml,g.yml)
wisp run --formula f.yml "review the diff" # the same
wisp run release --formula f.yml version=2.1 # the task f.yml declares as `release`, by its name
```
With no `--agent` and one agent declared, that agent runs it; `--agent` may name any agent the formula declares, and a
goal it names by name is the formula's. `wisp run --formula` runs a task the formula declares (with
`tasks.default` under it and its `{params}` filled); any other words are the prompt.
A **task file** (`wisp task export > fix.task.yml`, run with `wisp run -f fix.task.yml`) can name its formula
instead of carrying a copy of it: a file beside it, a module of its folder's `.wisp/`, or a list of them.
```yaml
wisp: 1
task: { prompt: Fix the flaky test, agent: critic, goal: green-build }
formula: [./wisp.yml, module.team]
```
The names in its task (agent, goal, connectors, crew, team, project) are read against those and against what this wisp
has; one that names nothing is refused before anything runs. The same works from your harness (`wisp_launch`'s
`formula`) and in the app (`+` → Formula or task file… in New task).
---
# The .wisp folder
Source: https://trywisp.dev/docs/concepts/wisp-folder.md
```text
.wisp/
wisp.yml the folder's own settings (history tracking)
*.wisp.yml your setup: agents, crew, skills, workflows… (formulas)
lock.yml the modules' pinned versions
modules/ the modules, fetched by wisp init
tasks/
2026/11/-.task.yml one tracked task: what was asked, its agent, its commits, its files
2026/11/-.report.md what the agent answered
history/.jsonl.zst the task's full transcript, scrubbed and compressed
```
## One file per task
Each tracked task is its own file, named by its id, so two branches never conflict on the same file. The files are
small text you can read and review in a PR: "this PR was written by these three tasks".
## How much is kept
A tracked task keeps its spec (what was asked, with which agent and base commit), its report and its transcript. The
transcript is scrubbed of secrets, `.env` values and private paths before it's written, and compressed (a typical
one is tens of KB). `wisp track --level spec|report|full` chooses how much; `wisp untrack ` takes it out.
## Linked to the code
When Ship it commits a task's work, each commit carries a trailer:
```text
Wisp-Task: 01a1bc
```
The task file lists its commits and its PR. So you can go both ways:
- **Code to task**: `wisp blame :` names the task that wrote a line, what it was asked and its PR.
- **Task to code**: `wisp log` lists the tasks that built the repo, `wisp tasks --touching ` the ones that
touched a path.
## Carry on
`wisp resume ` starts a new task from where an old one stopped, on today's code: its spec, its report and a
summary of its transcript become the new task's context. Anyone with the repo can do it, not only whoever ran the
task. `wisp rerun ` instead replays a task from the commit it started on.
---
# Machines and wisp Cloud
Source: https://trywisp.dev/docs/concepts/machines-and-cloud.md
Every computer that runs wisp is a **machine**. Your wisp can run tasks on the others, and they all show in one
list.
## Ways to reach a machine
| How | When |
| --- | --- |
| **wisp Cloud (the grid)** | Each computer signs in to the grid. No SSH, no open ports: the grid connects them. |
| **SSH** | A computer you can already `ssh` to. wisp runs over that connection. |
| **Local** | This computer. |
Add one in the app (your avatar → Machines), or declare it:
```yaml
machines:
studio: { transport: ssh, address: me@studio.local }
```
Then pick it under New task, or from a terminal:
```sh
wisp "run the full test suite" --on studio
wisp ls --on studio
```
## wisp Cloud
[grid.trywisp.dev](https://grid.trywisp.dev) gives you your own wisp on a server. Sign in with GitHub or Google and
your agents keep working after you close the laptop. Use it from the browser, from your phone, or as one more
machine in your app.
```sh
wisp cloud signin # sign this computer in to wisp Cloud
wisp computer on # put this computer on the grid, so your other wisps and your phone reach it
```
You can run your own grid on your server with `wisp grid serve` (see [Machines, the Grid and wisp Cloud](../../guides/run/machines/)).
## Pinning work to a machine
A crew member can be tied to a machine (`machine: studio`), so its jobs always run there, and a delegate can run on
another computer than its lead, on a copy of the lead's work.
---
# Plugins
Source: https://trywisp.dev/docs/concepts/plugins.md
wisp's core knows no feature. Running Claude Code, the task list, Ship it, the crew, budgets, Slack: each is a
**plugin**. There are about fifty built in, and yours plug in the same way.
## What a plugin can add
- **Commands**: things wisp can do. Every command is reachable from the app, the CLI (`wisp `), the
SDKs and MCP.
- **Settings**, with their type and default.
- **UI**: a pane, a Settings page, a button in a toolbar, a card in an answer. UI plugins draw with wisp's own
components, so they look like wisp.
- **Resource kinds**, so your setup can be declared in a formula.
- **Events and hooks**: react when something happens, or check a run before it starts.
## How plugins talk
A plugin only reaches another through that plugin's public API: its commands, events and extension points. It
never reaches into another's code. That's why a built-in can be switched off or replaced by yours.
## Permissions
Nothing is allowed by default. A plugin's manifest (`wisp-plugin.json`) lists what it may do
(`runtime:get`, `git:diff`, `channels:send`…). A plugin you install starts **off** and shows what it asks for;
switching it on is your consent.
## Kinds of plugin
| Kind | Runs as |
| --- | --- |
| Declarative | A manifest only: settings, events and the commands it calls. |
| With UI | Its manifest plus a `ui.js` that runs in a sandboxed worker: no DOM, no network. It describes wisp components and calls wisp as itself. |
| Exec | A program of yours, in any language, that talks to wisp over stdin/stdout (JSON-RPC). |
| Built-in | Rust, compiled into wisp. |
Start with [Make wisp your own](../../plugins/make-wisp-your-own/).
---
# Factories
Source: https://trywisp.dev/docs/concepts/factories.md
A **factory** runs a task through a line of **stations** instead of handing it to one agent. Each station is its own
agent with its own prompt, and each hands its work to the next:
1. **Spec**: an agent writes the spec (what it must do, its constraints, how we'll know it's done, the plan) without
changing a file. You approve it, change it in your own words, or stop.
2. **Build**: an agent builds it to the spec, in a worktree of its own. Give it two agents and both build it; the first
whose checks pass goes on.
3. **Checks**: commands run in the build's folder (`npm test`, `npm run lint`). A gate is code, not an agent's word.
4. **Review**: one or more reviewers read the change and each ends with APPROVE or CHANGES. Their votes count as a
goal's judges do: majority, all or any.
5. **Ship**: the PR opens from the build's worktree. You merge it, or it merges by itself if you say so.
A failed check or a review that asks for changes goes **back to build** with what failed, as the next round: the same
build agent gets a follow-up, so it keeps its context and its worktree. After `max` rounds (3 by default) the run asks
you whether to keep going, or stops if the factory says `then: stop`.
## One task, one row
A factory run is one task in the list. Its stations are its children, and a band at the top of the task shows each
station as a step: where it is ("Review · round 2 of 3"), what each station gave, and what waits on you. Questions
(approve the spec, merge the PR) are the task's own question card, so you answer them from the app, the phone, the
TUI, the CLI or a chat channel.
## `default` is always there
With no setup, `--factory` (or **Factory** in New task's picker) runs the built-in `default`: a spec you approve, the
build in its own worktree, the project's `test` command as the checks, one review, and a PR you merge, back to build
at most 3 rounds. Each station runs on the task's agent, or your default harness. Declare your own under `factories:`;
one named `default` replaces the built-in one.
```yaml
agents:
planner: { harness: claude, mode: plan, instructions: "Write the spec: what changes, and how we'll know it works." }
reviewer: { harness: codex, mode: plan, instructions: "Correctness first, then tests." }
critic: { harness: claude, mode: plan, instructions: "Look for what the others missed." }
factories:
careful:
stations:
spec: { agent: planner, approve: human }
build: { agents: [claude, codex] }
checks: { run: [npm test, npm run lint], timeout: 15 }
review: { agents: [reviewer, critic], vote: all }
ship: { pr: true, merge: human }
loop: { back_to: build, max: 3, then: ask }
budget: { usd: 20 }
```
What each field takes is in the [resource kinds reference](../../reference/kinds/). How to run a task through one,
everywhere you work, is in [Run a task through a software factory](../../guides/run/software-factory/).
## What it builds on
A factory uses what wisp already does: each station is an ordinary task (budgets cap it, worktrees hold its changes),
the review counts votes as goals do (a task's goal is what every reviewer judges against, and a declared goal's judges
review when the station names none), every wait is a question on the task, and shipping is wisp's own Ship and Merge.
A run from an agent (`wisp_launch`) never runs a station above its own mode and never merges without you.
---
# Guides
Source: https://trywisp.dev/docs/guides.md
Each guide gets one thing done. Steps come in four tabs, **Desktop app**, **Phone app**, **TUI** and **CLI**: pick the one you use, and
every page remembers it.
## Start with your agent
- [Claude Code](https://trywisp.dev/docs/guides/agents/claude-code/)
- [Codex](https://trywisp.dev/docs/guides/agents/codex/)
- [Cursor](https://trywisp.dev/docs/guides/agents/cursor/)
- [opencode](https://trywisp.dev/docs/guides/agents/opencode/)
- [GitHub Copilot](https://trywisp.dev/docs/guides/agents/copilot/)
- [Grok Build](https://trywisp.dev/docs/guides/agents/grok/)
- [Antigravity](https://trywisp.dev/docs/guides/agents/antigravity/)
## Apps
- [The desktop app](https://trywisp.dev/docs/guides/apps/desktop-app/): macOS, Windows and Linux: install, update, what the window adds.
- [wisp on your phone](https://trywisp.dev/docs/guides/apps/phone-app/): The iPhone and Android apps, and wisp in your phone's browser today.
- [The terminal UI](https://trywisp.dev/docs/guides/apps/tui/): wisp tui: every key, the palette and the views.
## Declare
- [Build a software factory as code](https://trywisp.dev/docs/guides/declare/software-factory-as-code/): Your agents, crew, machines and workflows in .wisp/, planned and applied like infrastructure.
- [Share skills, AGENTS.md files and MCP servers](https://trywisp.dev/docs/guides/declare/share-skills-and-mcps/): One setup for the whole team, reviewed in a pull request.
## Run
- [Run a task and follow up](https://trywisp.dev/docs/guides/run/run-and-follow-up/)
- [Compare agents and try it two ways](https://trywisp.dev/docs/guides/run/compare-and-try/)
- [Worktrees and shipping a PR](https://trywisp.dev/docs/guides/run/worktrees-and-shipping/)
- [Goals and judges](https://trywisp.dev/docs/guides/run/goals/)
- [Review by another agent](https://trywisp.dev/docs/guides/run/review-by-another-agent/)
- [Crew and check-ins](https://trywisp.dev/docs/guides/run/crew-and-check-ins/)
- [Automations, schedules and triggers](https://trywisp.dev/docs/guides/run/schedules-and-triggers/)
- [From Slack, Linear, Telegram and more](https://trywisp.dev/docs/guides/run/from-slack-and-linear/)
- [Long threads and fresh threads](https://trywisp.dev/docs/guides/run/long-threads/)
- [Machines, the Grid and wisp Cloud](https://trywisp.dev/docs/guides/run/machines/)
- [Budgets and usage limits](https://trywisp.dev/docs/guides/run/budgets-and-usage/)
- [MCP from your harness](https://trywisp.dev/docs/guides/run/mcp-from-your-harness/)
- [Ask about what just happened in your terminal](https://trywisp.dev/docs/guides/run/terminal-context/)
## Track
- [Track your agents' work beside your code](https://trywisp.dev/docs/guides/track/track-agent-work/): Every task in .wisp/tasks; wisp blame, log, resume and adopt.
## Make it yours
- [Make wisp your own](https://trywisp.dev/docs/plugins/make-wisp-your-own/): Plugins: add a command, a pane, a channel or a theme.
- [Import a wisp home](https://trywisp.dev/docs/migrate/import/)
---
# Start with Claude Code
Source: https://trywisp.dev/docs/guides/agents/claude-code.md
wisp runs Claude Code for you: in the background, in its own worktree, many tasks at once. It uses your own Claude
plan or API key. wisp never adds a bill of its own.
## What you need
The `claude` command. wisp looks for it on your `PATH`, then where the native installer puts it, then in the copy
the Claude desktop app downloads for its Code tab.
```sh
curl -fsSL https://claude.ai/install.sh | bash # macOS and Linux
irm https://claude.ai/install.ps1 | iex # Windows (PowerShell)
```
## Sign in
wisp uses Claude Code's own sign-in: a Pro or Max plan, or a key (`ANTHROPIC_API_KEY`, Bedrock, Vertex).
**Desktop app:**
Open **Settings** (the person button in the top bar, or **⌘K** → Settings) → **Agents**. Next to Claude Code, press **Sign in**, then **Open the sign-in page**
and sign in with your Claude account. Paste the code it shows you and press **Continue**. Installed it just now?
Press **Re-check**.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → **Agents**. Next to Claude Code, tap **Sign in**, then
**Open the sign-in page**. Sign in, copy the code it shows, come back, paste it and tap **Continue**.
**TUI:**
In the reply box, send:
```text
/accounts login start claude default
/accounts login input claude default
```
**CLI:**
```sh
wisp accounts login start claude default # prints the sign-in link
wisp accounts login input claude default # the code the page shows
wisp accounts login status claude default # signed in, and as whom
```
You can also run `claude` once in a terminal and sign in there. wisp reads the same login.
## Pick it, its model and its effort
Models: **Default** (what Claude Code is set to), **Fable**, **Opus**, **Sonnet**, **Haiku**. Effort: `low`,
`medium`, `high`, `xhigh`, `max`.
**Desktop app:**
In the New task box (**N**), click the harness chip in the footer (it reads *Claude Code · Opus*, for example). Pick
**Claude Code**, a model, and a thinking level. On a running task, the same chip in the reply box changes it for
the next follow-up.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right), then the harness chip under the box. Pick **Claude Code**, then a model and a thinking level. On a running task, tap the options chip in the reply bar, then the agent.
**TUI:**
Press **n** for a new task; in the composer, **Tab** cycles the mode. To move the open task to Claude Code, send
`/runtime set-agent --agent claude`. For a model and effort, start the task from the CLI.
**CLI:**
```sh
wisp "fix the flaky login test" --agent claude --model opus --effort high
wisp reply "now add a test" --agent claude --model sonnet
```
## Modes
- **Plan:** reads and plans, changes nothing.
- **Edits:** asks you before it runs a command. You allow, always allow or deny from the task (in the TUI: **y**,
**a**, **n**).
- **Full auto:** no permission prompts at all. Use it on repos you trust.
Pick the mode with the chip left of the harness, **Tab** in the TUI, or `--mode plan|edits|auto`.
## What wisp adds for Claude Code
- **Several accounts.** Settings → Agents → **Add another Claude account** (a personal one and a work one, say).
Each keeps its own limits. wisp skips one at its limit when you start a task, and never switches to get around
a limit. CLI: `wisp accounts list claude`.
- **Usage windows.** Claude Code reports your 5-hour and weekly windows on every run. See
[Budgets and usage](../../run/budgets-and-usage/).
- **Subagents.** Settings → Usage → **Subagents run on** picks Haiku, Sonnet or the task's own model for Claude
Code's own subagents. `--try subagents=haiku` runs a task twice to compare.
- **Lean runs.** Settings → Agents → **Lean Claude Code runs** starts Claude Code without telemetry and update
checks: about a second faster.
- **Questions and approvals** reach you in wisp, on your phone, or in chat, and the run waits.
## Open in Claude Code
Carry on with the agent yourself, in the same conversation.
**Desktop app:**
Open the task's **⋯** at its top right → **Open in › Open in Claude Code** (key **T**). Claude Code opens in a terminal in the side panel.
**Phone app:**
Open the task, then **⋯** (iPhone) or **⋮** (Android) → **This task › Open in Claude Code**. Claude Code's own screen opens in a terminal on the phone.
**TUI:**
With the task open, press **o**. You come back to the TUI when you quit Claude Code.
**CLI:**
```sh
wisp runtime resume-command # prints the command that resumes it in a terminal
```
Sessions you ran in Claude Code outside wisp come in with `wisp adopt`. To let Claude Code start wisp tasks itself,
see [MCP from your harness](../../run/mcp-from-your-harness/).
---
# Start with Codex
Source: https://trywisp.dev/docs/guides/agents/codex.md
wisp runs Codex in the background, one worktree per task, on your own ChatGPT plan or OpenAI key.
## What you need
The `codex` command. wisp also finds the standalone installer's copy, and the Codex inside the ChatGPT desktop app
on macOS (on Windows that copy can't be run from outside the app).
```sh
npm i -g @openai/codex
```
## Sign in
**Desktop app:**
Open **Settings** (the person button in the top bar, or **⌘K** → Settings) → **Agents** → **Sign in** next to Codex. Open the sign-in page, enter the code wisp shows,
and wait: wisp sees when you're done. A key instead? Press **Keys** and paste it.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → **Agents** → **Sign in** next to Codex. Open the sign-in page,
enter the code wisp shows, and come back: wisp sees when you're done. A key instead? Tap **Keys** and paste it.
**TUI:**
Send `/accounts login start codex default` in the reply box, and follow the link it gives.
**CLI:**
```sh
wisp accounts login start codex default # a link and a code
wisp accounts login status codex default
```
Or run `codex login` yourself. A key in `OPENAI_API_KEY` or `CODEX_API_KEY` works too.
## Pick it, its model and its effort
wisp reads Codex's own model list. Effort: `minimal`, `low`, `medium`, `high`, `xhigh`.
**Desktop app:**
Click the harness chip in the New task footer (**N**), pick **Codex**, then a model and a thinking level. On a running task, the same chip in the reply box changes it for the next follow-up.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right), then the harness chip under the box. Pick **Codex**, then a model and a thinking level. On a running task, tap the options chip in the reply bar, then the agent.
**TUI:**
Send `/runtime set-agent --agent codex` to move the open task to Codex.
**CLI:**
```sh
wisp "add a dark mode toggle" --agent codex --effort high
wisp runtime agents --json # the models each harness has
```
Modes work as everywhere: **Plan** changes nothing, **Edits** asks before commands, **Full auto** never asks
(`--mode plan|edits|auto`).
## What wisp adds for Codex
- **Several accounts:** Settings → Agents → **Add another Codex account**. Each keeps its own limits.
- **Usage windows:** wisp reads Codex's 5-hour and weekly windows, and any banked resets. Settings → Usage →
**Check Codex while work waits** asks Codex every 10 minutes how they stand, so held work goes as soon as a
window resets. Nothing is spent.
- **Automations stop at:** Codex can have its own line, so your ChatGPT chats keep room on a shared plan.
- **Questions** from Codex reach you in wisp and the run waits.
## Open in Codex
**Desktop app:**
Open the task's **⋯** at its top right → **Open in › Open in Codex** (key **T**). Codex opens in a terminal in the side panel.
**Phone app:**
Open the task, then **⋯** (iPhone) or **⋮** (Android) → **This task › Open in Codex**. Codex's own screen opens in a terminal on the phone.
**TUI:**
Press **o** in the open task. Quit Codex to come back.
**CLI:**
```sh
wisp runtime resume-command
```
Next: [Budgets and usage](../../run/budgets-and-usage/), [MCP from your harness](../../run/mcp-from-your-harness/).
---
# Start with Cursor
Source: https://trywisp.dev/docs/guides/agents/cursor.md
wisp runs the Cursor CLI, `cursor-agent`, in the background, one worktree per task, on your own Cursor account.
## What you need
The Cursor CLI. The Cursor editor doesn't include it.
```sh
curl https://cursor.com/install -fsS | bash # macOS and Linux
```
On Windows, follow [cursor.com/cli](https://cursor.com/cli).
## Sign in
**Desktop app:**
Open **Settings** (the person button in the top bar, or **⌘K** → Settings) → **Agents** → **Sign in** next to Cursor, then **Open the sign-in page**. Or press **Keys**
and paste a Cursor API key.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → **Agents** → **Sign in** next to Cursor, then
**Open the sign-in page**. Or tap **Keys** and paste a Cursor API key.
**TUI:**
Send `/accounts login start cursor default` and open the link it gives.
**CLI:**
```sh
wisp accounts login start cursor default
wisp accounts login status cursor default
```
Or run `cursor-agent login` yourself, or set `CURSOR_API_KEY`.
## Pick it and its model
wisp reads the models from `cursor-agent --list-models`. Cursor has no effort setting.
**Desktop app:**
Click the harness chip in the New task footer (**N**), pick **Cursor**, then a model. On a running task, the same chip in the reply box changes it for the next follow-up.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right), then the harness chip under the box. Pick **Cursor**, then a model. On a running task, tap the options chip in the reply bar, then the agent.
**TUI:**
Send `/runtime set-agent --agent cursor` to move the open task to Cursor.
**CLI:**
```sh
wisp "rename the config loader" --agent cursor --model
```
Modes: **Plan**, **Edits**, **Full auto** (`--mode plan|edits|auto`).
## What's different with Cursor
`cursor-agent` takes no MCP server by flag. So it has no wisp tools in a task: when it needs you, it ends its
answer with a question block, and you answer in the reply box. It can't start other wisp tasks either.
## Open in Cursor
**Desktop app:**
Open the task's **⋯** at its top right → **Open in › Open in Cursor** (key **T**). Cursor opens in a terminal in the side panel.
**Phone app:**
Open the task, then **⋯** (iPhone) or **⋮** (Android) → **This task › Open in Cursor**. Cursor's own screen opens in a terminal on the phone.
**TUI:**
Press **o** in the open task.
**CLI:**
```sh
wisp runtime resume-command
```
---
# Start with opencode
Source: https://trywisp.dev/docs/guides/agents/opencode.md
opencode is the quickest way to start: it has free models and needs no account. wisp can install it for you.
## Install it
**Desktop app:**
With no agent installed, home offers **Install opencode**. Otherwise open **Settings** (the person button in the
top bar, or **⌘K** → Settings) → **Agents** and press **Install** next to opencode. It goes into
`~/.wisp/tools`, usually in under a minute.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → **Agents** and tap **Install** next to opencode. It installs on
the computer the phone is working on, usually in under a minute.
**TUI:**
Send `/accounts install opencode`.
**CLI:**
```sh
wisp accounts install opencode
```
Or install it yourself: `npm i -g opencode-ai`.
## Sign in (optional)
Free models need nothing. For other providers, sign in with opencode's own login in a terminal, then press
**Re-check** in Settings → Agents (`wisp accounts recheck`). The row says **Free models only** until a provider is
signed in.
## Pick it and its model
wisp reads opencode's models and their variants. The effort you pick becomes the model's variant.
**Desktop app:**
Click the harness chip in the New task footer (**N**), pick **opencode**, then a model. Type to search a long list. On a running task, the same chip in the reply box changes it for the next follow-up.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right), then the harness chip under the box. Pick **opencode**, then a model. Type to search a long list. On a running task, tap the options chip in the reply bar, then the agent.
**TUI:**
Send `/runtime set-agent --agent opencode` to move the open task to opencode.
**CLI:**
```sh
wisp "write the missing docstrings" --agent opencode --model
```
Modes: **Plan**, **Edits**, **Full auto** (`--mode plan|edits|auto`). In Edits, a command opencode wasn't allowed
to run shows as blocked on the task.
## What wisp adds for opencode
- wisp's MCP server and your grants go in with each run, merged over your own `OPENCODE_CONFIG_CONTENT`.
- When a provider rate-limits it, opencode retries in silence. wisp notices and stops the run, so it doesn't hang.
- **Update to …** in Settings → Agents runs opencode's own upgrade.
## Open in opencode
**Desktop app:**
Open the task's **⋯** at its top right → **Open in › Open in opencode** (key **T**). opencode opens in a terminal in the side panel.
**Phone app:**
Open the task, then **⋯** (iPhone) or **⋮** (Android) → **This task › Open in opencode**. opencode's own screen opens in a terminal on the phone.
**TUI:**
Press **o** in the open task.
**CLI:**
```sh
wisp runtime resume-command
```
---
# Start with GitHub Copilot
Source: https://trywisp.dev/docs/guides/agents/copilot.md
wisp runs the GitHub Copilot CLI, `copilot`, in the background, one worktree per task. It needs a GitHub Copilot
plan.
## What you need
```sh
npm i -g @github/copilot
```
## Sign in
Copilot signs in with its own login. Run `copilot login` once in a terminal, then tell wisp to look again.
**Desktop app:**
Open **Settings** (the person button in the top bar, or **⌘K** → Settings) → **Agents** → **Re-check**. Copilot shows **Ready** once it's signed in.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → **Agents** → **Re-check**. Copilot shows **Ready** once it's
signed in.
**TUI:**
Send `/accounts recheck`.
**CLI:**
```sh
wisp accounts recheck
```
## Pick it, its model and its effort
wisp reads Copilot's models from its own config help. Effort: `low`, `medium`, `high`, `xhigh`.
**Desktop app:**
Click the harness chip in the New task footer (**N**), pick **Copilot**, then a model and a thinking level. On a running task, the same chip in the reply box changes it for the next follow-up.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right), then the harness chip under the box. Pick **Copilot**, then a model and a thinking level. On a running task, tap the options chip in the reply bar, then the agent.
**TUI:**
Send `/runtime set-agent --agent copilot` to move the open task to Copilot.
**CLI:**
```sh
wisp "update the README badges" --agent copilot --effort medium
```
Modes: **Plan**, **Edits**, **Full auto** (`--mode plan|edits|auto`). In Edits, a tool Copilot wasn't allowed to
use shows on the task as a card with the exact rule to allow it.
## What's different with Copilot
- Copilot bills in premium requests, not dollars. Its turns count in Settings → Usage as turns and outcomes, not
spend.
- wisp gives each new conversation its id up front, so a task and its Copilot session always match.
- wisp trusts the task's folder for Copilot, so it doesn't stop to ask.
## Open in Copilot
**Desktop app:**
Open the task's **⋯** at its top right → **Open in › Open in Copilot** (key **T**). Copilot opens in a terminal in the side panel.
**Phone app:**
Open the task, then **⋯** (iPhone) or **⋮** (Android) → **This task › Open in Copilot**. Copilot's own screen opens in a terminal on the phone.
**TUI:**
Press **o** in the open task.
**CLI:**
```sh
wisp runtime resume-command
```
---
# Start with Grok
Source: https://trywisp.dev/docs/guides/agents/grok.md
wisp runs Grok Build, the `grok` command, in the background, one worktree per task, on your own xAI account.
## What you need
The `grok` command on your `PATH`. Install it from [x.ai/cli](https://x.ai/cli).
## Sign in
**Desktop app:**
Open **Settings** (the person button in the top bar, or **⌘K** → Settings) → **Agents** → **Sign in** next to Grok. Open the sign-in page and enter the code wisp shows.
Or press **Keys** and paste an xAI key.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → **Agents** → **Sign in** next to Grok. Open the sign-in page and
enter the code wisp shows. Or tap **Keys** and paste an xAI key.
**TUI:**
Send `/accounts login start grok default` and follow the link it gives.
**CLI:**
```sh
wisp accounts login start grok default
wisp accounts login status grok default
```
Or run `grok login` yourself, or set `XAI_API_KEY`.
## Pick it, its model and its effort
wisp reads `grok models` and the levels each model takes. Effort: `low`, `medium`, `high`, `xhigh`.
**Desktop app:**
Click the harness chip in the New task footer (**N**), pick **Grok**, then a model and a thinking level. On a running task, the same chip in the reply box changes it for the next follow-up.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right), then the harness chip under the box. Pick **Grok**, then a model and a thinking level. On a running task, tap the options chip in the reply bar, then the agent.
**TUI:**
Send `/runtime set-agent --agent grok` to move the open task to Grok.
**CLI:**
```sh
wisp "profile the slow import" --agent grok --effort high
```
Modes: **Plan**, **Edits**, **Full auto** (`--mode plan|edits|auto`). A run without a terminal refuses what needs
approval. wisp shows each refusal on the task as blocked.
## What wisp adds for Grok
- wisp's tools (asking you a question, and the rest) reach Grok through an agent definition wisp writes for the
run.
- Your prompt and wisp's rules go in as files, not on the command line.
## Open in Grok
**Desktop app:**
Open the task's **⋯** at its top right → **Open in › Open in Grok** (key **T**). Grok opens in a terminal in the side panel.
**Phone app:**
Open the task, then **⋯** (iPhone) or **⋮** (Android) → **This task › Open in Grok**. Grok's own screen opens in a terminal on the phone.
**TUI:**
Press **o** in the open task. Grok's own screen takes no first prompt, so wisp types it in for you.
**CLI:**
```sh
wisp runtime resume-command
```
---
# Start with Antigravity
Source: https://trywisp.dev/docs/guides/agents/antigravity.md
wisp runs the Antigravity CLI, `agy`, in the background, one worktree per task, on your own Google account.
## What you need
The `agy` command. The Antigravity app doesn't include it: install the CLI from
[antigravity.google](https://antigravity.google/docs/cli/headless/).
## Sign in
`agy` signs in the first time you run it.
**Desktop app:**
Open **Settings** (the person button in the top bar, or **⌘K** → Settings) → **Agents** → **Sign in** next to Antigravity, and finish the sign-in it opens. Or press
**Keys** and paste a Gemini key.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → **Agents** → **Sign in** next to Antigravity, and finish the
sign-in it opens. Or tap **Keys** and paste a Gemini key.
**TUI:**
Send `/accounts login start antigravity default`.
**CLI:**
```sh
wisp accounts login start antigravity default
wisp accounts login status antigravity default
```
Or run `agy` once yourself, or set `GEMINI_API_KEY`.
## Pick it, its model and its effort
wisp reads `agy models`. Effort: `low`, `medium`, `high`.
**Desktop app:**
Click the harness chip in the New task footer (**N**), pick **Antigravity**, then a model and a thinking level. On a running task, the same chip in the reply box changes it for the next follow-up.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right), then the harness chip under the box. Pick **Antigravity**, then a model and a thinking level. On a running task, tap the options chip in the reply bar, then the agent.
**TUI:**
Send `/runtime set-agent --agent antigravity` to move the open task to Antigravity.
**CLI:**
```sh
wisp "split the big component" --agent antigravity --effort medium
```
Modes: **Plan**, **Edits**, **Full auto** (`--mode plan|edits|auto`).
## What's different with Antigravity
`agy` reads MCP servers only from its own config, and takes no instructions by flag. So wisp puts its
instructions ahead of your first message, and the agent has no wisp tools in a task: when it needs you, it ends its
answer with a question block, and you answer in the reply box.
## Open in Antigravity
**Desktop app:**
Open the task's **⋯** at its top right → **Open in › Open in Antigravity** (key **T**). Antigravity opens in a terminal in the side panel.
**Phone app:**
Open the task, then **⋯** (iPhone) or **⋮** (Android) → **This task › Open in Antigravity**. Antigravity's own screen opens in a terminal on the phone.
**TUI:**
Press **o** in the open task. wisp types your prompt in for you and trusts the folder for that session.
**CLI:**
```sh
wisp runtime resume-command
```
---
# The desktop app
Source: https://trywisp.dev/docs/guides/apps/desktop-app.md
The desktop app is wisp in its own window. It is the same wisp as in the browser and on your phone: one small
local server, `wisp serve`, and one UI. The window adds what a browser tab can't do well.
## Install it
Pick the line for your computer.
| Computer | Get it |
| --- | --- |
| macOS 13.3 or later | `brew install --cask wispagents/tap/wisp`, or `curl -fsSL https://trywisp.dev/install.sh \| bash -s -- --app` |
| Windows | `wisp-windows--setup.exe` from the [latest release](https://github.com/WispAgents/wisp/releases/latest) |
| Linux | the `.AppImage` or the `.deb` from the [latest release](https://github.com/WispAgents/wisp/releases/latest) (glibc 2.35 or later) |
The release also has `SHA256SUMS.txt`, to check what you downloaded. On macOS, `--app` checks it for you and puts
wisp in your Applications folder.
Installed wisp with npm? You don't need a separate download on macOS or Windows: `wisp desktop` fetches the small
window once, checks it against the release, and opens it. On Linux it opens a browser tab for now.
## Open it
**Desktop app:**
Open **wisp** from your Applications folder, Start menu or app launcher. It starts its server and shows your tasks.
Open it again and you get the same window: there is only ever one. **⌘K** (Ctrl-K on Windows and Linux) finds any
task, command or setting.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
The phone app doesn't start wisp on a computer. Open the **Computers** tab and tap a computer that is on: you see
its tasks, live.
**TUI:**
The TUI talks to the same server. With the app open, `wisp tui` in any terminal shows the same tasks, live.
**CLI:**
```sh
wisp # opens the app (a browser tab when there's no app)
wisp desktop # always the app window
wisp --browser # a browser tab instead: http://localhost:4477
```
## What the window adds
- **A badge** on the Dock or taskbar icon with how many tasks need you.
- **System notifications** when a task finishes or asks. Click one to go straight to that task.
- **Your shell's `PATH`.** Started from the Dock or Finder, the app still finds `claude`, `codex` and the rest.
- **Links open in your browser**, and the window keeps wisp.
- **Menus and keys:** Reload (**Cmd/Ctrl-R**), zoom (**Cmd/Ctrl-=**, **-**, **0**), full screen.
- **Closing the window:** on macOS your agents keep running and the app stays in the Dock. On Windows and Linux,
closing the window quits wisp and stops its server.
## Updates
The app updates itself. When a new version is out, its top bar shows **Update to …**.
**Desktop app:**
Press **Update to …** in the top bar, or open the person button → **Settings** → **Updates**: pick a channel
(**Stable**, **Beta** or **Nightly**), **Check now**, then **Update now**. wisp restarts; running tasks are stopped,
and it says how many first.
**Phone app:**
Updating wisp on a computer is done on that computer: see the Desktop app tab.
**TUI:**
Send `/update check`, then `/update install`.
**CLI:**
```sh
wisp update # is there a newer wisp?
wisp update apply # install it
```
A Homebrew install follows stable releases only; update it with `brew upgrade`.
## Next
- [The terminal UI](../tui/)
- [The phone app](../phone-app/)
- [Run your first task](../../../start/first-task/)
---
# The phone app
Source: https://trywisp.dev/docs/guides/apps/phone-app.md
The wisp apps for iPhone and Android are not out yet. Until they are, wisp works in your phone's browser, and your
agents can reach your phone with notifications you answer from the lock screen.
## Join the waitlist
Leave your email at [trywisp.dev/app.html#phone](https://trywisp.dev/app.html#phone). It is only used to tell you
when the app is out.
## What the app will do
The app is built for each phone: Material design on Android, Apple's look on iPhone. Every wisp feature is in it.
- **Your computers, anywhere.** Sign in to wisp Cloud with **Continue with GitHub** or **Continue with Google**.
Your cloud wisp and every computer you put on the Grid show up; tap one to work there. Or add a computer over
SSH: its address and your password or key, with its host key checked by a QR code.
- **Tasks:** start one, follow it live, answer its questions, and read the report.
- **Swipe a task:** right to **Mark done**, left to **Save for later**. Each swipe also has a button. Swipe the
task's header to go to the next or previous task.
- **Crew as stories:** a row of faces at the top of Tasks. A ring shows who is working, who has a new report and
who is waiting on you. Tap a face to see their story, and reply to it.
- **Notifications** that let you answer or approve without opening the app.
## Until then: wisp in your phone's browser
Your phone needs a wisp it can reach. Pick one:
- **Your cloud wisp.** Sign in at [grid.trywisp.dev](https://grid.trywisp.dev). It runs on a server, so it works
when your laptop sleeps.
- **Your own computer, on the Grid.** Turn it on below, then open your Grid address on the phone. No SSH and no
open ports.
**Desktop app:**
On home, the tip **Reach this wisp from anywhere** has **Set up**. Or open **⌘K** → **Settings** → **Machines** →
**Reach this computer from anywhere**.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
This is switched on at the computer itself (see the Desktop app tab). Then, in the phone app, open **Computers**
and sign in to wisp Cloud with GitHub or Google: the computer shows in the list.
**TUI:**
Send `/grid-client computer --on`.
**CLI:**
```sh
wisp computer on # put this computer on your Grid (--grid : sign in there first)
wisp computer status
wisp computer off
```
On the phone, open the page and add it to your home screen. It then opens full screen, like an app. On iPhone:
**Share** → **Add to Home Screen**.
## Notifications on your phone
wisp can tell your phone when a task finishes or needs you, with buttons to answer. Set it up in avatar →
**Settings** → **Phone**. Two ways work today:
- **ntfy:** switch it on and wisp picks a long, random topic. Install the ntfy app, subscribe to the topic, and tap a
button on a notification to answer. Answers are signed, so nobody else can send them.
- **Telegram:** make a bot with @BotFather, paste its token, and send your bot the link code. Answer with buttons or
in your own words.
**Desktop app:**
Open the person button in the top bar → **Settings** → **Phone**: pick ntfy or Telegram, follow **Set it up**, then
**Send a test**.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → **Phone**, and set it up the same way.
**TUI:**
Send `/channels setup ntfy --enabled --notify asks,finished`, then `/channels test`.
**CLI:**
```sh
wisp channels setup ntfy --enabled --notify asks,finished
wisp channels status # what each channel still needs
wisp channels test --channel ntfy
```
Slack, Discord and email are in the same place; see [From Slack and Linear](../../run/from-slack-and-linear/).
---
# The terminal UI
Source: https://trywisp.dev/docs/guides/apps/tui.md
`wisp tui` is wisp full screen in your terminal. It shows the same tasks as the app, live, and does what the app
does: start tasks, follow them, answer questions, review changes. Nothing is polled; every key answers at once.
```sh
wisp tui
```
It talks to the wisp server like the app and the CLI do, and starts it if it isn't running.
## The screen
- **Tasks**, on the left, in the same sections as the app.
- **The open task:** its live transcript, step by step, with its state in the header.
- **A side pane:** the changes (**d**) or the Thread pane with the task's Notes (**t**).
- **The composer** at the bottom, and a status bar under it.
**Tab** moves between zones. **[** and **]** narrow or widen the focused one (or drag its border). The mouse works
too. Press **?** for the keys at any time.
## Keys
| Where | Keys | What it does |
| --- | --- | --- |
| Everywhere | **Ctrl-K** or **:** | Command palette: tasks, views, commands, settings |
| Everywhere | **?** | This help (**j** **k** scroll it on a small screen) |
| Everywhere | **Tab**, **Shift-Tab** | Next zone. In the composer: cycle the mode, Plan → Edits → Full auto |
| Everywhere | **g** then **c a m s , h t** | Go to crew, automations, machines, My Stuff, settings, history, tasks |
| Everywhere | **[** **]** | Narrow or widen the focused zone |
| Everywhere | **Ctrl-C**, **q** | Quit (**q** outside the composer) |
| Tasks | **j** **k**, **↑** **↓** | Move |
| Tasks | **Enter**, **l** | Open the task |
| Tasks | **n** | New task |
| Tasks | **i** | Reply to the selected task |
| Tasks | **/** | Search |
| The task | **i**, **Enter** | Write (the composer) |
| The task | **j** **k** | Move between steps |
| The task | **Space** | Open or close the step (a tool call, a diff) |
| The task | **o** | Open in its harness (Claude Code, Codex…), back here after |
| The task | **1**–**9** | Answer the question with that choice |
| The task | **y**, **a**, **n** | Allow, always allow, or deny a tool |
| The task | **Esc** | Interrupt the running turn |
| The task | **d** | The changes pane (diffs). Again: close it |
| The task | **t** | The Thread pane: the task's Notes and how worn it is. Again: close it |
| The task | **s** | Stop |
| The task | **PgUp** **PgDn**, **G** | Scroll; to the end (and follow) |
| Composer | **Enter** | Send (queued while a turn runs) |
| Composer | **Alt-Enter**, **Ctrl-J** | New line |
| Composer | **@** | Mention a task, crew member, machine, My Stuff item or file |
| Composer | **/** | A command: `/btw`, `/fork`, `/stop`, or any wisp command as `/` (`/ship ship`, `/goal set --text "…"`) |
| Composer | **↑** | History, in an empty box |
| Composer | **Ctrl-E** | Edit in `$EDITOR` |
| Composer | **Alt-↑** **Alt-↓**, **Ctrl-S** | Reorder the queued follow-up; send it now |
| Composer | **Esc** | Leave the composer (interrupts when it's empty and a turn runs) |
| Views | **j** **k** | Move |
| Views | a letter | The row's action (shown in the view's footer) |
| Views | **r** | Reload |
## The palette
**Ctrl-K** (or **:**) finds anything by name: a task, a view, a setting, or any wisp command. Commands show by
their title with the words you'd type in the CLI at the right, for example *Add a computer · machines add*.
## Commands with `/`
In the composer, any CLI command runs as `/ …`, with the same words and flags as `wisp …`. As you type, the line under the box shows how to use it.
```text
/machines add --name studio --address me@studio
/goal set --text "all tests pass"
/runtime set-mode --mode plan
```
When the command acts on a task, the open task is the one it acts on, unless you give an id. With no task open
it asks you for one.
## Views
**g** and a letter opens a view: a table over the same data as the app's screens. The footer lists the letters
for the selected row.
| View | Go | Row actions |
| --- | --- | --- |
| Crew | **g c** | **n** new member, **a** give a job, **c** check in, **w** wake, **p** pause, **u** resume, **x** remove |
| Automations | **g a** | **f** fire, **t** test |
| Machines | **g m** | **c** connect, **x** disconnect |
| My Stuff | **g s** | **l** launch, **d** remove |
| Settings | **g ,** | |
| Repo history | **g h** | |
**g t** goes back to your tasks. Plugins can add views of their own the same way.
---
# Build a software factory as code
Source: https://trywisp.dev/docs/guides/declare/software-factory-as-code.md
A **software factory** is a set of agents that turn work into pull requests without you starting each one: a
builder picks up issues, a line of stations (spec, build, checks, review, ship) carries each one to a PR, a fixer jumps
on red CI, and a nightly job keeps the dependencies fresh. In wisp the whole factory is a few files in `.wisp/`, reviewed and changed in pull
requests like the rest of your code.
Start with `wisp init` in the repo: it makes `.wisp/` with a `wisp.yml`. This guide then builds the factory step by
step, one file per part (any `*.wisp.yml` in the folder is read). Every field used here is in the [resource kinds reference](../../../reference/kinds/).
## 1. The agents
Say which harness does what, once, and refer to it everywhere else.
```yaml
# .wisp/agents.wisp.yml
wisp: 1
agents:
builder: { harness: claude, model: opus, mode: auto, skills: [house-style] }
reviewer: { harness: codex, effort: high, mode: plan, instructions: "Correctness first, then tests, then style." }
fixer: { harness: claude, mode: auto }
skills:
house-style: { description: How we write code here, path: docs/house-style.md }
```
## 2. The crew
Crew members are agents that stay, with a role and a brief. They're who the triggers below wake.
```yaml
# .wisp/crew.wisp.yml
crew:
bob:
role: builder
agent: builder
brief: "Build what an issue asks. Write the test first. Open a PR; never merge."
sandbox: job # each job in a worktree of its own
cron: "every weekday at 9" # a check-in of its own each morning
parallel: 2
ada:
role: reviewer
agent: reviewer
brief: "Review every PR the crew opens. Request changes or approve; never merge."
```
## 3. The triggers
A trigger starts work when something happens. Its `on` is any of the
[events and trigger sources](../../../reference/triggers/).
```yaml
# .wisp/triggers.wisp.yml
triggers:
build-labeled-issues:
on: issue.labeled
label: agent # an issue labeled "agent" (GitHub, Linear or Jira, through wisp.issues)
crew: bob
prompt: "Build {event.summary}"
concurrency: queue
budget: { perRun: 5, perDay: 40 }
review-crew-prs:
on: pr.opened
crew: ada
fix-red-ci:
on: ci.failed
followUp: true # a follow-up to the task whose PR failed, with the failing log
cooldown: 30m
rate: 5/h
```
`when: { days: mon tue wed thu fri, hours: "9-18" }` keeps a trigger to working hours; `approval: true` makes a job
wait for your yes before it starts.
## 4. Goals: done means done
A task with a goal is sent back after each turn until its judges agree the goal is met. Declare goals once, by
name, and point tasks at them; `default` under `goals:` and under `tasks:` gives every goal and every task its
defaults, and their own fields win.
```yaml
# .wisp/goals.wisp.yml
goals:
default: { judges: [reviewer], vote: majority, maxRounds: 6 } # every goal's defaults
green-build: { text: "npm test passes and the build is green", judges: [reviewer] }
tasks:
default: { agent: builder, mode: auto, worktree: true } # every task's defaults
fix-build: { prompt: Make the build pass, goal: green-build } # a goal by name, or inline { text: … }
```
`wisp validate` names a goal no one declared. `tasks.default` never runs on its own and holds no prompt, steps or
schedule; every run of a task (by hand, by its schedule, from a trigger's `task:`) takes it. Tasks you start another
way (`wisp "…"`, New task, a crew member's job) don't.
Attach a declared goal when you start any task:
**Desktop app:**
**New task** → **+** → **Goal…** lists the declared goals by name; pick one, or **New goal…** to write your own.
**Phone app:**
**New task** → **+** → **Goal…**, then a goal by name or **New goal…**.
**TUI:**
From any reply box (**i**): `wisp "Make the build pass" --goal green-build`; on an open task, `/goal set green-build`.
**CLI:**
```sh
wisp "Make the build pass" --goal green-build
wisp goal set green-build
```
Your own agent does the same with `wisp_launch`'s `goal`. More in [Goals and judges](../../run/goals/).
## 5. The line every task goes through
A **factory** puts a task through stations instead of one agent: a spec you approve, a build in its own worktree,
checks that are commands, a review, and a PR you merge. A failed check or review goes back to the build with what
failed, up to a limit, then asks you. Declare the line once and point tasks at it.
```yaml
# .wisp/factories.wisp.yml
factories:
default: # replaces the built-in default
stations:
spec: { agent: builder, approve: human }
build: { agent: builder, worktree: true }
checks: { run: [npm test, npm run lint] }
review: { agents: [reviewer], vote: majority }
ship: { pr: true, merge: human }
loop: { back_to: build, max: 3, then: ask }
tasks:
ship-fix: { prompt: Fix the failing test, factory: default } # or `factory:` under tasks.default: every task
triggers:
build-labeled-issues-through-the-line:
on: issue.labeled
label: factory
prompt: "Build {event.summary}"
factory: default
```
Start any task through it with `wisp "…" --factory`, **Factory** in New task's picker, or `wisp_launch`'s `factory`.
More in [Run a task through a software factory](../../run/software-factory/).
## 6. A nightly workflow
A workflow is steps with dependencies, run by hand (`wisp run nightly`) or by a trigger.
```yaml
# .wisp/nightly.wisp.yml
triggers:
every-night: { on: schedule, cron: "every day at 2", workflow: nightly }
workflows:
nightly:
budget: { usd: 20 }
tasks:
deps: { agent: builder, prompt: "Update the dependencies that have patch releases. Run the tests." }
audit: { agent: reviewer, needs: [deps], prompt: "Review the dependency update: ${{ tasks.deps.output }}" }
```
## 7. Guardrails
```yaml
# .wisp/budget.wisp.yml
budget: { stopAt: "75", taskUsd: 10 } # automations stop at 75% of a usage window; $10 at most per task
```
Settings → Agents → Usage also has *Stop a run silent for*, which stops a run that sits with no output.
## 8. Check it, then turn it on
**Desktop app:**
**⌘K** → **Settings** → Advanced → **Setup** → **Import**. Paste a formula and press **See what it changes**: what
it adds, changes and removes, and the secrets it needs. Then **Apply**. A repo's `.wisp/` folder is read by the CLI
(CLI tab).
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Writing and reading a whole formula is a job for a computer: use the Desktop app tab. The phone's Settings →
Advanced → **Setup** → **Import** works the same if you have a formula to paste.
**TUI:**
Run the CLI commands (next tab) in a terminal. Then **g c** shows the crew and **g a** the triggers that came in.
**CLI:**
```sh
wisp validate # the schema and the references
wisp plan # what will change
wisp apply # turn it on
wisp graph # what refers to what, as Graphviz
```
Commit `.wisp/`. Anyone who clones the repo and runs `wisp apply` gets the same factory. Change it the way you
change code: a branch, a pull request, a review.
## Watch it run
**Desktop app:**
Each job is a task in the list, with the member's face on it. Click a member in the crew rail on the far left for
their jobs, or **Org** at the bottom of the rail for who hands work to whom. **⌘K** → **Settings** → Agents →
**Automations** lists the triggers and when they last ran.
**Phone app:**
Each job is a task in **Tasks**, with the member's face on it. The **Crew** tab lists the members: tap one for their
jobs, or **Org** for who hands work to whom. The person button at the top of **Tasks** → **Automations** lists the
triggers.
**TUI:**
**g c** for the crew, **g a** for the triggers (**t** tests one without starting anything), **g t** for the tasks.
**CLI:**
```sh
wisp ls --crew bob # one member's jobs
wisp ls --workflow nightly # a workflow's runs
wisp automations trigger log fix-red-ci
```
In a repo that [keeps its history](../../track/track-agent-work/), every job is saved next to the code it wrote.
More on the parts: [Crew and check-ins](../../run/crew-and-check-ins/),
[Automations, schedules and triggers](../../run/schedules-and-triggers/), [Goals and judges](../../run/goals/).
---
# Share skills, AGENTS.md and MCP servers with your team
Source: https://trywisp.dev/docs/guides/declare/share-skills-and-mcps.md
Your team wants every agent, on every harness, on every laptop, to know the same things: how you test, how you name
things, which MCP servers to use. wisp keeps that in your repo, so it's reviewed like code and everyone gets it with
`git pull`. There are three parts: **rules** (`AGENTS.md` and instructions), **skills**, and **MCP servers**.
## Rules: AGENTS.md
Claude Code, Codex, Cursor, opencode and the others read `AGENTS.md` at the root of the repo. Keep your house rules
there and commit it. Claude Code reads `CLAUDE.md` instead: make it one line, `@AGENTS.md`, so both read the same
file. A folder deeper in the repo can have its own `AGENTS.md` for the rules of that part.
`wisp init` adds one short section to `AGENTS.md` (and to `CLAUDE.md` when there is one): it tells agents how to read
the tasks behind the code (`wisp tasks --touching `). It adds it once, and only beside `.wisp/`.
Rules that only some agents follow go on the agent profile, or on the project:
```yaml
agents:
reviewer: { harness: codex, mode: plan, instructions: "Review only. Never change files. Correctness first." }
projects:
api: { path: https://github.com/acme/api, instructions: "Every endpoint gets a test in tests/api." }
```
A crew member has its own `AGENTS.md` in its kit, followed on every job. See
[Crew and check-ins](../../run/crew-and-check-ins/).
## Skills
A **skill** is a how-to an agent picks up when it needs it: "how we write migrations", "how to release". Write it as
a markdown file, or a folder with a `SKILL.md`, then declare it and give it to the agents that need it.
```yaml
# .wisp/skills.wisp.yml
wisp: 1
skills:
migrations: { description: How we write and test database migrations, path: docs/skills/migrations.md }
release: { description: How to cut a release, path: .wisp/skills/release }
agents:
builder: { harness: claude, skills: [migrations, release] }
helper: { harness: codex, skills: [migrations] }
```
A relative `path` is the repo's. The `description` is what an agent reads to decide whether to use a skill, so say
what it's for. A short skill can be inline, with `body:` instead of `path:`. Each task records which skills it had
and which it used. To see whether a skill helps, run the task with and without it:
[Try it two ways](../../run/compare-and-try/).
## MCP servers
Declare an MCP server once as a **connector**. Every agent that should have it gets it, on every harness.
```yaml
# .wisp/connectors.wisp.yml
wisp: 1
connectors:
linear: { url: "https://mcp.linear.app/sse", oauth: true }
postgres:
command: npx
args: ["-y", "@modelcontextprotocol/server-postgres"]
env: { DATABASE_URL: "${secret:DB_URL}" }
agents: [builder] # only these agent profiles get it
modes: [plan, edits] # and only in these modes
```
**Secrets never go in the file.** `${secret:NAME}` names one; each person sets the value on their own computer:
**Desktop app:**
**⌘K** → **Settings** → Agents → **Connectors**. A connector that needs a key or a sign-in says so; **Sign in**
opens the server's page for an `oauth: true` server. The token stays in your secrets file.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → Agents → **Connectors**. A connector that needs a
sign-in says so; **Sign in** opens the server's page. A key is easier to paste from the Desktop app tab.
**TUI:**
Secrets are typed hidden, so set them from a terminal (CLI tab). Then check the server:
```text
/connectors list
```
**CLI:**
```sh
wisp secret set DB_URL # typed, not shown
printf %s "$DB_URL" | wisp secret set DB_URL
wisp validate # says which secrets aren't set here yet
```
## Already have MCP servers?
The MCP servers in Claude Code's or Codex's own config can come in as connectors, so every harness gets them.
**Desktop app:**
**⌘K** → **Settings** → Agents → **Connectors** → **Found in your harnesses** → **Review**, tick them, and **Add**.
**Phone app:**
Person button → **Settings** → Agents → **Connectors** → **Found in your harnesses** → **Review**, tick them, and
**Add**.
**TUI:**
```text
/connectors import --names linear,sentry
```
**CLI:**
```sh
wisp connectors list # yours, and the ones found in your harnesses
wisp connectors import --names linear,sentry
wisp export connectors > .wisp/connectors.wisp.yml # as a formula to commit
```
## Many repos: modules
Put the shared setup in its own repo (`acme/wisp-setup`) and use it everywhere as a module:
```yml
# .wisp/team.wisp.yml in each repo
modules:
team: { source: "git::https://github.com/acme/wisp-setup//team?ref=v3" }
```
`wisp init` fetches it and pins it in `.wisp/lock.yml`. Moving to `?ref=v4` is one pull request per repo, reviewed
like any other change. See [Formulas](../../../concepts/formulas/).
## Without git: share through wisp Cloud
```sh
wisp share skill.migrations # a link: the skill and what it references
wisp share connector.linear --access people:ana,ben
wisp open # the other side: see what it adds, then import it
```
A shared setup never carries a secret: it names the ones it needs, and whoever imports it sets their own. In the
app, Settings → Advanced → **Setup** → **Share setup** makes the same formula to copy.
---
# Run a task under a formula, and reference everything by name
Source: https://trywisp.dev/docs/guides/declare/run-under-a-formula.md
A formula declares things once, each with a name: agents, skills, connectors, goals, tasks. Everything else names
them. You can run one task under a formula without applying it (nothing is left behind), and every name a task gives
is checked first, with what there is when it names nothing.
```yaml
# review.wisp.yml
wisp: 1
variables:
model: { type: string, default: opus }
agents:
critic: { harness: claude, model: "${var.model}", instructions: Be strict about tests }
goals:
green: { text: npm test passes }
tasks:
release: { prompt: "Release {version}: changelog, bump, tag", agent: "${agent.critic}", goal: green }
```
`agent: "${agent.critic}"` and `agent: critic` are the same: a field that names a thing takes its name or a reference,
and an agent field also takes a harness (`codex`) or `auto`.
## Try a setup on one task
**Desktop app:**
In **New task**, press **+** → **Formula or task file…** and pick `review.wisp.yml`. It shows as a **Formula:** chip
by the prompt; the task you send runs under it (its agents, skills, connectors and goals are that task's), and **✕**
on the chip takes it off. Pick a task file instead and its prompt, agent and goal fill New task. A name the file gives
that names nothing is said in a toast, with what there is, and nothing is attached.
**Phone app:**
The phone's New task doesn't pick files. Apply the formula from a computer (CLI tab), then pick its agent and goal by
name on the phone: **Goal…** lists the declared goals.
**TUI:**
The TUI's New task doesn't pick a formula yet: start it from a terminal (CLI tab) and it shows in the TUI's list like
any task.
**CLI:**
```sh
wisp "review the diff" --formula review.wisp.yml # its one agent runs it
wisp "review the diff" --formula review.wisp.yml,team.yml --agent critic
wisp run release --formula review.wisp.yml version=2.1 # the task it declares, by its name
```
From your harness, `wisp_launch` takes the same: `{ "prompt": "…", "formula": "review.wisp.yml" }`.
## Task files that point at your formula
`wisp task export > fix.task.yml` writes what a task was asked. Instead of the copy of the setup it carries,
point it at your formula: a file beside it, a module of the folder's `.wisp/`, or a list of them.
```yml
wisp: 1
task: { prompt: Fix the flaky login test, agent: critic, goal: green }
formula: [./review.wisp.yml, module.team]
```
```sh
wisp run -f fix.task.yml
```
Its agent, goal, connectors, crew member, team and project are read against those files and what this wisp has. One
that names nothing stops it before anything runs:
```text
✗ fix.task.yml: no agent named critc: agents has critic (or claude, codex, auto)
```
A file named twice, or the task file itself, is refused too.
## Checked before anything runs
`wisp validate` (and `wisp apply`, Setup → Import, a grid deploy) checks every name in every kind: a trigger's
`task:`, a crew member's `agent:` and who they delegate to, a notification's channel, a connector's agents, a setting
such as `channels.project`. A loop of delegations (`ada` → `bo` → `ada`) is refused, and so is taking away something
another thing still names. The [formulas page](../../../concepts/formulas/) has the details.
---
# Run a task and follow up
Source: https://trywisp.dev/docs/guides/run/run-and-follow-up.md
A task is one ask to one agent, in your project. This guide covers the loop you use every day: start it, follow it,
send follow-ups, and stop it when it goes the wrong way.
## Start a task
**Desktop app:**
Press **New task** (**N** or **⌘L**), type what you want and press **Enter**. Above the box, pick the project. In the
footer, pick the mode (Plan, Edits or Full auto), the harness and model, and where it runs (**This computer** or
another machine). The **+** button adds files, a goal, delegates, a second agent to compare, or a later start.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right), type the task and tap **Send**. The chips under
the box pick the project, the mode, the harness and model, and where it runs. **+** adds files.
**TUI:**
Run `wisp tui` and press **n**. Type the task and press **Enter**. **Tab** cycles the mode: plan, edits, auto.
Type `@` to bring in a file, a crew member or a machine.
**CLI:**
```sh
wisp "add a dark mode toggle" # in the repo: starts it and follows it
wisp "add a dark mode toggle" -d --json # starts it and prints its id at once
wisp "fix the flaky test" --agent codex --model gpt-5 --effort high --mode edits
wisp "run the full test suite" --on studio # on another machine
```
Other options: `--cwd DIR`, `--also DIR` (a second folder the agent may use), `--no-worktree` (work in the
project folder itself), `--wait` (block until it ends).
Each task runs in its own git worktree by default, so tasks never step on each other. See
[Worktrees and shipping a PR](../worktrees-and-shipping/).
## Watch it
**Desktop app:**
The task page shows what the agent does, step by step, then its answer as cards: a summary, the diff, the tests.
The list on the left says which tasks work, which need you and which are done. **J** and **K** move to the next and
previous task; **V** opens the full transcript.
**Phone app:**
Tap a task in **Tasks**. It shows the steps live, then the answer. The pills under the title (*Changes +n −n*,
the PR) open the changes and the PR as a sheet. **⋯** (iPhone) or **⋮** (Android) → **Show ›** has the full transcript.
**TUI:**
Press **Enter** on a task to open it. **j** and **k** move between steps, **Space** opens one, **G** follows the
end. **d** opens the changes pane.
**CLI:**
```sh
wisp ls --state running,waiting
wisp attach # live: its steps, its answer, its questions; then a reply box
wisp wait # block until it finishes or asks you something
wisp show # the latest answer as markdown
```
In `wisp attach`, **Ctrl-C** detaches; a second **Ctrl-C** stops the task. `last` works as `` for your newest
task.
## Follow up
**Desktop app:**
Press **/** to jump to the reply box under the answer, type, and press **Enter**. While the agent works, the
**Queue** button decides what a follow-up does: it waits for the turn to end, or it interrupts now. Queued
follow-ups show above the box. Drag them to change the order, edit them, **Combine with the next one**, or
**Send now**.
To ask something without stopping the run, open the task's **⋯** at its top right → **Task options ›
Side discussion…**, or type `/btw is this safe?`. The answer shows beside the run, and the run carries on.
**Phone app:**
Type in the reply bar and tap **Send**. The options chip in the reply bar has **Queue** (send it after this
turn) and **Send later**. To ask on the side without stopping the run, type `/btw is this safe?`.
**TUI:**
Press **i**, type and press **Enter**. While a turn runs, the follow-up is queued. **Alt-↑** and **Alt-↓**
reorder the last queued one; **Ctrl-S** sends it now. Ask on the side with:
```text
/btw is this safe?
```
**CLI:**
```sh
wisp reply "also add a test" # interrupts the turn and sends now
wisp reply --queue "then update the docs"
wisp reply --agent codex "review what you did" # another harness from here on
wisp btw "is this safe?" # answers on the side, the run goes on
```
You can also schedule a follow-up for later: **Start later** in the **+** menu, or
`wisp later add --text "check the deploy" --in 60` (minutes).
## Stop it
**Desktop app:**
Press **Stop** in the reply box while it works, and confirm. Queued follow-ups stay, held until you send one.
**Phone app:**
Tap **Stop** in the reply bar while it works, and confirm. Queued follow-ups stay, held until you send one.
**TUI:**
**Esc** interrupts the running turn. **s** stops the task. Or send `/stop`.
**CLI:**
```sh
wisp stop
```
## A held turn
wisp holds a turn before it starts when something needs your yes: the repo asks to run its own programs (hooks,
MCP servers, a worktree setup script), the harness changed since wisp last ran it, or the turn would push a usage
window past your line (see [Budgets and usage](../budgets-and-usage/)). The task shows **Held** and says why.
**Desktop app:**
The held card has **Trust and start**, **Run without them** (without the repo's own programs) and
**Skip this run**. A turn held for a usage window offers **Start now** or **Wait**.
**Phone app:**
The held card shows in the task with the same buttons: **Trust and start**, **Run without them** and
**Skip this run**, or **Start now** and **Wait** for a usage window.
**TUI:**
With the task open, send `/runtime held --action start` (or `without`, or `skip`).
**CLI:**
```sh
wisp held start # or: without, skip
```
## Carry on yourself
To take the conversation into the harness's own window, open the task's **⋯** menu, **Open in** (in the TUI, **o**).
When you come back, wisp picks the task up where you left it.
---
# Compare agents and try it two ways
Source: https://trywisp.dev/docs/guides/run/compare-and-try.md
Not sure which agent does a job best? Give the same ask to several of them and see. **Compare** runs one task on
several harnesses at once. **Try it two ways** runs it twice on one harness with one thing changed, so you learn
what that thing is worth.
Every run gets its own task and its own worktree, so the runs never touch each other.
## Compare harnesses
**Desktop app:**
1. Press **N** for **New task**, and type the task.
2. Press **+**, then **Compare with another agent…**. A second harness joins the one you picked. Add more the same
way, or remove one with its **×**.
3. Press **Enter**. One task per harness starts, grouped in the list under **Compare**.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
1. Tap the compose button at the top right (iPhone) or **New task** (Android), and write the task.
2. Tap **⋯** (More options), then **Compare with another agent…**. A second harness joins the one you picked.
3. Start it. One task per harness starts, grouped in the list under **Compare**.
**TUI:**
Start the runs from the CLI (next tab). Each run is a task in the TUI's list, and opens like any other task.
**CLI:**
```sh
wisp "make the list query fast" --compare claude,codex
wisp "make the list query fast" --agent claude --model opus --compare codex:gpt-5,opencode
```
`--compare` takes `harness[:model]`, comma separated. `--agent` (with its `--model`) is the first run.
## Try it two ways
Same harness, same model, same ask. Run B changes one thing:
- **Subagents:** the subagents run on Haiku, Sonnet, or the task's own model.
- **Skills:** off. No skills or slash commands; plugins, agents and `CLAUDE.md` stay.
**Desktop app:**
1. In **New task**, press **+**, then **Compare with another agent…**.
2. Pick the **same** harness for the second run. Its picker then shows **What's different**.
3. Pick what run B changes (**Subagents** or **Skills**) and press **Enter**.
**Phone app:**
1. In New task, tap **⋯** (More options), then **Compare with another agent…**.
2. Pick the **same** harness for the second run. Its picker then shows **What's different**.
3. Pick what run B changes (**Subagents** or **Skills**) and start it.
**TUI:**
Start the pair from the CLI (next tab). Both runs show in the TUI's list.
**CLI:**
```sh
wisp "add pagination to /users" --agent claude --try skills=off
wisp "add pagination to /users" --agent claude --try subagents=haiku
```
`--try` needs `--agent`, edits (not Plan) and a worktree. It can't go with `--compare`.
## Read the comparison
**Desktop app:**
Open any run, then **⋯** at the task's top right → **Compare runs**, or open the **Compare** group in the list. Each
run is a column: time, cost, tokens, agent steps, files, tests, and how much of your plan it took. A line on top says
what differed ("used 30% fewer tokens and took 2 min less than A"). One run each is noisy, so it tells you that
too.
**Phone app:**
Open any run, then **⋯** (iPhone) or **⋮** (Android) in its top bar → **Show › Compare runs**. You get the same
numbers per run, and the line that says what differed.
**TUI:**
Open each run with **Enter** and press **d** for its changes.
**CLI:**
```sh
wisp ls --state done
wisp show # each run's answer
wisp usage # what each task took
```
## Keep one
Keeping a run archives the others. Their worktrees are deleted with their changes, so ship nothing from them first.
**Desktop app:**
In Compare, press **Keep this** under the run you want, then **Keep this one**. wisp opens the kept run; ship it
when you're ready.
**Phone app:**
In Compare, tap **Keep this** under the run you want, then **Keep this one**. wisp opens the kept run.
**TUI:**
Open the run you want. For a *Try it two ways* pair, send:
```text
/runtime trial keep
```
For a compare, open each run you don't want and send `/runtime archive --archived`.
**CLI:**
```sh
wisp runtime trial keep # a Try it two ways run: the other is archived
wisp runtime archive --archived # a compare: archive each run you don't keep
```
## When to use which
- **Compare** to choose a harness or a model for a kind of work.
- **Try it two ways** to check a setting: are your skills helping, or do cheaper subagents do as well?
- To have one agent **check** another's work instead, see [Review by another agent](../review-by-another-agent/).
---
# Run a task through a software factory
Source: https://trywisp.dev/docs/guides/run/software-factory.md
A [factory](../../../concepts/factories/) runs a task through stations instead of one agent: a spec you approve, a
build in its own worktree, checks that are commands, a review, and a PR you merge. A failed check or review goes back
to the build with what failed, up to a limit. `default` works with no setup.
## 1. Start a task through a factory
**Desktop app:**
In **New task** (**N**), open the harness pill under the box. The last row is **Factory**: its pane lists the
factories by name, **default** first, with their stations. Pick one, write the task and send. Any other row is one
agent, as before.
**Phone app:**
Tap **New task**, then the harness pill. The row of harnesses ends with **Factory**; pick a factory in the list under
it, write the task and tap Send.
**TUI:**
Run `wisp tui` and start it from any reply box (**i**) as a command: `wisp "Fix the add bug" --factory`. The run's
task shows its stations in its header: `default: ✓ spec · ● build · ○ checks · ○ review · ○ ship`.
**CLI:**
```sh
wisp "Fix the add bug" --factory # the built-in default
wisp "Fix the add bug" --factory careful # a factory you declared
wisp run fix-issue --factory careful # a declared task, through a factory
```
`--factory` with `--compare` is refused: a factory compares builders with `stations.build.agents`.
Your own agent starts one with `wisp_launch`'s `factory` (in `wisp mcp` and in a task's own MCP server). A run an agent
starts never runs a station above its own mode and never merges without you.
## 2. Approve the spec
The spec station writes the spec without changing a file, then the run waits on you. The question card under the
task says **Approve the spec?**: **Approve** builds it, **Stop** ends the run, and anything you type instead is what to
change. The spec is written again and you're asked again.
**Desktop app:**
Press **Approve** on the card, or type what to change in the reply box. The band over the task shows the spec's first
lines; **⋯ → Open Spec** opens the spec station's task to read all of it.
**Phone app:**
The run's task shows the band and the card; tap **Approve**. A notification says when the run waits on you.
**TUI:**
Open the task (**Enter**); the question is under it. Answer with **i** and `Approve`, or your words.
**CLI:**
```sh
wisp show # the stations, and the question it asks
wisp reply Approve # or what to change
```
## 3. Follow the build, the checks and the review
The band shows each station as a step: done, running, waiting on you, failed. When a check fails, the band says which
command and its last lines, the build gets them as round 2 (**Build · round 2 of 3**), and the checks run again. A
review that asks for changes goes back the same way. Past the limit the run asks **Keep going?**: **One more round**,
**Stop**, or your words as what to try next.
The checks run the built code in the build's worktree, without wisp's own variables, tokens, secrets or harness keys,
and what they print is masked as a task's `.env` values are. If the build didn't run in Full auto (its commands needed
your yes), the run asks first: **Run `npm test` on the built code?** with **Run**, **Skip** or **Stop**.
**⋯ → Open Build** (or any station) opens that station's task: its transcript, its diff, its worktree. You can't
follow up the run's own task: it has no agent of its own; follow up a station's task instead. **⋯ → Stop the run**
stops its stations and kills a check that's running. If wisp restarts meanwhile, the run picks up where it was.
## 4. Merge
The ship station opens the PR from the build's worktree, with the spec, the checks and the review in its body. The run
asks **Merge it?**: **Merge** squash-merges it, **Leave it open** ends the run with the PR open. `merge: auto` merges
without asking; `merge: none` never merges.
## 5. Make your own factory
Declare it in a formula (`.wisp/factories.wisp.yml`, or any formula), then `wisp apply`, or run a task under the
formula without applying it (`wisp "…" --factory careful --formula f.yml`, a task file's `formula:`).
```yaml
agents:
planner: { harness: claude, mode: plan, instructions: "Write the spec: what changes, and how we'll know it works." }
reviewer: { harness: codex, mode: plan, instructions: "Correctness first, then tests." }
critic: { harness: claude, mode: plan, instructions: "Look for what the others missed." }
factories:
careful:
description: Two builders, lint and tests, two reviewers
stations:
spec: { agent: planner, approve: human } # approve: none to skip your yes
build: { agents: [claude, codex] } # the first whose checks pass goes on
checks: { run: [npm test, npm run lint] } # none: the project's test command
review: { agents: [reviewer, critic], vote: all }
ship: { pr: true, merge: human }
loop: { back_to: build, max: 3, then: ask } # back_to: spec revises the spec instead
budget: { usd: 20 } # no new station once spent
tasks:
default: { factory: careful } # every declared task's run goes through it
```
`wisp validate` names a factory or a station's agent that names nothing, and an unknown station. A goal on the task
is what the spec and every reviewer judge against; a declared goal's judges review when the review names none.
---
# Worktrees and shipping a PR
Source: https://trywisp.dev/docs/guides/run/worktrees-and-shipping.md
Each task works in a **worktree**: its own branch in its own folder, made from your repo. Ten agents can work at once
and never collide, and your own checkout stays as you left it. When the work is good, wisp commits it, pushes it and
opens the pull request.
## Worktree or in place
New tasks get a worktree by default. To work in the project folder itself:
**Desktop app:**
In **New task** (**N**), click **This computer · Worktree** in the footer and switch it to work in place. The
choice is kept for your next tasks. Settings → General → **Worktree per task** sets the default.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap **New task** (on iPhone, the compose button at the top right), then the **This computer · Worktree** chip,
and switch it to work in place. The person button at the top of **Tasks** → **Settings** → **General** →
**Worktree per task** sets the default.
**TUI:**
Press **g** then **,** for settings and find `worktrees.worktree`, or send `/settings set --key worktrees.worktree --value off`.
**CLI:**
```sh
wisp "fix the typo in the README" --no-worktree
wisp settings set worktrees.worktree off # the default for every new task
```
A project can say how its worktrees work: commands to run in a new one, files to copy in, and what to do when a task
is done.
```yaml
projects:
api:
path: https://github.com/acme/api # or the folder's absolute path
setup: ["npm ci"]
worktree:
include: [".env"] # untracked files copied into each worktree
onDone: remove-clean # ask | remove-clean | keep
cleanupDays: 7
fixConflicts: true # an agent resolves PR conflicts by itself
```
The first time a repo asks to run its own setup, wisp holds the turn and asks you
(see [A held turn](../run-and-follow-up/#a-held-turn)).
## Read the changes
**Desktop app:**
Open the side panel (**]**) on its **Changes** tab, or press **D**: every file the task changed, with `+` and `−`
counts against the base branch. Comments you leave on lines go to the agent when you send them.
**Phone app:**
Tap the **Changes** pill under the task's title (*Changes +n −n*). The changes open as a sheet, file by file.
**TUI:**
With the task open, press **d** for the changes pane. Press **d** again to close it.
**CLI:**
```sh
wisp show # the answer, with its diff
wisp ship view --session # each repo's branch, its changes and what would ship
```
## Ship it
Shipping commits what's uncommitted, pushes the branch and opens a pull request (or pushes to the one it has).
**Desktop app:**
Press **Ship** at the top of the task (**S**). Check the title and description (**Write it with …** has the agent
write them), tick **Open as a draft** if you want, then **Commit & open PR**.
**Phone app:**
Open **⋯** (iPhone) or **⋮** (Android) in the task's top bar → **Ship it…**. Check the title and description, tick
**Open as a draft** if you want, then **Commit & open PR**.
**TUI:**
With the task open, press **i** and send:
```text
/ship ship --session --title "Add a rate limit to /login"
```
**CLI:**
```sh
wisp ship # commit, push, open the PR
wisp ship --draft
```
## Checks, reviews and conflicts
The **PR** tab follows the pull request: its checks, its reviews and comments, and whether it can merge. wisp
checks GitHub every minute.
- **A failing check:** **Ask to fix** puts the check's name and the end of its log in the reply box. Read it, then
send.
- **A review comment:** it lands in the reply box the same way, to send to the agent.
- **Conflicts with the base branch:** **Fix conflicts** sends the task a follow-up to merge its base in and push.
With Settings → General → **Auto-fix PR conflicts** on, it does that by itself.
**Desktop app:**
Side panel → **PR** (or press **P**). The same buttons show on the PR strip at the top of the task.
**Phone app:**
Tap the PR pill under the task's title. The sheet's **PR** tab has the same buttons.
**TUI:**
```text
/ship details --session
/ship fix-conflicts --session
```
**CLI:**
```sh
wisp ship details --session # every PR of the task, checks and reviews included
wisp ship fix-conflicts --session
```
## Merge
Merging squash-merges the PR on GitHub, fast-forwards your local base branch, and removes the worktree unless it
holds uncommitted work.
**Desktop app:**
**PR** tab → **Merge**, then **Merge PR**. If checks fail or no other harness reviewed it, wisp says so first;
**Merge anyway** goes ahead.
**Phone app:**
On the PR sheet: **Merge**, then **Merge PR**. If checks fail or no other harness reviewed it, wisp says so
first; **Merge anyway** goes ahead.
**TUI:**
```text
/ship merge --session
```
**CLI:**
```sh
wisp merge
```
## Tidy up
Finished worktrees are cleaned up after a while. A worktree that holds work is never removed without your yes.
**Desktop app:**
Settings → Computers → **Worktrees** lists them, with how much room they take. On a task, **⋯** at its top right →
**Task options › Keep worktree** keeps it out of the cleanup.
**Phone app:**
On a task, **⋯** (iPhone) or **⋮** (Android) → **Keep and copy › Keep worktree** keeps it out of the cleanup. The person
button at the top of **Tasks** → **Settings** → **Worktrees** lists them all.
**TUI:**
Send `/worktrees keep --id --keep true`.
**CLI:**
```sh
wisp worktrees view # the worktrees on disk
wisp worktrees keep --id --keep true
wisp worktrees sweep # tidy idle worktrees now
wisp settings set worktrees.onDone ask # when a task is done: ask, remove or keep
```
Before you merge, you can have another harness read the diff: see [Review by another agent](../review-by-another-agent/).
---
# Goals and judges
Source: https://trywisp.dev/docs/guides/run/goals.md
Agents often stop before the work is done. A **goal** fixes that. After each turn, one or more **judges** read the
code and the answer, and vote. If the goal isn't met, the task gets another turn with what is missing.
## Set a goal
Write what *done* means, in one line you could check yourself: "all tests pass and the build is green".
**Desktop app:**
- **New task** (**N**): type `/goal all tests pass` in the box and press **Enter**. A *Done when* line holds the
goal; the task keeps going until it holds.
- **A task that is already running:** type `/goal all tests pass` in its reply box, or open **⋯** at the top right of
the task, then **Task options › Set goal…**.
- The **Goal** band at the top of the task shows the round, each judge's vote and why.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
- **A new task:** tap **New task**, write `/goal all tests pass`, and send.
- **A running task:** open it, type `/goal all tests pass` in the reply bar, or tap the options chip in the reply bar
and choose **Goal**.
- **⋯** (iPhone) or **⋮** (Android) in the task's top bar → **This task › Set goal…** works too.
**TUI:**
Run `wisp tui`, open the task (**Enter**), press **i** to write, and send `/goal set --text "all tests pass"`.
The goal shows in the task's header, in its colour: working, checking, met or stopped.
**CLI:**
```sh
wisp goal set "all tests pass"
wisp goal set "all tests pass" --kick # judge it now if the task isn't running
```
`` is the task's id (`wisp ls` lists them). An empty goal clears it.
## Pick the judges
By default the task's own agent checks its work. For a second opinion, add judges: other harnesses, other models,
or crew members. A judge on a different harness doesn't share the agent's blind spots.
How their votes count:
- **Majority:** most judges agree.
- **All:** every judge agrees.
- **Any:** one is enough.
**Desktop app:**
On **New task**, **Judges** sits at the end of the *Done when* line. On a running task, open **⋯ → Task options ›
Goal checks…**, then **Judges** → **Add judge**, and pick how they vote. Your choice is kept for your next goals.
**Phone app:**
Open the task, then **⋯** / **⋮** → **This task › Goal checks…** → **Judges** → **Add judge**, and pick how they vote.
**TUI:**
With the task open, press **i** and send:
```text
/goal set --text "all tests pass" --judges codex,claude/opus/high --vote all
```
Any `wisp` command works this way in the TUI's reply box; the open task is the one it acts on.
**CLI:**
```sh
wisp goal set "all tests pass" --judges codex,claude/opus/high --vote all
```
A judge is a harness (`codex`), a harness with its model and effort (`claude/opus/high`), or a crew member by name.
`--judges ""` means no judges: wisp's own quick check decides.
In a formula, `goals.default` holds every goal's judges, vote and round limit (see below).
## Declare goals by name
Write a goal once and use it by name: from a task in a formula, from the command line, from your agent, or from the
app. `goals.default` is what every goal takes when it doesn't say (its judges, how they vote, its round limit); a
goal's own fields win.
```yaml
# .wisp/goals.wisp.yml
agents:
reviewer: { harness: codex, effort: high, mode: plan } # judges are agents by name, or harnesses
goals:
default: { judges: [reviewer], vote: majority, maxRounds: 6 } # every goal's defaults
green-build: { text: "npm test passes and the build is green", judges: [reviewer, codex] }
docs-clean: { text: "the docs build with no broken links" }
tasks:
fix-build: { prompt: Make the build pass, goal: green-build } # a goal by name
tidy: { prompt: Tidy up the code, goal: { text: "the linter is quiet" } } # or inline
```
`wisp validate` names a goal that isn't declared (`tasks.fix-build: no goal named green-buld: goals has docs-clean,
green-build`), before anything runs. `default` is never a goal of its own, and has no text. A task gets the goal as
it is declared when the task starts.
**Desktop app:**
On **New task**, open **+** → **Goal…**: the declared goals are listed by name, each with what done means, then
**New goal…** to write your own. A declared goal fills the *Done when* line and the chip says its name
(**Goal: green-build**); change the words and it's your own goal instead. In a task's reply box, **+** → **Goal…**
sets one on the task the same way.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap **New task**, then **+** → **Goal…** and pick a declared goal by name, or **New goal…**. In a task, the reply
bar's **+** → **Goal…** does the same.
**TUI:**
Start a task with a declared goal by sending `wisp "Make the build pass" --goal green-build` from any reply box
(**i**). On the open task, send `/goal set green-build`: a declared goal's name is that goal.
**CLI:**
```sh
wisp "Make the build pass" --goal green-build # a declared goal, by name
wisp "Fix the flaky test" --goal-text "the test passes 50 times in a row" # or in words
wisp goal set green-build # on a task already started
wisp goal declared # the goals declared here
```
`--goal` with a name no goal has is refused, and says which goals there are.
## While it runs
**Desktop app:**
The task's **Goal** band has **Pause goal**, **Resume goal**, **Edit goal…** and **Drop goal**. **Why** shows
what each judge said.
**Phone app:**
Tap the **Goal** band at the top of the task for **Pause goal**, **Resume goal**, **Edit goal…** and **Drop goal**.
**TUI:**
With the task open, send `/goal pause`, `/goal resume`, `/goal check` or `/goal drop`. **Ctrl-K** finds any of
them by name.
**CLI:**
```sh
wisp goal check # judge now, on the last answer
wisp goal pause
wisp goal resume
wisp goal drop
```
When the goal runs out of rounds without being met, the task stops and asks you what to do. A judge can also say
the goal **can't be done**, with why, so you don't burn rounds on it.
## Act on the result
`goal.met` and `goal.failed` are events. A [trigger](../schedules-and-triggers/) can act on them: ship the pull
request when the goal is met, or tell a crew member when it isn't.
## From your own agent
Your harness can set goals too, through wisp's MCP tools (see [MCP from your harness](../mcp-from-your-harness/)).
Ask it: "start a wisp task to fix the flaky test, with the goal *the test passes 50 times in a row*", or "… with the
goal green-build": `wisp_launch`'s `goal` takes a declared goal's name or words.
---
# Review by another agent
Source: https://trywisp.dev/docs/guides/run/review-by-another-agent.md
An agent is bad at finding its own mistakes. A different harness, with a different model, finds other ones. wisp can
have a second agent read the work before you merge it, in a few ways:
| Way | What it does |
| --- | --- |
| **Review by another harness** | Each PR is read by a harness other than the one that wrote it, and the tests run again. |
| **A crew reviewer** | A crew member with a reviewer's brief reviews when you ask, or on every PR. |
| **A delegate** | The task's own agent hands the review to another agent and reads its report. |
| **Judges** | Other agents vote on whether a task's goal is met. See [Goals and judges](../goals/). |
## Review every PR by another harness
With this on, when a task's PR opens or gets a new push, another harness reads the diff and lists what it would
fix, by severity, and the tests run again on the PR's head. It runs on that harness's own account. Merging stays
possible: wisp just says when a PR isn't reviewed or the review found issues.
**Desktop app:**
**⌘K** → **Settings** (or the person button in the top bar) → General → **Review by another harness**. Pick
**Another harness than the author**, or one harness.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → General → **Review by another harness**. Pick
**Another harness than the author**, or one harness.
**TUI:**
```text
/settings set --key review.harness --value other
```
**CLI:**
```sh
wisp settings set review.harness other # or codex, claude, opencode … ; off to stop
```
In a formula, for the whole team:
```yaml
settings:
review.harness: other
```
## Read the review, review again
**Desktop app:**
Press **P** to open the **PR** tab in the side panel. It shows the review: **Reviewed**, **Reviewing**, or how many
issues it found, with each finding. A finding goes to the task's agent through the reply box, so you can read it
before you send. Not reviewed yet, or not since the last push? Click the line to review it now, or use the task's
**⋯** → **Review PR #n**.
**Phone app:**
Tap the PR pill under the task's title. The PR pane opens as a sheet, with the review and each finding. Tap a finding
to put it in the reply bar. Not reviewed since the last push? Tap the review line to review it now.
**TUI:**
With the task open:
```text
/review view
/review maybe --force
```
**CLI:**
```sh
wisp review view # the task's review
wisp review maybe --force # review it again now
```
`review.finished` is an event, so a [trigger](../schedules-and-triggers/) can act on it.
## Ask a crew reviewer
A crew member keeps a brief, a kit of skills and a notebook across jobs, so their reviews follow your rules. See
[Crew and check-ins](../crew-and-check-ins/) to add one.
**Desktop app:**
In the task's reply box, write `@ada review this PR` and press **Enter**. Ada's answer lands under your message, and
her job shows on her page.
**Phone app:**
In the task's reply bar, write `@ada review this PR` and tap **Send**. Ada's answer lands under your message.
**TUI:**
Press **i** and type `@ada review this PR`; `@` lists your crew.
**CLI:**
```sh
wisp crew ask ada "review this PR: correctness first"
```
To have Ada review every PR the crew opens, declare a trigger:
```yaml
agents:
reviewer: { harness: codex, effort: high, mode: plan, instructions: "Review only. Never change files." }
crew:
ada:
role: reviewer
agent: reviewer
brief: "Review every PR the crew opens. List what you would fix, by severity. Never merge."
triggers:
review-every-pr:
on: pr.opened
crew: ada
```
## Delegate the review
A task can hand parts of its work to other agents and read their reports.
**Desktop app:**
In New task or the reply box, press **+**, then **Delegate…**. **Add delegate**, pick a harness and model, and
under **Use for** write `review`. Then ask: "when you're done, have the reviewer check it".
**Phone app:**
In New task, tap **Delegate**. In a running task, tap the options chip in the reply bar, then **Delegate**. **Add
delegate**, pick a harness and model, and under **Use for** write `review`. Then ask: "when you're done, have the
reviewer check it".
**TUI:**
Write it in the follow-up: "hand the review to @ada and fix what she finds".
**CLI:**
```sh
wisp reply "hand the review to @ada and fix what she finds"
```
## Compare is not review
[Compare](../compare-and-try/) runs the same ask on several agents so you can pick one result. A review keeps one
result and has another agent check it.
---
# Crew and check-ins
Source: https://trywisp.dev/docs/guides/run/crew-and-check-ins.md
A **crew member** is an agent that stays. It has a name, a role, a brief it follows on every job, a kit of skills,
and a notebook it keeps between jobs. You give it **jobs**; it can also **check in** on its own, on a schedule, and
wake up when something happens. Each job is a task you can open, follow up and ship.
## Add a member
**Desktop app:**
Press **Add a crew member** (the **+** in the crew rail, on the far left). Give them a **Name**, a **Role**, and
under **Their job** what they look after and what they should never do. Pick the **Harness**, the **Mode**, the
**Project folder**, how often they **Check in**, and **Jobs at once**. Then **Add to your crew**.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Open the **Crew** tab and tap **Add**. Give them a **Name**, a **Role** and **Their job**, pick the harness and how
often they check in, then **Add to your crew**.
**TUI:**
Press **g** then **c** for the crew view, then **n** for a new member.
**CLI:**
```sh
wisp crew create --name Ada --role reviewer --agent codex --mode plan \
--brief "Review every PR the crew opens. Never merge." --cron "every weekday at 9"
wisp crew # your crew
```
Or declare them, and share them with the repo:
```yaml
crew:
ada:
role: reviewer
agent: codex
mode: plan
brief: "Review every PR the crew opens. List what you would fix. Never merge."
cron: "every weekday at 9"
parallel: 1
```
## Give a job
**Desktop app:**
Click the member in the crew rail. Type in **Give Ada a job…** and press **Enter**. In any other task, write
`@ada …` in the reply box: the job is about that task, and Ada's answer lands under your message.
**Phone app:**
Open the **Crew** tab and tap the member. Type in **Give Ada a job…** and send. In any task, write `@ada …` in the
reply bar: the job is about that task, and Ada's answer lands under your message.
**TUI:**
In the crew view (**g c**), select the member and press **a**. Or, in any task, write `@ada …` in the reply box.
**CLI:**
```sh
wisp crew assign ada "update the changelog for the last release"
wisp crew ask ada "can you check this?" # in a task: the answer lands under your message
wisp ls --crew ada # Ada's jobs
```
## Check-ins
A check-in is a job the member gives itself: it looks at what it looks after and reports, or stays quiet when
nothing is new. **Checks in** takes *Only when asked*, *Every 30 min*, *Hourly*, *Every morning*, *Weekday
mornings*, *Mondays*, *On call*, or your own words ("every 2 hours").
**Desktop app:**
On the member's page: **Check in now**. **Pause** stops check-ins, triggers and delegations until **Resume**.
**Phone app:**
**Crew** tab → the member: **Check in now**, **Pause** and **Resume** are on their page.
**TUI:**
In the crew view: **c** check in, **w** wake, **p** pause, **u** resume, **x** remove.
**CLI:**
```sh
wisp crew checkin ada
wisp crew update ada --paused
wisp crew update ada --cron "every 2 hours"
wisp crew wake ada "the nightly build failed" # a job because something happened
```
Members also wake on events: **Also starts when** on their page, or `wakes:` in a formula
(`- { on: pr.opened }`). See [Automations, schedules and triggers](../schedules-and-triggers/).
## Org: who hands work to whom
A member's **delegates** are who its jobs can hand work to: other members, or agents on any harness. The **Org**
page draws them as arrows. A job that was itself delegated works alone, so work never goes round in circles.
**Desktop app:**
Press **Org** at the bottom of the crew rail. Select a member to choose its delegates, or drag from a card's handle
onto another member. Drag a card to move it; **Reset layout** puts everyone back.
**Phone app:**
Open the **Crew** tab and tap **Org**. Tap a member to choose its delegates.
**TUI:**
```text
/crew graph
```
**CLI:**
```sh
wisp crew graph # who wakes whom
wisp crew update ada --team '[{"crew":"linus","why":"release notes"}]'
```
## Kit, notebook and track record
- **Skills and instructions:** an `AGENTS.md` they follow on every job, and skills they read when a job needs one.
Drop `.md` files on their page. A member can propose additions; you accept them with **Add to their kit**.
- **Notebook:** what they remember between jobs. Edit it on their page.
- **Track record:** `wisp crew stats` shows how each member's jobs went.
## Share a crew
```sh
wisp crew export ada,linus # a crew file (refused while it holds a secret)
wisp crew share ada,linus # a link through wisp Cloud
wisp crew import --url # review it; members come in paused
```
## On your phone
The phone app shows your busy crew as **stories** under the Tasks bar. A ring says who waits on you, who has a new
report and who works. Tap one to see what they do now and their last report; swipe for the next member, down to
close. Reply in the box at the bottom (**Message Ada…**), or rate the report **Good** or **Try again**. See
[Phone app](../../apps/phone-app/).
---
# Automations, schedules and triggers
Source: https://trywisp.dev/docs/guides/run/schedules-and-triggers.md
Automations start work without you. A **recipe** is a prompt you run again and again. A **trigger** starts a task
when something happens: a time, a red CI run, a labelled issue, a task that finished, a webhook. It can start a new
task, run a recipe or a workflow, wake a crew member, or follow up the task the event came from.
## Recipes
A recipe is a saved prompt. A `{word}` in it becomes a field you fill in when you run it.
**Desktop app:**
On a task, **⋯** at its top right → **Task options › Save as recipe…**. Or **⌘K** → **Settings** → Agents →
**Automations** → Recipes → **Manage** → **New recipe**. Run one from **+** → **Recipes** in New task's footer.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
On a task, **⋯** (iPhone) or **⋮** (Android) in its top bar → **Keep and copy › Save as recipe…**. Run one from New
task: **⋯** (More options) → **Recipes**.
**TUI:**
**Ctrl-K** and type the recipe's name, or send `/automations task run --name release`.
**CLI:**
```sh
wisp recipes # list them
wisp run release 2.1.0 # values fill its {params} in order, or key=value
```
## Make a trigger
**Desktop app:**
**⌘K** → **Settings** → Agents → **Automations** → Triggers → **Manage** → **New trigger**. Pick what starts it:
**Schedule**, **CI failed**, **Issue labelled**, **Task finished**, **Task marked done**, **Webhook called**,
**Slack mention**, **Linear issue created** or **Sentry alert**. Say what to **Run** (a prompt or a recipe), where,
and with which harness, then **Create trigger**. Under **Send to**, pick a crew member to make it their job.
**Phone app:**
Tap the person button at the top of **Tasks** → **Automations** → Triggers → **Manage** → **New trigger**. The
choices are the same as on the desktop; finish with **Create trigger**.
**TUI:**
Press **g** then **a** for the automations view: **f** fires the selected trigger, **t** tests it (a dry run that
starts nothing).
**CLI:**
```sh
wisp automations trigger ls
wisp automations trigger test weekday-triage # the decision and the filled prompt, starting nothing
wisp automations trigger fire weekday-triage
wisp automations trigger log weekday-triage # its deliveries
```
Or declare them in your repo's `.wisp/` folder:
```yaml
triggers:
weekday-triage:
on: schedule
cron: "every weekday at 9"
tz: Europe/Zurich
prompt: "Look at the issues opened since yesterday and label them."
tests-on-change:
on: files.changed
debounce: 2m
prompt: "Run the tests for what changed and report failures only."
fix-red-ci:
on: ci.failed
followUp: true # a follow-up to the task whose PR failed
cooldown: 30m
after-done:
on: task.done
if: "event.payload.project == 'api'"
prompt: "Write release notes for {event.summary}"
```
`on:` takes any event wisp emits: `wisp events ls` lists them, and the [triggers reference](../../../reference/triggers/)
says which plugin offers each.
## Keep it in bounds
| Field | What it does |
| --- | --- |
| `concurrency` | `skip` (default), `queue`, `replace` or `parallel:N` when it fires while a run is going |
| `rate` | at most this many runs: `5/h`, `20/d` |
| `debounce` | events within this window become one job |
| `cooldown` | after a failed run, wait this long |
| `when` | only these days and hours: `{ days: [mon, tue, wed, thu, fri], hours: "9-18" }` |
| `budget` | `{ perRun: 5, perDay: 40 }` in dollars |
| `approval` | the job waits for your yes before it starts |
A job waiting for approval shows in the app; from a terminal,
`wisp automations trigger approve --yes`.
## Webhooks
Anything that can POST can start a task. Each webhook trigger has its own secret URL, shown on the trigger once you
create it. Switch on Settings → Agents → Automations → **Webhook triggers** first; while it's off, every URL refuses.
```yaml
triggers:
sentry:
on: webhook
header: Sentry-Hook-Signature
secret: "${secret:SENTRY_HOOK}"
mode: plan
prompt: "A Sentry alert: {event.summary}. Find the cause; don't fix yet."
```
With `header`, each call must be signed with the secret, which is never sent, only checked. Set it with
`wisp secret set SENTRY_HOOK`. What comes from outside can steer the agent, so start webhook tasks in Plan.
## Declared tasks and workflows
A declared task can carry its own schedule, and a workflow chains several:
```yaml
tasks:
deps:
prompt: Update the dependencies with patch releases and run the tests
schedule: "every day at 2"
worktree: true
```
`wisp run deps` runs it by hand. For workflows, see
[Build a software factory as code](../../declare/software-factory-as-code/).
## Later, on one task
**Start later** (in New task's **+**, or the reply box's) sends a task or a follow-up at a time you pick. A turn
that hit a usage limit can carry on when the window resets.
```sh
wisp later add --text "check that the deploy went out" --in 60 # minutes from now
wisp later list
```
## What happened, and why
```sh
wisp events tail --type 'ci.*' # recent events
wisp events why # what caused one, root first
wisp events parked # events a trigger gave up on, and why
```
---
# Call wisp and your crew from Slack, Linear and more
Source: https://trywisp.dev/docs/guides/run/from-slack-and-linear.md
You don't have to open wisp to use it. Message it from where your team talks, hand it issues from your tracker,
and answer its questions from your phone. Each message starts or follows up a real task you can open in wisp later.
| Where | What you can do |
| --- | --- |
| Slack, Discord, Telegram | Start a task, give a crew member a job, follow up, answer, stop. |
| Email | The same, by mail to a secret address (on a cloud wisp). |
| GitHub | `/wisp …` in a comment on an issue or PR; the answer comes back as a comment. |
| Linear, Jira, GitHub issues | Start a task from an issue, or let a label or a new issue start one. |
| ntfy, the phone app | Questions and finished tasks, with buttons to answer, reply, mark done or stop. |
| Your own harness | wisp's MCP tools: see [MCP from your harness](../mcp-from-your-harness/). |
## Set up a channel
Each channel is off until you switch it on, and wisp reaches out to the service, so nothing has to reach your
computer. Tokens go to `~/.wisp/secrets.json`, never to a formula.
**Desktop app:**
**⌘K** → **Settings** → General → **Phone**. Pick the channel and follow its steps:
- **Slack:** **Copy manifest**, then at api.slack.com/apps **Create New App → From a manifest**. Paste the app
token and the bot token. Then **Link yourself**: send the link code to the bot in a DM.
- **Discord:** in the Developer Portal, **New Application**, then **Bot → Reset Token**. Paste the bot token, then
**Add to a server** and send the bot the link code.
- **Telegram:** create a bot with @BotFather, paste its token, send the bot the link code.
- **ntfy:** switch it on (wisp picks a long, random topic), subscribe to it in the ntfy app, **Send a test**.
- **GitHub:** sign in to the GitHub CLI (`gh auth login`) on this computer.
- **Email:** on a cloud wisp, add the address you send from, then mail the **Secret address** it shows.
**Send me** picks what a channel tells you about: questions, finished tasks or both.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks** → **Settings** → General → **Phone**, pick the channel and follow the
same steps. Telegram and ntfy are quick from the phone. Slack and Discord mean copying tokens between sites, which is
easier in the Desktop app tab.
**TUI:**
```text
/channels status
/channels setup --transport ntfy --enabled
/channels test --channel ntfy
```
**CLI:**
```sh
wisp channels status # each channel: on, connected, what it still needs
wisp channels setup telegram --enabled --secrets '{"token":"123456:ABC…"}'
wisp channels setup ntfy --enabled --notify asks,finished
wisp channels test # a test to every channel that's on
```
Or declare a channel for the whole team; each person sets the secret on their own computer:
```yaml
channels:
team-slack:
transport: slack
enabled: true
token: "${secret:SLACK_BOT_TOKEN}"
allow: [U01ANA, U02BEN] # who may talk to it
cap: edits # the most a message may start: plan or edits, never Full auto
notifications:
slack-news: { to: team-slack, on: [finished, asks, failed] }
```
```sh
wisp secret set SLACK_BOT_TOKEN # typed hidden, never an argument
```
## Talk to it
Write what you'd type in New task. Options go first and end at a colon:
```text
fix the flaky login test
@ada review PR 42
in api on studio with opus high plan: why is the cache slow?
```
- `@ada` gives the job to the crew member Ada. Her answer comes back in the thread.
- `in api` picks the project, `on studio` the machine, `with opus high` the model and thinking, `plan` the mode.
- Reply in the thread to follow up. Buttons under a question answer it.
Commands: `/help`, `/projects`, `/models`, `/crew`, `/machines`, `/status`, `/new`, `/stop`, `/done`, and `/btw`
(ask on the side without interrupting).
A message sent to wisp Cloud can start a task on one of your computers: Settings → General →
**Accept tasks from channels**, then write `on laptop fix the login`. It runs in Plan unless you ask, Edits at most.
## From GitHub
With GitHub on, comment on an issue or a pull request in a repo you have as a project:
```text
/wisp fix this
/wisp @ada review this PR
/wisp in api with opus plan: why does this test fail?
```
Only your own comments count, and Full auto can't be asked for from there. On a public repo, the reply is a short
fixed line unless you switch on **Full reports on public repos**.
## From Linear, Jira or GitHub issues
**Desktop app:**
In New task's footer, **+** → **Start from an issue…** lists your project's open GitHub issues and the Linear and Jira
issues assigned to you. **Connect Linear…** or **Connect Jira…** signs you in the first time. Picking an issue fills
the prompt.
**Phone app:**
In New task, tap **⋯** (More options) → **Start from an issue**. Pick an issue and it fills the prompt.
**TUI:**
Write the issue's link or number in the task, or use a trigger (below).
**CLI:**
```sh
wisp "fix https://linear.app/acme/issue/ENG-42"
wisp connectors list # Linear and Jira come in through connectors
```
**By itself:** a trigger starts a task, or gives a crew member a job, when an issue gets a label or a new Linear
issue arrives. In the app: Automations → **New trigger** → **Issue labelled** or **Linear issue created**.
```yaml
crew:
bob: { role: builder, agent: claude }
triggers:
agent-label:
on: issue.labeled # GitHub issues, polled with gh
label: agent
crew: bob
prompt: "Build {event.summary}"
from-linear:
on: webhook # in Linear: Settings → API → Webhooks, this trigger's URL
header: Linear-Signature
secret: "${secret:LINEAR_WEBHOOK_SECRET}"
match: { type: Issue, action: create }
mode: plan
prompt: "Triage this Linear issue: {event.summary}"
```
A **Slack mention** trigger works the same way: `on: chat.message`, `match: { channel: slack }`, and `users:`, the
Slack member IDs who may start it. See [Automations, schedules and triggers](../schedules-and-triggers/).
## On your phone
The phone app, or ntfy, tells you when a task finishes, asks you something, or goes silent while it spends your
plan, with buttons to answer, reply, mark it done or stop it. Set it up in Settings → General → **Phone**, and see
[Phone app](../../apps/phone-app/).
---
# Long threads and fresh threads
Source: https://trywisp.dev/docs/guides/run/long-threads.md
A long conversation wears out. The agent forgets a rule you gave early on, repeats a fix that already failed, or
loses the why after a compaction. wisp keeps the task's state apart from the conversation, in its **Notes**, so the
conversation can be thrown away and the task carries on.
## Notes
Each task has Notes, in sections that are rewritten, never appended:
| Section | What it holds |
| --- | --- |
| Goal | what done looks like |
| Constraints | musts and must-nots |
| Decisions | what was chosen, and why |
| Tried and failed | what didn't work, and why |
| Where it stands | the state right now |
| Open questions | what is still unclear |
| Key files | the files that matter |
The agent keeps them with its `wisp_notes` tool, and you can edit any section. Before each follow-up, wisp puts the
Notes as they are now in front of your message, and says so when your message changes something said earlier.
Subagents read their lead's Notes, so they share its decisions.
**Desktop app:**
Open **⋯** at the task's top right → **Task options › Thread**. The **Thread** tab opens in the side panel (**]**
shows or hides the panel). Each section shows who wrote it and when; **Edit** rewrites it, and its history shows
earlier versions.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap **⋯** (iPhone) or **⋮** (Android) in the task's top bar → **Show › Thread**. The Notes open as a sheet; tap a
section to edit it.
**TUI:**
With the task open, press **t** for the Thread pane. To rewrite a section:
```text
/threads notes-update --section constraints --text "No new dependencies"
```
**CLI:**
```sh
wisp notes # the task's Notes
wisp notes --set "constraints=No new dependencies"
wisp threads revisions # every earlier version, and who wrote it
```
A formula can give a task its first Notes:
```yaml
tasks:
login-limit:
prompt: Add a rate limit to /login
notes:
goal: 5 attempts per minute per IP, then 429 with Retry-After
constraints: [No new dependencies, Keep the public API of auth/login]
```
## How worn is the thread
The thread's health comes from what wisp already sees, with no extra model calls: how full the context is, how many
compactions and turns, and the same error coming back. When it's worn, the Thread tab says so and offers **Fresh
thread**.
After a compaction, wisp asks a throwaway copy of the conversation what it still remembers of the goal, constraints,
decisions and failures. The answer shows as a line in the task ("Kept 6 of 8"), and what was lost goes in front of
your next follow-up, so the agent gets it back.
**Desktop app:**
The top of the **Thread** tab: *Fresh*, *Worn* and the facts behind it ("context 85% full · 3 compactions · same
error 4×"). **Compactions** lists what each one kept and lost.
**Phone app:**
The top of the **Thread** sheet (**⋯** / **⋮** → **Show › Thread**) shows the same health line and **Compactions**.
**TUI:**
The Thread pane (**t**) shows the same health line.
**CLI:**
```sh
wisp threads health
wisp threads audits # what each compaction kept and lost
```
## Start a fresh thread
A fresh thread is a new conversation on the **same task**. It starts from a brief: the Notes, the files changed and
the last turns. You can read and edit the brief first. The old conversation stays linked.
**Desktop app:**
**Thread** tab → **Fresh thread**. Read the brief, change it if you like, then **Start fresh thread**.
**Phone app:**
**Thread** sheet → **Fresh thread**. Read the brief, change it if you like, then **Start fresh thread**.
**TUI:**
With the task open:
```text
/threads fresh-brief
/threads fresh
```
**CLI:**
```sh
wisp fresh --print # show the brief, start nothing
wisp fresh -f brief.md # start from your own brief
wisp fresh
```
## From your harness
In a repo with a `.wisp/` folder, your own harness gets the `wisp_notes` tool through wisp's MCP server, so a
session you run outside wisp can keep Notes too. See [MCP from your harness](../mcp-from-your-harness/).
---
# Machines, the Grid and wisp Cloud
Source: https://trywisp.dev/docs/guides/run/machines.md
Every computer that runs wisp is a **machine**. Your wisp can start tasks on the others, and all their tasks show in
one list. A desktop at home keeps working while your laptop sleeps.
| How | When |
| --- | --- |
| **SSH** | A computer you can already `ssh` to. wisp installs itself there. |
| **A wisp Grid** | Each computer signs in to the same grid, which connects them. No SSH, no open ports. |
| **wisp Cloud** | The grid at [grid.trywisp.dev](https://grid.trywisp.dev): sign in and you also get a cloud computer. |
## Add a computer over SSH
Turn on SSH on the other computer (on a Mac: System Settings → General → Sharing → Remote Login; on Linux:
`openssh-server`).
**Desktop app:**
Click the person button in the top bar → **Machines** (or **⌘K** → **Settings** → Computers → **Machines**). Type
its **SSH address** (`you@studio.local`, or a Host from `~/.ssh/config`), give it a **Name**, then **Add and
connect**. The first time, type your password for that computer once; wisp sets up a key so it won't ask again.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Open the **Computers** tab and add a computer over SSH: its **SSH address**, a **Name**, then **Add and connect**.
The first time, type your password for that computer once.
**TUI:**
Press **g** then **m** for the machines view: **c** connects the selected one, **x** disconnects it. To add one:
```text
/machines add --name studio --transport ssh --address you@studio.local
```
**CLI:**
```sh
wisp machines hosts # the hosts in ~/.ssh/config
wisp machines add --name studio --transport ssh --address you@studio.local
wisp machines list # your machines and how each is doing
```
Or declare it:
```yaml
machines:
studio: { transport: ssh, address: you@studio.local }
```
Not on the same network? Install Tailscale on both computers and use the name it gives.
## Add a computer through the Grid
Sign in to the same grid on each computer. They find each other through it.
**Desktop app:**
**⌘K** → **Settings** → Computers → **Cloud** → **Sign in to a wisp Grid**, with GitHub or Google. Then **This
computer on the grid** turns this computer on, so your other wisps and your phone reach it.
**Phone app:**
Open the **Computers** tab and sign in to wisp Cloud (or your own grid) with GitHub or Google. Every computer on that
grid shows there. To put a computer on the grid, sign in from that computer (Desktop app tab).
**TUI:**
```text
/grid-client signin --add-computer
/grid-client status
```
**CLI:**
```sh
wisp cloud signin # wisp Cloud; or: wisp cloud signin https://grid.example.com
wisp computer on # this computer on the grid
wisp computer status
```
## Run there
**Desktop app:**
In New task's footer, click **This computer** and pick the machine. On a running task, **Runs on** by the reply box
moves the task, its branch and its history to another computer.
**Phone app:**
In New task, tap **This computer** and pick the machine.
**TUI:**
Start the TUI on that machine: `wisp tui --on studio`. Its list is that machine's tasks.
**CLI:**
```sh
wisp "run the full test suite" --on studio
wisp ls --on studio # any command takes --on
```
To keep work on one machine: `machine: studio` on a crew member, `on: studio` on a workflow step. A delegate can run
on another computer than its lead, on a copy of the lead's work; its changes come back when it finishes.
## wisp Cloud
Sign in at [grid.trywisp.dev](https://grid.trywisp.dev) and you get your own wisp on a server, with Claude Code,
Codex and Cursor installed. It works while your computers sleep. Use it in the browser, from the phone app, or as one
more machine in your app. It sleeps when nothing is going on and wakes when you open it.
```sh
wisp cloud status
wisp cloud accounts # each grid account signed in to here
wisp cloud switch
```
## Sandboxes
A **sandbox** is a box of its own on your grid, for one piece of work. The agent can install, run and break
anything there, never on your computer. It's deleted with its task.
**Desktop app:**
In New task's footer, click **This computer** and pick **Sandbox**, or start the prompt with `/sandbox`. **⌘K** →
**Settings** → Computers → **Sandboxes** signs Claude in once for every sandbox, sets the **Env vars** they all get,
and lists **Your sandboxes**.
**Phone app:**
In New task, tap **This computer** and pick **Sandbox**, or start the prompt with `/sandbox`. Person button at the
top of **Tasks** → **Settings** → Computers → **Sandboxes** lists **Your sandboxes**.
**TUI:**
```text
/sandbox launch --prompt "try the migration on a copy of the database" --cwd /path/to/project
```
**CLI:**
```sh
wisp sandbox launch --prompt "try the migration" --cwd . # a task in a sandbox of its own
wisp sandbox info # your sandboxes, their owners, what they start with
```
Sandboxes run on your own subscriptions. A delegate, a crew member's jobs and a goal's judges can work in one too.
## Run your own Grid
A Grid is wisp for many people on your server. Try one on your computer, then run it for real:
```sh
wisp grid dev # a grid here, for trying it out
wisp grid serve --data /srv/grid # a real grid, from /srv/grid/grid.json, behind a reverse proxy
```
A real grid signs people in with GitHub, Google or OIDC, and runs each person's box as a container. People then sign
in with `wisp cloud signin https://grid.example.com`.
---
# Budgets and usage
Source: https://trywisp.dev/docs/guides/run/budgets-and-usage.md
wisp runs your agents on your own plans. This page shows how to see what each task takes from them, and how to
keep work that runs on its own from using up a window you need.
## Usage windows
Claude Code and Codex report your plan's **usage windows** on every run: the 5-hour window and the weekly one
(and, on some Claude plans, separate Opus and Sonnet weeks). wisp keeps the latest reading for each account and
knows which tasks took which part.
Cursor, Antigravity and Copilot report tokens but not cost (Copilot bills in premium requests). Their turns count
in turns and outcomes, not in spend.
## See your usage
**Desktop app:**
- Home shows each window's use beside your tasks. Click it to open **Settings** → **Usage** (or **⌘K** →
**Settings** → Agents → **Usage**).
- **Usage** has **Plan budget** (each account's windows, when they reset, and **Where the window went**, task by
task), then **Spend**, **Turns**, **Worked** and **Questions** over the last 7 days, with charts **By project**
and **By harness · model**.
- The harness picker in New task's footer shows how much of each account's window is used.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
- Tap the person button at the top of **Tasks** → **Settings** → Agents → **Usage**. It holds the same **Plan
budget**, **Spend**, **Turns** and charts.
- In New task, tap the harness row: the picker shows how much of each account's window is used.
**TUI:**
Send `/budget view claude --named` for an account's windows, or `/budget plan-windows` for each window this
period and the tasks' parts of it.
**CLI:**
```sh
wisp usage # your limits this period
wisp usage --agent claude # that harness's, by task
wisp budget view codex # an account's usage windows
wisp budget compare claude # tokens per turn by account, per model
```
## Ask near the limit
Before a task would take a 5-hour or weekly window past your line, wisp asks first. The default line is 90%.
A task you start waits for your yes. Scheduled runs and crew jobs wait in **Needs you** until the window resets.
Each yes moves that window's line up a step until it resets.
**Desktop app:**
**⌘K** → **Settings** → **Usage** → **Ask near the limit**: Off, 80%, 90% or 95%. When it asks, the New task box
says how far the task may take the window, with **Start anyway**, **Wait until …** the reset, and **Keep editing**.
**Phone app:**
Person button → **Settings** → **Usage** → **Ask near the limit**. When it asks, New task shows **Start anyway**,
**Wait until …** the reset, and **Keep editing**.
**TUI:**
Send `/settings set budget.limitHold 80` (or `off`, `90`, `95`).
**CLI:**
```sh
wisp settings set budget.limitHold 80
wisp "refactor the parser" --yes # go ahead past the line this once
```
## Keep automations off your limit
**Automations stop at** sets where check-ins, triggers, goal rounds and agents' own follow-ups stop on a window.
They go on by themselves after it resets. What you start yourself always runs. Claude Code and Codex can each have
their own line; Codex's leaves room for your ChatGPT chats on a shared plan.
**Desktop app:**
**⌘K** → **Settings** → **Usage** → **Automations stop at**: Off, 50%, 75% or 90%. Under it, each harness's line is
**Same** or its own.
**Phone app:**
Person button → **Settings** → **Usage** → **Automations stop at**, with each harness's own line under it.
**TUI:**
Send `/budget set-stop autoStop 75`, or `/budget set-stop autoStopCodex 50` for Codex's own line.
**CLI:**
```sh
wisp budget set-stop autoStop 75 # off | 50 | 75 | 90
wisp budget set-stop autoStopClaude same # same | off | 50 | 75 | 90
wisp budget hold claude default # what holds this account's unattended work
wisp budget reset-at claude default # when it can run again
```
In a formula:
```yaml
budget:
stopAt: "75"
codex: "50"
taskUsd: 5 # at most this many dollars per task
```
## At the limit
When a run hits its limit, **Wait for the reset** decides what happens. On, the task waits under **Scheduled** and
carries on in the same conversation when the window resets. Off (the default), it stops and asks you.
`wisp settings set runtime.limitWait true` turns it on.
With [several accounts](../../agents/claude-code/), a task you start skips an account at its limit. wisp never
switches accounts to get around a limit on its own.
## More in Settings → Usage
- **Check Codex while work waits:** while work waits on a Codex plan, wisp asks Codex every 10 minutes how its
windows stand. A reset that comes early lets the work go at once. Nothing is spent.
- **Drain watch:** warns, here and on your phone, when an account's last two hours took twice its usual share for
the same work. **Copy report** puts the numbers in words for a support ticket.
- **Spare allowance:** when a weekly window resets within a day with a fifth or more left, home says so.
- **Stop a run silent for:** a run with no output for 30 minutes while its plan still moves is told to your phone.
Pick a time to stop such a run by itself.
- **Subagents run on:** the model Claude Code's own subagents use.
---
# MCP from your harness
Source: https://trywisp.dev/docs/guides/run/mcp-from-your-harness.md
You don't have to leave the agent you already use. `wisp mcp` serves wisp's tools over MCP, so Claude Code, Codex,
opencode or any MCP client can hand work to wisp: start a task in the background, wait for it, read its report and
follow up.
## Add wisp to your harness
One command, in your repo, does it for Claude Code and Codex:
```sh
wisp skill install --agent claude # .mcp.json, a SessionEnd hook, .claude/skills/wisp
wisp skill install --agent codex # [mcp_servers.wisp] in ~/.codex/config.toml
wisp skill install --agent all # Claude Code, Codex and opencode
```
- **Claude Code:** `.mcp.json` gets wisp's MCP server (`wisp mcp`), `.claude/settings.json` a `SessionEnd` hook
(each session you end is brought into wisp with `wisp adopt --hook`), and `.claude/skills/wisp/SKILL.md` tells
it when to use wisp. Commit them and your team has it too.
- **Codex:** `~/.codex/config.toml` gets `[mcp_servers.wisp]`. Codex has no end-of-session hook: bring its
sessions in with `wisp adopt --all --since 1d`.
- **opencode:** the skill goes in place; add the server by hand in `opencode.json`:
```json
{ "mcp": { "wisp": { "type": "local", "command": ["wisp", "mcp"] } } }
```
**Cursor** (`.cursor/mcp.json`) **and any other MCP client:** point it at `wisp mcp` on stdio.
```json
{ "mcpServers": { "wisp": { "command": "wisp", "args": ["mcp"] } } }
```
No global `wisp`? Use `npx -y wisp-agents mcp` in its place. Tasks start in the folder the client started
`wisp mcp` in, usually your project.
## The skill on its own
The wisp skill tells an agent when to hand work to wisp, how to brief it, how to wait, and to pass a waiting
agent's question on to you instead of answering it.
```sh
wisp skill # print it, to read first
wisp skill install --agent codex --project # .codex/skills/wisp in this repo
```
`--agent` takes `claude`, `codex`, `opencode` or `all`. `--project` writes into the repo, to commit for your team.
## The tools
| Tool | What it does |
| --- | --- |
| `wisp_launch` | Start a task on any harness, model, effort, mode or machine. Returns its id at once; `wait` blocks. |
| `wisp_list` | Tasks, newest first, with their state and a one-line summary. |
| `wisp_get` | A task's state and latest report as markdown, and any question it is waiting on. |
| `wisp_wait` | Block until a task finishes or asks something. |
| `wisp_reply` | Follow up, or answer its question. Can switch harness, model, effort or mode. |
| `wisp_stop` | Stop a running task. |
| `wisp_agents` | The harnesses installed, with their models and thinking levels, and your machines. |
An agent running *inside* a wisp task gets more: `ask_user`, `wisp_pr`, `wisp_watch`, the crew and connectors,
and `resume_later`. Every tool is in [MCP tools](../../../reference/mcp-tools/).
## What to ask your agent
- "Send the flaky-test fix to wisp on Codex and keep going on the UI."
- "Start three wisp tasks, one per failing package, and tell me when they're done."
- "Ask wisp what my last task changed."
- "Start a wisp task to fix the login bug, with the goal *the e2e suite passes*." (See [Goals](../goals/).)
## Follow what it started
Tasks your agent starts are ordinary wisp tasks.
**Desktop app:**
They show in your task list like any other. Open one to read it, answer it or follow up. **J** and **K** move
between them.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
They show in **Tasks** like any other. Tap one to read it, answer it or follow up from the reply bar.
**TUI:**
They show in the Tasks zone. **Enter** opens one; **i** replies.
**CLI:**
```sh
wisp ls --watch
wisp attach
```
## Sessions you run outside wisp
Work you did in your harness without wisp can come in too, so it's in your history:
```sh
wisp adopt --all --since 7d
```
---
# Ask about what just happened in your terminal
Source: https://trywisp.dev/docs/guides/run/terminal-context.md
A command just failed in your terminal. You don't have to copy the error. Type:
```sh
wisp "check the error above"
```
wisp looks at what just happened in this terminal and adds it to the task. The agent gets:
- the folder you are in, your shell, the git branch and `git status`;
- your last commands (up to 10), with their exit codes when wisp knows them;
- the terminal's last 200 lines of output, when your terminal lets wisp read them.
Before it sends anything, wisp says in one line what it added:
```text
◌ with terminal context: 2 commands, 31 lines from tmux, git status, 1 secret masked (--show-context to see it, --no-context to leave it out)
```
## When wisp adds it
wisp adds the context when your words ask about what is above: "check the error above", "fix that error", "why did
that fail", "what I just ran", "explain the output". Other tasks don't get it.
| Flag | What it does |
| --- | --- |
| `--context` | add it, whatever the words say |
| `--no-context` | leave it out this time |
| `--show-context` | add it, and print exactly what was added |
| `--lines N` | how many lines of output to take (200 by default, at most 5000) |
To turn it off for good:
```sh
wisp settings set termctx.enabled false
```
## Where the output comes from
wisp asks your terminal for its text. It never runs your command again to see what it printed.
| Terminal | What wisp reads |
| --- | --- |
| tmux | this pane (`tmux capture-pane`) |
| WezTerm | this pane (`wezterm cli get-text`) |
| kitty | this window, when remote control is on (`allow_remote_control yes` in kitty.conf) |
| iTerm2 | this session; macOS asks once to let wisp control iTerm2 |
| Apple Terminal | the front tab; macOS asks once to let wisp control Terminal |
| VS Code and other terminals | no output: the commands, their exit codes and the folder only |
When wisp can't read the output, the context says so, and the agent works from the commands, their exit codes and the
folder. Inside tmux, any terminal works, VS Code's included.
## Know every command and its exit code
Without help, wisp reads your last commands from your shell's history file. That file doesn't keep exit codes, so
wisp can't tell which command failed. Add the shell hook once, and wisp knows each command, its folder, its exit code
and how long it took:
```sh
# zsh: add this line to ~/.zshrc
eval "$(wisp shell-init zsh)"
# bash: add this line to ~/.bashrc
eval "$(wisp shell-init bash)"
# fish: add this line to ~/.config/fish/config.fish
wisp shell-init fish | source
```
The hook writes one line per command to a private file in `~/.wisp/term/` (only you can read it). It stays on this
computer, it is never synced, and lines older than 7 days are dropped. It records nothing else. To stop, remove the
line from your rc file.
The hook also lets an automation start when a command fails: the `terminal.failed` trigger
(see [Triggers](/docs/reference/triggers/)).
## Secrets stay out
Everything goes through the same secret scan as the rest of wisp before it leaves your terminal. API keys, tokens and
the values of secret environment variables become ``. The one-line summary says how many were masked.
Here is what `--show-context` printed after a failed `node` command in tmux, with a key printed just before it:
```text
## Terminal context
Where: `/private/tmp/wisp-tc/proj` (zsh), on branch `main`
Last commands (oldest first):
- `echo "using key "` → exit 0
- `node -e "require(\"./config.json\")"` → exit 1
The terminal's last 31 lines (from tmux):
...
Error: Cannot find module './config.json'
...
```
## In the TUI and the app
`wisp tui` takes the whole terminal, so there is nothing above it to read. Quit it (or use another pane), run
`wisp "check the error above"` in the shell where the command failed, and the task shows up in the TUI and the app
like any other.
---
# Track your agents' work beside your code
Source: https://trywisp.dev/docs/guides/track/track-agent-work.md
When agents write most of a codebase, `git log` tells you *what* changed, but not *what was asked*, *what the agent
was thinking* or *what it tried first*. wisp keeps that next to the code: each task that built the repo is a file in
`.wisp/tasks/`, linked to its commits, for everyone who clones the repo.
## 1. Turn it on
```sh
cd your-repo
wisp init # .wisp/ with history tracked in "ask" mode, and a note in AGENTS.md
git add .wisp AGENTS.md && git commit -m "chore: track agent work"
```
```yaml
# .wisp/wisp.yml
wisp: 1
history: { track: ask, inject: true }
```
- `track: ask` offers to save each task you ship or mark done; `auto` saves them all; `manual` only what you save
yourself.
- `inject: true` starts each new task with the past tasks on the files its prompt names.
## 2. Save tasks
Saving writes the task's spec, its report and its transcript into `.wisp/tasks/` and `.wisp/history/`, for you to
commit with the code, or in the same PR. Everything is scrubbed first: keys, tokens, `.env` values and private paths
never reach the repo.
**Desktop app:**
On a task wisp offers to save, press **Save to repo**. Any other task: **⋯** at its top right.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
On a task wisp offers to save, tap **Save to repo**. Any other task: **⋯** (iPhone) or **⋮** (Android) in its top
bar.
**TUI:**
With the task open, send:
```text
/history track --level full
```
**CLI:**
```sh
wisp track # --level spec|report|full (full is the default)
wisp untrack # take it out again
```
Old work too: a task from before the folder existed can be saved the same way.
## 3. Link commits to tasks
Ship it already adds `Wisp-Task: ` to each commit it makes. For the commits an agent makes itself:
```sh
wisp hook install # a git hook: commits made in a task's run get the trailer
wisp hook status
```
## 4. Bring in work done outside wisp
Ran Claude Code or Codex in a terminal? Bring those sessions in as tasks:
```sh
wisp adopt --all --since 7d --track # the last week's sessions in this repo, saved
wisp skill install --agent claude # from now on, Claude Code hands each session to wisp when it ends
```
`history: { adopt: ask | auto | off }` says what happens to a session that ends.
## 5. Use the history
**Desktop app:**
**⌘K** → **Repo**. **Repo history** lists the tracked tasks of the project, newest first. Filter by words, a path
(`src/auth/`) or an agent. Open one to read what was asked and what happened; **Resume** starts a new task that
carries on from there, on today's code.
**Phone app:**
Type `Repo` in the search field at the top of **Tasks** and tap **Repo**. **Repo history** lists the tracked tasks,
newest first. Open one to read what was asked and what happened; **Resume** starts a new task from there.
**TUI:**
Press **g** then **h** for Repo history. To find the task behind a line:
```text
/history blame --target src/auth/login.ts:42 --repo /path/to/repo
```
**CLI:**
```sh
wisp log # every tracked task, newest first
wisp log src/auth # the tasks that touched a path
wisp blame src/auth/login.ts:42 # the task behind that line: what was asked, its summary, its PR
wisp tasks --touching src/auth # the same, for scripts and agents (--json)
wisp resume # a new task that carries on from there, on today's code
wisp rerun # the same ask, from the commit it started on
```
Your agents read it too: the note `wisp init` puts in `AGENTS.md` tells them to look up the tasks behind a file
before they change it.
## Why it's safe to commit
- **No merge conflicts:** one file per task, named by its id.
- **Small:** specs and reports are short text; transcripts are compressed.
- **Reviewable:** a PR shows which tasks wrote it, and anyone can read what was asked.
---
# Use wisp from your agent or editor
Source: https://trywisp.dev/docs/integrations/your-agent.md
You don't have to leave the agent you already use. wisp serves its tools over MCP, so Claude Code, Codex, Cursor or
any MCP client can start wisp tasks, hand work to your crew, read past tasks and check wisp's state, without you
opening wisp.
## One command
```sh
wisp skill install --agent claude # in your repo
wisp skill install --agent codex
```
For Claude Code this writes:
- `.mcp.json`: wisp's MCP server (`wisp mcp`) for this repo.
- `.claude/skills/wisp/SKILL.md`: when and how to use wisp.
- `.claude/settings.json`: a `SessionEnd` hook, so each session you end is handed to wisp
([kept in the repo](../../guides/track/track-agent-work/) if you track history).
For Codex it adds `[mcp_servers.wisp]` to `~/.codex/config.toml`. Codex has no end-of-session hook; bring sessions
in with `wisp adopt --all --since 1d`.
`wisp skill` prints the skill without installing it, to read first or use with another agent.
## Any MCP client
Point it at `wisp mcp` (stdio):
```json
{ "mcpServers": { "wisp": { "command": "wisp", "args": ["mcp"] } } }
```
## What it can do
From your agent (`wisp mcp`): start a task on any agent, model or machine (`wisp_launch`), list and read tasks
(`wisp_list`, `wisp_get`), wait for one (`wisp_wait`), follow up (`wisp_reply`), stop it (`wisp_stop`), and see
which agents are set up (`wisp_agents`).
An agent running *inside* a wisp task gets more: asking you a question (`ask_user`), attaching a PR (`wisp_pr`),
showing a live page beside the task (`wisp_watch`), the crew and connectors, and coming back later
(`resume_later`). All of them are in [the reference](../../reference/mcp-tools/).
---
# Make wisp your own
Source: https://trywisp.dev/docs/plugins/make-wisp-your-own.md
Everything in wisp is a plugin: the task list, Ship it, the crew, the channels. Yours plug in the same way, with the
same API, so whatever a built-in can do, your plugin can do too. Pick the smallest step that does what you want.
## 1. Change a setting
Most changes are a setting. Every one is in [the settings reference](../../reference/settings/).
**Desktop app:**
**⌘K** (Ctrl-K on Windows and Linux) → **Settings**, or the person button in the top bar → **Settings**. **Search
settings** at the top finds a setting by name.
In the browser (`wisp --browser`, or your cloud wisp) it's the same window, menus and keys.
**Phone app:**
Tap the person button at the top of **Tasks**, then **Settings**. The search field at the top of **Tasks** also finds
a setting by name.
**TUI:**
Press **g** then **,** for the settings view, or **Ctrl-K** and type the setting's key.
**CLI:**
```sh
wisp settings list
wisp settings get review.harness
wisp settings set review.harness other
```
## 2. Declare it in a formula
Agents, skills, MCP servers, tasks, workflows, triggers and the crew can be declared in your repo, reviewed and
shared like code. Settings too:
```yaml
settings:
review.harness: other
worktrees.onDone: ask
```
See [Formulas](../../concepts/formulas/) and [Build a software factory as code](../../guides/declare/software-factory-as-code/).
## 3. Switch a built-in off
Don't use a part of wisp? Switch it off. Everything it made goes with it: its timers, processes and watchers. Switch
it back on any time.
**Desktop app:**
Settings → Advanced → **Plugins**. Each built-in has its switch; one that others need says why.
**Phone app:**
Person button at the top of **Tasks** → **Settings** → Advanced → **Plugins**. Each built-in has its switch.
**TUI:**
```text
/plugins set-enabled --id wisp.slack --enabled false
```
**CLI:**
```sh
wisp plugin # every plugin, on or off
wisp plugin disable wisp.slack
wisp plugin enable wisp.slack
```
## 4. Ask an agent to write a plugin
Describe the change ("a floating button that opens all my open PRs") and an agent writes it as a plugin. It writes
a plugin, never your code. The agent gets four extra tools:
- `wisp_plugins`: the plugins you have, and each one's manifest.
- `wisp_plugin_schema`: the whole plugin reference, with worked examples.
- `wisp_plugin_data`: a sample of the real answer of a command the plugin will call, so it reads the right fields.
- `wisp_plugin_check`: wisp's own checker, run on the plugin before it's installed.
**Desktop app:**
Settings → Advanced → **Plugins** → **Cast a plugin**. Describe the change and press **Enter**. When the task
ends, the plugin is installed **off**: read what it asks for, then **Switch it on**.
**Phone app:**
Person button → **Settings** → Advanced → **Plugins** → **Cast a plugin**. Describe the change and send. When the
task ends, the plugin is installed **off**: read what it asks for, then **Switch it on**.
**TUI:**
Start a task (**n**) that asks for it: "write a wisp plugin in ~/.wisp/plugins/hello that adds a button opening my
open PRs". The agent checks it with `wisp_plugin_check` before it's done. Then install it (below).
**CLI:**
```sh
wisp plugin new hello # a starting folder in ~/.wisp/plugins/hello
wisp "write a wisp plugin in ~/.wisp/plugins/hello that adds a button opening my open PRs"
```
## 5. Write one yourself
A plugin is a folder with a `wisp-plugin.json`:
| Kind | What's in the folder | Good for |
| --- | --- | --- |
| Declarative | the manifest only | settings, a theme, commands it calls on events |
| With UI | the manifest and a `ui.js` | a Settings page, a pane, a button, a card in an answer |
| Exec | the manifest and a program in any language | new commands, reacting to events, talking to other tools |
[Your first plugin](../first-plugin/) builds an exec plugin step by step.
[Plugin examples](../../reference/plugin-examples/) has complete UI plugins to copy, and the
[manifest reference](../../reference/plugin-api/) lists every key and component.
## Install, share, remove
What you install starts off, and runs only with the permissions its manifest asks for, never yours. Installing a
newer version replaces the old one, and it stays off until you switch it on again.
**Desktop app:**
Settings → Advanced → **Plugins** → **Install a plugin**: a folder a colleague sent, or its git URL. You see what it
asks for, then **Switch it on**. **Trust** lets it run as its own process with your environment, and its styles
apply; only trust code you've read.
**Phone app:**
Person button → **Settings** → Advanced → **Plugins** → **Install a plugin**, with its git URL. You see what it asks
for, then **Switch it on**. A folder on your computer is easier from the Desktop app tab.
**TUI:**
```text
/plugins list
/plugins set-enabled --id user.hello --enabled true
```
**CLI:**
```sh
wisp plugin install ./my-plugin # a folder
wisp plugin install https://github.com/you/wisp-hello # a git repo
wisp plugin enable user.hello
wisp plugin trust user.hello # its own process, your environment, its styles
wisp plugin remove user.hello
```
To share a plugin with your team, put it in a git repo, or list it in a formula (`plugins:`) so `wisp apply` brings
it in.
## Safe by default
- A plugin reaches only what its `permissions` name. A call outside them is refused.
- An untrusted plugin runs fenced in: no page, no network, no storage. It draws with wisp's components only, so it
can't look like something it isn't.
- A plugin talks to the rest of wisp only through public commands and events, so the built-ins it uses can change
inside without breaking it.
---
# Your first plugin
Source: https://trywisp.dev/docs/plugins/first-plugin.md
This page builds **Hello**, a plugin with one command, `user.hello.greet`. It's a small Node program, but an exec
plugin can be written in any language that reads and writes lines.
## 1. Start it
```sh
wisp plugin new hello
```
This writes `~/.wisp/plugins/hello/wisp-plugin.json`, a plugin with the id `user.hello` that does nothing yet. A
plugin of yours always has an id that starts with `user.`, and each of its commands starts with that id.
## 2. The manifest
Replace `wisp-plugin.json` with:
```json
{
"wispPlugin": 1,
"id": "user.hello",
"name": "Hello",
"version": "1.0.0",
"api": "^1",
"description": "Says hello.",
"server": { "exec": ["node", "hello.mjs"] },
"activation": ["onCommand:user.hello.greet"],
"permissions": [],
"contributes": {
"commands": [{ "id": "user.hello.greet", "title": "Say hello to someone" }]
}
}
```
- `server.exec` is the program wisp starts, in the plugin's folder.
- `activation` says when to start it: here, on the first call of its command. Until then it costs nothing.
- `permissions` is what it may do. Hello calls nothing, so it asks for nothing. Every key is in the
[manifest reference](../../reference/plugin-api/).
## 3. The program
wisp and the program talk JSON-RPC 2.0, one message per line, over the program's stdin and stdout. wisp sends
`initialize`. The program registers its commands, then answers. After that, each call is a `command.run`.
```js
// hello.mjs
const commands = {
'user.hello.greet': async (args) => ({ text: `Hello, ${args?.name || 'you'}!` }),
};
let next = 0;
const waiting = new Map();
const send = (m) => process.stdout.write(JSON.stringify({ jsonrpc: '2.0', ...m }) + '\n');
// a request to wisp, answered by a message with the same id
const request = (method, params) =>
new Promise((ok, fail) => {
const id = ++next;
waiting.set(id, { ok, fail });
send({ id, method, params });
});
readline.createInterface({ input: process.stdin }).on('line', async (line) => {
const m = JSON.parse(line);
if (!m.method) {
const w = waiting.get(m.id);
waiting.delete(m.id);
return m.error ? w?.fail(m.error) : w?.ok(m.result);
}
try {
let result = null;
if (m.method === 'initialize') {
for (const id of Object.keys(commands)) await request('command.register', { id });
result = { ok: true };
} else if (m.method === 'command.run') {
result = await commands[m.params.id](m.params.args);
}
if (m.id !== undefined) send({ id: m.id, result });
} catch (e) {
if (m.id !== undefined) send({ id: m.id, error: { code: -32000, message: String(e?.message ?? e) } });
}
});
```
Write anything you want to log to stderr: stdout is only for messages.
The program can ask wisp for more with the same `request`: `run` (call another command, within the plugin's
permissions), `emit` (send one of its events), `on` (hear an event), `settings.get` and `hook` (check a call before it
runs).
## 4. Switch it on and call it
A plugin you install starts off, so you see what it asks for before it runs.
```sh
wisp plugin enable user.hello
wisp user hello greet --name Ada
```
```
text Hello, Ada!
```
The command is everywhere at once, with no more work:
- `wisp help user` lists it, and `wisp user hello greet --help` shows its flags.
- The SDKs and your agent's MCP tools can call `user.hello.greet`.
- Other plugins can call it, if their manifest asks for `user:hello.greet`.
## 5. Share it
Put the folder in a git repo. Anyone can then install it, off, and switch it on:
```sh
wisp plugin install https://github.com/you/wisp-hello
```
## A plugin with UI
A plugin can also draw: a Settings page, a pane, a card. Its UI is one `ui.js` that runs sandboxed and describes
wisp's own components, so it looks like wisp in light and dark. [Plugin examples](../../reference/plugin-examples/)
has complete ones to copy, and [the manifest reference](../../reference/plugin-api/) lists every component.
---
# CLI
Source: https://trywisp.dev/docs/reference/cli.md
> Generated from the code by `apps/docs/scripts/reference.mjs`: edit the source, not this page.
`wisp --help` prints this. `wisp help [verb]` lists a plugin's verbs and a verb's flags: every plugin command below is also `wisp ` (see [Commands](../commands/)).
**Commands and tasks.** Words that aren't a command are a task: `wisp fix the flaky test` starts one. A line whose first word is one of wisp's command groups (`computer`, `cloud`, `grid`, `crew`, `trigger`, `plugin`, `recipes`, `machines`, `machine`, `share`, `version`, `skill`, `mcp`, …) is that command when one word follows: a verb it doesn't have (`wisp update deps`, `wisp settings open`) prints its verbs and exits 2. Two or more words after it are a task (`wisp update the readme`, `wisp share the results with the team`). `show`, `stop`, `wait`, `reply`, `attach` and `btw` take a task's id, or `last` for the newest; one other word is a slip, two or more a task (`wisp show me where the bug is`). A few command words also start everyday prompts and are a task when their command's argument isn't there: `wisp ship the docs`, `wisp run the tests`, `wisp plan the migration` (`ship`, `merge`, `run`, `plan`, `init`, `notes`, `export`, …). A verb the group doesn't have (`wisp computer start`), a flag its command doesn't take, or words it doesn't take print the group's verbs or the command's usage and exit 2. To start a task that begins with such a word, quote it as one argument (`wisp "computer start fails on boot, fix it"`) or put `--` first (`wisp -- computer start fails on boot`). A plugin's name is its command only when one of its verbs follows (`wisp channels refresh`, where a bad flag is an error too); otherwise the line is a task, so `wisp review the auth module` and `wisp update the readme` start tasks.
**Terminal context.** After a command fails, `wisp "check the error above"` adds what just happened in this terminal to the task: the last commands and their exit codes, the failing one's output (tmux, WezTerm, kitty, iTerm2, Terminal), the folder and git status, with secrets masked. `--context`, `--no-context`, `--show-context` and `--lines N` decide it for one run; `wisp shell-init zsh|bash|fish` adds the hook that records each command's exit code. See [Ask about what just happened in your terminal](../../guides/run/terminal-context/).
```text
usage:
wisp open wisp
wisp "task" launch a task in this folder
wisp serve run wisp here, in this terminal, without opening anything (--port N --host ADDR)
wisp add [folder] add a project: a folder here, a path or a git link (wisp add a README is a task)
wisp "task" -d launch it and return with its id (the default outside a terminal; --wait blocks)
wisp attach follow a task live: its steps, its answer, its questions; a reply box after
(Ctrl-C detaches, a second Ctrl-C stops it)
wisp ls list sessions (the newest 50; --state running,waiting,review,done|needs --limit N --all, -a: all, archived too
--watch: follow the list)
wisp show state + latest presentation as markdown (--watch: follow its turn live)
wisp wait block until it finishes or asks you something
wisp reply "text" follow up (answers a pending question) (--queue --mode plan|edits|auto
--agent ID --model ID --effort LEVEL: switch harness / model from here on)
wisp btw "question" ask on the side without interrupting the run; prints the answer
wisp stop stop a run
wisp held start|without|skip a turn held before it started: start it (Trust and start), run it without the
repo's own programs, or skip this run
wisp ship commit, push and open a PR for a worktree session (--draft)
wisp merge squash-merge its PR and sync your local base branch
wisp run [values…] run a saved recipe; values fill its {params} in order, or key=value
wisp recipes list recipes
wisp plugin list plugins
wisp plugin new start a plugin of your own in ~/.wisp/plugins/
wisp plugin enable|disable|trust|untrust switch a plugin on or off; trust one you installed (its theme applies)
wisp plugin install install one, off, and see what it asks for; remove takes it out
wisp crew list your crew
wisp crew pause|resume stop a member's check-ins and jobs, or start them again (by name or id)
wisp init a .wisp/ folder here: wisp.yml, the AGENTS.md note, its modules fetched and locked
(asks first outside a git repo or project; --here: make it anyway)
wisp plan|destroy what applying .wisp/ would change; take out everything it declares (--yes)
wisp fmt format the .wisp/ folder (--check)
wisp workspace [list|show|select|new NAME] the folder's workspaces: one set of variables each
wisp output [name]|graph|mv FROM TO the folder's outputs, its references as Graphviz, rename an address
wisp track keep a task in this repo's .wisp/tasks, for you to commit (--level spec|report|full)
wisp untrack take a tracked task out again
wisp log [path] the tracked tasks, newest first; with a path, the ones that touched it
wisp blame : which task wrote that line, and what it was asked
wisp resume a new task that carries on from where that one stopped, on today's code
wisp adopt [|--all] bring in sessions you ran in a harness outside wisp (--since 7d --track)
wisp notes [] [--set section=text] a task's Notes (goal, decisions, what failed, state …); --set rewrites one
wisp fresh [] [--print] [-f brief.md] a new conversation on the same task, from a brief (--print shows it)
wisp hook install|uninstall|status a git hook that adds Wisp-Task: to commits a task's agent makes
wisp secret set|rm NAME a secret your formulas reference as ${secret:NAME}: piped in or typed hidden, never an argument
wisp import [home] bring another wisp home (~/.wisp) in: its plan first, then on yes (--dry-run --yes)
wisp apply -f wisp.yml your setup as code: plan, diff, confirm (--dry-run --yes --prune --trust --profile P)
wisp diff|validate -f F what apply would change; schema and checks (wisp schema: the editor schema)
wisp export [kinds…] what's set up here, as a formula (--include ui,account --format yaml|json|toml)
wisp task spec|export|formula|history what was asked, to share, the setup it ran with, its family
wisp run -f x.task.yml a shared task spec, on your code; its formula: ./wisp.yml, module.x or inline
(wisp run [k=v]: by name, --wait)
wisp run --formula F a task a formula declares, by its name, nothing applied (--formula F "…": a prompt)
wisp rerun the same ask from the same commit (--from latest --formula f.yml[,g.yml]
--fill-from-snapshot --steps N --agent … --last N --project P --wait)
wisp ls --agent|--crew|--workflow|--formula f.yml|--since 7d tasks by what made them
wisp history export --since 30d every task as JSONL, scrubbed
wisp share a signed .wisp-task, previewed with its redactions (--level spec|report|full --to cloud|file|gist
--access anyone|people:a,b|teams:t|password --expires 7d --publish)
wisp share . a setup (with what it references) to wisp Cloud (--to cloud --access … --publish)
wisp shares what you've shared: access, views, imports, versions (--revoke ID --updates)
wisp open a shared task or setup: its plan, then run, import or apply it (--run --their-setup --compare --import --yes)
wisp cloud signin|status|signout wisp Cloud (or another grid: wisp cloud signin )
wisp cloud accounts|switch|remove each grid account signed in to; switch or sign out of one
wisp version print this wisp's version (also --version, -v)
wisp update [apply] is there a newer wisp? apply installs it (wisp help update: check, view)
wisp usage your limits this period and what each task took (--agent ID: that harness's, by task)
wisp machines|machine your machines and this one: list, add, remove… (wisp help machines)
wisp spell|spells spells are plugins: wisp plugin new|install
wisp computer on|off|status this computer on the grid, reachable from your other wisps (on --grid : signs in there first)
wisp --on … run any command on that machine (wisp ls --on studio, wisp "task" --on cloud)
wisp desktop open the wisp app window
wisp mcp run the MCP server (stdio) for other agents and editors
wisp skill [install] print / install the wisp agent skill (--agent claude|codex|opencode|all --project)
wisp grid dev|init|serve|doctor wisp Grid: wisp for many people on your server (wisp grid help)
wisp … any command of any plugin, flags from its arguments (wisp crew create --name Ada)
wisp help [plugin [verb]] every plugin's commands, a plugin's verbs, a verb's flags
wisp completions zsh|bash|fish shell completions from the same catalogue
wisp shell-init zsh|bash|fish a hook for your shell's rc file: wisp then knows each command you ran, its folder and
its exit code (kept 7 days on this machine; eval "$(wisp shell-init zsh)" in ~/.zshrc)
wisp tasks --touching |--tracked the tracked tasks (.wisp/tasks) behind a path, or all of them (--json)
wisp sdk types ts|py [FILE] typed commands for the SDKs (a .d.ts or a .pyi), from the same catalogue
wisp -- ls the repo a task that starts with a command's word; or quote it as one: wisp "computer start fails"
(after a command group, computer, cloud, grid, crew, plugin, settings…, one word it
doesn't have is an error naming its verbs; two or more are a task: wisp share the results
with the team. show, stop, wait, reply, attach and btw take a task's id or last; other
words after them are a task: wisp show me where the bug is)
launch options: --mode plan|edits|auto --agent claude|codex|opencode|cursor|antigravity|grok|copilot --model ID --effort LEVEL
--cwd DIR --also DIR (repeatable) --wait --json --no-worktree --compare agent[:model],…: one task per harness
--try subagents=haiku|sonnet|task --try skills=off run it twice on --agent, the second with
that changed (repeatable or comma separated); Compare says what differed
--goal NAME keep going until a goal declared by name (goals: in a formula) is met
--goal-text "…" the same with what done means in words
--formula f.yml[,g.yml] run under these formulas, nothing applied (its agents, skills, connectors…)
--factory [NAME] run it through a software factory (spec, build, checks, review, ship); alone: default
--yes go ahead although it takes a usage window past your Ask near the limit line
terminal context: wisp "check the error above" attaches what just happened in this terminal: its last commands, their
exit codes, the failing one's output (tmux, WezTerm, kitty, iTerm2, Terminal), the folder and git status,
secrets masked; never runs a command again (--context --no-context --show-context --lines N)
options: --port N --browser --no-open --json --version
```
---
# Commands
Source: https://trywisp.dev/docs/reference/commands.md
> Generated from the code by `apps/docs/scripts/reference.mjs`: edit the source, not this page.
Every command a plugin contributes. The app, the TUI, the CLI (`wisp `), the SDKs, MCP tools and other plugins all call these. **Reads** marks a command that changes nothing.
## wisp.accounts
wisp.accounts host: accounts, sign-in, harness watch (before:run), harness disk, live limits, usage, allowance
| Command | What it does | Reads |
| --- | --- | --- |
| `accounts.list` | A harness's accounts | yes |
| `accounts.harnesses` | Every harness that can have several accounts, with its watch | yes |
| `accounts.add` | Add another account | |
| `accounts.update` | Rename, set the kind, or move an account | |
| `accounts.remove` | Sign an account out and forget it | |
| `accounts.watch` | What wisp pinned of a harness's program | yes |
| `accounts.watch.trust` | Trust this version of a harness | |
| `accounts.watch.ask` | Ask before running a changed harness | |
| `accounts.login` | A sign-in as it stands | yes |
| `accounts.login.start` | Sign in with the CLI's own login | |
| `accounts.login.input` | Paste back the sign-in code | |
| `accounts.login.cancel` | Stop a sign-in | |
| `accounts.login.status` | Signed in, and as whom | yes |
| `accounts.logout` | Sign out with the CLI's own sign-out | |
| `accounts.keys` | Which providers have an API key | yes |
| `accounts.keys.set` | Save a provider's API key | |
| `accounts.keys.remove` | Remove a provider's API key | |
| `accounts.keys.test` | Test a provider's API key | |
| `accounts.install` | Install a harness wisp can install itself | |
| `accounts.upgrade` | Update a harness to its latest version | |
| `accounts.recheck` | Detect every harness again | |
| `accounts.cool` | Mark an account at its usage limit until its reset (launches you start skip it) | |
| `accounts.limits` | Read an account's usage windows | yes |
## wisp.automations
triggers, watchers, recipes, cron schedules, inbound webhooks
| Command | What it does | Reads |
| --- | --- | --- |
| `automations.tasks` | Declared tasks | yes |
| `automations.task.set` | Declare a task | |
| `automations.task.remove` | Remove a declared task | |
| `automations.task.run` | Run a declared task | |
| `automations.trigger.ls` | Triggers | yes |
| `automations.trigger.fire` | Fire a trigger | |
| `automations.trigger.test` | Test a trigger (dry run) | yes |
| `automations.trigger.log` | A trigger's deliveries | yes |
| `automations.trigger.push` | Send triggers an event | |
| `automations.trigger.approve` | Approve a trigger's job | |
| `automations.trigger.resume` | Resume a paused trigger | |
| `automations.trigger.switch` | Switch a trigger off or on | |
| `automations.trigger.remove` | Remove a trigger | |
| `automations.release` | Rows held for a harness's plan stop saying so (its plan reset early) | |
| `automations.sources` | Trigger sources | yes |
## wisp.budget
usage windows, Automations stop at, banked resets, the before:run budget guard, compare metrics
| Command | What it does | Reads |
| --- | --- | --- |
| `budget.view` | An account's usage windows | yes |
| `budget.compare` | Tokens per turn by account, per model | yes |
| `budget.planWindows` | Each usage window this period and the tasks' parts of it | yes |
| `budget.hold` | What holds an account's unattended work | yes |
| `budget.ask` | Ask near the limit: the usage window a send would take past your line, before it's made | yes |
| `budget.resetAt` | When an account at its usage limit can run again | yes |
| `budget.record` | Record an account's usage windows | |
| `budget.dismissDrain` | Drain watch: hide an account window's card until a later run shows it again | |
| `budget.dismissNotice` | Hide a window's notice until that window changes again | |
| `budget.setStop` | Automations stop at | |
## wisp.channels
wisp.channels: the hub every way of reaching wisp from outside goes through (plan §6.11.3): the channel and notification kinds
| Command | What it does | Reads |
| --- | --- | --- |
| `channels.view` | Which channels are on | yes |
| `channels.update` | Change a channel's settings | |
| `channels.test` | Send a test to a channel, or to every channel that's on | |
| `channels.status` | How each channel is set up (Settings → Phone): on or off, connected, what it still needs; secrets only as saved or not | yes |
| `channels.setup` | Set up a channel (ntfy, Telegram, Slack, Discord, GitHub, email): switch it on or off, save its tokens (kept in secrets.json) and settings | |
| `channels.send` | Send a notice | |
| `channels.notify` | Notify about a task | |
| `channels.act` | Act on a task from a channel | |
| `channels.inbound` | A message the grid held | |
| `channels.routed` | A message the grid routed | |
| `channels.rotate` | Replace a channel's private URL | |
| `channels.extra` | A channel's extra view | yes |
| `channels.refresh` | Read the channels again | |
## wisp.cli
the command-line frontend: verbs generated from the command catalogue, terminal block renderers, live attach
| Command | What it does | Reads |
| --- | --- | --- |
| `cli.catalogue` | The commands you may run, with their arguments | yes |
## wisp.connectors
The MCP servers agents get: the connector resource kind, what each run gets, and Settings → Connectors (add, test, import from the harnesses' configs, OAuth sign-in).
| Command | What it does | Reads |
| --- | --- | --- |
| `connectors.list` | Every connector, the servers found in the harnesses' configs, and the reach | yes |
| `connectors.add` | Add a connector (its secrets go to the secrets file) | |
| `connectors.update` | Change a connector, or switch it on or off | |
| `connectors.remove` | Remove a connector and its secrets | |
| `connectors.test` | Start a connector and list its tools | |
| `connectors.import` | Add servers found in the harnesses' own configs, or hide them | |
| `connectors.signin` | Sign in to a remote connector (OAuth): the page to open | |
| `connectors.oauthFinish` | Finish a connector's sign-in | |
| `connectors.signout` | Sign out of a connector | |
| `connectors.agent.list` | The user's connectors, as a task's agent reads them (wisp_connectors) | yes |
| `connectors.agent.add` | Add a connector from a task, key names only (wisp_connector_add) | |
| `connectors.agent.signin` | What a connector needs from the user before it works (wisp_connector_signin) | yes |
| `connectors.call` | Call one tool of a remote connector, with its own sign-in (the issue picker lists Linear and Jira through them) | |
## wisp.crew
crew members: schedules, check-ins, jobs, mentions, notebooks, sharing
| Command | What it does | Reads |
| --- | --- | --- |
| `crew.wake` | Wake a crew member: a job, because something happened | |
| `crew.wakeMentions` | Wake the crew members a text mentions | |
| `crew.list` | Your crew | yes |
| `crew.get` | A member and their jobs | yes |
| `crew.layout` | Where each member sits on the Org page | yes |
| `crew.set_layout` | Move members on the Org page | |
| `crew.create` | Add a member | |
| `crew.adopt` | Add a task to the crew | |
| `crew.update` | Change a member | |
| `crew.remove` | Let a member go | |
| `crew.detach` | Make a spell's member yours | |
| `crew.ask` | Ask a crew member in a task: their answer lands under your message | |
| `crew.reply` | Reply to a crew member's answer in a task: the same job carries on | |
| `crew.assign` | Give a member a job | |
| `crew.checkin` | Check in now | |
| `crew.stats` | Each member's track record | yes |
| `crew.graph` | Who wakes whom | yes |
| `crew.export` | Share members as a crew file (refused while it holds a secret) | yes |
| `crew.import` | Review a crew file, or add its members (paused) | |
| `crew.share` | Share members or the whole crew as a link (wisp Cloud; refused while it holds a secret) | |
| `crew.kit` | Skills and instructions a member's kit can take | yes |
| `crew.agent.kit` | Propose skills or instructions for a member's kit (wisp_crew_kit) | |
| `crew.agent.add` | Add a member, or the members a shared link or crew file holds, paused (wisp_crew_add) | |
| `crew.agent.list` | The crew, or one member in full, as an agent reads it (wisp_crew) | yes |
| `crew.agent.edit` | Change a member: only the fields given; remember adds notebook lines (wisp_crew_edit) | |
| `crew.agent.remove` | Remove a member; a member's own job can't remove itself (wisp_crew_remove) | |
## wisp.events
The durable event log from outside the process: tail, why, retry, the catalogue, the events topic, MCP wisp_events, and sinks (a signed webhook) (ADR-0044)
| Command | What it does | Reads |
| --- | --- | --- |
| `events.tail` | What happened: durable events by type, subject or since | yes |
| `events.why` | What caused an event: its chain, root first | yes |
| `events.retry` | Deliver a parked event again | |
| `events.parked` | Events a subscription gave up on, and why | yes |
| `events.ls` | Every event type wisp emits | yes |
| `events.sinksStatus` | Where events are forwarded, and how each sink is doing | yes |
| `events.resume` | Resume a paused sink | |
## wisp.factory
software factories: a task through stations (spec you approve, build, checks that are commands, review by a vote, ship a PR you merge), looped back to build with a limit (ADR-0114)
| Command | What it does | Reads |
| --- | --- | --- |
| `factory.list` | Factories (declared) | yes |
| `factory.names` | Factories a task can run through | yes |
| `factory.set` | Add or change a factory | |
| `factory.remove` | Remove a factory | |
| `factory.stop` | Stop a factory run | |
## wisp.git
Git for every other plugin: repo handles (git.service@1), status, diffs from the merge-base, worktrees, staging and commits. Every git call runs async through the proc service.
| Command | What it does | Reads |
| --- | --- | --- |
| `git.status` | A folder's git status | yes |
| `git.changes` | What the work changed since its base | yes |
| `git.revert` | Put a file or hunk back as the base had it | |
| `git.stage` | Stage or unstage a file or hunk | |
| `git.commit` | Commit what's staged | |
| `git.tools` | Is git installed, and gh signed in | yes |
| `git.clone` | Clone a repo | |
| `git.origin` | A folder's repo (its origin), to run its task on another computer | yes |
| `git.githubRepos` | Your GitHub repos (gh's sign-in), newest first, minus the projects here: Projects' click to clone | yes |
| `git.checkout` | This computer's checkout of a repo: one already here, else a clone | |
| `git.restoreTurn` | Put a task's folder back as it was before one of its turns | |
## wisp.goal
goals: rounds, verdicts, judges, stalls
| Command | What it does | Reads |
| --- | --- | --- |
| `goal.set` | Set, change or clear a task's goal | |
| `goal.pause` | Pause a task's goal: no judging until it resumes | |
| `goal.resume` | Resume a task's paused goal | |
| `goal.drop` | Drop a task's goal | |
| `goal.check` | Judge a task's goal now, on its last answer | |
| `goal.declared` | The goals declared by name (goals: in a formula) | |
## wisp.grid-client
Sign in to a wisp Grid (RFC 8628), the grid and grid-tunnel transports, this computer's tunnel, and wisp Cloud as a share destination (ADR-0010, 0038, 0041)
| Command | What it does | Reads |
| --- | --- | --- |
| `grid-client.signin` | Sign in to wisp Cloud (or another grid): adds an account and makes it current | |
| `grid-client.sandbox` | Make a sandbox on the grid, as a machine | |
| `grid-client.sandboxes` | Your sandboxes on the grid | yes |
| `grid-client.sandboxRemove` | Delete a sandbox (its box and home) | |
| `grid-client.sandboxInfo` | Sandboxes on the grid: whether it makes them, their sign-ins and env names | yes |
| `grid-client.sandboxLogin` | A sign-in every sandbox starts with, sealed on the grid | |
| `grid-client.sandboxLogout` | Take a sandbox sign-in off the grid | |
| `grid-client.sandboxEnv` | An env var every sandbox gets (empty: taken out) | |
| `grid-client.teams` | Team spaces on the grid: list, make, show, add or remove a member | |
| `grid-client.signinStatus` | How a sign-in is going | yes |
| `grid-client.signinCancel` | Stop a sign-in | |
| `grid-client.status` | Signed in where, and this computer on the grid | yes |
| `grid-client.signout` | Sign out of the current grid account | |
| `grid-client.accounts` | The grid accounts signed in to here, the current one marked | yes |
| `grid-client.accountSwitch` | Make another signed-in grid account the current one | |
| `grid-client.accountRemove` | Sign out of one grid account (its cloud box and computers leave Machines) | |
| `grid-client.computer` | Turn this computer on or off on the grid | |
| `grid-client.shares` | What I've shared through wisp Cloud | yes |
| `grid-client.access` | Change who may open a share, its expiry, or its place in the gallery | |
| `grid-client.revoke` | Stop sharing | |
| `grid-client.fetch` | Open a share link | yes |
| `grid-client.imported` | Record a share taken in (for update available) | |
| `grid-client.updates` | Imported shares with an update | yes |
| `grid-client.keys` | Your API keys for scripting your cloud wisp (never the keys themselves) | yes |
| `grid-client.keysCreate` | Make an API key for scripting your cloud wisp, shown once | |
| `grid-client.keysRevoke` | Revoke an API key: anything using it stops at once | |
| `grid-client.reply` | Report a routed task back to the chat it came from | |
## wisp.history
A repo's agent history in .wisp/: track, blame, offers, resume requests, context injection (ADR-0033, 0042)
| Command | What it does | Reads |
| --- | --- | --- |
| `history.track` | Save a task into its repo's .wisp/ | |
| `history.save` | Save to repo (an offered task) | |
| `history.untrack` | Take a task out of the repo's history | |
| `history.blame` | Which task made this | yes |
| `history.resumeRequest` | Ask to resume an earlier task | |
| `history.resumeAnswer` | Approve or deny a resume request | |
| `history.requests` | Resume requests | yes |
| `history.list` | The repo's committed agent history (the Repo tab, wisp ls --repo) | yes |
| `history.report` | A tracked task's report and what was asked | yes |
## wisp.issues
issues to start a task from: a project's GitHub issues (gh), the Linear and Jira issues assigned to you
| Command | What it does | Reads |
| --- | --- | --- |
| `issues.list` | List issues to start a task from | yes |
## wisp.later
follow-ups and reminders scheduled on tasks, For later, /after plans
| Command | What it does | Reads |
| --- | --- | --- |
| `later.add` | Schedule a follow-up or a reminder on a task | |
| `later.park` | Save a task for later, or unsave it | |
| `later.list` | What is scheduled on a task | yes |
| `later.edit` | Another time or text, or send it now | |
| `later.cancel` | Cancel what is scheduled | |
| `later.done` | Mark done: the agent's wake-ups go | |
| `later.plans` | Planned tasks and reminders | yes |
| `later.getPlan` | A plan | yes |
| `later.plan` | Plan a task or a reminder | |
| `later.editPlan` | Change a plan | |
| `later.cancelPlan` | Cancel a plan | |
| `later.nextAt` | The soonest thing that will run | yes |
| `later.tick` | Look for what came due | |
| `later.waitAtLimit` | Carry on once the usage window resets | |
| `later.agent.schedule` | The agent's own wake-up (resume_later) | |
| `later.zone` | The user's time zone | |
## wisp.learn
What wisp learns about how you work: preferences and lessons, globally and per project, from a retro of each quiet task; later tasks' prompts carry them
| Command | What it does | Reads |
| --- | --- | --- |
| `learn.view` | What wisp has learned: preferences and lessons, and the recent retros | yes |
| `learn.set` | Replace one list of what wisp has learned (global or a project's) | |
| `learn.retro` | Learn from a task now: a retro of it, without waiting for it to go quiet | |
## wisp.lsp
wisp.lsp: language servers for the editor (definition, references, hover, diagnostics, rename, completion)
| Command | What it does | Reads |
| --- | --- | --- |
| `lsp.ask` | Ask the task's language server | |
| `lsp.install` | Install a language server | |
## wisp.machine
What agents cost this computer, the RAM/CPU and usage-limit holds, stopping what runs left behind, and Watch.
| Command | What it does | Reads |
| --- | --- | --- |
| `machine.load` | What the RAM/CPU guard reads and holds | yes |
| `machine.read` | What agents cost this computer: memory, CPU, disk, leftovers | yes |
| `machine.stop` | Stop a process a task's run left running | |
| `machine.fix` | File a fix for processes a run left running | |
| `machine.harness.clean` | Remove the harnesses' crash dumps and stale files | |
| `machine.automations.pause` | Pause automations until a time (0 resumes them) | |
## wisp.machines
Peers, your other computers, over wisp's sync protocol: the ssh and loopback transports, the mirrored task lists, commands routed to the owner with the same key, the machines.peers service
| Command | What it does | Reads |
| --- | --- | --- |
| `machines.add` | Add a computer | |
| `machines.update` | Rename a computer or change how it is reached | |
| `machines.remove` | Remove a computer | |
| `machines.connect` | Connect to a computer | |
| `machines.disconnect` | Disconnect from a computer | |
| `machines.stop` | Stop wisp on a computer (or restart it) | |
| `machines.letIn` | Type the password once so this computer's key is let in | |
| `machines.follow` | Watch an asleep computer without waking it | |
| `machines.recheckAgents` | Detect a computer's coding agents again | |
| `machines.list` | Your computers and how each is doing | yes |
| `machines.get` | One computer and how it is doing | yes |
| `machines.sessions` | The tasks a computer shows, as last seen | yes |
| `machines.hosts` | Hosts in ~/.ssh/config | yes |
| `machines.discover` | Computers this one already knows how to reach | yes |
| `machines.reachable` | Can other devices reach this computer | yes |
| `machines.call` | A request to a computer's wisp | |
| `machines.route` | Run a command on the computer that owns its row | |
| `machines.carry` | Copy the lead's work onto a computer for a delegate (a copy under wisp's own folder there) | |
| `machines.takeIn` | Take carried work into its copy (on the computer it was carried to) | |
| `machines.changes` | A carried copy's changes since it came in | yes |
| `machines.send` | Pack a folder here and upload it raw to a computer's route (a sandbox's project) | |
| `machines.uncarry` | A lead's delegate on a computer goes: its task and its copies there | |
| `machines.dropCopies` | Delete the copies a lead's delegates got (on the computer they were carried to) | |
| `machines.bring` | A carried copy's changes, into the lead's folder here | |
## wisp.mcp
wisp.mcp host: the MCP server for agents and editors over POST /api/mcp and stdio, each tool a kernel command
| Command | What it does | Reads |
| --- | --- | --- |
| `mcp.rpc` | One MCP JSON-RPC message | |
| `mcp.tools` | The MCP tools this caller is offered | yes |
| `mcp.session.set` | What a session's run is, for its tools | |
## wisp.plugins
The plugin manager: which plugins this wisp has, switching them on and off (the plugin kind)
| Command | What it does | Reads |
| --- | --- | --- |
| `plugins.list` | Which plugins this wisp has | yes |
| `plugins.setEnabled` | Switch a plugin on or off | |
| `plugins.install` | Install a plugin of yours from a folder or a git URL (off until you switch it on) | |
| `plugins.uninstall` | Remove a plugin you installed | |
| `plugins.trust` | Trust a plugin you installed (or take the trust back): it reloads | |
| `plugins.folder` | Where this wisp keeps your plugins (its home's plugins folder) | yes |
| `plugins.ui` | What your untrusted plugins show in the app (their UI modules) | yes |
| `plugins.styles` | The part styles of the plugins that are on and trusted (themes), for the app's @layer plugins | yes |
| `plugins.agent.list` | The plugins you have, in plain words, for an agent writing one (wisp_plugins) | yes |
| `plugins.agent.schema` | The reference for writing an untrusted plugin: manifest, kit descriptors, commands, examples (wisp_plugin_schema) | yes |
| `plugins.agent.data` | A sample of what a read-only command answers, for a plugin being written (wisp_plugin_data) | yes |
| `plugins.agent.check` | Check a plugin without installing it: what it does, or every problem (wisp_plugin_check) | yes |
## wisp.push
wisp.push: the push transport for wisp.channels (phones paired by their own keys, notes sealed with HPKE, posted through the grid relay)
| Command | What it does | Reads |
| --- | --- | --- |
| `push.pair` | Pair this phone for notifications: its relay handle and its own public key | |
| `push.unpair` | Stop sending notifications to a paired phone | |
| `push.devices` | The phones that get this wisp's notifications | yes |
| `push.answer` | A choice or a reply from a notification, signed by this wisp | |
## wisp.resources
wisp as code: plan, apply and export every plugin's resource kinds (wisp.yml)
| Command | What it does | Reads |
| --- | --- | --- |
| `resources.kinds` | What this wisp can declare | yes |
| `resources.plan` | What applying a formula would change | yes |
| `resources.apply` | Apply a formula | |
| `resources.export` | Everything set up here, as a formula | yes |
| `resources.read` | Read a pasted formula: the resources it declares and the secrets it needs | yes |
| `resources.overlay` | A formula as one task's overlay (nothing applied), and a task resolved under it with every name it gives checked | yes |
| `resources.write` | The setup as a formula's text (Share setup) | yes |
| `resources.secretSet` | Set a secret a formula references as ${secret:NAME} (kept in secrets.json, never in a formula) | |
| `resources.secretRemove` | Remove a secret a formula references | |
| `resources.rename` | Rename a resource in place (wisp mv) | |
| `resources.refresh` | Take what wisp has as the baseline (--refresh-only) | |
## wisp.review
review by another harness: a task's PR head read by a harness other than the author, the tests run again on it
| Command | What it does | Reads |
| --- | --- | --- |
| `review.maybe` | Review the pull request with another harness | |
| `review.view` | The task's review | yes |
## wisp.router
Auto: picks a harness, model and effort per task (bandit), classifies limits
| Command | What it does | Reads |
| --- | --- | --- |
| `router.view` | Settings → Auto and what it learned | yes |
| `router.set` | Change Settings → Auto | |
| `router.preview` | What Auto would run for a prompt | yes |
| `router.reset` | Forget what Auto learned | |
| `router.signal` | Something happened to a routed task | |
| `router.record` | A launch went out with a route | |
## wisp.runtime
Tasks (sessions), their turns and activity, the follow-up queue and the harness lifecycle
| Command | What it does | Reads |
| --- | --- | --- |
| `runtime.create` | Start a task | |
| `runtime.followUp` | Send a task a follow-up | |
| `runtime.stop` | Stop a task's turn | |
| `runtime.rename` | Rename a task | |
| `runtime.archive` | Archive or unarchive a task | |
| `runtime.markRead` | Mark a task read or unread | |
| `runtime.setState` | Set a task's state | |
| `runtime.delete` | Delete a task | |
| `runtime.queue.edit` | Edit a queued follow-up | |
| `runtime.queue.sendNow` | Send a queued follow-up now | |
| `runtime.queue.merge` | Merge queued follow-ups into one | |
| `runtime.queue.text` | Change a queued follow-up's text | |
| `runtime.release` | Release a held task | |
| `runtime.held` | Start or skip a task's held turn | |
| `runtime.setMode` | Set the mode a task's next turns run in | |
| `runtime.setLean` | Run a task's turns lean (on, off, or none to follow Settings) | |
| `runtime.setAgent` | Set the harness a task's next turns run on | |
| `runtime.forLater` | Save a task for later, or take it out | |
| `runtime.pin` | Pin a task in the list, or unpin it | |
| `runtime.queue.order` | Reorder a task's queued follow-ups | |
| `runtime.queue.cancel` | Take a queued follow-up out | |
| `runtime.get` | A task | yes |
| `runtime.resumeCommand` | The command that resumes a task's conversation in a terminal | yes |
| `runtime.list` | The task list | yes |
| `runtime.slots` | Plugins' slots of every task | yes |
| `runtime.turns` | A task's turns | yes |
| `runtime.activity` | A task's activity | yes |
| `runtime.cold` | A large idle task's prompt cache: gone cold or not, and what Compact now would cost | yes |
| `runtime.presentation` | A task's presentation | yes |
| `runtime.setExt` | Set a plugin's slot on a task | |
| `runtime.turn.setExt` | Set a plugin's slot on a turn | |
| `runtime.note` | Add a note to a task | |
| `runtime.settle` | Settle a task that stopped | |
| `runtime.search` | Search tasks | yes |
| `runtime.agents` | The harnesses a task can run on | yes |
| `runtime.defaultModel` | The model a harness's Default runs in a folder | yes |
| `runtime.card` | Add a card to the list | |
| `runtime.import` | Import tasks from another wisp home | |
| `runtime.ask` | An agent asks the user a question | |
| `runtime.answer` | Answer an agent's question | |
| `runtime.setup.ask` | An agent asks the user to change their setup (a connector, the crew, a project): a card, run on Allow | |
| `runtime.unask` | Take back a question a plugin put on a task | |
| `runtime.pollAnswer` | Has the question been answered | yes |
| `runtime.approval` | A live approval of a tool call | |
| `runtime.approveBlocked` | Allow what the last turn's permissions blocked | |
| `runtime.btw` | A side question on a copy of the conversation | |
| `runtime.btw.drop` | Drop a side question | |
| `runtime.probe` | Ask a copy of a task's conversation something, answering only, kept nowhere | |
| `runtime.reveal` | Show an answer's picture or video in its folder | |
| `runtime.unmasked` | Reveal one hidden .env value of a task's turn | yes |
| `runtime.compact` | Compact the conversation | |
| `runtime.terminal` | Open a terminal task's CLI | |
| `runtime.rerun` | Run a signed-out turn again | |
| `runtime.fork` | Fork the task from a turn | |
| `runtime.trial` | Try it two ways: run a task twice on one harness with one setting changed | |
| `runtime.trial.keep` | Keep one run of Try it two ways (the other is archived) | |
| `runtime.delegate` | Start subagents | |
| `runtime.results` | Subagents' reports | yes |
| `runtime.quick` | One answer from a harness, outside any task | |
| `runtime.quickCancel` | Stop a quick run under way (its process tree killed) | |
| `runtime.signIn` | Rerun this turn when its sign-in lands | |
| `runtime.signInDone` | A sign-in finished | |
| `runtime.overage` | A turn billed past its plan | |
| `runtime.agent.sessions` | An agent lists the user's tasks (wisp_sessions) | yes |
| `runtime.agent.watch` | An agent keeps a page beside its task (wisp_watch) | |
| `runtime.agent.session` | An agent reads a task (wisp_session) | yes |
| `runtime.agent.tag` | An agent tags its task with its topics (wisp_tag) | |
| `runtime.agent.blocks` | An agent reads the fields of answer blocks (wisp_blocks) | yes |
| `runtime.agent.stats` | An agent reads tool stats across the user's tasks (wisp_stats) | yes |
| `runtime.agent.available` | An agent reads what it can run work on (wisp_available) | yes |
| `runtime.agent.task` | An agent acts on another task (wisp_task) | |
| `runtime.profiles` | Agent profiles | yes |
| `runtime.profile.set` | Add or change an agent profile | |
| `runtime.profile.remove` | Remove an agent profile | |
| `runtime.spec` | A task's spec: what was asked, from which code, under which formula | yes |
| `runtime.snapshot` | The formula a task ran with | yes |
| `runtime.history` | Tasks by what made them | yes |
| `runtime.adopt` | Import a shared task, read-only | |
| `runtime.projectRun` | Run a project's run scripts | |
| `runtime.discover` | Git repos on this computer that aren't projects yet | yes |
| `runtime.folders` | Folders a typed path could go on to (the folder pickers' suggestions) | yes |
| `runtime.exec` | Run a one-click command from a presentation in the task's folder | |
| `runtime.appState` | Keep an app block's state on its turn | |
| `runtime.usage` | Spend, turns, how many worked and questions asked over the last days | yes |
| `runtime.projectTest` | Set the command that runs a project's tests | |
| `runtime.projectAdd` | Add a folder as a project (the same folder stays one project; a taken name gets -2) | |
## wisp.sandbox
Sandboxes on your wisp Grid: a task's (/sandbox), a delegate's, a crew job's or member's, a goal's judges'; seeded with the project, deleted with their owner (ADR-0047)
| Command | What it does | Reads |
| --- | --- | --- |
| `sandbox.launch` | Start a task in a sandbox of its own (/sandbox) | |
| `sandbox.place` | A seeded sandbox for a delegate, a crew job or member, or a goal's judges | |
| `sandbox.seed` | Take a project in (inside a sandbox only) | |
| `sandbox.patch` | A project's changes since it came in (inside a sandbox only) | yes |
| `sandbox.bring` | A delegate's changes in its sandbox, into the lead's folder here | |
| `sandbox.own` | Name a sandbox's owner once it exists (a crew job's task) | |
| `sandbox.drop` | Delete the sandboxes of a task, a crew member, or one by its machine | |
| `sandbox.info` | Your sandboxes, their owners, and what they start with | yes |
| `sandbox.claude.begin` | Sign in to Claude for every sandbox (claude setup-token) | |
| `sandbox.claude.code` | The code Claude's sign-in page showed | |
| `sandbox.claude.state` | How the Claude sign-in for sandboxes is going | yes |
| `sandbox.logout` | Take a sandbox sign-in off the grid | |
| `sandbox.env` | An env var every sandbox gets (empty: taken out) | |
## wisp.settings
wisp.settings: list, read and change every plugin's settings (the kernel's registry), and /config
| Command | What it does | Reads |
| --- | --- | --- |
| `settings.list` | Every setting | yes |
| `settings.get` | A setting's value | yes |
| `settings.set` | Change a setting | |
## wisp.share
share a task as a signed .wisp-task bundle (spec, report or full), previewed with its redactions; open one someone sent; send any share to a destination (wisp Cloud) through share.destination@1
| Command | What it does | Reads |
| --- | --- | --- |
| `share.preview` | What a share of this task would send | yes |
| `share.bundle` | Share a task (a signed bundle) | |
| `share.open` | Open a shared task | yes |
| `share.import` | Import a shared task, read-only | |
| `share.send` | Share a task, a setup or a doc to a destination (wisp Cloud) | |
| `share.destinations` | Where shares can go, and whether each is ready | yes |
| `share.create` | Share a task as a link (a passkey locks it) | |
| `share.stop` | Stop sharing a task's link | |
| `share.peek` | What a pasted share link is, before it's taken in | yes |
## wisp.ship
Ship it: commit what a worktree task left, push its branch, open or update its PR; follow its checks and reviews, fix conflicts with a follow-up, squash-merge the reviewed head and fast-forward the user's checkout.
| Command | What it does | Reads |
| --- | --- | --- |
| `ship.fix_conflicts` | Fix a task's PR conflicts: the task merges its base in | |
| `ship.check_log` | The end of a failing check's log | yes |
| `ship.agent.pr` | Attach a PR to a task, or detach one, as its agent (wisp_pr) | |
| `ship.track` | Track a task's repos for Ship it | |
| `ship.view` | What a task would ship | yes |
| `ship.ship` | Commit, push and open a pull request | |
| `ship.write` | Have a task's agent write its pull request's title and description | |
| `ship.refresh` | Ask GitHub about a task's pull requests | |
| `ship.details` | A task's pull requests in full | yes |
| `ship.merge` | Squash-merge a task's pull request | |
| `ship.attach` | Attach a pull request to a task | |
| `ship.recheck` | Recheck what a task has to ship | |
## wisp.stuff
My Stuff: what you and your agents kept from tasks (pictures, videos, docs, code, files, links and apps), the apps' launches and databases, the panes wisp ships, and uploads
| Command | What it does | Reads |
| --- | --- | --- |
| `stuff.list` | List My Stuff | yes |
| `stuff.get` | Read one item | yes |
| `stuff.find` | Find in My Stuff (wisp_stuff) | yes |
| `stuff.describe` | One item in full, for an agent | yes |
| `stuff.grant` | What a pane may use now | yes |
| `stuff.save` | Save to My Stuff | |
| `stuff.update` | Edit an item | |
| `stuff.restore` | Back to the version before | |
| `stuff.remove` | Remove from My Stuff | |
| `stuff.allow` | Allow a pane what it asks for | |
| `stuff.setPublished` | Record where an app is published | |
| `stuff.bundle` | An app's files packed for publishing (its secrets left out) | yes |
| `stuff.launch` | Launch an app | |
| `stuff.stop` | Stop an app | |
| `stuff.resetData` | Reset an app's data | |
| `stuff.upload` | Read an attachment | yes |
| `stuff.receive` | Keep a file that came another way (an email's attachment) as an upload | |
| `stuff.uploads` | Read attachments | yes |
| `stuff.removeUpload` | Remove an attachment | |
| `stuff.starters` | The panes wisp ships | yes |
| `stuff.addStarter` | Add a starter pane to My Stuff | |
| `stuff.reveal` | Show an item in its folder | |
| `stuff.targets` | Where an app can be published | yes |
| `stuff.publish` | Publish an app: a link anyone can open | |
| `stuff.unpublish` | Take an app's public link down | |
| `stuff.agent.save` | Save to My Stuff, as a task's agent (wisp_save) | |
| `stuff.agent.list` | My Stuff as a task's agent reads it (wisp_stuff) | yes |
## wisp.telemetry
wisp.telemetry: anonymous usage stats: the catalogue, opt-out, scrubbing, batching and the distinct id, delivered to every telemetry.sink (ADR-0021)
| Command | What it does | Reads |
| --- | --- | --- |
| `telemetry.track` | Record a usage event | |
| `telemetry.set` | Usage stats on or off | |
| `telemetry.flush` | Send what is queued now | |
| `telemetry.feedback` | Send feedback to the wisp team | |
## wisp.termctx
wisp in a terminal knows what just happened there: the terminals' own read commands (tmux, WezTerm, kitty, iTerm2, Terminal), the opt-in shell hook's log, and terminal.failed as a trigger source (ADR-0023)
| Command | What it does | Reads |
| --- | --- | --- |
| `termctx.sources` | How to read this terminal's recent output | yes |
## wisp.terminal
wisp.terminal: the plugin, wired to the kernel, proc and HTTP routes
| Command | What it does | Reads |
| --- | --- | --- |
| `terminal.open` | Open a terminal | |
| `terminal.input` | Type into a terminal | |
| `terminal.close` | Hang a terminal up | |
| `terminal.shell.start` | Start the task's shell | |
| `terminal.get` | A terminal | yes |
| `terminal.shell.info` | The task's shell, for the panel | yes |
| `terminal.app.open` | Open a folder (and a command) in the terminal app Settings names | |
| `terminal.run.start` | Run the task's app for its Preview | |
| `terminal.run.info` | The task's app: running or not, its port, a command to start from | yes |
| `terminal.apps` | This computer's terminal apps | yes |
## wisp.threads
Long threads (ADR-0079): a task's Notes kept outside the conversation (wisp_notes, the Thread tab, wisp notes), the note before each follow-up, the thread's health, and where long command output goes
| Command | What it does | Reads |
| --- | --- | --- |
| `threads.notes` | A task's Notes: its goal, constraints, decisions, what failed, where it stands | yes |
| `threads.notesUpdate` | Rewrite one section of a task's Notes | |
| `threads.revisions` | Every earlier version of a task's Notes, with who wrote it | yes |
| `threads.health` | How worn a task's thread is: context, compactions, turns, the same error again | yes |
| `threads.freshBrief` | The brief a fresh thread would start from (the Notes, the files changed, the last turns), to read and edit | yes |
| `threads.fresh` | Start a new conversation on the same task from a brief; the old one stays linked | |
| `threads.audits` | What each compaction kept of a task's goal, constraints, decisions and what failed | yes |
## wisp.update
wisp.update: a newer wisp, checked daily (npm dist-tags or GitHub Releases), and installed with npm or Homebrew
| Command | What it does | Reads |
| --- | --- | --- |
| `update.check` | Check for a newer wisp now | |
| `update.install` | Install the newer wisp | |
| `update.view` | This wisp's version, and the newest one | yes |
## wisp.workflows
orchestration as code: DAGs of task specs with needs, if, matrix, outputs, retries, timeouts, budget and concurrency
| Command | What it does | Reads |
| --- | --- | --- |
| `workflows.list` | Workflows | yes |
| `workflows.set` | Add or change a workflow | |
| `workflows.remove` | Remove a workflow | |
| `workflows.run` | Run a workflow | |
## wisp.worktrees
A checkout per session: made from the fresh base, prepared (.worktreeinclude, setup steps), brought back, removed only when nothing would be lost; Settings → Worktrees and the hourly sweep; Done's folders; project trust, a before:run guard that holds a turn until the repo's own programs are trusted.
| Command | What it does | Reads |
| --- | --- | --- |
| `worktrees.source` | Open a file of a task's folder (the file view) | yes |
| `worktrees.save` | Save a file of a task's folder (refused while it runs, or if it changed) | |
| `worktrees.files` | A task folder's (or a project's) files, as git lists them | yes |
| `worktrees.warm` | Fetch a project's remote now, while its task is typed (New task) | yes |
| `worktrees.grep` | Where a name is declared in a task's folder (Go to definition) | yes |
| `worktrees.create` | Make a session's worktree | |
| `worktrees.ensure` | Bring a removed worktree back from its branch | |
| `worktrees.remove` | Remove a worktree when nothing would be lost | |
| `worktrees.status` | A worktree's changes, commits and pushes | yes |
| `worktrees.view` | Worktrees on disk | yes |
| `worktrees.viewLast` | Worktrees on disk, as last looked | yes |
| `worktrees.clean` | Remove worktrees by hand | |
| `worktrees.keep` | Keep a task's worktree, or stop keeping it | |
| `worktrees.bringIn` | Bring in worktrees another tool left in a project, as tasks | |
| `worktrees.dismiss` | Stop offering a project's other worktrees (Not now) | |
| `worktrees.sweep` | Tidy idle worktrees now | |
| `worktrees.done.list` | Done's folders | yes |
| `worktrees.done.apply` | Remove or keep Done's folders | |
| `worktrees.done.tidy` | Remove what's clean and on its branch | |
| `worktrees.trust` | Trust a repo's setup and start | |
| `worktrees.trust.pending` | What a repo would run before it is trusted | yes |
---
# Settings
Source: https://trywisp.dev/docs/reference/settings.md
> Generated from the code by `apps/docs/scripts/reference.mjs`: edit the source, not this page.
Every setting, by plugin, as Settings shows it and `wisp.yml` sets it (`settings:` with the key). The default applies until you change it.
## wisp.accounts
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `accounts.updateCheck` | bool | `true` | Check for newer harness versions: once a day, wisp asks npm for the latest Claude Code, Codex and opencode (npm then knows which of them you have) |
## wisp.automations
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `automations.webhookTriggers` | bool | `false` | Webhook triggers: other services may start this computer's webhook triggers (POST /api/triggers/ with its secret) |
## wisp.budget
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `budget.drainWatch` | bool | `false` | Drain watch: tell the phone when a plan moves much faster than usual for the same work |
| `budget.limitHold` | `off` · `80` · `90` · `95` | `"90"` | Ask near the limit: before a task would take a usage window past this percent, ask first (automations wait for the reset) |
| `budget.liveLimits` | bool | `false` | Check Codex while work waits: read its usage every 10 minutes while work waits for its plan (spends nothing) |
| `budget.silentStop` | `off` · `1` · `2` · `4` · `8` | `"off"` | Stop a run silent for: stop a run with no output for this many hours (a run silent 30 minutes while its plan moves is always told to your phone) |
| `budget.spareCard` | bool | `true` | Spare allowance: say on home when a weekly window resets within a day with a fifth or more left |
| `budget.windowNotice` | bool | `true` | Window notices: say when a usage window changed length or resets early |
## wisp.channels
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `channels.acceptChannels` | bool | `false` | Accept tasks from channels: messages routed here through wisp Cloud (“on this computer …”) may start tasks. Switch it on at this computer. |
| `channels.project` | string | `""` | Default project: where a task from a channel (Slack, Discord, Telegram, email) runs when its message names none ('': the last used) |
## wisp.crew
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `crew.tint` | bool | `true` | Crew tint: with the crew rail, the task list takes a very light tint of the colour of the member you pick. |
## wisp.events
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `events.sinks` | json | `[]` | Event sinks |
## wisp.git
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `git.maskEnvFiles` | bool | `true` | Hide .env values: what a task shows of a .env file (its output, edits, blocks, Changes) leaves wisp as dots until you reveal one |
| `git.cloneDir` | string | `""` | Where a pasted repo URL is cloned ('': the first of ~/code, ~/dev, ~/Developer, ~/projects… that exists, else ~/code) |
## wisp.grid-client
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `grid-client.previews` | bool | `false` | Show local pages in previews |
## wisp.learn
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `learn.enabled` | bool | `true` | Learn from your tasks: a short retro after each quiet task, kept as preferences and lessons later tasks follow |
## wisp.machine
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `machine.memoryFloor` | `off` · `10` · `15` · `20` · `25` | | Automations wait while free memory is under this percent |
| `machine.cpuCeiling` | `off` · `100` · `150` · `200` | | Automations wait while the CPU stays over this percent of a core per core |
| `machine.maxRuns` | `off` · `4` · `6` · `8` · `12` · `16` · `auto` | | Runs at once before automations wait |
| `machine.batteryHold` | `off` · `20` · `40` | | On battery under this percent, check-ins and the crew queue wait |
## wisp.review
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `review.harness` | `off` · `other` · `claude` · `codex` · `antigravity` · `copilot` · `opencode` · `cursor` · `grok` | `"off"` | Review by another harness |
## wisp.runtime
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `runtime.retentionDays` | int | `0` | Days a finished task stays in the list before it's archived (0: always) |
| `runtime.leanRuns` | `off` · `on` · `all` | `"on"` | Lean Claude Code runs (no telemetry or update checks, and no claude.ai connectors): on, only wisp's own side runs; all, every run; off, none |
| `runtime.apps` | bool | `true` | Interactive answers: agents may answer with a small app |
| `runtime.watch` | bool | `true` | Watch agents work: agents may open what they built in wisp's browser to check it |
| `runtime.blocks` | bool | `true` | wisp blocks: answers come as cards (off: plain markdown) |
| `runtime.subagentModel` | `task` · `haiku` · `sonnet` | `"task"` | The model Claude Code's subagents run on (task: the task's own) |
| `runtime.projectOrder` | json | `[]` | Your project order (names): the chips, New task's row and the Projects list show them so; drag to change it |
| `runtime.subagents` | json | `[]` | The team new tasks start with: [{ name, agent, model?, effort?, use? }] (New task pre-fills it; a task's own team wins) |
| `runtime.auto` | bool | `false` | Auto: wisp picks the harness, model and thinking level for each task. Off until it's reworked (the owner, 2026-11-17): the one switch; the app hides Auto while it's off |
| `runtime.launch` | json | `{}` | New task's last pick: { agent, models: { : model }, labels: { : name }, efforts: { : level } }; a task that names no harness runs on its agent |
| `runtime.teams` | json | `[]` | Delegate's saved teams (presets): [{ id, name, members: [{ name, agent, model?, effort?, use?, count?, machine? }] }]; Presets picks one, Save as preset keeps one |
| `runtime.limitWait` | bool | `false` | Wait for the reset: a task at its usage limit carries on by itself after the reset, in the same conversation |
| `runtime.followUp` | `interrupt` · `queue` | `"interrupt"` | A follow-up while a task works: interrupt it, or queue after it |
| `runtime.setupAnswerSets` | json | `[]` | The API keys' capability sets (custom:) you let answer an agent's setup cards (ADR-0113): none unless you list them |
## wisp.settings
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `settings.timeZone` | string | `""` | Time zone: the one scheduled times are read in, an IANA name like Europe/Zurich (the app sets it from your device) |
| `settings.editor` | string | `"vscode"` | The editor files open in (vscode, cursor, windsurf, zed, idea, none) |
| `settings.notify` | `on` · `off` | `"off"` | Desktop notifications when a task needs you or finishes |
| `settings.readTimes` | `on` · `off` | `"on"` | Read times in prompts: a prompt that starts with a time (“in 5 min …”, “tomorrow at 9 …”) is scheduled for then |
| `settings.transcript` | `on` · `off` | `"off"` | Open tasks on their transcript instead of the answer |
## wisp.ship
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `ship.fixConflicts` | bool | `false` | Fix merge conflicts by itself: when a task's PR has conflicts, its agent is asked to fix them without waiting for you |
## wisp.stuff
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `stuff.panes` | string | `""` | Panes: @task or @home, comma separated |
## wisp.termctx
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `termctx.enabled` | bool | `true` | Terminal context: wisp in a terminal may attach what just happened there |
## wisp.terminal
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `terminal.terminal` | string | `"wisp"` | Open tasks in: wisp, one of this computer's terminal apps (its id) or custom |
| `terminal.command` | string | `""` | Take over with a custom command ({cmd} is the agent's resume command) |
| `terminal.terminalSessions` | `on` · `off` | `"off"` | Babysitting mode: each task opens straight in the agent's own terminal |
## wisp.threads
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `threads.compactAudit` | bool | `false` | Check compactions: after a compaction, wisp asks a copy of the conversation what it still remembers of the task's Notes and reminds the agent of what it lost (one short extra run each) |
## wisp.update
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `update.updateChannel` | `stable` · `beta` · `nightly` | `"stable"` | Update channel |
## wisp.worktrees
| Key | Type | Default | What it does |
| --- | --- | --- | --- |
| `worktrees.cleanup` | `off` · `3` · `7` · `14` · `30` | | Idle worktrees go after this many days (unset: 7, counted from when wisp got it) |
| `worktrees.max` | `off` · `20` · `40` · `80` | `"40"` | Worktree folders kept before the oldest idle ones go |
| `worktrees.onDone` | `ask` · `remove` · `keep` | `"ask"` | When a task is done, its worktree folders |
| `worktrees.projectAsk` | `on` · `off` | `"on"` | Ask before trusting a new project's setup scripts |
| `worktrees.worktree` | `on` · `off` | `"on"` | New tasks run in their own worktree by default |
---
# MCP tools
Source: https://trywisp.dev/docs/reference/mcp-tools.md
> Generated from the code by `apps/docs/scripts/reference.mjs`: edit the source, not this page.
wisp serves its tools over MCP. A task's agent gets them on every run; `wisp mcp` serves them (stdio) to any agent or editor you point at it, so you can drive wisp from where you already work.
## In a task
What an agent wisp runs can call.
| Tool | What it does | Arguments (? optional) |
| --- | --- | --- |
| `ask_user` | Ask the user a question through wisp and wait for their answer. Use when a decision would change the rest of your work (ambiguous requirements, risky/destructive steps, choosing between approaches). The user may take minutes or hours to answer. Do not use it for trivial choices you can make yourself. | `question`, `context`?, `options`? |
| `resume_later` | Schedule a follow-up to this same task: at that time wisp sends your message back to you in this conversation, with your full context, as if the user had typed it. Use it when you must wait before you can go on (a deploy rolling out, CI running, a rate limit, "check again in 10 minutes"), or when the user asks you to do something later ("in 5 minutes do X"). After scheduling, end your turn with your report saying what you will check then; do not sleep or poll. Pass cancel with an id to drop one you scheduled. | `minutes`?, `at`?, `message`?, `cancel`? |
| `wisp_tag` | Tag this task with the topics it is about, so the user can find it later by searching wisp (⌘K, or #tag). Call it once you know what the task is about, in your first turn, and again only if the work moves to another topic: it replaces the tags. 3–8 short lowercase words or hyphenated terms a person would search for: the area or feature (auth, billing, search), the tech (redis, react, postgres), the kind of work (bugfix, refactor, research, release). Not the project name or words already in the title. | `tags` |
| `wisp_pr` | Attach a GitHub pull request to this task, so the user sees it on the task like one opened with Ship it: its state, checks and reviews, kept current, with Merge. Call it for every PR you open (gh pr create) or work on in this task, one call per PR; a task can have several. remove=true detaches one. | `pr`, `remove`? |
| `wisp_watch` | Let the user watch your work while you do it, instead of waiting for your answer: put up a page beside this task in wisp and keep it current as you go. Worth it for long or many-step work the user would like to follow (a migration across many files, a test or benchmark run, a crawl, a data job, a design taking shape); not for quick tasks or plain questions. You decide what the page shows and how: a progress bar and a checklist, a table filling in, a chart, a diagram growing. Two ways: a page you write that draws your progress, or the real thing running (the app you are building, on its dev server). action "open": html (one self-contained page: inline CSS and JS; scripts, styles and fonts from https CDNs are fine; no fetch, no relative files), path (an .html file you wrote, read again on "reload"), or url (a running app, e.g. `http://localhost:5173:` start its dev server first, in the background), a title, and optionally run: { command, cwd, note }, how the user runs or checks the thing themselves (shown under the page). The page uses wisp's theme as CSS variables (var(--ink), var(--muted), var(--line), var(--accent), var(--good), var(--bad), var(--surface), var(--sans), var(--mono)) and gets your data with wisp.on('state', (s) => draw(s)) (called with the last state at once, then on every update; wisp.state is the last one). action "state": state (JSON, up to 64 KB: what the page draws now; merge: true merges it into the last one), caption optional. Send it after each meaningful step, not on every keystroke. action "caption": one line on what you are doing now. With a url: action "navigate" with path ("/settings") or url shows the page you just changed; "reload" when hot reload missed it; "state" is for your own page only. action "reload": after you edited the page. action "close": when the work is done (the page stays, with its last state; a url keeps showing while its server runs). | `action`, `title`?, `html`?, `path`?, `url`?, `state`?, `merge`?, `caption`?, `run`? |
| `wisp_save` | Save something to the user's My Stuff in wisp: their shelf of things kept from tasks (pictures, videos, documents, code, any file, links), where they browse and search them later. wisp keeps a copy, so it stays when the task or its folder goes. Call it when the user asks you to save or keep something for them ("save that to my stuff", "keep the logo"), not on your own for everything you make. One item per call; give exactly one of path, text, url or app. For a bigger thing (slides, a demo, a small tool), build it as a static web app (index.html with its JS, CSS and assets; no server, no install step; bundle dependencies in or load them from a CDN) and save its folder as app: wisp serves and launches it for the user. With id, it updates an item they already have (a mentioned one, or from wisp_stuff) instead of adding one; the version before is kept. Show what you saved in your answer as a "stuff" block with its id. | `path`?, `text`?, `url`?, `app`?, `cover`?, `id`?, `name`?, `title`?, `note`?, `tags`?, `pin`?, `publish`? |
| `wisp_stuff` | List or search the user's My Stuff in wisp: what they (or agents) saved from tasks, newest first, each with its title, kind, note, tags and the path of its file (or its url). Read-only. Use it when the user refers to something they saved ("use the logo from my stuff"): read or copy the file from its path. | `query`?, `id`?, `kind`?, `limit`? |
| `wisp_blocks` | The fields of answer blocks your instructions only name (graph, app), with an example. Read one before you put it in your final message. Read-only and answered at once. | `types` |
| `wisp_stats` | Read-only stats about the user's past wisp tasks: how many tool calls each kind of action made (run = shell, read, edit, search, web, agent, tool = other MCP tools, ask), broken down by harness, project and day, plus turns, cost, tokens and success rate. Use when the user asks about their wisp usage, which tools or harnesses their tasks use, or what tasks cost. | `days`?, `agent`?, `project`? |
| `wisp_sessions` | List the user's other wisp tasks, newest first: id, title, state (running \| waiting \| review \| done), harness, project, last update and a one-line summary. Read-only. Use it to find a task the user refers to; read one with wisp_session. | `query`?, `state`?, `project`?, `archived`?, `limit`? |
| `wisp_session` | Read another wisp task by id: its title, state, harness, folder and branch, every request the user made in it, and a turn's report as markdown (summary, diffs, tests, next steps). Read-only. Use it when the prompt mentions a wisp task ("@Title (wisp task )") or the user asks what another task did. | `id`, `turn`? |
| `wisp_crew` | List the user's crew in wisp: their long-lived agents, each with a name, role, brief, folder, harness, schedule and jobs. Read-only. Use it before changing a member, or when the user asks who is on their crew. With `member`: that one in full, their whole brief, notebook and kit (skills and instructions files, with their text), to read before you change their notebook or propose kit files. | `member`? |
| `wisp_crew_add` | Add a member to the user's crew in wisp, when the user asks for one ("add a crew member who watches CI"), or when you need help for a job and the user's brief lets you hire it. They work as tasks: on their schedule (cron), when the user tags @Name in a prompt, or when another task delegates to them. Write the brief to them, from what the user asked. Pick a short, friendly name if the user gave none. Returns the new member. When the user gives a shared crew file or link ("add the member from gist:abc123"), pass it as `from` instead. | `name`?, `role`?, `brief`?, `cwd`?, `agent`?, `model`?, `effort`?, `mode`?, `cron`?, `parallel`?, `paused`?, `avatar`?, `checkin`?, `from`? |
| `wisp_crew_edit` | Change a member of the user's crew in wisp (rename, new brief, schedule, folder, harness, pause, notebook…) when the user asks. Only the fields given change. Their skills and instructions files aren't set here: propose those with wisp_crew_kit. | `member`, `name`?, `role`?, `brief`?, `cwd`?, `agent`?, `model`?, `effort`?, `mode`?, `cron`?, `parallel`?, `paused`?, `avatar`?, `notebook`?, `remember`? |
| `wisp_crew_kit` | Propose skills or instructions files for a crew member's kit, when the user asks you to give them, write or improve one ("give Gucci a skill for UI reviews"). A skill is a how-to for one kind of work, read when a job fits its description; an instructions file (rules, e.g. AGENTS.md) is followed on every job. Nothing changes yet: wisp shows the files under your answer, and the user reads them and picks what to add. The same name as one they have replaces it. Read the member with wisp_crew { member } first. Write each file for them: concrete steps, checklists, commands and paths, not generic advice. | `member`, `files` |
| `wisp_crew_remove` | Remove a member from the user's crew in wisp. Their brief, notebook and schedule are deleted; their jobs stay as ordinary tasks. Only when the user asked to remove that member, or a member you added for a job is done; if unsure who they meant, ask the user first. A crew member's job can't remove that member itself. | `member` |
| `wisp_connectors` | List the user's connectors in wisp: MCP servers that every task's agent gets (in Edits and Full auto), whatever the harness. Each with its URL or command and whether it works, how many tools it has, or what it needs (a sign-in, a key). Read-only. | |
| `wisp_connector_add` | Add an MCP server to the user's connectors in wisp, when the user asks ("add PostHog", "connect Linear"). Remote: give its URL (for well-known services look up their official MCP URL, e.g. https://mcp.posthog.com/mcp). Local: give the command that starts it. Never pass secret values: list the names of the env vars (local) or headers (remote) it needs, and then call wisp_connector_signin, where the user signs in or types them. A local one asks the user first, since it runs a command on their computer. wisp checks it at once and says whether it works or what it needs. Tasks get it from their next turn. | `name`, `url`?, `command`?, `env`?, `headers`? |
| `wisp_connector_signin` | Show the user a card in this task to sign in to a connector (a Sign in button for servers with an account, like PostHog or Linear) or to type the keys it needs, and wait like ask_user. It ends on its own once the connector works, or when the user skips. Call it after wisp_connector_add or wisp_connectors says one needs a sign-in or keys. | `name`, `why`? |
| `wisp_available` | What the user has in wisp to run work on, in one read: harnesses on this computer (installed or not, models, thinking levels), their machines (other computers and cloud computers, online or not, the harnesses on each), projects, saved subagent presets, this task's own subagents and the crew. Read-only. Read it before you pick a harness, model or machine for delegate or wisp_launch. | |
| `wisp_launch` | Start a new wisp task, as the user would from wisp's prompt box: its own agent, conversation and card, which the user follows and replies to on its own. Use it when the user asks you to start, kick off or hand off tasks ("start a task to…", "open a new conversation for…", "run this on my devbox"); for help with your own work, use delegate instead. Returns the new task's id at once (wait=true blocks until it finishes or asks). Show each task you start in your answer as a "task" block. | `prompt`, `project`?, `cwd`?, `scratch`?, `also`?, `machine`?, `agent`?, `model`?, `effort`?, `mode`?, `worktree`?, `goal`?, `factory`?, `formula`?, `subagents`?, `preset`?, `wait`?, `timeout_seconds`? |
| `wisp_task` | Act on another wisp task, as the user would from its card. action: reply (a follow-up, or the answer when it is asking; agent, model, effort or mode switch it from then on; queue=true waits for its current run instead of interrupting), stop, done (mark it done), archive, unarchive, rename (title), or wait (block until it finishes or asks, then return its report). Only when the user asks, or for tasks you started. Find tasks with wisp_sessions. | `task`, `action`, `text`?, `queue`?, `mode`?, `agent`?, `model`?, `effort`?, `title`?, `timeout_seconds`? |
| `approve` | Internal: wisp asks the user to approve a tool call your permissions do not allow on their own. Never call this yourself. | `tool_name`, `input`?, `tool_use_id`? |
| `subagent_results` | Wait for delegated tasks and return their reports. Pass the ids delegate returned; with none, every task delegated in this turn. | `ids`?, `wait`? |
| `wisp_plugins` | The plugins the user has: their own first (on or off, untrusted unless they trusted one), each in plain words with where it shows, what it may do, its folder and its whole wisp-plugin.json; then wisp's built-in ones, one line each. Read-only. Use it before writing or changing a plugin. | |
| `wisp_plugin_schema` | The complete reference for writing a wisp plugin the user installs (the untrusted tier): manifest fields, the UI module's wisp API, kit descriptors (components, props, events), tokens, parts and icons, where it may show, every command it may call with the permission it needs, and worked examples. Read-only. | |
| `wisp_plugin_data` | Run a read-only wisp command a plugin would call (wisp.call) and return a sample of its real answer, so the plugin reads the right fields. Only commands that read, and only those this task may run. Read-only. | `command`, `args`? |
| `wisp_plugin_check` | Check a plugin without installing it. Returns ok and what it does in plain words, or every problem to fix. Nothing of it runs: the manifest goes through wisp's own checker and each UI module's text is read for what fails in its sandbox. | `manifest`, `files`? |
## From your agent or editor (`wisp mcp`)
What `wisp mcp` offers outside a task.
| Tool | What it does | Arguments (? optional) |
| --- | --- | --- |
| `wisp_launch` | Hand a coding task to a background agent in wisp. The agent works autonomously in the given folder and ends with a presentation (summary, diffs, test results). Returns the session id at once; pass wait=true to block until it finishes or asks a question. Use for independent, well-scoped tasks that can run in parallel with your own work. | `prompt`, `project`?, `cwd`?, `also`?, `agent`?, `mode`?, `model`?, `effort`?, `worktree`?, `goal`?, `factory`?, `formula`?, `subagents`?, `preset`?, `machine`?, `wait`?, `timeout_seconds`? |
| `wisp_list` | List wisp sessions, newest first, with state (running \| waiting \| review \| done) and a one-line summary. | `state`?, `cwd`?, `limit`? |
| `wisp_get` | Read a session: its state and the latest presentation as markdown (diffs, tests, next steps), plus any question the agent is waiting on. | `id` |
| `wisp_wait` | Block until a session finishes or asks a question, then return it like wisp_get. Returns early with timed_out if it is still running. | `id`, `timeout_seconds`? |
| `wisp_reply` | Send a follow-up to a session; it resumes the same agent conversation. If the agent is waiting on a question, this answers it. A follow-up sent while it runs interrupts it (queue=true waits for the run to finish instead). mode switches the session’s mode from this follow-up on. agent / model / effort switch the harness, model or thinking level from this follow-up on (see wisp_agents); a new harness is handed the conversation so far. | `id`, `text`, `queue`?, `mode`?, `agent`?, `model`?, `effort`? |
| `wisp_stop` | Stop a running session. | `id` |
| `wisp_agents` | Which harnesses are installed, with their models and thinking levels, and the user’s machines (other computers, cloud computers) with theirs. | |
---
# Answer blocks
Source: https://trywisp.dev/docs/reference/answer-blocks.md
> Generated from the code by `apps/docs/scripts/reference.mjs`: edit the source, not this page.
An agent wisp runs ends its final message with a ```wisp block: `{"blocks": [...]}`. wisp draws each block (the diff, the tests, the preview…) and hides the rest of the message. This is the catalogue the agent is given, word for word.
## `hero`
```json
{"type":"hero","title":"","topic":"","summary":"<1–2 sentences>","status":"done|partial|blocked|info"}
```
Always first. "topic" is what the user asked about as a short noun phrase ("Rate limit on /login"), not what you did; wisp names the task with it. Optional after the first turn.
## `markdown`
```json
{"type":"markdown","text":""}
```
## `steps`
```json
{"type":"steps","title":"…","items":[{"title":"…","detail":"…","status":"done|skipped|failed"}]}
```
What you did, in order.
## `stats`
```json
{"type":"stats","items":[{"label":"tests passing","value":42,"unit":"","delta":"+6","tone":"good|bad|neutral"}]}
```
Numbers animate; use real numbers only.
## `files`
```json
{"type":"files","items":[{"path":"src/a.ts","change":"added|modified|deleted|renamed","note":"why"}]}
```
## `diff`
```json
{"type":"diff","file":"src/a.ts","caption":"…"}
```
Shows the REAL diff of your edits to that file (wisp captured them). Use for the 1–3 most important changes. Optionally add "before"/"after" strings to show a hand-picked snippet instead.
## `tests`
```json
{"type":"tests","command":"npm test","passed":48,"failed":1,"skipped":2,"durationMs":5300,"failures":[{"name":"auth > rejects expired token","message":"expected 401, got 500","file":"test/auth.test.ts:42"}]}
```
A test/lint/type-check run you actually executed. Prefer this over "terminal" for test runs.
## `commits`
```json
{"type":"commits","items":[{"hash":"a1b2c3d","message":"feat(auth): add rate limiter","files":3,"additions":120,"deletions":8}],"branch":"feat/limit"}
```
Commits you created, if any.
## `graph`
```json
{"type":"graph",…} Branch graph: merge conflicts, a rebase, where branches diverged. Read its fields with `wisp_blocks` (mcp__wisp__wisp_blocks) before you use it.
```
## `tree`
```json
{"type":"tree","title":"…","items":[{"path":"src/auth/limiter.ts","change":"added","note":"…"}]}
```
A file tree; use for new modules/scaffolding where structure matters.
## `code`
```json
{"type":"code","language":"ts","code":"…","caption":"…","file":"src/a.ts","line":10,"highlight":[3,4]}
```
Key snippet (new API, signature, config) — not whole files.
## `compare`
```json
{"type":"compare","before":{"label":"Before","items":["…"]},"after":{"label":"After","items":["…"]}}
```
## `flow`
```json
{"type":"flow","title":"…","nodes":[{"id":"a","label":"Request","note":"…"}],"edges":[["a","b","label"]]}
```
Architecture / data flow / sequence. Edges optional (nodes are chained in order if omitted).
## `chart`
```json
{"type":"chart","title":"…","unit":"ms","items":[{"label":"before","value":420},{"label":"after","value":95}]}
```
## `terminal`
```json
{"type":"terminal","command":"npm test","output":"","exitCode":0}
```
## `checklist`
```json
{"type":"checklist","title":"…","items":[{"text":"…","done":true}]}
```
Where a ship, release or deploy stands, one item per stage, done or not.
## `callout`
```json
{"type":"callout","tone":"info|success|warn|danger","title":"…","text":"…"}
```
Risks, caveats, assumptions you made. Rare: if every answer has one, none stand out.
## `image`
```json
{"type":"image","path":"relative/or/absolute.png","caption":"…"}
```
A screenshot or generated image on disk. Every UI change gets one (desktop and phone if both matter).
## `video`
```json
{"type":"video","path":"relative/or/absolute.mp4","caption":"…"}
```
A video you made or recorded (mp4, webm, mov), played inline. Use it instead of linking the file.
## `preview`
```json
{"type":"preview","url":"http://localhost:5173/settings","device":"mobile|tablet|desktop|1280x720","title":"…","caption":"…"}
```
A live web page shown in the answer, in a sandboxed frame at that screen size: a dev server you started, a deployed page you changed. The best evidence for a new feature: the user clicks through it in place. Point the url at the page that shows the change, not the root. Pick the device that shows it (mobile for a responsive fix); the user can switch sizes. Keep the server running and say so.
## `map`
```json
{"type":"map","title":"…","places":[{"name":"Blue Bottle Coffee","address":"66 Mint St, San Francisco, CA 94103","note":"…"}],"route":false}
```
Addresses or places (an office, a venue, shops to visit): wisp shows them on a Google map, each with Open in Google Maps. Full street addresses, or "lat"/"lng"; all of them in one block. "route": true adds directions through them in order.
## `doc`
```json
{"type":"doc","path":"docs/plan.md","title":"…","caption":"…"}
```
A markdown file you wrote for the user to read (a plan, report, spec, ADR). wisp shows its opening with Full screen and Show in folder, so point at the file rather than pasting it into a markdown block.
## `task`
```json
{"type":"task","id":"8e64708d4b75","note":"…"}
```
Another wisp task (from wisp_sessions or wisp_session) that you found or point to. wisp shows its title and state and the user opens it with a click. Use one per task instead of naming ids in prose.
## `stuff`
```json
{"type":"stuff","id":"0bac5acb43c9","note":"…"}
```
Something you saved or updated in the user's My Stuff (its id). An app shows with Launch and opens inside wisp; the rest with Open. One per thing you saved this turn.
## `question`
```json
{"type":"question","question":"…","options":[{"label":"Short choice","reply":"full message sent back to you"}]}
```
When you need a decision. The user's click resumes you with the reply.
## `blocked`
```json
{"type":"blocked","items":[{"tool":"shell","detail":"npm publish","why":"needs network access"}]}
```
Actions your permissions or sandbox refused (a denied tool call, a command that failed for lack of network or write access). wisp shows them with an Allow & retry button. Not for ordinary failures.
## `actions`
```json
{"type":"actions","title":"…","items":[{"label":"Run tests","command":"npm test"},{"label":"Follow up","reply":"…"}]}
```
One-click shell commands (executed in the project root) or follow-up actions the user may want to trigger. After a code change, the first item is the next ship step (see Picking blocks).
## `next`
```json
{"type":"next","items":["Suggested follow-up the user might send", "…"]}
```
Usually last. 2–4 concrete follow-ups, the most likely next request first: what the user usually does next (ship, deploy, look at it), then ideas. {"type":"hero","title":"Login now rate-limited","topic":"Rate limit on /login","summary":"Added a sliding-window limiter to /login. 5 attempts per minute per IP.","status":"done"}, {"type":"diff","file":"src/auth/login.ts"}, {"type":"tests","command":"npm test","passed":48,"failed":0,"skipped":0,"durationMs":4100}, {"type":"callout","tone":"warn","title":"Assumption","text":"Behind a proxy, so I read the IP from X-Forwarded-For."}, {"type":"actions","items":[{"label":"Commit and open a PR","reply":"Commit this and open a PR"}]}, {"type":"next","items":["Make the limit configurable","Add the same limiter to /reset-password"]}
---
# Resource kinds
Source: https://trywisp.dev/docs/reference/kinds.md
> Generated from the code by `apps/docs/scripts/reference.mjs`: edit the source, not this page.
Everything a formula (`.wisp/*.wisp.yml`, or `wisp apply -f file`) can declare, one section per top-level key. Each key takes a list of named items (`- name: reviewer`). `wisp schema` prints the same as JSON Schema, for your editor.
## The formula
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `accounts`? | [account] \| map of account | A harness account (its sign-in stays in the harness's own folder). |
| `agents`? | [agent] \| map of agent | A named, reusable agent: which harness and how it runs ("reviewer = codex, high effort, plan mode, the linear connector"). A task, a crew member, a team slot or a judge names one, or gives one inline. |
| `apps`? | [app] \| map of app | An app or a pane: where its code comes from and what it may do. |
| `budget`? | [budget] \| map of budget | Where unattended work stops on a usage window, and what a task or workflow may spend. |
| `capabilities`? | [capability] \| map of capability | A capability set: what its holder may do. |
| `channels`? | [channel] \| map of channel | A channel: where people talk to wisp and hear back from it. |
| `connectors`? | [connector] \| map of connector | An MCP server: a command wisp starts, or a URL it reaches. |
| `crew`? | [crew] \| map of crew | A crew member: who they are, what runs their jobs, when they check in. |
| `factories`? | [factory] \| map of factory | A software factory (`factories:` in a formula). |
| `goals`? | [goal] \| map of goal | A goal: what done means and how it's judged after each turn. `goals.default` has no text: it's every goal's judges, vote, round limit and sandbox. |
| `harnesses`? | [harness] \| map of harness | A harness CLI: where it comes from, which version is trusted, its own defaults. |
| `include`? | string \| [string] | other formulas read first (paths, URLs) |
| `machines`? | [machine] \| map of machine | A computer: this one (`this`) or a peer wisp reaches. |
| `notifications`? | [notification] \| map of notification | What notifies where: events to a channel or a webhook. |
| `panes`? | [pane] \| map of pane | An app or a pane: where its code comes from and what it may do. |
| `pipelines`? | [pipeline] \| map of pipeline | The steps after a run, by name (a task or a workflow step names one: `pipeline: careful`). |
| `plugins`? | [plugin] \| map of plugin | A plugin by its id (`wisp.telegram`, `user.mine`). |
| `profiles`? | map of object | parts picked with --profile NAME |
| `projects`? | [project] \| map of project | A project: a folder wisp works in, and how. |
| `settings`? | map of setting | Settings by key (wisp settings list) |
| `skills`? | [skill] \| map of skill | A skill given to agents: a folder or file, or the text inline. |
| `tasks`? | [task] \| map of task | A task you can run by name, by schedule or from a trigger. |
| `teams`? | [team] \| map of team | A lead and the subagents it may hand work to. |
| `tools`? | [tools] \| map of tools | wisp's tools for one agent profile or mode (its name): what it gets and what it doesn't. |
| `triggers`? | [trigger] \| map of trigger | A trigger. |
| `ui`? | [ui] \| map of ui | How wisp looks on this device. |
| `wisp` | `1` | the formula format |
| `workflows`? | [workflow] \| map of workflow | A workflow: its steps by name, and what bounds a run. |
## `accounts:` (account)
A harness account (its sign-in stays in the harness's own folder).
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `kind`? | string | personal \| work |
| `label`? | string | what it shows as |
## `agents:` (agent)
A named, reusable agent: which harness and how it runs ("reviewer = codex, high effort, plan mode, the linear connector"). A task, a crew member, a team slot or a judge names one, or gives one inline.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `account`? | string | a harness account by name (accounts are personal: never exported unless asked) |
| `connectors`? | [string] | connectors (MCP servers) it gets, by name |
| `effort`? | string | low \| medium \| high \| the harness's own levels |
| `harness`? | string | the harness that runs it (`claude`, `codex`, `cursor`, `opencode`, …; `auto` lets the router pick) |
| `instructions`? | string | standing instructions every task it runs starts with |
| `mode`? | string | plan \| edits \| auto |
| `model`? | string | the harness's model id ('' = the harness's own default) |
| `skills`? | [string] | skills it gets, by name |
| `subagentModel`? | string | the model its subagents use |
## `apps:` (app)
An app or a pane: where its code comes from and what it may do.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `enabled`? | boolean | off: kept but not shown |
| `grants`? | [string] | what it may call (commands, topics) |
| `inline`? | string | its code inline (a single-file app) |
| `schema`? | | its data's shape (JSON Schema) |
| `source`? | string | a folder, or `starter:` for one wisp ships |
## `budget:` (budget)
Where unattended work stops on a usage window, and what a task or workflow may spend.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `claude`? | string | Claude Code's own line (same \| off \| 50 \| 75 \| 90) |
| `codex`? | string | Codex's own line (same \| off \| 50 \| 75 \| 90) |
| `drainWatch`? | boolean | warn when a window is about to drain |
| `stopAt`? | string | off \| 50 \| 75 \| 90: percent of a window where automations stop |
| `taskUsd`? | number | at most this many dollars per task |
## `capabilities:` (capability)
A capability set: what its holder may do.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `allow`? | [string] | permissions it grants (`runtime:create`, `crew:*`) |
| `channels`? | [string] | the channels whose messages act with it |
| `deny`? | [string] | permissions it never grants, over `allow` |
| `key`? | string | an API key that holds it, as `${secret:NAME}` |
## `channels:` (channel)
A channel: where people talk to wisp and hear back from it.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `allow`? | [string] | who may speak to it (chat ids, user names, addresses) |
| `cap`? | string | the most a message may start: plan \| edits (never auto) |
| `enabled`? | boolean | off by default: nothing is received or sent until it's on |
| `routing`? | | the transport's own settings (ntfy: `server`, `topic`; Slack: `appToken`…), merged into its config; where its tasks run (a project or machine), and thread rules |
| `token`? | string | its bot token or key, as `${secret:NAME}` |
| `transport` | string | telegram \| slack \| discord \| github \| email \| ntfy |
## `connectors:` (connector)
An MCP server: a command wisp starts, or a URL it reaches.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agents`? | [string] | the agent profiles that get it (empty: every one) |
| `args`? | [string] | |
| `command`? | string | the program (stdio servers) |
| `enabled`? | boolean | off: declared but no agent gets it |
| `env`? | map of string | its environment; secrets as `${secret:NAME}` |
| `headers`? | map of string | HTTP headers; secrets as `${secret:NAME}` |
| `modes`? | [string] | the modes that get it (plan, edits, auto; empty: all) |
| `oauth`? | boolean | it signs in with OAuth (the token stays in secrets) |
| `url`? | string | the server's URL (HTTP servers) |
## `crew:` (crew)
A crew member: who they are, what runs their jobs, when they check in.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent`? | string | an agent profile's name or a harness (`reviewer`, `codex`) |
| `avatar`? | string | a spirit code or an emoji ('' rolls one from the name) |
| `brief`? | string | the standing instructions every job of theirs starts with |
| `color`? | string | |
| `cron`? | string | when they check in: a cron, or words ("every weekday at 9") |
| `cwd`? | string | the folder they work in |
| `effort`? | string | |
| `kit`? | [any] | their kit: `[{ name, description?, body }]` skills and notes |
| `machine`? | string | the computer their jobs run on ('' = this one) |
| `mode`? | string | plan \| edits \| auto |
| `model`? | string | |
| `notebook`? | string | their notebook (a file: it stays a file) |
| `on`? | [string] | The "also starts when" (`ci`, `done`, `finished`): read as `wakes` on import |
| `parallel`? | integer | how many of their jobs may run at once |
| `paused`? | boolean | no check-ins or jobs until resumed |
| `role`? | string | what they do ("reviewer", "release manager") |
| `sandbox`? | string | '' \| job \| own: a worktree per job, or one of their own |
| `team`? | [any] | who they delegate to: `[{ crew, why? }]` |
| `wakes`? | [crew.TriggerSpec] | what else wakes them (ADR-0043): triggers whose target is this member (`on: crew.reported`, `on: pr.review_requested`, `on: schedule` …); `cron` stays the shorthand for one schedule |
### crew.Budget
What a trigger may spend.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `perDay`? | number | USD a day, across its runs |
| `perRun`? | number | USD a run (the run is stopped past it, by wisp.budget's guard) |
### crew.TriggerSpec
A trigger.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent`? | string | |
| `approval`? | boolean | the job waits for a yes before it starts (never in Full auto) |
| `at`? | integer | once: when (ms since the epoch) |
| `branch`? | string | |
| `budget`? | crew.Budget | |
| `concurrency`? | string | skip \| queue \| replace \| parallel: (skip by default) |
| `cooldown`? | string | after a failed run, wait this long before the next ("30m") |
| `crew`? | string | a crew member gets the work instead (a wake) |
| `cron`? | string | schedule: a cron or words ("every weekday at 9") |
| `debounce`? | string | events within this window become one job listing them all ("10m", "30s") |
| `enabled`? | boolean | |
| `every`? | integer | minutes between polls (a polled source) |
| `factory`? | string | the software factory its own prompt runs through (ADR-0114; a declared `task:` says its own) |
| `followUp`? | boolean | or a follow-up to the task the event came from |
| `header`? | string | webhook: the header that signs each call (`X-Hub-Signature-256`, `Sentry-Hook-Signature`, `Linear-Signature`, `X-PagerDuty-Signature`): an HMAC-SHA256 of the body under the secret, hex, with or without `sha256=`/`v1=`. With it the secret is never sent, only checked. |
| `if`? | string | an expression over `event` (`event.payload.branch == 'main'`), as workflows' `if` |
| `label`? | string | an issue's or PR's label |
| `match`? | object | any other field of the source, matched against the event's payload (a string, a glob, or a list) |
| `mode`? | string | plan \| edits \| auto |
| `model`? | string | |
| `on` | string | the source: `schedule`, `once`, `webhook`, `manual`, or an event type (`task.finished`, `pr.opened`, `chat.message`, …) |
| `project`? | string | the project it watches, and the folder its task runs in |
| `prompt`? | string | or a prompt of its own: `{event.summary}`, `{event.payload.x}` are filled in |
| `rate`? | string | at most this many runs: "5/h", "20/d" |
| `secret`? | string | webhook: its secret, as `${secret:NAME}` |
| `task`? | string | the declared task it starts (its `{params}` from the event) |
| `tz`? | string | schedule and `when`: an IANA zone ("Europe/Zurich"); this computer's by default |
| `users`? | [string] | chat.message: who may (names or ids; `anyone` for an open channel) |
| `when`? | crew.When | |
| `workflow`? | string | or a workflow runs, with the event as its input |
### crew.When
When a trigger may run: outside these, an event is skipped or queued until the window opens.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `days`? | [string] | mon tue wed thu fri sat sun (every day when empty) |
| `hours`? | string | "9-17" (local hours, start inclusive, end exclusive) |
| `outside`? | string | skip (default) \| queue |
| `tz`? | string | |
## `factories:` (factory)
A software factory (`factories:` in a formula).
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `budget`? | | `{ usd: 20 }`: no new station starts once the run's stations have cost this much |
| `description`? | string | |
| `loop`? | factory.Loop | |
| `stations` | factory.Stations | |
### factory.BuildStation
Builds it, in a worktree of its own.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent`? | string | |
| `agents`? | [string] | two or more build it side by side, each in its own worktree; the first whose checks pass goes on |
| `mode`? | string | plan \| edits \| auto (default: the run's) |
| `prompt`? | string | |
| `worktree`? | boolean | a worktree of its own (default: yes, in a project) |
### factory.ChecksStation
The gate that is code: commands run in the build's folder, in order; one that exits non-zero fails it.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `run`? | [string] | each `sh -c` in the build's folder (none: the project's own `test` command) |
| `timeout`? | integer | minutes each may run (default 10) |
### factory.Loop
Where a failed check or review goes, how many rounds it may take, and what happens past them.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `back_to`? | string | build (the default) \| spec |
| `max`? | integer | rounds in all (default 3; 0: a failure goes straight to `then`) |
| `then`? | string | ask (the default): it asks you whether to keep going \| stop: the run ends failed |
### factory.ReviewStation
Reviewers read the build's folder and each says APPROVE or CHANGES: what to fix.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent`? | string | |
| `agents`? | [string] | |
| `prompt`? | string | |
| `vote`? | string | majority (the default) \| all \| any |
### factory.ShipStation
Opens the PR from the build's worktree, and merges it.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `draft`? | boolean | |
| `merge`? | string | human (the default): it asks before merging \| auto: merges once it's open \| none: leaves it open |
| `pr`? | boolean | open a PR (default: yes) |
### factory.SpecStation
Writes the spec: its answer is what every later station is given. Read-only (Plan mode).
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent`? | string | an agent profile's name or a harness ('' : the task's, else your default) |
| `approve`? | string | `human` (the default): the run waits for your yes on the spec; `none`: it goes on by itself |
| `prompt`? | string | more instructions for it |
### factory.Stations
A factory's stations: the ones it has, always run in this order.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `build`? | factory.BuildStation | |
| `checks`? | factory.ChecksStation | |
| `review`? | factory.ReviewStation | |
| `ship`? | factory.ShipStation | |
| `spec`? | factory.SpecStation | |
## `goals:` (goal)
A goal: what done means and how it's judged after each turn. `goals.default` has no text: it's every goal's judges, vote, round limit and sandbox.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `judges`? | array | the agent profiles that judge; `[]` on purpose: no judges, the task's own quick check |
| `maxRounds`? | integer | turns a goal may take before it stops and asks |
| `sandbox`? | boolean | its judges run in a sandbox of their own, seeded with the task's folder (ADR-0047) |
| `text`? | string | what has to be true for it to be met ("npm test passes and the build is green") |
| `vote`? | string | majority \| all \| any |
## `harnesses:` (harness)
A harness CLI: where it comes from, which version is trusted, its own defaults.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `effort`? | string | |
| `enabled`? | boolean | installed or not (false: wisp never offers it) |
| `from`? | string | npm \| brew \| path |
| `lean`? | boolean | lean runs: wisp's short base prompt instead of the harness's own |
| `liveLimits`? | boolean | read its usage limits while it runs |
| `model`? | string | |
| `package`? | string | what `from` installs: the npm package (default: the harness's own) or the brew formula |
| `path`? | string | its program when `from: path` |
| `pin`? | string | the version wisp trusts (a newer one asks first); `from: npm` installs this one |
## `machines:` (machine)
A computer: this one (`this`) or a peer wisp reaches.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `address`? | string | its address (host, ssh target or grid name) |
| `limits`? | machine.MachineLimits | |
| `onGrid`? | boolean | this computer is on the grid, so other computers reach it |
| `port`? | integer | its wisp's port (ssh, loopback), when it isn't the default |
| `transport`? | string | local \| ssh \| grid \| grid-tunnel |
### machine.MachineLimits
What a computer may take on before automations wait.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `batteryHold`? | integer | on battery under this percent, check-ins and the crew queue wait (off, 20 or 40) |
| `cpuCeiling`? | integer | automations wait while the CPU stays over this percent of its cores |
| `heavyLock`? | boolean | one heavy step (a build, the tests) at a time |
| `maxRuns`? | integer | runs at once (default: one per 3 GB of memory) |
| `memoryFloor`? | integer | automations wait while free memory is under this percent |
## `notifications:` (notification)
What notifies where: events to a channel or a webhook.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `on` | [string] | events: `finished`, `asks`, `failed`, `limit`, `drain`, a trigger's name |
| `projects`? | [string] | only for these projects (empty: every one) |
| `to` | string | a channel's name, or a webhook URL |
## `panes:` (pane)
An app or a pane: where its code comes from and what it may do.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `enabled`? | boolean | off: kept but not shown |
| `grants`? | [string] | what it may call (commands, topics) |
| `inline`? | string | its code inline (a single-file app) |
| `schema`? | | its data's shape (JSON Schema) |
| `source`? | string | a folder, or `starter:` for one wisp ships |
## `pipelines:` (pipeline)
The steps after a run, by name (a task or a workflow step names one: `pipeline: careful`).
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `atLimit`? | string | at a usage limit: next (another account or harness) \| wait |
| `bestOf`? | integer | run it this many times and keep the best |
| `judge`? | string | the agent profile that picks the best, or reviews |
| `onError`? | string | on an error: escalate (a stronger model) \| retry \| stop |
| `review`? | string | a review by this agent profile after each run |
## `plugins:` (plugin)
A plugin by its id (`wisp.telegram`, `user.mine`).
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `config`? | | its own configuration |
| `enabled`? | boolean | on or off |
| `source`? | string | where a user's plugin comes from: a path, `gist:` or a URL |
| `version`? | string | the version it stays on |
## `profiles:` (account)
A harness account (its sign-in stays in the harness's own folder).
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `kind`? | string | personal \| work |
| `label`? | string | what it shows as |
## `projects:` (project)
A project: a folder wisp works in, and how.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent`? | string | the agent profile or harness its tasks use unless they say |
| `color`? | string | |
| `instructions`? | string | notes every task in it starts with (learned preferences, per-project rules) |
| `path` | string | the folder (absolute), or a repo URL cloned into the worktree dir |
| `run`? | [string] | commands that start the project (a dev server), for Run |
| `setup`? | [string] | commands run in a new worktree before the first turn |
| `test`? | string | the command that runs its tests (Auto learns from whether a task's tests pass) |
| `trust`? | project.ProjectTrust | |
| `worktree`? | project.WorktreePolicy | |
### project.ProjectTrust
What a project trusts without asking: its hooks, MCP servers and setup script.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `hooks`? | boolean | |
| `mcp`? | [string] | the project's own MCP servers, by name |
| `setup`? | boolean | |
### project.WorktreePolicy
How a project uses worktrees.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `cleanupDays`? | integer | days a finished task's worktree stays before cleanup |
| `dir`? | string | where clones and worktrees go |
| `enabled`? | boolean | each task in a worktree of its own |
| `fixConflicts`? | boolean | resolve merge conflicts with an agent |
| `include`? | [string] | untracked files copied into each worktree (`.env`, `node_modules`) |
| `max`? | integer | at most this many worktrees at once |
| `onDone`? | string | when a task is done: ask \| remove-clean \| keep |
## `settings:` (setting)
Settings by key (wisp settings list)
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `accounts.updateCheck`? | boolean | Check for newer harness versions: once a day, wisp asks npm for the latest Claude Code, Codex and opencode (npm then knows which of them you have) |
| `automations.webhookTriggers`? | boolean | Webhook triggers: other services may start this computer's webhook triggers (POST /api/triggers/ with its secret) |
| `budget.drainWatch`? | boolean | Drain watch: tell the phone when a plan moves much faster than usual for the same work |
| `budget.limitHold`? | `off` · `80` · `90` · `95` | Ask near the limit: before a task would take a usage window past this percent, ask first (automations wait for the reset) |
| `budget.liveLimits`? | boolean | Check Codex while work waits: read its usage every 10 minutes while work waits for its plan (spends nothing) |
| `budget.silentStop`? | `off` · `1` · `2` · `4` · `8` | Stop a run silent for: stop a run with no output for this many hours (a run silent 30 minutes while its plan moves is always told to your phone) |
| `budget.spareCard`? | boolean | Spare allowance: say on home when a weekly window resets within a day with a fifth or more left |
| `budget.windowNotice`? | boolean | Window notices: say when a usage window changed length or resets early |
| `channels.acceptChannels`? | boolean | Accept tasks from channels: messages routed here through wisp Cloud (“on this computer …”) may start tasks. Switch it on at this computer. |
| `channels.project`? | string | Default project: where a task from a channel (Slack, Discord, Telegram, email) runs when its message names none ('': the last used) |
| `crew.tint`? | boolean | Crew tint: with the crew rail, the task list takes a very light tint of the colour of the member you pick. |
| `events.sinks`? | | Event sinks |
| `git.cloneDir`? | string | Where a pasted repo URL is cloned ('': the first of ~/code, ~/dev, ~/Developer, ~/projects… that exists, else ~/code) |
| `git.maskEnvFiles`? | boolean | Hide .env values: what a task shows of a .env file (its output, edits, blocks, Changes) leaves wisp as dots until you reveal one |
| `grid-client.previews`? | boolean | Show local pages in previews |
| `learn.enabled`? | boolean | Learn from your tasks: a short retro after each quiet task, kept as preferences and lessons later tasks follow |
| `machine.batteryHold`? | `off` · `20` · `40` | On battery under this percent, check-ins and the crew queue wait |
| `machine.cpuCeiling`? | `off` · `100` · `150` · `200` | Automations wait while the CPU stays over this percent of a core per core |
| `machine.maxRuns`? | `off` · `4` · `6` · `8` · `12` · `16` · `auto` | Runs at once before automations wait |
| `machine.memoryFloor`? | `off` · `10` · `15` · `20` · `25` | Automations wait while free memory is under this percent |
| `review.harness`? | `off` · `other` · `claude` · `codex` · `antigravity` · `copilot` · `opencode` · `cursor` · `grok` | Review by another harness |
| `runtime.apps`? | boolean | Interactive answers: agents may answer with a small app |
| `runtime.auto`? | boolean | Auto: wisp picks the harness, model and thinking level for each task. Off until it's reworked (the owner, 2026-11-17): the one switch; the app hides Auto while it's off |
| `runtime.blocks`? | boolean | wisp blocks: answers come as cards (off: plain markdown) |
| `runtime.followUp`? | `interrupt` · `queue` | A follow-up while a task works: interrupt it, or queue after it |
| `runtime.launch`? | | New task's last pick: { agent, models: { : model }, labels: { : name }, efforts: { : level } }; a task that names no harness runs on its agent |
| `runtime.leanRuns`? | `off` · `on` · `all` | Lean Claude Code runs (no telemetry or update checks, and no claude.ai connectors): on, only wisp's own side runs; all, every run; off, none |
| `runtime.limitWait`? | boolean | Wait for the reset: a task at its usage limit carries on by itself after the reset, in the same conversation |
| `runtime.projectOrder`? | | Your project order (names): the chips, New task's row and the Projects list show them so; drag to change it |
| `runtime.retentionDays`? | integer | Days a finished task stays in the list before it's archived (0: always) |
| `runtime.setupAnswerSets`? | | The API keys' capability sets (custom:) you let answer an agent's setup cards (ADR-0113): none unless you list them |
| `runtime.subagentModel`? | `task` · `haiku` · `sonnet` | The model Claude Code's subagents run on (task: the task's own) |
| `runtime.subagents`? | | The team new tasks start with: [{ name, agent, model?, effort?, use? }] (New task pre-fills it; a task's own team wins) |
| `runtime.teams`? | | Delegate's saved teams (presets): [{ id, name, members: [{ name, agent, model?, effort?, use?, count?, machine? }] }]; Presets picks one, Save as preset keeps one |
| `runtime.watch`? | boolean | Watch agents work: agents may open what they built in wisp's browser to check it |
| `settings.editor`? | string | The editor files open in (vscode, cursor, windsurf, zed, idea, none) |
| `settings.notify`? | `on` · `off` | Desktop notifications when a task needs you or finishes |
| `settings.readTimes`? | `on` · `off` | Read times in prompts: a prompt that starts with a time (“in 5 min …”, “tomorrow at 9 …”) is scheduled for then |
| `settings.timeZone`? | string | Time zone: the one scheduled times are read in, an IANA name like Europe/Zurich (the app sets it from your device) |
| `settings.transcript`? | `on` · `off` | Open tasks on their transcript instead of the answer |
| `ship.fixConflicts`? | boolean | Fix merge conflicts by itself: when a task's PR has conflicts, its agent is asked to fix them without waiting for you |
| `stuff.panes`? | string | Panes: @task or @home, comma separated |
| `termctx.enabled`? | boolean | Terminal context: wisp in a terminal may attach what just happened there |
| `terminal.command`? | string | Take over with a custom command ({cmd} is the agent's resume command) |
| `terminal.terminal`? | string | Open tasks in: wisp, one of this computer's terminal apps (its id) or custom |
| `terminal.terminalSessions`? | `on` · `off` | Babysitting mode: each task opens straight in the agent's own terminal |
| `threads.compactAudit`? | boolean | Check compactions: after a compaction, wisp asks a copy of the conversation what it still remembers of the task's Notes and reminds the agent of what it lost (one short extra run each) |
| `update.updateChannel`? | `stable` · `beta` · `nightly` | Update channel |
| `worktrees.cleanup`? | `off` · `3` · `7` · `14` · `30` | Idle worktrees go after this many days (unset: 7, counted from when wisp got it) |
| `worktrees.max`? | `off` · `20` · `40` · `80` | Worktree folders kept before the oldest idle ones go |
| `worktrees.onDone`? | `ask` · `remove` · `keep` | When a task is done, its worktree folders |
| `worktrees.projectAsk`? | `on` · `off` | Ask before trusting a new project's setup scripts |
| `worktrees.worktree`? | `on` · `off` | New tasks run in their own worktree by default |
## `skills:` (skill)
A skill given to agents: a folder or file, or the text inline.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `body`? | string | the skill's text, when it isn't a file |
| `description`? | string | what it is for (agents read it to pick it) |
| `extra`? | | extra fields a harness's skill format has |
| `path`? | string | a SKILL.md or its folder |
## `tasks:` (task)
A task you can run by name, by schedule or from a trigger.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent`? | string | an agent profile's name or a harness |
| `connectors`? | [string] | |
| `crew`? | string | the crew member it runs for |
| `effort`? | string | |
| `factory`? | string | the software factory it runs through (ADR-0114): a factory's name (`default` is always there); its stations run it instead of one agent |
| `goal`? | | the goal judged after each turn: a declared goal's name (`green-build`, from `goals:`), or inline (`{ text: tests pass, judges: [reviewer] }`); `{ name: green-build, maxRounds: 3 }` is the declared one with its own limit |
| `mode`? | string | plan \| edits \| auto |
| `model`? | string | |
| `notes`? | task.SeedNotes | the Notes it starts with (ADR-0097): `{ goal: …, constraints: [...] }`, kept by wisp.threads |
| `paused`? | boolean | paused: its schedule doesn't fire (it still runs by hand) |
| `project`? | string | the folder it runs in |
| `prompt`? | string | what to do; `{param}` is filled from the run's values (every task but `tasks.default` has one) |
| `schedule`? | string | when it runs by itself: a cron or words ("every day at 2"), in UTC |
| `steps`? | [string] | prompts sent after the first, each when the turn before ends |
| `title`? | string | its name as you wrote it ("Run tests"), shown on its chip, when the name (a key: `wisp recipes run run-tests`) can't hold it. |
| `worktree`? | boolean | run in a worktree of its own |
### task.SeedNotes
The Notes a formula's task starts with (ADR-0097, `notes:` on a task, ADR-0026/0027): a section's text, a list section's items. Unknown sections are refused when the formula is checked.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `constraints`? | [string] | must and must-not, one each |
| `decisions`? | [string] | what was chosen, and why |
| `failed`? | [string] | what didn't work, and why |
| `files`? | [string] | key files |
| `goal`? | string | what done looks like |
| `open`? | [string] | open questions |
| `state`? | string | where it stands |
## `teams:` (team)
A lead and the subagents it may hand work to.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `lead`? | string | the lead's agent profile |
| `members`? | map of team.TeamSlot | its subagents, by name |
### team.TeamSlot
One seat on a team.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent` | string | an agent profile's name or a harness |
| `count`? | integer | copies of it the lead may run at once |
| `why`? | string | what the lead gives it |
## `tools:` (tools)
wisp's tools for one agent profile or mode (its name): what it gets and what it doesn't.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `allow`? | [string] | tool names (`wisp_ask`, `wisp_delegate`, `wisp_*`); empty: every one |
| `deny`? | [string] | tool names it never gets |
## `triggers:` (trigger)
A trigger.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent`? | string | |
| `approval`? | boolean | the job waits for a yes before it starts (never in Full auto) |
| `at`? | integer | once: when (ms since the epoch) |
| `branch`? | string | |
| `budget`? | trigger.Budget | |
| `concurrency`? | string | skip \| queue \| replace \| parallel: (skip by default) |
| `cooldown`? | string | after a failed run, wait this long before the next ("30m") |
| `crew`? | string | a crew member gets the work instead (a wake) |
| `cron`? | string | schedule: a cron or words ("every weekday at 9") |
| `debounce`? | string | events within this window become one job listing them all ("10m", "30s") |
| `enabled`? | boolean | |
| `every`? | integer | minutes between polls (a polled source) |
| `factory`? | string | the software factory its own prompt runs through (ADR-0114; a declared `task:` says its own) |
| `followUp`? | boolean | or a follow-up to the task the event came from |
| `header`? | string | webhook: the header that signs each call (`X-Hub-Signature-256`, `Sentry-Hook-Signature`, `Linear-Signature`, `X-PagerDuty-Signature`): an HMAC-SHA256 of the body under the secret, hex, with or without `sha256=`/`v1=`. With it the secret is never sent, only checked. |
| `if`? | string | an expression over `event` (`event.payload.branch == 'main'`), as workflows' `if` |
| `label`? | string | an issue's or PR's label |
| `match`? | object | any other field of the source, matched against the event's payload (a string, a glob, or a list) |
| `mode`? | string | plan \| edits \| auto |
| `model`? | string | |
| `on` | string | the source: `schedule`, `once`, `webhook`, `manual`, or an event type (`task.finished`, `pr.opened`, `chat.message`, …) |
| `project`? | string | the project it watches, and the folder its task runs in |
| `prompt`? | string | or a prompt of its own: `{event.summary}`, `{event.payload.x}` are filled in |
| `rate`? | string | at most this many runs: "5/h", "20/d" |
| `secret`? | string | webhook: its secret, as `${secret:NAME}` |
| `task`? | string | the declared task it starts (its `{params}` from the event) |
| `tz`? | string | schedule and `when`: an IANA zone ("Europe/Zurich"); this computer's by default |
| `users`? | [string] | chat.message: who may (names or ids; `anyone` for an open channel) |
| `when`? | trigger.When | |
| `workflow`? | string | or a workflow runs, with the event as its input |
### trigger.Budget
What a trigger may spend.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `perDay`? | number | USD a day, across its runs |
| `perRun`? | number | USD a run (the run is stopped past it, by wisp.budget's guard) |
### trigger.When
When a trigger may run: outside these, an event is skipped or queued until the window opens.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `days`? | [string] | mon tue wed thu fri sat sun (every day when empty) |
| `hours`? | string | "9-17" (local hours, start inclusive, end exclusive) |
| `outside`? | string | skip (default) \| queue |
| `tz`? | string | |
## `ui:` (ui)
How wisp looks on this device.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `editor`? | string | the editor files open in (`code`, `cursor`, `zed`) |
| `keys`? | map of string | key → action |
| `layout`? | | panel sizes and what's open |
| `readTimes`? | boolean | show read times on answers |
| `terminal`? | string | the terminal app |
| `theme`? | string | light \| dark \| system |
| `transcript`? | string | compact \| full |
| `view`? | string | list \| board |
## `workflows:` (workflow)
A workflow: its steps by name, and what bounds a run.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `budget`? | | `{ usd: 20 }`: no new step starts once the run has cost this much |
| `concurrency`? | integer | at most this many steps run at once (0: no limit) |
| `description`? | string | |
| `inputs`? | object | values a run takes (`wisp run release-check version=2.1`), with their defaults |
| `on`? | | what starts it by itself (`{ trigger: nightly }`); by hand otherwise |
| `project`? | string | the folder its steps run in unless they say |
| `tasks` | map of workflow.StepSpec | |
### workflow.StepSpec
One step of a workflow: a task spec plus when it runs.
| Field (? optional) | Type | What it is |
| --- | --- | --- |
| `agent`? | string | an agent profile's name or a harness |
| `effort`? | string | |
| `goal`? | | |
| `if`? | string | run only when this is true: `${{ tasks.tests.output.failed > 0 }}` (skipped otherwise) |
| `matrix`? | map of [any] | one run per combination: `{ agent: [claude, codex] }` |
| `mode`? | string | plan \| edits \| auto |
| `model`? | string | |
| `needs`? | [string] | steps that must end first |
| `on`? | string | the computer it runs on (a machine's name; '' = this one) |
| `optional`? | boolean | a failure doesn't fail the run (the steps after it still see it failed) |
| `output`? | | its output's shape (a JSON Schema); without one, the output is what its answer gives |
| `project`? | string | the folder it runs in (default: the run's) |
| `prompt` | string | what to do; `${{ tasks..output. }}`, `${{ inputs. }}` and `${{ matrix. }}` are filled in |
| `retries`? | integer | tries again this many times when it fails |
| `steps`? | [string] | prompts after the first, each when the turn before ends |
| `timeout`? | integer | minutes it may run before it is stopped and counts as failed |
| `worktree`? | boolean | |
---
# Plugin manifest and UI
Source: https://trywisp.dev/docs/reference/plugin-api.md
> Generated from the code by `apps/docs/scripts/reference.mjs`: edit the source, not this page.
A plugin is a folder with a `wisp-plugin.json` and, for UI, one `.js` module. wisp checks the manifest against these keys: an unknown key is refused, with the one you probably meant. Start with [Your first plugin](../../plugins/first-plugin/).
## Manifest keys
| Key | What it is |
| --- | --- |
| `wispPlugin` | 1. Required. |
| `id` | Required. "user." (lowercase, dots or dashes): a plugin you install is always user.*; wisp's own ids are reserved. |
| `name` | What the user sees it called. |
| `version` | Required. "1.0.0": bump it when you change a plugin the user already has. |
| `api` | Required. The plugin API range it's written for: "^1". |
| `description` | One sentence: what it does for the user. |
| `author` | Who wrote it. |
| `kind` | Leave it out ("module" is for wisp's own built-ins). |
| `extends` | Another plugin's id this one adds to (rare). |
| `requires` | { "": "" }: plugins it needs on. A built-in plugin carries wisp's version: "^1.0.0-0" takes this alpha and every 1.x (a plain "^1" waits for 1.0.0). |
| `provides` | { "": { "version": "1.0.0" } }: a contract it implements (rare). |
| `permissions` | What it may do, as permissions ("plugins:read", "runtime:list"). Its UI's wisp.call runs as the plugin and is checked against these, never the user's. Each command's permission is in the list of commands below. Switching it on is the user's consent to them. |
| `server` | { "exec": ["", …args] }: a process of its own, started in its folder with an emptied environment, speaking JSON-RPC. Leave it out for a plugin that is only UI and settings. ("builtin" is wisp's own crates only.) |
| `activation` | When it starts: "onStartup", "onCommand:", "onView:", … (kinds below). Lazy is better: the first event that needs it. |
| `disable` | Built-in plugin ids it switches off while it's on (an override; rare). |
| `contributes` | What it adds to wisp: the sections below. |
| `migrations` | A folder of forward-only SQL migrations for its own tables (a server plugin; rare). |
| `trust` | Ignored on install: anything installed is untrusted until the user trusts it in Settings → Plugins. |
| `qa` | wisp's own QA hook; leave it out. |
## `contributes`
| Key | What it adds |
| --- | --- |
| `commands` | [{ "id": "user..", "title": "…", "readOnly": true }]: commands its server answers (ids start with the plugin's id). |
| `events` | Events its server emits, by name and version. |
| `topics` | Topics its server publishes for clients to watch. |
| `points` | Extension points it offers other plugins (rare). |
| `settings` | [{ "key": "user..", "type": "bool", "default": false, "title": "…" }]: settings of its own (types below), shown in Settings. |
| `setSettings` | { "": value }: values it sets for other plugins' settings while it's on (a theme, a preset). |
| `ui` | [{ "id": "user..pane", "attachTo": { "id": "shell.settings", "input": "pane" }, "component": "./ui.js#default", "title": "…" }]: what it shows. component is a .js module in its folder, run in a sandboxed Worker; where it may show is below. |
| `parts` | Part names it adds for themes to style (an untrusted UI draws only kit components; it can't style anything). |
| `partStyles` | A theme: { "": { "": "" } }, plus ":root" for token overrides (--accent) and "@light" / "@dark" for one theme only. Applies in the app's @layer plugins while the plugin is on and you trusted it (wisp plugin trust ); an untrusted plugin's styles never apply. Only the properties and values listed under Themes below pass. |
| `icons` | Icons it adds by name (a trusted plugin; an untrusted UI's descriptors take no icons). |
| `blocks` | Answer block types it renders (its UI at shell.block). |
| `recipes` | Automation recipes it brings, read-only to the user. |
| `triggerSources` | Event names automations can start on ("on" names), known even while it's off. |
## The UI module
A `contributes.ui` entry's `component` is a `.js` file in the plugin's folder. It runs in a Worker in a sandboxed frame: no DOM, no network, no storage, no imports, one file of at most 256 KB. Its `wisp` has only:
- `wisp.render(tree)`: draw this tree of components (call it again to update; nodes update in place).
- `wisp.call(command, args)`: run a wisp command as the plugin, checked against the plugin's own permissions (never yours). Every command is in [Commands](../commands/).
- `wisp.on(event, fn)`: `fn(value)` runs when a component with `on: event` fires.
A node is a string (text) or `{ c: 'Component', p: { …props }, k: [ …children ], on: 'event' }`. No HTML, no class, no style: anything not listed below is dropped, so a plugin always looks like wisp, in light and dark.
| Component | Props |
| --- | --- |
| `Stack` | `gap`: `0` · `1` · `2` · `3` · `4` · `5` · `6` · `7` · `8` · `9`; `align`: `start` · `center` · `end` · `stretch` · `baseline`; `justify`: `start` · `center` · `end` · `between` Takes children (`k`). |
| `Inline` | `gap`: `0` · `1` · `2` · `3` · `4` · `5` · `6` · `7` · `8` · `9`; `align`: `start` · `center` · `end` · `stretch` · `baseline`; `justify`: `start` · `center` · `end` · `between` Takes children (`k`). |
| `Text` | `size`: `xs` · `sm` · `md` · `lg`; `weight`: `regular` · `medium` · `semibold`; `tone`: `ink` · `ink-2` · `muted` · `faint` · `neutral` · `accent` · `good` · `warn` · `bad` · `info`; `mono`: bool; `truncate`: bool Takes children (`k`). |
| `Button` | `variant`: `primary` · `secondary` · `ghost` · `danger`; `size`: `xs` · `sm` · `md` · `lg`; `disabled`: bool; `label`: string Fires `on`: a click (no value). |
| `Input` | `value`: string; `placeholder`: string; `type`: `text` · `password` · `number` · `search`; `size`: `sm` · `md` · `lg`; `label`: string Fires `on`: each edit (its text). |
| `Switch` | `checked`: bool; `label`: string; `disabled`: bool Fires `on`: a flip (true or false). |
| `Select` | `value`: string; `items`: items; `placeholder`: string; `label`: string Fires `on`: a pick (the item's value). |
| `SettingsRow` | `title`: string; `description`: string; `control`: node |
| `ListRow` | `title`: string; `sub`: string |
| `Callout` | `tone`: `neutral` · `accent` · `good` · `warn` · `bad` · `info`; `title`: string Takes children (`k`). |
| `Code` | `text`: string; `block`: bool; `lang`: string |
| `Markdown` | `source`: string |
## Where a plugin's UI shows (`attachTo.id`)
| Place | Where | Drawn |
| --- | --- | --- |
| `shell.settings` | a pane in Settings → Advanced | yes |
| `shell.side` | a side view | not drawn yet |
| `shell.block` | a block renderer | not drawn yet |
| `shell.toolbar` | a toolbar button | not drawn yet |
Limits: 10000 characters per text, 2000 nodes, 32 levels, 200 items per Select.
## Themes (`partStyles`)
A theme is a plugin with only a manifest: `contributes.partStyles` maps the `data-part` names of what you want to restyle (see them in the browser's inspector: `data-part="composer.send"`) to CSS declarations. wisp writes them into the app's `@layer plugins`, after its own styles, so they win without `!important`. They apply while the plugin is on **and you trusted it**: a plugin you install is untrusted until you say otherwise, and an untrusted plugin's styles never apply.
```sh
wisp plugin install ./pink # installed, off and untrusted
wisp plugin trust user.pink # its styles may apply
wisp plugin enable user.pink # on: the app restyles at once; disable or remove it and they go
```
```json
"partStyles": {
":root": { "--accent": "#d6336c" },
"composer.send": { "background": "#d6336c", "color": "#ffffff", "border-radius": "999px" },
"@dark": { ":root": { "--accent": "#ff7aa8" }, "composer.send": { "background": "#ff7aa8", "color": "#1a1a1a" } }
}
```
- A key is a part name (`composer.send`: lowercase, dot-namespaced), `:root` for token overrides (custom properties only, like `--accent`), or `@light` / `@dark` holding the same map for that theme only (when the app's theme is set to it, or follows the system and the system is in it).
- A property is a custom property (`--anything`) or one of: `accent-color`, `align-items`, `align-self`, `backdrop-filter`, `background`, `background-color`, `background-image`, `background-position`, `background-repeat`, `background-size`, `border`, `border-bottom`, `border-bottom-color`, `border-bottom-left-radius`, `border-bottom-right-radius`, `border-bottom-style`, `border-bottom-width`, `border-color`, `border-left`, `border-left-color`, `border-left-style`, `border-left-width`, `border-radius`, `border-right`, `border-right-color`, `border-right-style`, `border-right-width`, `border-style`, `border-top`, `border-top-color`, `border-top-left-radius`, `border-top-right-radius`, `border-top-style`, `border-top-width`, `border-width`, `box-shadow`, `caret-color`, `color`, `column-gap`, `cursor`, `display`, `fill`, `filter`, `flex`, `flex-direction`, `flex-grow`, `flex-shrink`, `font-family`, `font-size`, `font-style`, `font-variant-numeric`, `font-weight`, `gap`, `height`, `justify-content`, `letter-spacing`, `line-height`, `margin`, `margin-bottom`, `margin-left`, `margin-right`, `margin-top`, `max-height`, `max-width`, `min-height`, `min-width`, `opacity`, `order`, `outline`, `outline-color`, `outline-offset`, `outline-style`, `outline-width`, `padding`, `padding-bottom`, `padding-left`, `padding-right`, `padding-top`, `row-gap`, `stroke`, `text-align`, `text-decoration`, `text-decoration-color`, `text-shadow`, `text-transform`, `transition`, `visibility`, `width`.
- A value is plain CSS of at most 200 characters: no `;`, braces, `<`, `>`, `\`, `@`, `!`, comments or unbalanced quotes; `url()` only with a `data:image/` URL, and no `image-set()`: a theme fetches nothing. At most 400 declarations. Anything else is refused when the plugin installs.
---
# Events and trigger sources
Source: https://trywisp.dev/docs/reference/triggers.md
> Generated from the code by `apps/docs/scripts/reference.mjs`: edit the source, not this page.
A trigger starts work when something happens. Its `on` is one of these. A trigger whose plugin is off stays declared but doesn't fire until you switch the plugin on. See [Schedules and triggers](../../guides/run/schedules-and-triggers/) and the trigger's fields in [Resource kinds](../kinds/).
| `on:` | Offered by | Kind |
| --- | --- | --- |
| `chat.message` | wisp.channels | a source |
| `ci.failed` | wisp.github | a source |
| `ci.passed` | wisp.github | a source |
| `crew.job_filed` | wisp.crew | an event |
| `crew.reported` | wisp.crew | an event |
| `files.changed` | wisp.worktrees | a source |
| `goal.failed` | wisp.goal | an event |
| `goal.met` | wisp.goal | an event |
| `issue.labeled` | wisp.issues | a source |
| `issue.opened` | wisp.issues | a source |
| `later.fired` | wisp.later | an event |
| `machines.online` | wisp.machines | an event |
| `manual` | wisp.automations | a source |
| `once` | wisp.automations | a source |
| `pr.merged` | wisp.ship | an event |
| `pr.opened` | wisp.ship | an event |
| `review.finished` | wisp.review | an event |
| `schedule` | wisp.automations | a source |
| `session.asked` | wisp.runtime | an event |
| `task.asked` | wisp.runtime | an event |
| `task.done` | wisp.runtime | an event |
| `task.failed` | wisp.runtime | an event |
| `task.finished` | wisp.runtime | an event |
| `task.held` | wisp.runtime | an event |
| `terminal.failed` | wisp.termctx | a source |
| `trigger.fired` | wisp.automations | an event |
| `turn.ended` | wisp.runtime | an event |
| `turn.finished` | wisp.runtime | an event |
| `turn.held` | wisp.runtime | an event |
| `webhook` | wisp.automations | a source |
---
# Plugin examples
Source: https://trywisp.dev/docs/reference/plugin-examples.md
> Generated from the code by `apps/docs/scripts/reference.mjs`: edit the source, not this page.
Each is a complete plugin: its manifest passes wisp's own check in its tests, and agents that write plugins for you are shown the same ones. Put the files in `~/.wisp/plugins//`, then `wisp plugin enable `. See [Build plugins](../../plugins/first-plugin/).
## My plugins
*Asked for:* A Settings pane that lists my plugins and which are on
`wisp-plugin.json`
```json
{
"wispPlugin": 1,
"id": "user.my-plugins",
"name": "My plugins",
"version": "1.0.0",
"api": "^1",
"description": "Lists the plugins this wisp has and which are on.",
"permissions": [
"plugins:read"
],
"activation": [
"onView:user.my-plugins.pane"
],
"contributes": {
"ui": [
{
"id": "user.my-plugins.pane",
"attachTo": {
"id": "shell.settings",
"input": "pane"
},
"component": "./ui.js#default",
"title": "My plugins"
}
]
}
}
```
`ui.js`
```js
// runs in a Worker: no DOM, no network. It only describes kit components and calls wisp as itself.
const show = (rows, error) => wisp.render({ c: 'Stack', p: { gap: '2' }, k: [
{ c: 'Inline', p: { justify: 'between' }, k: [
{ c: 'Text', p: { weight: 'semibold' }, k: [`${rows.length} plugins`] },
{ c: 'Button', p: { label: 'Refresh', size: 'sm', variant: 'ghost' }, on: 'refresh' },
] },
...(error ? [{ c: 'Callout', p: { tone: 'bad', title: error } }] : []),
...rows.map((r) => ({ c: 'ListRow', p: { title: r.id, sub: `${r.version} · ${r.enabled ? 'on' : 'off'}` } })),
] });
const load = () => wisp.call('plugins.list', {}).then((rows) => show(rows), (e) => show([], e.message));
wisp.on('refresh', load);
show([]);
load();
```
## Scratch
*Asked for:* A pane with a note I can type and a switch, that remembers nothing outside itself
`wisp-plugin.json`
```json
{
"wispPlugin": 1,
"id": "user.scratch",
"name": "Scratch",
"version": "1.0.0",
"api": "^1",
"description": "A note and a switch, kept while the pane is open.",
"permissions": [],
"contributes": {
"ui": [
{
"id": "user.scratch.pane",
"attachTo": {
"id": "shell.settings",
"input": "pane"
},
"component": "./ui.js#default",
"title": "Scratch"
}
]
}
}
```
`ui.js`
```js
let note = '';
let loud = false;
const draw = () => wisp.render({ c: 'Stack', p: { gap: '3' }, k: [
{ c: 'SettingsRow', p: { title: 'Loud', description: 'Shows the note as a callout', control: { c: 'Switch', p: { checked: loud }, on: 'loud' } } },
{ c: 'Input', p: { value: note, placeholder: 'A note', label: 'Note' }, on: 'note' },
loud ? { c: 'Callout', p: { tone: 'info', title: note || 'Nothing yet' } } : { c: 'Text', p: { tone: 'muted', size: 'sm' }, k: [note || 'Nothing yet'] },
] });
wisp.on('note', (v) => { note = String(v); draw(); });
wisp.on('loud', (v) => { loud = v === true; draw(); });
draw();
```
## Focus
*Asked for:* A setting of my own that other things can read, with no UI
`wisp-plugin.json`
```json
{
"wispPlugin": 1,
"id": "user.focus",
"name": "Focus",
"version": "1.0.0",
"api": "^1",
"description": "A focus-mode switch in Settings.",
"permissions": [],
"contributes": {
"settings": [
{
"key": "user.focus.on",
"type": "bool",
"default": false,
"title": "Focus mode"
}
]
}
}
```
## Pink
*Asked for:* A theme: a pink send button, a warmer accent, and its own shade in dark mode
`wisp-plugin.json`
```json
{
"wispPlugin": 1,
"id": "user.pink",
"name": "Pink",
"version": "1.0.0",
"api": "^1",
"description": "A pink send button and a warmer accent. A theme applies once you trust it: wisp plugin trust user.pink.",
"permissions": [],
"contributes": {
"partStyles": {
":root": {
"--accent": "#d6336c"
},
"composer.send": {
"background": "#d6336c",
"color": "#ffffff",
"border-radius": "999px"
},
"@dark": {
":root": {
"--accent": "#ff7aa8"
},
"composer.send": {
"background": "#ff7aa8",
"color": "#1a1a1a"
}
}
}
}
}
```
---
# Import a wisp home
Source: https://trywisp.dev/docs/migrate/import.md
Have a wisp home from another install, or a `~/.wisp` folder copied from another computer? Its setup and its task
history come in with one command. It shows its plan first and changes nothing until you say yes.
## Import
**Desktop app:**
Importing runs in a terminal. Run the CLI command, then open the desktop app: what came in is already there.
**Phone app:**
Importing runs in a terminal on the computer, so it can't be done from the phone. Run the CLI command there,
then open that computer in the phone app: what came in is already there.
**TUI:**
Quit the TUI (**q**), run the CLI command, then `wisp tui` again.
**CLI:**
```sh
wisp import --dry-run # the plan only
wisp import # the plan, then "Import it? [y/N]"
wisp import --yes # no question (for scripts)
wisp import /path/to/other/home # another folder than ~/.wisp
```
Outside a terminal, `wisp import` needs `--yes`.
## What comes over
It reads the home's `config.json` and its `sessions` folder, and brings in:
- **Projects.** A project whose folder isn't on this computer is left out, and the plan says so.
- **Defaults**, as settings: your default harness, model and effort among them.
- **Recipes**, as declared tasks.
- **Automations and schedules**, as triggers.
- **Crew members** and **teams**.
- **Machines** and **connectors**.
- **Task history:** every task with its transcript and its changes per turn. Tasks are history, so they are
imported, never planned. A task already imported is skipped, so you can run the import again.
The plan shows each change as `wisp apply` would. Notes under it name anything that didn't carry over: a spell, for
one, isn't imported; [Make wisp your own](../../plugins/make-wisp-your-own/) shows how to build it as a
[plugin](../../concepts/plugins/), or ask an agent to.
## Secrets
Tokens and keys are never written into a plan. A connector's environment or a channel's token that wisp already
has becomes a `${secret:NAME}` reference. Any other is named in the plan's notes. Set it with:
```sh
wisp secret set NAME # typed hidden, or piped: echo "$TOKEN" | wisp secret set NAME
```
## Keep your setup in the repo
After importing, write it out as a formula you can review and commit:
```sh
wisp export > .wisp/setup.wisp.yml
```
See [Formulas](../../concepts/formulas/).