Change wisp itself, by asking: spells

Cast one

1. Start wisp. $npx wisp-agentsCopy
2. Say what to change. ⌘K → Cast a spell…, Settings → Spells, or type /spell in the prompt box: /spell a floating button that opens all my open PRs, with how many there are. Be as specific as you like about where it goes and what it shows.
3. Look at the preview. The agent works in an empty folder of its own: it reads wisp’s spell reference, samples your real data, checks the spell with wisp until it passes, and hands it back as a card. The card shows its buttons as they will look, its panels drawn with your data, and a plain-words list of what it adds.
4. Try it, then keep it. Try it applies the spell to this window only; Undo takes it back. Turn on keeps it. A follow-up on the card changes it (“make it a top bar button”, “only for api-server”), and “remove the … spell” drops it.

Every spell you have is in Settings → Spells, with a switch, its reach, and export, copy and remove.

What a spell can change

What’s in a spell file

A spell is one JSON object. Only wispSpell, id and name are required; everything else is a list of things to add or change. This is the whole My PRs spell:

{
  "wispSpell": 1,
  "id": "my-prs",
  "name": "My PRs",
  "version": "1.0.0",
  "description": "Open every PR you have open on GitHub, from a floating button.",
  "data": {
    "prs": {
      "gh": ["search", "prs", "--author", "@me", "--state", "open", "--json", "url,title,repository"],
      "refresh": 120
    }
  },
  "buttons": [
    {
      "slot": "float",
      "icon": "github",
      "label": "My PRs",
      "badge": {
        "count": "prs"
      },
      "do": {
        "openAll": {
          "data": "prs",
          "field": "url"
        }
      }
    }
  ]
}

• id, version: the file is ~/.wisp/spells/<id>.json. A changed spell keeps its id and bumps its version, so installing it again updates it in place.
• data: named sources wisp fetches for the spell. Here prs is a read-only gh command, refreshed every 120 seconds.
• buttons: each names a slot, a label, an icon, an optional badge (here: how many items prs has) and what it does.

The other top-level fields:

Text, labels, links and gh arguments can use {field} templates filled from the card’s task: {title}, {branch}, {project}, {agent}, {pr.number}, {pr.url} and more. In slash commands, {args} is what you typed after the command.

Where things can go

Spells never touch wisp’s page directly. They name a slot, and wisp puts the button, chip or panel there with its own markup, so wisp updates don’t break them.

Panels open as a dialog, a side drawer, pinned above the feed, or inside an open card. To restyle or hide something, a spell names a part (card.title, launcher.input, topbar.machines, …) and sets a short list of allowed CSS properties, props such as density or monospace, or the order of the card head.

The split view (tasks in a sidebar, the open one beside it) is a spell’s too: settings: { "view": "split" } switches to it, the sidebar part takes width, side (left, the default, or right) and details (full shows the model, machine and project on every row), split.main takes a readWidth, split.home a greeting over the prompt box, and the sidebar.top and split.head slots take buttons.

What buttons can do

Each action has a reach, and a spell’s reach is the furthest of its actions. You see it before you turn the spell on.

Data and scripts

A spell can read two kinds of data, and wisp fetches both; spell code never touches the network.

• wisp’s own routes, read-only: /sessions, /sessions/:id, /usage, /usage/tools, /projects, /recipes, /triggers, /machines, /agents, /preferences, /spells.
• Read-only gh commands: gh pr list|view|status|checks|diff, gh search prs|issues|repos|commits, gh issue list|view|status, gh run list|view, gh repo view|list, gh release list|view, gh workflow list|view, gh api. gh api may only read: no -X, -f, -F or --input.

To draw a panel, a spell carries a script: plain JavaScript functions that get the data and return wisp’s report blocks (stats, charts, checklists, callouts, tables of files, …). wisp checks what comes back and draws it with its own renderer. This is the panel behind Tool stats:

{
  "wispSpell": 1,
  "id": "tool-stats",
  "name": "Tool stats",
  "version": "1.0.0",
  "data": {
    "tools": {
      "wisp": "/usage/tools?days=30"
    }
  },
  "buttons": [
    {
      "slot": "topbar",
      "icon": "stats",
      "label": "Tools",
      "do": {
        "panel": "tools"
      }
    }
  ],
  "panels": [
    {
      "id": "tools",
      "title": "Tool calls · last 30 days",
      "as": "dialog",
      "data": ["tools"],
      "render": "tools"
    }
  ],
  "script": "export function tools({ tools: t }) {\n  return [\n    { type: 'stats', items: [{ label: 'tool calls', value: t.total.calls }, { label: 'turns', value: t.total.turns }, { label: 'spend', value: Math.round(t.total.cost * 100) / 100, unit: '$' }] },\n    { type: 'chart', title: 'By kind', items: t.kinds.map((k) => ({ label: k.kind, value: k.calls })) },\n    { type: 'chart', title: 'By harness', items: t.agents.map((a) => ({ label: a.agent, value: a.calls })) },\n  ];\n}"
}

Blocks, prompt rules and hooks

Spells also change what agents do, for every harness or only some (harnesses), and for every task or only some projects, agents or modes (when).

• Blocks. A new report block type. wisp tells agents about it while the spell is on, and the spell’s script draws it. The doc line is what agents read.
• Prompt rules. Lines added to agents’ system prompts: “Codex runs npm run lint before reporting”.
• Hooks. On turn.finished, turn.failed, session.started, session.waiting, if status, testsFailed, agent, project, hasPr, mode match, reply, mark done, archive, notify or call a webhook. max caps how often per task (default once).

{
  "wispSpell": 1,
  "id": "fix-failing-tests",
  "name": "Fix failing tests",
  "version": "1.0.0",
  "hooks": [
    {
      "on": "turn.finished",
      "if": {
        "testsFailed": true
      },
      "max": 1,
      "do": {
        "reply": "Some tests fail. Fix them, rerun the suite and report again."
      }
    }
  ]
}

Why it’s safe to keep one

• Spell code can’t reach anything. It runs in a sandboxed frame with no network, no page and no wisp API. It gets the data wisp fetched and returns blocks, which wisp checks and draws itself.
• Data is read-only. Spells read wisp’s own routes and read-only gh commands. They can’t merge, push or write.
• You see how far it reaches. Each spell is Safe, Acts for you, Reads GitHub or Runs commands, with every command listed. A command asks you before its first run.
• Some things stay put. Questions, approvals and Settings → Spells can’t be restyled or hidden, so a spell can’t lock you out of turning it off.
• Off means gone. Turning a spell off puts wisp back exactly as it was. WISP_SAFE=1 starts wisp with every spell off.

Share it with your team

Settings → Spells exports a spell as a .spell.json file, or copies its JSON for a chat. A colleague drops the file on wisp, pastes it (or a link) into Settings → Spells, or runs:

wisp spell install ./my-prs.spell.json --on
wisp spell install https://example.com/my-prs.spell.json
wisp spell install gist:<id>

They see the same review first, and it stays off until they turn it on. Commit a team’s spells to a repo and everyone installs the same set.

From the terminal

wisp spell cast "a /explain command that asks for a plain-words explanation" --wait
wisp spell export my-prs > my-prs.spell.json
wisp spell off --all

Over HTTP the same lives under /spells; see Integrations.

When something looks wrong

• wisp looks odd and you don’t know why. Settings → Spells → Turn every spell off, then turn them back on one at a time. If wisp won’t even open properly, start it with WISP_SAFE=1.
• A spell is listed as broken. wisp spell prints ! <id>: <why>. Usually it names a slot, part or action this version of wisp doesn’t have; ask for a follow-up on its card, or remove it.
• A button doesn’t show. Card buttons can have a when (only cards with a PR, only Codex tasks, …), and hidden parts take their buttons with them. Ask the agent which applies.
• The data is empty. gh sources need the GitHub CLI installed and signed in (gh auth status) on the machine wisp runs on.

Related guides

• Run coding agents in the backgroundHeadless runs that can still ask you, notify you, and report back in one screen.
• Multi-agent coding across Claude Code, Codex and moreA lead agent with a team on other harnesses, working in parallel.
• Run Claude Code and Codex in parallelSame task on both agents, or different tasks at once, each on its own branch.