wisp-agents 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 M0xoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="electron/icon.png" alt="wisp" width="120" />
+
+# wisp
+
+**Send coding agents off. Read the highlights.**
+
+Launch coding agents in the background, skip the transcript, and read the presentation they hand back when they finish.
+
+[![npm](https://img.shields.io/npm/v/wisp-agents?color=cb3837&logo=npm)](https://www.npmjs.com/package/wisp-agents)
+[![License: MIT](https://img.shields.io/badge/license-MIT-6a5cff.svg)](#license)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-339933?logo=node.js&logoColor=white)](https://nodejs.org)
+[![Electron](https://img.shields.io/badge/desktop-Electron-47848f?logo=electron&logoColor=white)](https://www.electronjs.org)
+[![Zero runtime deps](https://img.shields.io/badge/runtime%20deps-0-brightgreen)](package.json)
+[![Claude Code](https://img.shields.io/badge/harness-Claude%20Code-d97757)](https://claude.com/claude-code)
+
+[Quick start](#quick-start) · [Features](#features) · [CLI](#cli) · [Shortcuts](#keyboard-shortcuts) · [Architecture](#architecture) · [Adding a harness](#adding-a-harness) · [Roadmap](#roadmap)
+
+</div>
+
+---
+
+## Why wisp?
+
+Agent transcripts are long, and you rarely need them. wisp runs agent harnesses (Claude Code today, with Codex and opencode planned) on your projects in the background. When an agent finishes, it hands you a short, animated **presentation**: diffs, test results, commits, flows, and decisions. The session then waits in your queue.
+
+From there you can **follow up**, **answer its questions**, **take it over** in your terminal, or **mark it done**.
+
+```text
+ you ──▶ "fix the flaky auth test" ──▶ agent works in the background
+                                              │
+ you ◀── hero · diff · tests · next steps ◀───┘   (no transcript to read)
+```
+
+## Features
+
+| | |
+|---|---|
+| 🚀 **Fire and forget** | Launch a task from the UI or from any folder with `wisp "…"`. Each folder becomes a project. |
+| 🎞️ **Presentations, not transcripts** | Agents end with structured blocks that render as an animated, skimmable report. |
+| ❓ **Live questions** | Agents get an `ask_user` tool, so they can pause mid-run. Your answer goes straight back to the running agent. |
+| 🧾 **Real diffs** | Edits come from the agent's own tool calls, so `diff` blocks show what actually changed. |
+| 📥 **A queue** | Sessions sort into *Needs you*, *Working* (with a live one-line status), and *Done*. |
+| 🖥️ **Take over** | Opens your terminal with `claude --resume <id>` in the project folder. Works with Terminal, iTerm, Ghostty, Warp, kitty, WezTerm, or a custom command. |
+| 📎 **Attachments** | Paste screenshots or drop images, video, logs, or PDFs into the launcher. |
+| 🔐 **Permission modes** | Choose **Plan** (read-only), **Edits** (file edits auto-accepted), or **Full auto** for each launch. |
+| 🪶 **No runtime dependencies** | The server uses only Node built-ins. Electron is needed only for the desktop app. |
+
+## Quick start
+
+> **Requirements:** Node.js ≥ 20 and [Claude Code](https://claude.com/claude-code) (`claude`) installed and signed in.
+
+```sh
+npx wisp-agents                          # open the wisp desktop app
+npx wisp-agents "fix the flaky auth test" # launch a task in the current folder
+npx wisp-agents --browser                # or use it in the browser → http://localhost:4477
+```
+
+The first run downloads Electron for the desktop app; if that isn't possible, wisp opens in the browser instead.
+
+Or install it globally to get the `wisp` command everywhere:
+
+```sh
+npm install -g wisp-agents
+wisp "fix the flaky auth test"
+```
+
+From source:
+
+```sh
+git clone https://github.com/M0xoo/wisp.git
+cd wisp
+
+# Browser mode, with nothing to install:
+node bin/wisp.js           # → http://localhost:4477
+
+# Desktop app:
+npm install                # pulls Electron
+npm run app
+```
+
+On first launch, the *Welcome to wisp* session shows a live gallery of every presentation block.
+
+### Development
+
+```sh
+npm run dev        # desktop app: live reload for web/, relaunch on server/ and electron/ changes
+npm run dev:web    # browser mode, restarts the server when server/ changes
+```
+
+## CLI
+
+The CLI talks to a running wisp, or starts one if none is running. It works from any folder:
+
+```sh
+wisp                              # open wisp (or focus the running one)
+wisp "fix the flaky auth test"    # launch a task in this folder (it becomes a project)
+wisp add [path]                   # add a folder as a project (default: cwd)
+wisp --mode plan "audit deps"     # permission mode: plan | edits | auto
+```
+
+| Option | Description |
+|---|---|
+| `--port`, `-p N` | Port to use (default `4477`, or `WISP_PORT`) |
+| `--mode`, `-m` | `plan` · `edits` · `auto` |
+| `--browser`, `-b` | Use the browser instead of the desktop app |
+| `--no-open` | Just run the server; open nothing |
+| `--version`, `-v` | Print the version |
+
+> `npm install -g wisp-agents` (or `npm link` from a clone) puts `wisp` on your `PATH`. Without installing, use `npx wisp-agents …` with the same arguments.
+
+## Keyboard shortcuts
+
+| Key | Action |
+|---|---|
+| `N` | New task (focus the launcher) |
+| `⌘ ↵` | Launch and keep the launcher open for the next task |
+| `J` / `K` | Move down / up through the queue |
+| `O` / `↵` | Open or collapse the focused session |
+| `/` | Reply to the focused session |
+| `1`–`9` | Pick an option in a pending question |
+| `T` | Take over in your terminal |
+| `E` | Mark done and jump to the next session that needs you |
+| `R` | Replay the presentation |
+| `?` | Show all shortcuts |
+| `Esc` | Close, blur, or collapse |
+
+File paths in presentations open in your editor. VS Code, Cursor, Zed, and JetBrains IDEs are supported; pick one in **Settings**.
+
+## Architecture
+
+```text
+web/ (UI) ⇄ HTTP + SSE ⇄ server/ ── adapters/claude.js ── claude -p --output-format stream-json
+                                 └─ mcp-ask.js  (ask_user MCP tool, injected per run)
+```
+
+```text
+wisp/
+├── bin/
+│   └── wisp.js            # CLI: starts the server or talks to the running one
+├── server/
+│   ├── index.js           # HTTP API, SSE stream, static UI, uploads
+│   ├── runner.js          # session lifecycle, follow-ups, event normalization
+│   ├── protocol.js        # system prompt + ```wisp block parser (markdown fallback)
+│   ├── mcp-ask.js         # ask_user MCP server
+│   ├── store.js           # JSON-file persistence in ~/.wisp
+│   ├── terminal.js        # "take over" in your terminal
+│   ├── welcome.js         # the gallery session
+│   └── adapters/
+│       ├── index.js       # adapter registry + contract
+│       └── claude.js      # Claude Code adapter
+├── web/                   # vanilla JS UI, no build step
+│   ├── index.html
+│   ├── css/app.css
+│   └── js/{app,blocks,diff,md}.js
+└── electron/              # desktop shell
+    ├── main.js
+    └── preload.cjs
+```
+
+- **Protocol** (`server/protocol.js`): a system prompt tells agents to work autonomously and to end with a fenced `wisp` JSON block of presentation blocks. The parser reads that block, and falls back to plain markdown if it is missing.
+- **Adapters** (`server/adapters/`): one file per harness. An adapter turns a run into normalized events (`session`, `tool`, `change`, `text`, `result`, …) and provides a `resumeCommand` for take over.
+- **State** lives in `~/.wisp` (override with `WISP_HOME`): one JSON file per session, plus `config.json` and `uploads/`.
+
+### Presentation blocks
+
+`hero` · `markdown` · `steps` · `stats` · `files` · `tree` · `diff` · `code` · `tests` · `commits` · `terminal` · `compare` · `flow` · `chart` · `checklist` · `callout` · `image` · `question` · `next`
+
+## Adding a harness
+
+1. Copy `server/adapters/claude.js`.
+2. Implement `detect()`, `run()`, and `resumeCommand()`. The full contract is documented at the top of `server/adapters/index.js`.
+3. Register the adapter in `server/adapters/index.js`.
+
+If the harness has no system-prompt flag, prepend `systemPrompt` to the first prompt. If it supports MCP, pass `mcpServers` through so that `ask_user` works.
+
+## Roadmap
+
+- [x] Claude Code adapter
+- [x] Live `ask_user` questions
+- [x] Desktop app (Electron)
+- [ ] Codex adapter
+- [ ] opencode adapter
+
+## Contributing
+
+Issues and PRs are welcome. wisp has no build step: edit `web/` or `server/`, then run `npm run dev` (or `npm run dev:web`) to see your changes.
+
+## License
+
+[MIT](LICENSE) © M0xoo

package/bin/wisp.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// wisp — launcher + queue for coding agents.
+//
+//   wisp                   open the wisp desktop app (or focus the running one)
+//   wisp "fix the tests"   launch a wisp in the current folder
+//   wisp add [path]        add a folder as a project (default: current folder)
+//   --port N               port (default 4477, or WISP_PORT)
+//   --mode plan|edits|auto permission mode for a launch
+//   --browser              use the browser instead of the desktop app
+//   --no-open              just run the server, open nothing
+
+import { exec, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+const flags = { open: true, browser: false, port: Number(process.env.WISP_PORT) || 4477, mode: null };
+const words = [];
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--no-open') flags.open = false;
+  else if (a === '--browser' || a === '-b') flags.browser = true;
+  else if (a === '--port' || a === '-p') flags.port = Number(argv[++i]);
+  else if (a === '--mode' || a === '-m') flags.mode = argv[++i];
+  else if (a === '--version' || a === '-v') {
+    const { readFileSync } = await import('node:fs');
+    console.log(JSON.parse(readFileSync(new URL('../package.json', import.meta.url))).version);
+    process.exit(0);
+  } else if (a === '--help' || a === '-h') {
+    console.log('usage:\n  wisp                    open wisp\n  wisp "task"             launch a task in this folder\n  wisp add [path]         add a project\n\noptions: --port N  --mode plan|edits|auto  --browser  --no-open  --version');
+    process.exit(0);
+  } else words.push(a);
+}
+
+const base = `http://localhost:${flags.port}`;
+const api = (p, body) =>
+  fetch(`${base}/api${p}`, {
+    method: body ? 'POST' : 'GET',
+    headers: { 'content-type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  }).then(async (r) => {
+    const j = await r.json();
+    if (!r.ok) throw new Error(j.error || r.statusText);
+    return j;
+  });
+
+let running = false;
+try {
+  await api('/config');
+  running = true;
+} catch {}
+
+// The desktop app (Electron is an optional dependency) runs the server in its own process, so
+// it outlives this terminal. Without Electron, or with --browser/--no-open, serve from here.
+// A task or `add` sent to an already-running wisp just goes over the API, no window.
+const electron = flags.open && !flags.browser && (!running || !words.length) ? electronBinary() : null;
+if (electron) {
+  const child = spawn(electron, [fileURLToPath(new URL('..', import.meta.url))], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, WISP_PORT: String(flags.port) },
+  });
+  child.unref();
+  if (!running) await waitForServer();
+  console.log(`\n  ◌ wisp is open\n`);
+} else if (!running) {
+  const { startServer } = await import('../server/index.js');
+  await startServer({ port: flags.port });
+  console.log(`\n  ◌ wisp is floating at ${base}\n`);
+}
+
+let openPath = '/';
+if (words[0] === 'add') {
+  const dir = path.resolve(words[1] || process.cwd());
+  const p = await api('/projects', { path: dir }).catch((e) => console.error(`  ✗ ${e.message}`));
+  if (p) console.log(`  ✓ project added: ${p.name}  (${p.path})`);
+  if (running || electron) process.exit(0);
+} else if (words.length) {
+  const cfg = await api('/config');
+  const s = await api('/sessions', { prompt: words.join(' '), cwd: process.cwd(), agent: cfg.defaults.agent, mode: flags.mode || cfg.defaults.mode, model: cfg.defaults.model });
+  console.log(`  ◌ launched: ${s.title}`);
+  openPath = `/#/s/${s.id}`;
+  if (running || electron) process.exit(0); // the running wisp will show it in the queue
+}
+
+if (electron) process.exit(0);
+if (flags.open) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start ""' : 'xdg-open';
+  exec(`${cmd} "${base}${openPath}"`);
+}
+
+function electronBinary() {
+  try {
+    const bin = createRequire(import.meta.url)('electron'); // the electron package exports its binary path
+    return typeof bin === 'string' && existsSync(bin) ? bin : null;
+  } catch {
+    return null;
+  }
+}
+
+async function waitForServer() {
+  for (let i = 0; i < 150; i++) {
+    try {
+      return await api('/config');
+    } catch {
+      await new Promise((r) => setTimeout(r, 200));
+    }
+  }
+  console.error('  ✗ the wisp app did not start in time — try `wisp --browser`');
+  process.exit(1);
+}

package/electron/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1024" height="1024" viewBox="0 0 1024 1024">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#1d1c22"/><stop offset="1" stop-color="#0e0e10"/></linearGradient>
+    <radialGradient id="glow" cx="50%" cy="50%" r="50%"><stop offset="0" stop-color="#6a5cff" stop-opacity=".55"/><stop offset="1" stop-color="#6a5cff" stop-opacity="0"/></radialGradient>
+    <radialGradient id="orb" cx="36%" cy="32%" r="68%"><stop offset="0" stop-color="#fff"/><stop offset=".16" stop-color="#d9fff6"/><stop offset=".38" stop-color="#2fd0b4"/><stop offset=".78" stop-color="#6a5cff"/><stop offset="1" stop-color="#4b3fe0"/></radialGradient>
+  </defs>
+  <rect x="100" y="100" width="824" height="824" rx="190" fill="url(#bg)"/>
+  <circle cx="512" cy="512" r="330" fill="url(#glow)"/>
+  <circle cx="512" cy="512" r="210" fill="url(#orb)"/>
+  <circle cx="742" cy="360" r="16" fill="#fff" opacity=".9"/>
+  <circle cx="300" cy="650" r="10" fill="#bff" opacity=".7"/>
+  <circle cx="690" cy="720" r="7" fill="#fff" opacity=".6"/>
+</svg>

package/electron/main.js

@@ -0,0 +1,147 @@
+// wisp desktop shell. The Node server runs inside Electron's main process and
+// the window loads the same UI the browser mode serves.
+
+import { app, BrowserWindow, shell, nativeTheme, Menu, dialog, ipcMain } from 'electron';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const PORT = Number(process.env.WISP_PORT) || 4477;
+const URL_BASE = `http://localhost:${PORT}`;
+const DEV = process.env.WISP_DEV === '1';
+
+// Apps launched from Finder/Dock get a minimal PATH, so `claude` (nvm, homebrew,
+// ~/.local/bin…) wouldn't be found. Borrow the PATH from the user's login shell.
+function inheritShellPath() {
+  if (process.platform === 'win32') return;
+  try {
+    const sh = process.env.SHELL || '/bin/zsh';
+    const out = execFileSync(sh, ['-ilc', 'printf "__WISP__%s__WISP__" "$PATH"'], { encoding: 'utf8', timeout: 5000 });
+    const m = out.match(/__WISP__(.*)__WISP__/);
+    if (m?.[1]) process.env.PATH = m[1];
+  } catch {}
+}
+
+if (DEV) app.commandLine.appendSwitch('remote-debugging-port', process.env.WISP_DEBUG_PORT || '9339');
+if (!app.requestSingleInstanceLock()) app.quit();
+
+let win = null;
+let server = null;
+
+async function ensureServer() {
+  try {
+    await fetch(`${URL_BASE}/api/config`);
+    return; // a wisp server (e.g. from the CLI) is already running — just attach to it
+  } catch {}
+  const { startServer } = await import('../server/index.js');
+  server = await startServer({ port: PORT, handleSignals: false });
+}
+
+function createWindow() {
+  win = new BrowserWindow({
+    width: 1380,
+    height: 900,
+    minWidth: 720,
+    minHeight: 520,
+    title: 'wisp',
+    titleBarStyle: process.platform === 'darwin' ? 'hiddenInset' : 'default',
+    trafficLightPosition: { x: 16, y: 18 },
+    backgroundColor: nativeTheme.shouldUseDarkColors ? '#111111' : '#ffffff',
+    show: false,
+    webPreferences: { contextIsolation: true, sandbox: true, preload: path.join(here, 'preload.cjs') },
+  });
+
+  win.loadURL(URL_BASE);
+  win.once('ready-to-show', () => win.show());
+
+  // Editor links (vscode://…), docs links etc. open outside the app.
+  win.webContents.setWindowOpenHandler(({ url }) => {
+    if (!url.startsWith(URL_BASE)) shell.openExternal(url);
+    else return { action: 'allow' };
+    return { action: 'deny' };
+  });
+  win.webContents.on('will-navigate', (e, url) => {
+    if (!url.startsWith(URL_BASE)) {
+      e.preventDefault();
+      shell.openExternal(url);
+    }
+  });
+
+  // The page title carries the "needs you" count: "(3) wisp" → dock badge.
+  win.on('page-title-updated', (e, title) => {
+    e.preventDefault();
+    const n = Number(title.match(/^\((\d+)\)/)?.[1] || 0);
+    app.setBadgeCount(n);
+  });
+
+  win.on('closed', () => (win = null));
+}
+
+ipcMain.handle('wisp:pick-folder', async () => {
+  const r = await dialog.showOpenDialog(win, { properties: ['openDirectory', 'createDirectory'], buttonLabel: 'Add project' });
+  return r.canceled ? null : r.filePaths[0];
+});
+
+app.on('second-instance', () => {
+  if (!win) return createWindow();
+  if (win.isMinimized()) win.restore();
+  win.focus();
+});
+
+// Agents keep running with the window closed; quitting stops them.
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') app.quit();
+});
+app.on('activate', () => !win && createWindow());
+app.on('before-quit', () => server?.shutdown());
+
+// Dev: web/ edits reload the window, server/ or electron/ edits relaunch the app.
+// Agents run inside this process, so when wisp is working on itself a relaunch
+// would kill them mid-task: hold it until nothing is running.
+function watchForDev() {
+  const root = path.join(here, '..');
+  let timer;
+  let pending = null;
+  const debounce = (fn) => (clearTimeout(timer), (timer = setTimeout(fn, 120)));
+  const busy = () => server?.runner.live.size || 0;
+  const relaunch = () => {
+    if (busy()) return;
+    clearInterval(pending);
+    console.log('[wisp dev] relaunching');
+    server?.shutdown();
+    app.relaunch();
+    app.exit(0);
+  };
+  fs.watch(path.join(root, 'web'), { recursive: true }, () =>
+    debounce(() => BrowserWindow.getAllWindows().forEach((w) => w.webContents.reloadIgnoringCache())),
+  );
+  for (const dir of ['server', 'electron'])
+    fs.watch(path.join(root, dir), { recursive: true }, (_, file) =>
+      debounce(() => {
+        if (!busy()) return relaunch();
+        console.log(`[wisp dev] ${dir}/${file} changed — relaunching once ${busy()} running session(s) finish`);
+        pending ??= setInterval(relaunch, 2000);
+      }),
+    );
+  console.log('[wisp dev] watching web/ (reload) and server/, electron/ (relaunch when idle)');
+}
+
+app.whenReady().then(async () => {
+  app.setName('wisp');
+  if (process.platform === 'darwin') app.dock?.setIcon(path.join(here, 'icon.png'));
+  Menu.setApplicationMenu(
+    Menu.buildFromTemplate([
+      ...(process.platform === 'darwin' ? [{ role: 'appMenu' }] : []),
+      { role: 'fileMenu' },
+      { role: 'editMenu' },
+      { role: 'viewMenu' },
+      { role: 'windowMenu' },
+    ]),
+  );
+  inheritShellPath();
+  await ensureServer();
+  createWindow();
+  if (DEV) watchForDev();
+});

package/electron/preload.cjs

@@ -0,0 +1,6 @@
+// Minimal bridge for desktop-only niceties. Sandboxed preloads must be CommonJS.
+const { contextBridge, ipcRenderer } = require('electron');
+
+contextBridge.exposeInMainWorld('wispDesktop', {
+  pickFolder: () => ipcRenderer.invoke('wisp:pick-folder'),
+});

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "wisp-agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Launch coding agents, skip the transcript, read the presentation.",
+  "type": "module",
+  "bin": {
+    "wisp": "bin/wisp.js",
+    "wisp-agents": "bin/wisp.js"
+  },
+  "files": [
+    "bin/",
+    "electron/",
+    "server/",
+    "web/"
+  ],
+  "scripts": {
+    "start": "node bin/wisp.js",
+    "app": "electron .",
+    "dev": "WISP_DEV=1 electron .",
+    "dev:web": "node --watch-path=server bin/wisp.js --no-open",
+    "prepublishOnly": "node --check bin/wisp.js && node -e \"import('./server/index.js')\" && node --check electron/main.js"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "coding-agent",
+    "ai",
+    "agents",
+    "cli",
+    "launcher"
+  ],
+  "author": "M0xoo",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/M0xoo/wisp.git"
+  },
+  "homepage": "https://github.com/M0xoo/wisp#readme",
+  "bugs": {
+    "url": "https://github.com/M0xoo/wisp/issues"
+  },
+  "main": "electron/main.js",
+  "optionalDependencies": {
+    "electron": "^44.8.0"
+  }
+}