pi-spark 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026—PRESENT Zilong Liang
+
+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

@@ -0,0 +1,86 @@
+![Cover](./assets/cover.png)
+
+# Pi Spark
+
+A small, opinionated collection of [pi](https://pi.dev/) extensions.
+
+## Extensions
+
+- **Editor**: replaces the default editor with a compact working indicator and current model info.
+- **Footer**: shows the session info, cost, and context usage in one line, followed by extension statuses.
+- **Fullscreen**: clears the screen and scrollback on session start and pins the editor and footer to the bottom for a full-screen session.
+- **Presets**: switches named model presets with `/preset` and quick cycle shortcuts.
+- **Recap**: generates a short idle-session recap and exposes a `/recap` command for manual generation, inspired by [Claude Code's session recap](https://code.claude.com/docs/en/interactive-mode#session-recap).
+
+![Screenshot](./assets/screenshot.png)
+
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:pi-spark
+```
+
+Install from git:
+
+```bash
+pi install git:github.com/zlliang/pi-spark
+```
+
+## Configure
+
+Spark reads config from `~/.pi/agent/spark.json` and from the current project’s `.pi/spark.json`. Project config overrides matching global fields.
+
+Example:
+
+```json
+{
+  "editor": {
+    "spinner": "dots"
+  },
+  "footer": false,
+  "presets": {
+    "gpt": {
+      "provider": "openai-codex",
+      "model": "gpt-5.5",
+      "thinkingLevel": "medium"
+    },
+    "claude-opus": {
+      "provider": "anthropic",
+      "model": "claude-opus-4-8",
+      "thinkingLevel": "high"
+    }
+  },
+  "recap": {
+    "idle": 180000,
+    "provider": "openai-codex",
+    "model": "gpt-5.4-mini",
+    "thinkingLevel": "off"
+  }
+}
+```
+
+Notes:
+
+- Set an extension key to `false` to disable it.
+- The `editor.spinner` value can be `lights` or `dots`.
+- Presets can be selected with `/preset` or `/preset <key>`.
+- Cycle presets with `ctrl+super+p` and `ctrl+shift+super+p` (`super` is `command` on macOS).
+- The `recap.idle` value is in milliseconds and must be at least `5000`.
+
+## Recommended pi settings
+
+The Fullscreen extension pins the editor and footer to the bottom of the terminal. For the cleanest experience, pair it with pi's `terminal.clearOnShrink` setting, which clears empty rows when content shrinks so the pinned UI does not leave stale lines behind.
+
+Add this to `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project):
+
+```json
+{
+  "terminal": {
+    "clearOnShrink": true
+  }
+}
+```
+
+This setting defaults to `false` because it can cause flicker in some terminals. With Fullscreen enabled the trade-off is usually worth it.

package/extensions/editor/config.ts

@@ -0,0 +1,7 @@
+import * as z from "zod";
+
+import { spinnerPresetSchema } from "./spinner";
+
+export const editorConfigSchema = z.object({
+  spinner: spinnerPresetSchema.optional(),
+});

package/extensions/editor/index.ts

@@ -0,0 +1,111 @@
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+
+import { Spinner } from "./spinner";
+import { SplitLine } from "../shared/components/split-line";
+import { loadConfig } from "../shared/config";
+import { autoCollectEvents, PRESET_CHANGE, parsePresetChange } from "../shared/events";
+import { formatModel } from "../shared/format";
+
+import type { ExtensionAPI, ExtensionContext, KeybindingsManager } from "@earendil-works/pi-coding-agent";
+import type { TUI, EditorTheme } from "@earendil-works/pi-tui";
+
+class Editor extends CustomEditor {
+  private pi: ExtensionAPI;
+  private ctx: ExtensionContext;
+
+  private spinner: Spinner;
+  private slots: { modelBefore: string | undefined };
+
+  constructor(pi: ExtensionAPI, ctx: ExtensionContext, tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager, spinner: Spinner = new Spinner()) {
+    super(tui, theme, keybindings);
+
+    this.pi = pi;
+    this.ctx = ctx;
+
+    this.spinner = spinner;
+    this.spinner.setTUI(tui);
+    this.slots = { modelBefore: undefined };
+  }
+
+  setSlot(slot: keyof typeof this.slots, value: string | undefined): void {
+    this.slots[slot] = value;
+    this.tui.requestRender();
+  }
+
+  render(width: number): string[] {
+    const lines = super.render(width);
+    if (lines.length === 0) return lines;
+
+    lines[0] = this.renderTopBorder(width);
+
+    return lines;
+  }
+
+  private renderTopBorder(width: number): string {
+    const theme = this.ctx.ui.theme;
+
+    const left = this.getLeft();
+    const right = this.getRight();
+
+    return new SplitLine(left, right, {
+      padding: 1,
+      innerPadding: 1,
+      spacingChar: this.borderColor("─"),
+      ellipsis: theme.fg("dim", "…"),
+    }).render(width)[0];
+  }
+
+  private getLeft(): string {
+    const theme = this.ctx.ui.theme;
+
+    return theme.fg("accent", this.spinner.getFrame());
+  }
+
+  private getRight(): string {
+    const theme = this.ctx.ui.theme;
+
+    const modelBeforeText = this.slots.modelBefore;
+    const modelText = formatModel(this.ctx.model?.provider, this.ctx.model?.id, this.pi.getThinkingLevel());
+
+    return theme.fg("dim", [modelBeforeText, modelText].filter(Boolean).join(" • "));
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  const events = autoCollectEvents(pi);
+  let spinner: Spinner | undefined = undefined;
+
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    const config = loadConfig(ctx, "editor");
+    if (!config) return;
+
+    spinner = new Spinner(config.spinner);
+
+    ctx.ui.setWorkingVisible(false);
+    ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+      const editor = new Editor(pi, ctx, tui, theme, keybindings, spinner);
+
+      events.on(PRESET_CHANGE, (data) => {
+        const payload = parsePresetChange(data);
+        editor.setSlot("modelBefore", payload ? `preset:${payload}` : undefined);
+      });
+
+      return editor;
+    });
+  });
+
+  pi.on("agent_start", () => {
+    spinner?.start();
+  });
+
+  pi.on("agent_end", () => {
+    spinner?.stop();
+  });
+
+  pi.on("session_shutdown", () => {
+    spinner?.dispose();
+    spinner = undefined;
+  });
+}

package/extensions/editor/spinner.ts

@@ -0,0 +1,92 @@
+import * as z from "zod";
+
+import type { TUI } from "@earendil-works/pi-tui";
+
+export const spinnerPresetSchema = z.enum(["lights", "dots"]);
+
+type SpinnerPreset = z.infer<typeof spinnerPresetSchema>;
+
+interface SpinnerParams {
+  frames: string[];
+  interval: number | { min: number; max: number };
+  random: boolean;
+}
+
+const SPINNER_PRESETS: Record<SpinnerPreset, SpinnerParams> = {
+  lights: {
+    frames: ["○○○○", "●○○○", "○●○○", "○○●○", "○○○●", "●●○○", "●○●○", "●○○●", "○●●○", "○●○●", "○○●●", "●●●○", "●●○●", "●○●●", "○●●●", "●●●●"],
+    interval: { min: 120, max: 240 },
+    random: true,
+  },
+  dots: {
+    frames: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    interval: 80,
+    random: false,
+  },
+};
+
+const DEFAULT_SPINNER_PRESET = "lights";
+
+export class Spinner {
+  private tui: TUI | undefined;
+
+  private frames: string[];
+  private interval: number | { min: number; max: number };
+  private random: boolean;
+
+  private working: boolean = false;
+  private frameIndex: number = -1;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(preset: SpinnerPreset = DEFAULT_SPINNER_PRESET) {
+    const params = SPINNER_PRESETS[preset];
+
+    this.frames = params.frames;
+    this.interval = params.interval;
+    this.random = params.random;
+  }
+
+  setTUI(tui: TUI): void {
+    this.tui = tui;
+  }
+
+  getFrame(): string {
+    if (!this.working) return "";
+
+    return this.frames[this.frameIndex] ?? "";
+  }
+
+  start(): void {
+    this.stop();
+
+    this.working = true;
+    this.tick();
+  }
+
+  stop(): void {
+    this.working = false;
+    this.frameIndex = -1;
+
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+
+    this.tui?.requestRender();
+  }
+
+  dispose(): void {
+    this.stop();
+    this.tui = undefined;
+  }
+
+  private tick(): void {
+    if (!this.working) return;
+
+    this.frameIndex = this.random ? Math.floor(Math.random() * this.frames.length) : (this.frameIndex + 1) % this.frames.length;
+    this.tui?.requestRender();
+
+    const delay = typeof this.interval === "number" ? this.interval : this.interval.min + Math.floor(Math.random() * (this.interval.max - this.interval.min + 1));
+    this.timer = setTimeout(() => this.tick(), delay);
+  }
+}

package/extensions/footer/config.ts

@@ -0,0 +1,3 @@
+import * as z from "zod";
+
+export const footerConfigSchema = z.object({});

package/extensions/footer/index.ts

@@ -0,0 +1,122 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+import { SplitLine } from "../shared/components/split-line";
+import { loadConfig } from "../shared/config";
+import { formatContextUsage, formatCost, sanitizeText } from "../shared/format";
+import { getEntryUsage } from "../shared/usage";
+
+import type { ExtensionContext, ExtensionAPI, ReadonlyFooterDataProvider, Theme } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+
+class FooterComponent implements Component {
+  private ctx: ExtensionContext;
+  private theme: Theme;
+  private footerData: ReadonlyFooterDataProvider;
+
+  constructor(ctx: ExtensionContext, theme: Theme, footerData: ReadonlyFooterDataProvider) {
+    this.ctx = ctx;
+    this.theme = theme;
+    this.footerData = footerData;
+  }
+
+  invalidate(): void {
+    // No-op
+  }
+
+  render(width: number): string[] {
+    return [this.renderMainLine(width), this.renderStatusLine(width)].filter(Boolean);
+  }
+
+  private renderMainLine(width: number): string {
+    const left = this.getLeft();
+    const right = this.getRight();
+    return new SplitLine(left, right, {
+      primarySide: "right",
+      ellipsis: this.theme.fg("dim", "…"),
+    }).render(width)[0];
+  }
+
+  private getLeft(): string {
+    let text = formatCwd(this.ctx.sessionManager.getCwd(), process.env.HOME || process.env.USERPROFILE);
+
+    const branch = this.footerData.getGitBranch();
+    if (branch) text = `${text} [${branch}]`;
+
+    const sessionName = this.ctx.sessionManager.getSessionName();
+    if (sessionName) text = `${text} • ${sessionName}`;
+
+    return this.theme.fg("dim", text);
+  }
+
+  private getRight(): string {
+    const styledCostText = this.getStyledCostText();
+    const styledContextUsageText = this.getStyledContextUsageText();
+
+    return `${styledCostText}${this.theme.fg("dim", " • ")}${styledContextUsageText}`;
+  }
+
+  private getStyledCostText(): string {
+    const cost = this.ctx.sessionManager.getBranch().reduce((acc, entry) => {
+      const entryUsage = getEntryUsage(this.ctx, entry);
+      if (entryUsage) acc[entryUsage.type] += entryUsage.usage.cost.total;
+      return acc;
+    }, { subscription: 0, paid: 0 });
+
+    const isSubscription = this.ctx.model ? this.ctx.modelRegistry.isUsingOAuth(this.ctx.model) : false;
+    const subscriptionCostText = isSubscription || cost.subscription > 0 ? formatCost(cost.subscription, true) : undefined;
+    const paidCostText = !isSubscription || cost.paid > 0 ? formatCost(cost.paid, false) : undefined;
+    const costText = [subscriptionCostText, paidCostText].filter(Boolean).join(" + ");
+
+    const totalCost = cost.subscription + cost.paid;
+    if (totalCost > 20) return this.theme.fg("warning", costText);
+
+    return this.theme.fg("dim", costText);
+  }
+
+  private getStyledContextUsageText(): string {
+    const contextUsage = this.ctx.getContextUsage();
+    const contextUsageText = formatContextUsage(contextUsage);
+    const percent = contextUsage?.percent ?? null;
+
+    if (percent && percent > 90) return this.theme.fg("error", contextUsageText);
+    if (percent && percent > 70) return this.theme.fg("warning", contextUsageText);
+    return this.theme.fg("dim", contextUsageText);
+  }
+
+  /** Add extension statues on a single line, sorted by key alphabetically. */
+  private renderStatusLine(width: number): string {
+    const extensionStatuses = this.footerData.getExtensionStatuses();
+    if (extensionStatuses.size === 0) return "";
+
+    const statusLine = Array.from(extensionStatuses.entries())
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([, text]) => sanitizeText(text))
+      .join(this.theme.fg("dim", " • "));
+
+    return truncateToWidth(statusLine, width, this.theme.fg("dim", "..."));
+  }
+}
+
+function formatCwd(cwd: string, home?: string): string {
+  if (!home) return cwd;
+
+  const resolvedCwd = resolve(cwd);
+  const resolvedHome = resolve(home);
+  const relativeToHome = relative(resolvedHome, resolvedCwd);
+  const isInsideHome = relativeToHome === "" || (relativeToHome !== ".." && !relativeToHome.startsWith(`..${sep}`) && !isAbsolute(relativeToHome));
+  if (!isInsideHome) return cwd;
+
+  return relativeToHome === "" ? "~" : `~${sep}${relativeToHome}`;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    const config = loadConfig(ctx, "footer");
+    if (!config) return;
+
+    ctx.ui.setFooter((_tui, theme, footerData) => new FooterComponent(ctx, theme, footerData));
+  });
+}

package/extensions/fullscreen/config.ts

@@ -0,0 +1,3 @@
+import * as z from "zod";
+
+export const fullscreenConfigSchema = z.object({});

package/extensions/fullscreen/filler.ts

@@ -0,0 +1,36 @@
+import type { Component, TUI } from "@earendil-works/pi-tui";
+
+/**
+ * Fills the gap above the editor so the editor and footer stay pinned to the
+ * bottom of the terminal when the session content is shorter than one screen.
+ */
+export class BottomFiller implements Component {
+  private tui: TUI;
+  private measuring = false;
+
+  constructor(tui: TUI) {
+    this.tui = tui;
+  }
+
+  invalidate(): void {
+    // No-op
+  }
+
+  render(width: number): string[] {
+    // The TUI renders this component as part of its child tree, so measuring the
+    // siblings re-enters this render. Guard against the recursion and count our
+    // own contribution as zero lines while measuring.
+    if (this.measuring) return [];
+    this.measuring = true;
+
+    const rows = this.tui.terminal.rows;
+    let others = 0;
+    for (const child of this.tui.children) {
+      others += child.render(width).length;
+      if (others >= rows) break; // content already fills the screen
+    }
+
+    this.measuring = false;
+    return new Array(Math.max(0, rows - others)).fill("");
+  }
+}

package/extensions/fullscreen/index.ts

@@ -0,0 +1,47 @@
+import { BottomFiller } from "./filler";
+import { loadConfig } from "../shared/config";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+
+const WIDGET_KEY = "fullscreen";
+
+export default function (pi: ExtensionAPI) {
+  let tui: TUI | undefined;
+  let pendingClear = false;
+
+  /**
+   * Mount a persistent filler above the editor. The widget factory receives the TUI handle
+   * (otherwise unavailable via `ctx.ui`), so it both captures the TUI for clearing and pins the
+   * editor and footer to the bottom of the screen.
+   */
+  function mountFiller(ctx: ExtensionContext): void {
+    ctx.ui.setWidget(WIDGET_KEY, (capturedTui) => {
+      tui = capturedTui;
+
+      if (pendingClear) {
+        pendingClear = false;
+        queueMicrotask(() => capturedTui.requestRender(true));
+      }
+
+      return new BottomFiller(capturedTui);
+    });
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    const config = loadConfig(ctx, "fullscreen");
+    if (!config) return;
+
+    if (tui) {
+      // Force a full repaint, which resets the TUI's diff state and clears the screen and
+      // scrollback (`\x1b[2J\x1b[H\x1b[3J`), just like the built-in `clearOnShrink` behavior.
+      tui.requestRender(true);
+      return;
+    }
+
+    pendingClear = true;
+    mountFiller(ctx);
+  });
+}

package/extensions/presets/config.ts

@@ -0,0 +1,8 @@
+import * as z from "zod";
+
+import { modelSchema } from "../shared/config/model";
+
+export const presetsConfigSchema = z.record(z.string().min(1), modelSchema);
+
+export type PresetsConfig = z.infer<typeof presetsConfigSchema>;
+export type PresetConfig = PresetsConfig[string];

package/extensions/presets/index.ts

@@ -0,0 +1,72 @@
+import { Key } from "@earendil-works/pi-tui";
+
+import { PresetManager } from "./manager";
+import { showPresetSelector } from "./selector";
+import { loadConfig } from "../shared/config";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  let presetManager: PresetManager | undefined = undefined;
+
+  pi.on("session_start", (_event, ctx) => {
+    const config = loadConfig(ctx, "presets");
+    if (!config || Object.keys(config).length === 0) return;
+
+    presetManager = new PresetManager(pi, config);
+    presetManager.sync(ctx);
+
+    pi.registerCommand("preset", {
+      description: "Switch model preset",
+      getArgumentCompletions: (prefix: string) => {
+        if (!presetManager) return null;
+
+        const items = presetManager.keys
+          .filter((key) => key.startsWith(prefix))
+          .map((key) => ({ value: key, label: key, description: presetManager!.describe(key) }));
+
+        return items.length > 0 ? items : null;
+      },
+      handler: async (args, ctx) => {
+        if (!presetManager) return;
+
+        const key = args.trim();
+        if (key) {
+          await presetManager.apply(key, ctx);
+          return;
+        }
+
+        const selected = await showPresetSelector(ctx, presetManager);
+        if (selected) {
+          await presetManager.apply(selected, ctx);
+        }
+      },
+    });
+  });
+
+  pi.on("model_select", (_event, ctx) => {
+    presetManager?.sync(ctx);
+  });
+
+  pi.on("thinking_level_select", (_event, ctx) => {
+    presetManager?.sync(ctx);
+  });
+
+  pi.registerShortcut(Key.ctrlSuper("p"), {
+    description: "Cycle model preset forward",
+    handler: async (ctx) => {
+      await presetManager?.cycle(ctx, "forward");
+    },
+  });
+
+  pi.registerShortcut(Key.ctrlShiftSuper("p"), {
+    description: "Cycle model preset backward",
+    handler: async (ctx) => {
+      await presetManager?.cycle(ctx, "backward");
+    },
+  });
+
+  pi.on("session_shutdown", () => {
+    presetManager = undefined;
+  });
+}