morphe-ai 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Morphe
+
+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,125 @@
-# Temporary Holding Version
+# morphe
 
-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.
+Morphe in your terminal. Say what you want; the agent reads, writes and runs things in the folder you are in. You bring the model: a key for Claude, GPT, Gemini, Groq, DeepSeek, xAI or OpenRouter, a free local model through Ollama or LM Studio, or any server that speaks the OpenAI chat protocol. Your key is stored on your machine and sent only to the provider you chose.
+
+`morphe page` is the website in a shell: one sentence in, a working `index.html` out.
+
+## Install
+
+```bash
+npm i -g morphe-ai
+```
+
+Also works with `pnpm add -g morphe-ai`, `yarn global add morphe-ai` and `bun add -g morphe-ai`. Node.js 18 or newer.
+
+No Node.js? On Windows, grab `morphe-windows-x64.zip` from the releases page, unzip it and run `morphe.exe` (put it on your PATH to call it from anywhere).
+
+## First five minutes
+
+```bash
+morphe setup            # choose an endpoint, paste your key, pick a default model
+cd some-project
+morphe                  # chat; the agent works in this folder
+```
+
+One task and done:
+
+```bash
+morphe do "add a dark-mode switch to the header"
+```
+
+A page from a sentence, exactly like the site:
+
+```bash
+mkdir cafe && cd cafe
+morphe page "a menu page for a small café: prices, a few photos, opening hours"
+# -> index.html  (open it in a browser)
+```
+
+## Models
+
+A model is written `endpoint/model-id`:
+
+```bash
+morphe models                          # everything your keys can reach
+morphe use anthropic/claude-opus-5-5   # default for every run
+morphe -m groq/llama-3.3-70b-versatile # just this run
+```
+
+Built-in endpoints: `anthropic`, `openai`, `openrouter`, `gemini`, `groq`, `deepseek`, `xai`, `ollama`, `lmstudio`. Keys may also come from the usual environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `DEEPSEEK_API_KEY`, `XAI_API_KEY`).
+
+Any other OpenAI-compatible server: choose **custom** in `morphe setup`, or add it to `~/.morphe/settings.json`:
+
+```json
+{
+  "model": "together/meta-llama/Llama-3.3-70B-Instruct-Turbo",
+  "endpoints": {
+    "together": { "kind": "openai", "url": "https://api.together.xyz/v1", "key": "…" }
+  }
+}
+```
+
+## Modes
+
+| Mode    | What it may do |
+|---------|----------------|
+| `build` | Default. List, view, search, write, patch, run shell commands. |
+| `page`  | Build or edit a single `index.html`, like the website. Files only, never commands. |
+| `plan`  | Look around and write a plan. Changes nothing. |
+
+Pick one with `-M page`, or `:mode page` inside a chat. Your own modes are small JSON files in `~/.morphe/modes/` (everywhere) or `./.morphe/modes/` (this project):
+
+```json
+{
+  "about": "Reviews code and points out problems",
+  "tools": ["ls", "view", "glob", "grep"],
+  "model": "anthropic/claude-sonnet-5-5",
+  "system": "You are a careful reviewer. Report bugs, risky code and unclear names. Do not change files."
+}
+```
+
+Then `morphe -M reviewer`.
+
+**Tools:** `ls`, `view`, `glob`, `grep`, `write`, `patch`, `shell`. Every path is kept inside the project folder.
+
+## Project notes
+
+A `MORPHE.md` (or `AGENTS.md`) in the project root is read at the start of every chat. Put your stack, conventions and the commands to build and test there.
+
+## Asking before acting
+
+By default Morphe asks before it writes a file or runs a command. Answer `a` to allow that kind of action for the rest of the chat, pass `--auto` to skip the questions, or set it once in settings:
+
+```json
+{ "approve": { "write": "ask", "shell": "ask" } }
+```
+
+Values: `ask`, `allow`, `deny`. `morphe page` always writes without asking; that is its whole job.
+
+## Settings (`~/.morphe/settings.json`)
+
+| Key | Meaning |
+|-----|---------|
+| `model` | default `endpoint/model-id` |
+| `mode` | default mode (`build`) |
+| `effort` | Claude only: `low`, `medium`, `high`, `xhigh`, `max` |
+| `approve` | `{ "write": …, "shell": … }` |
+| `endpoints` | your keys and custom URLs |
+
+A project may override anything except keys in `./.morphe/settings.json`. Every chat is logged to `./.morphe/sessions/*.jsonl` so you can see later what was done.
+
+## Inside a chat
+
+`:model <ref>` · `:mode <name>` · `:models` · `:modes` · `:reset` · `:auto` · `:usage` · `:quit`
+
+## Building the executables
+
+```bash
+cd cli && npm install
+bun scripts/build.mjs windows-x64    # dist/morphe-windows-x64/morphe.exe + .zip + SHA256SUMS
+bun scripts/build.mjs                # all targets
+```
+
+## License
+
+MIT.

package/bin/morphe.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { run } from '../src/index.js';
+
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code || 0),
+  (err) => {
+    console.error(`\n  ✗ ${err?.message || err}`);
+    process.exit(1);
+  },
+);

package/package.json

@@ -1,6 +1,41 @@
-{
-  "name": "morphe-ai",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "morphe-ai",
+  "version": "0.2.1",
+  "description": "Morphe in your terminal. Say what you want built and the agent makes it in your project folder, on whichever model you bring: Claude, GPT, Gemini, Groq, DeepSeek, xAI, OpenRouter, or a local Ollama / LM Studio model.",
+  "type": "module",
+  "bin": {
+    "morphe": "bin/morphe.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun scripts/build.mjs",
+    "build:win": "bun scripts/build.mjs windows-x64",
+    "start": "node bin/morphe.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "morphe",
+    "ai",
+    "agent",
+    "cli",
+    "coding-agent",
+    "web-builder",
+    "claude",
+    "byok",
+    "vibe-coding"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^1.1.0",
+    "openai": "^7.39.0"
+  },
+  "author": "Morphe crew",
+  "homepage": "https://morpheagent.xyz"
+}

package/src/agent.js

@@ -0,0 +1,73 @@
+// The loop: ask the model, run what it asks for, feed the results back, until it stops.
+// Provider differences are hidden behind the two small clients in ./llm.
+import fs from 'node:fs';
+import path from 'node:path';
+import { endpoint, splitModel, LOCAL_DIR } from './config.js';
+import { anthropicClient, anthropicModels } from './llm/anthropic.js';
+import { openaiClient, openaiModels } from './llm/openai.js';
+import { systemPrompt } from './modes.js';
+import { TOOL_DEFS, describe, execute } from './tools.js';
+
+const MAX_STEPS = 50;
+
+export function listModels(ep) {
+  return ep.kind === 'anthropic' ? anthropicModels(ep) : openaiModels(ep);
+}
+
+/**
+ * A conversation with one model in one mode. `events`: { text, thinking, tool(name,input), done(usage), note(msg) }.
+ * `approve(kind, what)` decides writes and shell commands.
+ */
+export function createAgent({ settings, mode, modeName, modelRef, cwd = process.cwd(), approve }) {
+  const { endpoint: epName, model } = splitModel(modelRef);
+  const ep = endpoint(settings, epName);
+  const tools = TOOL_DEFS.filter((t) => mode.tools.includes(t.name));
+  const allowed = new Set(mode.tools);
+  const system = systemPrompt(mode, cwd);
+  const client = ep.kind === 'anthropic' ? anthropicClient(ep, model, { system, tools, effort: settings.effort }) : openaiClient(ep, model, { system, tools });
+  const history = [];
+  const totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  const transcript = openTranscript(cwd, modeName, modelRef);
+
+  async function send(text, events, signal) {
+    history.push(client.user(text));
+    transcript?.write({ role: 'user', text });
+    for (let step = 0; step < MAX_STEPS; step++) {
+      const r = await client.step(history, events, signal);
+      for (const k of Object.keys(totals)) totals[k] += r.usage[k] || 0;
+      if (r.stop === 'refusal') { events.note?.('The model declined this request. Try putting it differently.'); return; }
+      if (r.stop === 'pause_turn') { history.push(client.assistant(r)); continue; }
+      if (r.stop === 'max_tokens' && r.calls.length) { events.note?.('The reply was cut off mid tool call. Ask for the next part in smaller steps.'); return; }
+      history.push(client.assistant(r));
+      transcript?.write({ role: 'assistant', text: r.text, calls: r.calls.map((c) => c.name) });
+      if (!r.calls.length) return;
+      const results = [];
+      for (const call of r.calls) {
+        if (!call.input) { results.push({ id: call.id, text: 'The tool arguments were not valid JSON. Try again.', error: true }); continue; }
+        events.tool?.(call.name, call.input);
+        const out = await execute(call.name, call.input, { root: cwd, allowed, approve });
+        if (out.error) events.toolError?.(out.text);
+        results.push({ id: call.id, ...out });
+        transcript?.write({ role: 'tool', name: call.name, summary: describe(call.name, call.input), error: !!out.error });
+      }
+      const block = client.results(results);
+      Array.isArray(block) ? history.push(...block) : history.push(block);
+    }
+    events.note?.(`Stopped after ${MAX_STEPS} steps. Say "continue" to keep going.`);
+  }
+
+  return { send, totals, modelRef, modeName, endpointName: epName };
+}
+
+/** Every session is logged to .morphe/sessions/<timestamp>.jsonl so you can see what happened later. */
+function openTranscript(cwd, mode, model) {
+  try {
+    const dir = path.join(cwd, LOCAL_DIR, 'sessions');
+    fs.mkdirSync(dir, { recursive: true });
+    const file = path.join(dir, new Date().toISOString().replace(/[:.]/g, '-') + '.jsonl');
+    fs.appendFileSync(file, JSON.stringify({ started: new Date().toISOString(), mode, model }) + '\n');
+    return { file, write: (e) => fs.appendFileSync(file, JSON.stringify({ t: Date.now(), ...e }) + '\n') };
+  } catch {
+    return null;
+  }
+}

package/src/config.js

@@ -0,0 +1,66 @@
+// Where Morphe keeps its keys and preferences: ~/.morphe/settings.json, with per-project
+// overrides in ./.morphe/settings.json. Keys only ever live in the home file.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const HOME_DIR = process.env.MORPHE_HOME || path.join(os.homedir(), '.morphe');
+export const SETTINGS = path.join(HOME_DIR, 'settings.json');
+export const LOCAL_DIR = '.morphe';
+
+/** Known providers. Anything speaking the OpenAI chat protocol can be added as a custom endpoint. */
+export const PROVIDERS = {
+  anthropic: { kind: 'anthropic', title: 'Anthropic (Claude)', envKey: 'ANTHROPIC_API_KEY', suggest: 'claude-opus-5-5' },
+  openai: { kind: 'openai', title: 'OpenAI', url: 'https://api.openai.com/v1', envKey: 'OPENAI_API_KEY' },
+  openrouter: { kind: 'openai', title: 'OpenRouter', url: 'https://openrouter.ai/api/v1', envKey: 'OPENROUTER_API_KEY' },
+  gemini: { kind: 'openai', title: 'Google Gemini', url: 'https://generativelanguage.googleapis.com/v1beta/openai/', envKey: 'GEMINI_API_KEY' },
+  groq: { kind: 'openai', title: 'Groq', url: 'https://api.groq.com/openai/v1', envKey: 'GROQ_API_KEY' },
+  deepseek: { kind: 'openai', title: 'DeepSeek', url: 'https://api.deepseek.com/v1', envKey: 'DEEPSEEK_API_KEY' },
+  xai: { kind: 'openai', title: 'xAI (Grok)', url: 'https://api.x.ai/v1', envKey: 'XAI_API_KEY' },
+  ollama: { kind: 'openai', title: 'Ollama (local)', url: 'http://localhost:11434/v1', keyless: true },
+  lmstudio: { kind: 'openai', title: 'LM Studio (local)', url: 'http://localhost:1234/v1', keyless: true },
+};
+
+const BASE = { model: '', mode: 'build', effort: '', approve: { write: 'ask', shell: 'ask' }, endpoints: {} };
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (e) { if (e.code === 'ENOENT') return {}; throw new Error(`${file} is not valid JSON: ${e.message}`); }
+}
+
+export const loadHome = () => ({ ...structuredClone(BASE), ...readJson(SETTINGS) });
+
+export function loadSettings(cwd = process.cwd()) {
+  const home = loadHome();
+  const local = readJson(path.join(cwd, LOCAL_DIR, 'settings.json'));
+  return { ...home, ...local, approve: { ...home.approve, ...local.approve }, endpoints: { ...home.endpoints, ...local.endpoints } };
+}
+
+export function saveHome(settings) {
+  fs.mkdirSync(HOME_DIR, { recursive: true });
+  fs.writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + '\n', { mode: 0o600 });
+}
+
+/** "groq/llama-3.3-70b" -> { endpoint: "groq", model: "llama-3.3-70b" }. Model ids may contain slashes. */
+export function splitModel(ref) {
+  const i = (ref || '').indexOf('/');
+  if (i < 1) throw new Error(`A model is written as endpoint/model-id, for example anthropic/claude-opus-5-5 (got "${ref || ''}").`);
+  return { endpoint: ref.slice(0, i), model: ref.slice(i + 1) };
+}
+
+/** Everything needed to talk to one endpoint: kind, url, key. */
+export function endpoint(settings, name) {
+  const known = PROVIDERS[name];
+  const own = settings.endpoints?.[name];
+  if (!known && !own) throw new Error(`Unknown endpoint "${name}". Run "morphe setup" to add it.`);
+  const e = { name, kind: 'openai', ...known, ...own };
+  e.key = own?.key || (e.envKey && process.env[e.envKey]) || '';
+  if (!e.key && !e.keyless) throw new Error(`No key for "${name}". Run "morphe setup" or set ${e.envKey || 'a key in settings.json'}.`);
+  return e;
+}
+
+export function hideKeys(settings) {
+  const c = structuredClone(settings);
+  for (const e of Object.values(c.endpoints || {})) if (e.key) e.key = e.key.slice(0, 5) + '…' + e.key.slice(-3);
+  return c;
+}

package/src/index.js

@@ -0,0 +1,224 @@
+// morphe: the command line. Parses arguments, runs commands, hosts the chat.
+import { PROVIDERS, SETTINGS, endpoint, hideKeys, loadHome, loadSettings, saveHome, splitModel } from './config.js';
+import { createAgent, listModels } from './agent.js';
+import { loadModes } from './modes.js';
+import { describe } from './tools.js';
+import { LOGO, bad, faint, ok, orange, prompter, sky, spinner, strong } from './ui.js';
+import { VERSION } from './version.js';
+
+const USAGE = `${strong('morphe')} ${faint('v' + VERSION)} · say it, launch it
+
+${strong('Commands')}
+  morphe                         chat with the agent in this folder
+  morphe do "<task>"             one task, then exit
+  morphe page "<what>"           build index.html from one sentence (like the website)
+  morphe setup                   add an endpoint and your own key
+  morphe forget <endpoint>       remove a saved key
+  morphe models [endpoint]       what your keys can use
+  morphe use <endpoint/model>    set the default model
+  morphe modes                   list modes (build, page, plan, yours)
+  morphe settings                show settings (keys hidden)
+
+${strong('Flags')}
+  -m, --model <endpoint/model>   model for this run
+  -M, --mode <name>              mode for this run
+  --auto                         never ask before writing files or running commands
+  -h, --help · -v, --version
+
+${strong('In chat')}
+  :model <ref>  :mode <name>  :models  :modes  :reset  :auto  :usage  :quit
+
+Settings: ${SETTINGS}. Custom modes: ~/.morphe/modes/*.json or ./.morphe/modes/*.json. Project notes: MORPHE.md.`;
+
+export async function run(argv) {
+  const flags = { auto: false, model: '', mode: '' };
+  const rest = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--auto') flags.auto = true;
+    else if (a === '-m' || a === '--model') flags.model = argv[++i] || '';
+    else if (a === '-M' || a === '--mode') flags.mode = argv[++i] || '';
+    else if (a === '-h' || a === '--help') return void console.log(USAGE);
+    else if (a === '-v' || a === '--version') return void console.log(VERSION);
+    else rest.push(a);
+  }
+  const [cmd, ...args] = rest;
+  switch (cmd) {
+    case undefined: return chat(flags);
+    case 'do': return chat({ ...flags, task: args.join(' ') });
+    case 'page': return chat({ ...flags, mode: flags.mode || 'page', auto: true, task: args.join(' ') });
+    case 'setup': return setup();
+    case 'forget': return forget(args[0]);
+    case 'models': return models(args[0]);
+    case 'use': return use(args[0]);
+    case 'modes': return modes();
+    case 'settings': return void console.log(faint(SETTINGS) + '\n' + JSON.stringify(hideKeys(loadSettings()), null, 2));
+    case 'help': return void console.log(USAGE);
+    default: throw new Error(`"${cmd}" is not a command. For a task, write: morphe do "${cmd} ${args.join(' ')}".`);
+  }
+}
+
+/* ---------------------------------------------------------------- setup */
+async function setup() {
+  const p = prompter();
+  try {
+    console.log(LOGO);
+    console.log(strong('  Add an endpoint.') + faint(' Your key stays in ' + SETTINGS + ' on this machine.\n'));
+    const names = Object.keys(PROVIDERS);
+    names.forEach((n, i) => console.log(`  ${orange(String(i + 1).padStart(2))}  ${n.padEnd(11)} ${faint(PROVIDERS[n].title)}`));
+    console.log(`  ${orange(String(names.length + 1).padStart(2))}  ${'custom'.padEnd(11)} ${faint('any OpenAI-compatible URL')}`);
+    const n = Number(await p.ask('\n  which one? '));
+    if (!(n >= 1 && n <= names.length + 1)) throw new Error('Pick a number from the list.');
+    const home = loadHome();
+    let name;
+    const entry = {};
+    if (n === names.length + 1) {
+      name = (await p.ask('  name for it (letters, numbers, -): ')).toLowerCase();
+      if (!/^[a-z0-9_-]+$/.test(name)) throw new Error('Letters, numbers, - or _ only.');
+      entry.kind = 'openai';
+      entry.url = await p.ask('  base URL (e.g. https://api.together.xyz/v1): ');
+    } else name = names[n - 1];
+    const known = PROVIDERS[name] || {};
+    if (!known.keyless) {
+      const key = await p.secret(`  API key for ${name}${known.envKey ? faint(` (empty = use $${known.envKey})`) : ''}: `);
+      if (key) entry.key = key;
+    }
+    home.endpoints[name] = { ...home.endpoints[name], ...entry };
+
+    const sp = spinner('checking the connection…');
+    let ids = [];
+    try { ids = await listModels(endpoint(home, name)); sp.stop(); console.log(ok(`  ✓ connected, ${ids.length} models`)); }
+    catch (e) { sp.stop(); console.log(bad('  ✗ ' + reason(e))); if ((await p.ask('  save anyway? [y/N] ')).toLowerCase() !== 'y') return; }
+    const first = ids.includes(known.suggest) ? known.suggest : known.suggest || ids[0];
+    if (ids.length) { console.log(faint('\n  models:')); for (const id of ids.slice(0, 20)) console.log('    ' + id); if (ids.length > 20) console.log(faint(`    …${ids.length - 20} more (morphe models ${name})`)); }
+    const model = (await p.ask(`\n  default model${first ? faint(` [${first}]`) : ''}: `)) || first;
+    if (model) home.model = `${name}/${model}`;
+    saveHome(home);
+    console.log(ok(`\n  ✓ saved ${name}`) + (model ? ` · default model ${sky(home.model)}` : ''));
+    console.log(faint('  run `morphe` in any project folder to start.'));
+  } finally { p.close(); }
+}
+
+function forget(name) {
+  if (!name) throw new Error('Usage: morphe forget <endpoint>');
+  const home = loadHome();
+  if (!home.endpoints[name]) throw new Error(`Nothing saved for "${name}".`);
+  delete home.endpoints[name];
+  if (home.model.startsWith(name + '/')) home.model = '';
+  saveHome(home);
+  console.log(ok(`  ✓ forgot ${name}`));
+}
+
+async function models(only) {
+  const settings = loadSettings();
+  const names = only ? [only] : Object.keys(settings.endpoints).concat(Object.keys(PROVIDERS).filter((n) => PROVIDERS[n].envKey && process.env[PROVIDERS[n].envKey] && !settings.endpoints[n]));
+  if (!names.length) return console.log('  No endpoints yet. Run `morphe setup`.');
+  for (const name of names) {
+    console.log(strong('  ' + name));
+    try { for (const id of await listModels(endpoint(settings, name))) { const ref = `${name}/${id}`; console.log(ref === settings.model ? orange(`  ● ${ref}`) : `    ${ref}`); } }
+    catch (e) { console.log(bad('    ' + reason(e))); }
+  }
+}
+
+function use(ref) {
+  if (!ref) throw new Error('Usage: morphe use <endpoint/model>');
+  const home = loadHome();
+  endpoint(home, splitModel(ref).endpoint);
+  home.model = ref;
+  saveHome(home);
+  console.log(ok(`  ✓ default model: ${ref}`));
+}
+
+function modes() {
+  for (const [name, m] of Object.entries(loadModes())) console.log(`  ${orange(name.padEnd(10))} ${m.about}${m.model ? faint(` · ${m.model}`) : ''}${m.file ? faint(` · ${m.file}`) : ''}`);
+}
+
+const reason = (e) => (e?.status === 401 ? 'the key was rejected (401)' : e?.status ? `${e.status} ${e.message}` : e?.cause?.code === 'ECONNREFUSED' ? `nothing is listening at ${e.cause.address}:${e.cause.port}` : e?.message || String(e));
+
+/* ---------------------------------------------------------------- chat */
+async function chat(flags) {
+  const settings = loadSettings();
+  const allModes = loadModes();
+  let modeName = flags.mode || settings.mode || 'build';
+  if (!allModes[modeName]) throw new Error(`No mode called "${modeName}". See: morphe modes`);
+  let modelRef = flags.model || allModes[modeName].model || settings.model;
+  if (!modelRef) throw new Error('No model yet. Run `morphe setup` to add your own key, or pass -m endpoint/model.');
+
+  const gate = { ...settings.approve };
+  if (flags.auto) gate.write = gate.shell = 'allow';
+  const oneShot = flags.task !== undefined;
+  let p = null;
+  const ask = () => (p ||= prompter());
+
+  async function approve(kind, what) {
+    if (gate[kind] === 'allow') return true;
+    if (gate[kind] === 'deny' || !process.stdin.isTTY) return false;
+    const [head, ...body] = what.split('\n');
+    console.log('\n  ' + orange('?') + ' ' + strong(head) + body.map((l) => '\n    ' + (l.startsWith('+') ? ok(l) : l.startsWith('-') ? bad(l) : faint(l))).join(''));
+    const a = (await ask().ask(orange('  allow? ') + faint('[y]es / [n]o / [a]lways: '))).toLowerCase();
+    if (a === 'a') gate[kind] = 'allow';
+    return a === 'a' || a === 'y' || a === 'yes';
+  }
+
+  let agent = createAgent({ settings, mode: allModes[modeName], modeName, modelRef, approve });
+  const fresh = () => (agent = createAgent({ settings, mode: allModes[modeName], modeName, modelRef, approve }));
+
+  let col0 = true;
+  let spin = null;
+  const events = {
+    text(t) { spin?.stop(); spin = null; process.stdout.write(t); col0 = t.endsWith('\n'); },
+    thinking() { if (!spin) spin = spinner('thinking…'); },
+    tool(name, input) { spin?.stop(); spin = null; if (!col0) process.stdout.write('\n'); console.log(sky('  ▸ ') + faint(describe(name, input))); col0 = true; },
+    toolError(msg) { console.log(bad('    ✗ ' + msg.split('\n')[0].slice(0, 150))); },
+    note(msg) { spin?.stop(); spin = null; console.log('\n  ' + orange('!') + ' ' + msg); col0 = true; },
+  };
+
+  async function task(text) {
+    spin = spinner('thinking…');
+    try { await agent.send(text, events); }
+    catch (e) { spin?.stop(); spin = null; console.log('\n  ' + bad('✗ ' + reason(e))); if (oneShot) process.exitCode = 1; }
+    spin?.stop(); spin = null;
+    if (!col0) process.stdout.write('\n');
+    col0 = true;
+  }
+
+  if (oneShot) {
+    if (!flags.task) throw new Error('Tell me what to do: morphe do "<task>" or morphe page "<what>"');
+    await task(flags.task);
+    p?.close();
+    return process.exitCode;
+  }
+
+  ask();
+  console.log(LOGO);
+  const where = () => faint(`  mode ${modeName} · model ${modelRef} · ${process.cwd()}`);
+  console.log(where());
+  console.log(faint('  say what you want. :help for commands, :quit to leave.\n'));
+
+  const commands = {
+    help: () => console.log(USAGE),
+    model: (arg) => { if (!arg) return console.log(where()); endpoint(settings, splitModel(arg).endpoint); modelRef = arg; fresh(); console.log(ok(`  ✓ model ${arg}`) + faint(' (new conversation)')); },
+    mode: (arg) => { if (!arg) return console.log(where()); if (!allModes[arg]) throw new Error(`No mode "${arg}".`); modeName = arg; fresh(); console.log(ok(`  ✓ mode ${arg}`) + faint(` · ${allModes[arg].about} (new conversation)`)); },
+    models: async () => { const n = splitModel(modelRef).endpoint; for (const id of await listModels(endpoint(settings, n))) console.log(`    ${n}/${id}`); },
+    modes,
+    reset: () => { fresh(); console.log(ok('  ✓ new conversation')); },
+    auto: () => { const on = gate.write !== 'allow' || gate.shell !== 'allow'; gate.write = gate.shell = on ? 'allow' : 'ask'; console.log(on ? orange('  ⚡ auto: writes and commands run without asking') : ok('  ✓ asking again before writes and commands')); },
+    usage: () => { const t = agent.totals; console.log(faint(`  tokens this conversation: ${t.input + t.cacheRead + t.cacheWrite} in (${t.cacheRead} from cache) · ${t.output} out`)); },
+  };
+
+  for (;;) {
+    const line = (await p.ask(orange('  › '))).trim();
+    if (!line) continue;
+    if (line === ':quit' || line === ':q' || line === ':exit') break;
+    if (line.startsWith(':')) {
+      const [name, ...a] = line.slice(1).split(/\s+/);
+      try { if (commands[name]) await commands[name](a.join(' ')); else console.log(bad(`  no command :${name}. try :help`)); }
+      catch (e) { console.log(bad('  ✗ ' + reason(e))); }
+      continue;
+    }
+    await task(line);
+    console.log();
+  }
+  p.close();
+  return 0;
+}

package/src/llm/anthropic.js

@@ -0,0 +1,42 @@
+// Claude through the official SDK. One `step` = one model call; the agent loop lives in agent.js.
+import Anthropic from '@anthropic-ai/sdk';
+
+const FALLBACK_OK = new Set(['claude-fable-5-1', 'claude-opus-5-5', 'claude-opus-5', 'claude-sonnet-5-5']);
+
+export function anthropicClient(ep, model, { system, tools, effort }) {
+  const client = new Anthropic({ apiKey: ep.key, baseURL: ep.url });
+  const toolDefs = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.input_schema, eager_input_streaming: true }));
+  const useFallback = !ep.url && FALLBACK_OK.has(model);
+
+  return {
+    /** messages: Anthropic-shaped history. Resolves { text, calls:[{id,name,input}], stop, usage, content }. */
+    async step(messages, events, signal) {
+      const params = { model, max_tokens: 64000, system, tools: toolDefs, messages, cache_control: { type: 'ephemeral' }, thinking: { type: 'adaptive', display: 'summarized' } };
+      if (effort) params.output_config = { effort };
+      const stream = useFallback
+        ? client.beta.messages.stream({ ...params, betas: ['server-side-fallback-2026-07-01'], fallbacks: 'default' }, { signal })
+        : client.messages.stream(params, { signal });
+      stream.on('text', (t) => events.text?.(t));
+      stream.on('thinking', (t) => events.thinking?.(t));
+      const msg = await stream.finalMessage();
+      const u = msg.usage || {};
+      return {
+        content: msg.content,
+        text: msg.content.filter((b) => b.type === 'text').map((b) => b.text).join(''),
+        calls: msg.content.filter((b) => b.type === 'tool_use').map((b) => ({ id: b.id, name: b.name, input: b.input })),
+        stop: msg.stop_reason,
+        usage: { input: u.input_tokens || 0, output: u.output_tokens || 0, cacheRead: u.cache_read_input_tokens || 0, cacheWrite: u.cache_creation_input_tokens || 0 },
+      };
+    },
+    assistant: (r) => ({ role: 'assistant', content: r.content }),
+    results: (list) => ({ role: 'user', content: list.map((x) => ({ type: 'tool_result', tool_use_id: x.id, content: x.text, ...(x.error && { is_error: true }) })) }),
+    user: (text) => ({ role: 'user', content: text }),
+  };
+}
+
+export async function anthropicModels(ep) {
+  const client = new Anthropic({ apiKey: ep.key, baseURL: ep.url });
+  const out = [];
+  for await (const m of client.models.list()) out.push(m.id);
+  return out;
+}

package/src/llm/openai.js

@@ -0,0 +1,54 @@
+// Any endpoint that speaks the OpenAI chat protocol: OpenAI, OpenRouter, Gemini, Groq, DeepSeek,
+// xAI, Ollama, LM Studio, or a custom URL. Same `step` shape as the Anthropic client.
+import OpenAI from 'openai';
+
+const make = (ep) => new OpenAI({ apiKey: ep.key || 'none', baseURL: ep.url, defaultHeaders: { 'X-Title': 'Morphe CLI', ...ep.headers } });
+
+export function openaiClient(ep, model, { system, tools }) {
+  const client = make(ep);
+  const toolDefs = tools.map((t) => ({ type: 'function', function: { name: t.name, description: t.description, parameters: t.input_schema } }));
+
+  return {
+    async step(messages, events, signal) {
+      const stream = await client.chat.completions.create({ model, messages: [{ role: 'system', content: system }, ...messages], tools: toolDefs, stream: true, stream_options: { include_usage: true } }, { signal });
+      let text = '';
+      const calls = [];
+      const usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+      let stop = 'end_turn';
+      for await (const chunk of stream) {
+        if (chunk.usage) { usage.input = chunk.usage.prompt_tokens || 0; usage.output = chunk.usage.completion_tokens || 0; }
+        const choice = chunk.choices?.[0];
+        if (!choice) continue;
+        if (choice.finish_reason === 'length') stop = 'max_tokens';
+        const d = choice.delta;
+        if (d?.content) { text += d.content; events.text?.(d.content); }
+        for (const tc of d?.tool_calls || []) {
+          const i = tc.index ?? calls.length;
+          calls[i] ||= { id: '', name: '', args: '' };
+          if (tc.id) calls[i].id = tc.id;
+          if (tc.function?.name) calls[i].name += tc.function.name;
+          if (tc.function?.arguments) calls[i].args += tc.function.arguments;
+        }
+      }
+      const parsed = calls.filter(Boolean).map((c, i) => {
+        let input = null;
+        try { input = JSON.parse(c.args || '{}'); } catch { input = null; }
+        return { id: c.id || `call_${Date.now()}_${i}`, name: c.name, input, raw: c.args };
+      });
+      return { text, calls: parsed, stop, usage, content: null };
+    },
+    assistant: (r) => ({
+      role: 'assistant',
+      content: r.text || null,
+      ...(r.calls.length && { tool_calls: r.calls.map((c) => ({ id: c.id, type: 'function', function: { name: c.name, arguments: c.raw || JSON.stringify(c.input || {}) } })) }),
+    }),
+    results: (list) => list.map((x) => ({ role: 'tool', tool_call_id: x.id, content: x.error ? `error: ${x.text}` : x.text })),
+    user: (text) => ({ role: 'user', content: text }),
+  };
+}
+
+export async function openaiModels(ep) {
+  const out = [];
+  for await (const m of make(ep).models.list()) out.push(m.id);
+  return out.sort();
+}

package/src/modes.js

@@ -0,0 +1,64 @@
+// Modes decide what the agent is allowed to do and how it behaves.
+// Built-ins: build, page, plan. Your own: JSON files in ~/.morphe/modes/ or ./.morphe/modes/.
+import fs from 'node:fs';
+import path from 'node:path';
+import { HOME_DIR, LOCAL_DIR } from './config.js';
+import { ALL_TOOLS, FILE_TOOLS, READ_TOOLS } from './tools.js';
+
+const PAGE = `PAGE mode: the same job Morphe does on the web, here in this folder.
+The user describes a page, app, game or tool in plain language. Build it as ONE self-contained file, index.html, in the project root.
+- If index.html already exists, view it first. Prefer patch for small changes and write for larger ones. Keep what the user did not mention intact.
+- Everything inline: <style> and <script> live in the file. Libraries only from https://cdn.jsdelivr.net or https://unpkg.com, versions pinned.
+- Wrap localStorage in try/catch; no alert, confirm or prompt; no network calls other than CDN assets and public keyless APIs.
+- Make it really work: real state and interactions, no dead buttons, no lorem ipsum when realistic sample content fits.
+- Design with care: good type (Google Fonts are fine), room to breathe, one coherent palette, restrained motion, works at 360px wide, readable contrast.
+- Never paste the file into the reply. When done, say in a sentence or two what was built and remind the user to open index.html in a browser.`;
+
+const PLAN = `PLAN mode: read only. You cannot change files or run commands. Explore the project, then answer with a numbered plan the user can approve before anything is changed.`;
+
+export const BUILT_IN = {
+  build: { about: 'Reads, writes and runs commands in the project. The default.', tools: ALL_TOOLS, system: '' },
+  page: { about: 'One sentence in, a working index.html out, exactly like the website. No commands.', tools: FILE_TOOLS, system: PAGE },
+  plan: { about: 'Looks around and writes a plan. Changes nothing.', tools: READ_TOOLS, system: PLAN },
+};
+
+function fromFile(file) {
+  const m = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const tools = Array.isArray(m.tools) ? m.tools.filter((t) => ALL_TOOLS.includes(t)) : ALL_TOOLS;
+  return { about: m.about || 'custom mode', tools, system: m.system || '', model: m.model || '', file };
+}
+
+export function loadModes(cwd = process.cwd()) {
+  const modes = { ...BUILT_IN };
+  for (const dir of [path.join(HOME_DIR, 'modes'), path.join(cwd, LOCAL_DIR, 'modes')]) {
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) if (f.endsWith('.json')) modes[f.slice(0, -5)] = fromFile(path.join(dir, f));
+  }
+  return modes;
+}
+
+function projectNotes(cwd) {
+  for (const name of ['MORPHE.md', 'AGENTS.md']) {
+    const f = path.join(cwd, name);
+    if (fs.existsSync(f)) return `\n\n## Notes from the project (${name})\n${fs.readFileSync(f, 'utf8').trim()}`;
+  }
+  return '';
+}
+
+/** The system prompt for a mode in a given folder. */
+export function systemPrompt(mode, cwd = process.cwd()) {
+  const shell = process.platform === 'win32' ? 'cmd.exe' : process.env.SHELL || 'sh';
+  return `You are Morphe, a coding agent working inside the user's project from their terminal. They say what they want; you make it happen in the files.
+
+Where you are:
+- project root: ${cwd}
+- platform: ${process.platform}; the shell tool uses ${shell}
+- today: ${new Date().toISOString().slice(0, 10)}
+
+How you work:
+- Look before you leap: list and view the files that matter and follow the conventions already there.
+- Use patch for surgical edits and write for new files or rewrites.
+- When the project has a build or tests, run them after changing code and fix what breaks.
+- Keep replies short: what changed, and anything the user still has to do.
+- If a request is ambiguous and guessing wrong would be expensive, ask one short question first.${mode.system ? `\n\n${mode.system}` : ''}${projectNotes(cwd)}`;
+}

package/src/tools.js

@@ -0,0 +1,139 @@
+// What the agent can do to a project. Every path is resolved inside the project root; nothing
+// escapes it. Each tool returns a plain string the model reads back.
+import { execFile, spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKIP = new Set(['.git', 'node_modules', 'dist', 'build', '.next', '.morphe', '.venv', 'venv', '__pycache__', '.cache', 'coverage', 'target']);
+const CAP = 24_000;
+const cap = (s) => (s.length > CAP ? s.slice(0, CAP) + `\n…(${s.length - CAP} more characters)` : s);
+
+const prop = (type, description, extra = {}) => ({ type, description, ...extra });
+const def = (name, description, properties, required) => ({ name, description, input_schema: { type: 'object', properties, required, additionalProperties: false } });
+
+export const TOOL_DEFS = [
+  def('ls', 'List a folder inside the project.', { dir: prop('string', 'Folder relative to the project root. "." is the root.') }, ['dir']),
+  def('view', 'Read a text file with line numbers. Use from/count on long files.', { file: prop('string', 'Path relative to the project root.'), from: prop('integer', 'First line (1-based). Default 1.'), count: prop('integer', 'How many lines. Default 1500.') }, ['file']),
+  def('glob', 'Find files whose path matches a pattern such as "src/**/*.js".', { pattern: prop('string', 'Glob pattern relative to the project root.') }, ['pattern']),
+  def('grep', 'Search file contents with a regular expression. Lines come back as file:line: text.', { regex: prop('string', 'JavaScript regular expression.'), dir: prop('string', 'Folder to search. Default ".".') }, ['regex']),
+  def('write', 'Create a file or replace its whole content.', { file: prop('string', 'Path relative to the project root.'), content: prop('string', 'The complete new content.') }, ['file', 'content']),
+  def('patch', 'Replace one exact snippet in a file. The snippet must appear exactly once; include a few surrounding lines to make it unique.', { file: prop('string', 'Path relative to the project root.'), find: prop('string', 'Exact text to replace.'), replace: prop('string', 'Replacement text.') }, ['file', 'find', 'replace']),
+  def('shell', 'Run a shell command in the project root. Output is returned; it stops after 2 minutes.', { command: prop('string', 'The command line.') }, ['command']),
+];
+
+export const READ_TOOLS = ['ls', 'view', 'glob', 'grep'];
+export const FILE_TOOLS = [...READ_TOOLS, 'write', 'patch'];
+export const ALL_TOOLS = TOOL_DEFS.map((t) => t.name);
+
+function inside(root, p) {
+  const abs = path.resolve(root, p || '.');
+  const rel = path.relative(root, abs);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) throw new Error(`"${p}" is outside the project.`);
+  return abs;
+}
+
+function* files(root, dir = root) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP.has(e.name)) continue;
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) yield* files(root, full);
+    else if (e.isFile()) yield path.relative(root, full).replaceAll(path.sep, '/');
+  }
+}
+
+function globMatcher(pattern) {
+  let re = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '*' && pattern[i + 1] === '*') { re += pattern[i + 2] === '/' ? '(?:.*/)?' : '.*'; i += pattern[i + 2] === '/' ? 2 : 1; }
+    else if (c === '*') re += '[^/]*';
+    else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp(re + '$');
+}
+
+function runShell(command, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(command, { cwd, shell: true, env: process.env });
+    let out = '';
+    child.stdout.on('data', (d) => (out += d));
+    child.stderr.on('data', (d) => (out += d));
+    const timer = setTimeout(() => { child.kill(); out += '\n[stopped after 120 s]'; }, 120_000);
+    child.on('close', (code) => { clearTimeout(timer); resolve(`exit ${code}\n${cap(out.trim())}`); });
+    child.on('error', (e) => { clearTimeout(timer); resolve(`could not start: ${e.message}`); });
+  });
+}
+
+/** One-line description for the terminal. */
+export const describe = (name, input) => `${name} ${String(input?.file ?? input?.dir ?? input?.pattern ?? input?.regex ?? input?.command ?? '').split('\n')[0].slice(0, 90)}`.trim();
+
+/**
+ * Execute a tool. `ctx` = { root, allowed:Set, approve(kind, what):Promise<boolean> }.
+ * Returns { text, error }.
+ */
+export async function execute(name, input, ctx) {
+  const t = TOOL_DEFS.find((x) => x.name === name);
+  if (!t || !ctx.allowed.has(name)) return { text: `The tool "${name}" is not available in this mode.`, error: true };
+  for (const k of t.input_schema.required) if (typeof input?.[k] !== 'string') return { text: `"${k}" must be a string.`, error: true };
+  try {
+    switch (name) {
+      case 'ls': {
+        const list = fs.readdirSync(inside(ctx.root, input.dir), { withFileTypes: true }).filter((e) => !SKIP.has(e.name));
+        return { text: list.map((e) => (e.isDirectory() ? e.name + '/' : e.name)).join('\n') || '(empty folder)' };
+      }
+      case 'view': {
+        const lines = fs.readFileSync(inside(ctx.root, input.file), 'utf8').split('\n');
+        const from = Math.max(1, input.from || 1);
+        const take = lines.slice(from - 1, from - 1 + (input.count || 1500));
+        const tail = from - 1 + take.length < lines.length ? `\n…(${lines.length} lines in total)` : '';
+        return { text: cap(take.map((l, i) => `${from + i}: ${l}`).join('\n')) + tail };
+      }
+      case 'glob': {
+        const m = globMatcher(input.pattern);
+        const hits = [];
+        for (const f of files(ctx.root)) if (m.test(f) && hits.push(f) >= 400) break;
+        return { text: hits.join('\n') || 'nothing matched' };
+      }
+      case 'grep': {
+        const re = new RegExp(input.regex);
+        const base = inside(ctx.root, input.dir || '.');
+        const hits = [];
+        scan: for (const f of files(ctx.root, base)) {
+          let text;
+          try { text = fs.readFileSync(path.join(ctx.root, f), 'utf8'); } catch { continue; }
+          if (text.includes('\0')) continue;
+          const lines = text.split('\n');
+          for (let i = 0; i < lines.length; i++) if (re.test(lines[i]) && hits.push(`${f}:${i + 1}: ${lines[i].trim().slice(0, 180)}`) >= 200) break scan;
+        }
+        return { text: hits.join('\n') || 'no matches' };
+      }
+      case 'write': {
+        const file = inside(ctx.root, input.file);
+        const existed = fs.existsSync(file);
+        if (!(await ctx.approve('write', `${existed ? 'replace' : 'create'} ${input.file} (${input.content.split('\n').length} lines)`))) return { text: 'The user did not allow this write.', error: true };
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, input.content);
+        return { text: `${existed ? 'replaced' : 'created'} ${input.file}` };
+      }
+      case 'patch': {
+        const file = inside(ctx.root, input.file);
+        const text = fs.readFileSync(file, 'utf8');
+        const n = text.split(input.find).length - 1;
+        if (n !== 1) return { text: `the snippet appears ${n} times in ${input.file}; it has to appear exactly once`, error: true };
+        const preview = [...input.find.split('\n').slice(0, 6).map((l) => '- ' + l), ...input.replace.split('\n').slice(0, 6).map((l) => '+ ' + l)].join('\n');
+        if (!(await ctx.approve('write', `patch ${input.file}\n${preview}`))) return { text: 'The user did not allow this patch.', error: true };
+        fs.writeFileSync(file, text.replace(input.find, () => input.replace));
+        return { text: `patched ${input.file}` };
+      }
+      case 'shell': {
+        if (!(await ctx.approve('shell', `run: ${input.command}`))) return { text: 'The user did not allow this command.', error: true };
+        return { text: await runShell(input.command, ctx.root) };
+      }
+    }
+  } catch (e) {
+    return { text: e.message, error: true };
+  }
+}
+
+export { execFile };

package/src/ui.js

@@ -0,0 +1,44 @@
+// Terminal colours and a tiny prompt helper. No dependencies.
+import readline from 'node:readline';
+
+const colour = process.stdout.isTTY && !process.env.NO_COLOR;
+const wrap = (open) => (text) => (colour ? `\x1b[${open}m${text}\x1b[0m` : String(text));
+
+export const orange = wrap('38;5;208');
+export const sky = wrap('38;5;111');
+export const faint = wrap('2');
+export const strong = wrap('1');
+export const ok = wrap('32');
+export const bad = wrap('31');
+
+export const LOGO = orange(`
+  ███╗   ███╗ ██████╗ ██████╗ ██████╗ ██╗  ██╗███████╗
+  ████╗ ████║██╔═══██╗██╔══██╗██╔══██╗██║  ██║██╔════╝
+  ██╔████╔██║██║   ██║██████╔╝██████╔╝███████║█████╗
+  ██║╚██╔╝██║██║   ██║██╔══██╗██╔═══╝ ██╔══██║██╔══╝
+  ██║ ╚═╝ ██║╚██████╔╝██║  ██║██║     ██║  ██║███████╗
+  ╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝╚═╝     ╚═╝  ╚═╝╚══════╝`) + faint('\n  say it. launch it.\n');
+
+/** Line-based prompt. `secret` hides what is typed (for keys). */
+export function prompter() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: !!process.stdin.isTTY });
+  let hide = false;
+  const out = rl._writeToOutput.bind(rl);
+  rl._writeToOutput = (s) => out(hide && !s.includes('\n') ? '•'.repeat(s.length) : s);
+  const ask = (q) => new Promise((res) => rl.question(q, res));
+  return {
+    rl,
+    ask: async (q) => (await ask(q)).trim(),
+    secret: async (q) => { process.stdout.write(q); hide = true; const v = await ask(''); hide = false; return v.trim(); },
+    close: () => rl.close(),
+  };
+}
+
+/** A one-line spinner that can be replaced by the real output. */
+export function spinner(label) {
+  if (!process.stdout.isTTY) return { stop() {} };
+  const frames = ['◐', '◓', '◑', '◒'];
+  let i = 0;
+  const t = setInterval(() => process.stdout.write(`\r  ${sky(frames[i++ % 4])} ${label}`), 110);
+  return { stop() { clearInterval(t); process.stdout.write('\r' + ' '.repeat(label.length + 6) + '\r'); } };
+}

package/src/version.js

@@ -0,0 +1,2 @@
+// Mirrors package.json; kept in source so the compiled binary knows itself.
+export const VERSION = '0.2.1';