@sherif-fanous/pi-presets-plus 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+This changelog follows [Common Changelog](https://common-changelog.org/).
+
+## [0.1.0] - 2026-05-09
+
+_Initial release._
+
+[0.1.0]: https://github.com/sherif-fanous/pi-presets-plus/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sherif Fanous
+
+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,67 @@
+# pi-presets-plus
+
+A [Pi](https://github.com/badlogic/pi) extension that lets you bundle a model, thinking level, tools, and system prompt into a named preset, then switch between presets with one hotkey.
+
+## Why
+
+Pi already lets you change the model you talk to, how hard it thinks, which tools it can use, and what system prompt it follows. Each of those is its own setting, and tweaking them one at a time is fine for ad-hoc work but it gets tedious when you have a handful of working modes you keep coming back to: a fast cheap model for boilerplate, a heavy reasoning model for tricky design, a "review only" setup with no write tools and a strict prompt, a planning mode, an implementation mode.
+
+`pi-presets-plus` lets you save a complete setup as a named preset and switch to it with one keystroke.
+
+## Install
+
+```shell
+pi install npm:@sherif-fanous/pi-presets-plus
+```
+
+Or try it without installing:
+
+```shell
+pi -e npm:@sherif-fanous/pi-presets-plus
+```
+
+To uninstall:
+
+```shell
+pi remove npm:@sherif-fanous/pi-presets-plus
+```
+
+## Quick start
+
+1. Run `/presets` in any Pi session to open the preset picker.
+2. Press `n` to create a new preset, or `e` to edit an existing one.
+3. Press `F1` on any row in the editor to get help for that row.
+4. Save your preset and, optionally, give it a hotkey. From then on, pressing the hotkey switches to the preset. Run `/presets clear` to go back to Pi's defaults.
+
+The picker also lets you filter by name, switch the scope filter, reorder, duplicate, and delete presets. The footer always shows the keys you can press.
+
+## What's in a preset
+
+| Field    | What it does                                                                                                       |
+| -------- | ------------------------------------------------------------------------------------------------------------------ |
+| Name     | A short, memorable label for the preset. Names are unique within their scope.                                      |
+| Scope    | _User_ presets follow you across every project. _Project_ presets stay tied to one repo and can be shared.         |
+| Provider | The service that hosts the model (OpenAI, Anthropic, etc.). Only providers Pi knows about appear here.             |
+| Model    | The specific model Pi will use when this preset is active.                                                         |
+| Thinking | How much extra reasoning effort to ask for. Some models don't support every level; unavailable ones appear dimmed. |
+| Tools    | Either keep whatever tools are active, or pin an exact tool list to the preset.                                    |
+| Prompt   | Extra instructions added to Pi's system prompt while the preset is active. Pi's defaults are kept either way.      |
+| Hotkey   | Optional. A single key combination (like `ctrl+shift+1`) that switches to this preset.                             |
+
+## Where presets live
+
+| Scope   | Path                                                                                        |
+| ------- | ------------------------------------------------------------------------------------------- |
+| User    | `<agent-dir>/presets-plus/presets.json` (typically `~/.pi/agent/presets-plus/presets.json`) |
+| Project | `<repo>/.pi/presets-plus/presets.json`                                                      |
+
+If a project preset and a user preset share a name, the project preset wins while you're working in that project.
+
+## Commands
+
+| Command           | What it does                                                  |
+| ----------------- | ------------------------------------------------------------- |
+| `/presets`        | Opens the picker.                                             |
+| `/presets clear`  | Clears the active preset and returns to Pi's defaults.        |
+| `/presets reload` | Re-reads your preset files (use after editing them by hand).  |
+| `/presets status` | Shows the active preset's settings compared to Pi's defaults. |

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@sherif-fanous/pi-presets-plus",
+  "version": "0.1.0",
+  "description": "Pi extension: model + thinking + tools + system-prompt presets, with a UI on top.",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "pi-package",
+    "presets",
+    "favorites",
+    "model-presets",
+    "thinking-presets",
+    "tools-presets",
+    "system-prompt-presets"
+  ],
+  "license": "MIT",
+  "author": "Sherif Fanous",
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "prettier": {
+    "importOrder": [
+      "<BUILTIN_MODULES>",
+      "",
+      "<THIRD_PARTY_MODULES>"
+    ],
+    "importOrderTypeScriptVersion": "6.0.0",
+    "plugins": [
+      "@ianvs/prettier-plugin-sort-imports"
+    ]
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.13",
+    "@eslint/js": "^10.0.1",
+    "@ianvs/prettier-plugin-sort-imports": "^4.7.1",
+    "@mariozechner/pi-ai": "^0.73.0",
+    "@mariozechner/pi-coding-agent": "^0.73.0",
+    "@mariozechner/pi-tui": "^0.73.0",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "eslint": "^10.2.1",
+    "eslint-plugin-perfectionist": "^5.9.0",
+    "eslint-plugin-unicorn": "^64.0.0",
+    "fallow": "^2.55.0",
+    "prettier": "^3.8.3",
+    "sort-package-json": "^3.6.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.1",
+    "vitest": "^4.1.5"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "format": "prettier --write eslint.config.mjs package.json src/. tests/. tsconfig.json vitest.config.ts",
+    "format-check": "prettier --check eslint.config.mjs package.json src/. tests/. tsconfig.json vitest.config.ts",
+    "lint": "biome lint src/. tests/. && eslint src/. tests/.",
+    "sort-package-json": "npx sort-package-json",
+    "test": "vitest",
+    "type-check": "tsc --noEmit"
+  }
+}

package/src/activation/active-state.ts

@@ -0,0 +1,25 @@
+/**
+ * In-memory active-preset reference for the activation runtime.
+ *
+ * Owns the module-scoped state cell tracking which preset is currently
+ * active; it does NOT persist session entries, update status, or mutate
+ * pi model/tool state.
+ */
+import type { ActivePresetState } from "../types.js";
+
+let active: ActivePresetState | undefined;
+
+/** Remove the current active-preset attachment. */
+export function clearActive(): void {
+  active = undefined;
+}
+
+/** Return the current active-preset attachment, if any. */
+export function getActive(): ActivePresetState | undefined {
+  return active;
+}
+
+/** Replace the current active-preset attachment. */
+export function setActive(next: ActivePresetState): void {
+  active = next;
+}

package/src/activation/apply.ts

@@ -0,0 +1,236 @@
+/**
+ * Preset apply flow.
+ *
+ * Owns the end-to-end activation of a preset: writing model, thinking, and
+ * tool state, recording the baseline overlay, persisting activation, and
+ * refreshing status. It does NOT own command lookup, session restore, or
+ * picker UI.
+ */
+import { ACTIVATED_MESSAGE_TYPE } from "../messages.js";
+import type { LoadedPreset } from "../types.js";
+import { updateStatus } from "../ui/status.js";
+import { getActive, setActive } from "./active-state.js";
+import { captureBaseline } from "./baseline.js";
+import { markClean } from "./dirty.js";
+import { snapshotPresetForDrift } from "./drift.js";
+import { stateMatches } from "./state-matches.js";
+import { effectiveThinkingLevel } from "./thinking.js";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+
+/**
+ * Counter (not boolean) so nested `withSelfTriggeredModelSet` calls cannot
+ * silently drop the guard when the inner call's `finally` runs while the
+ * outer call is still in flight. Today there is only one caller, but the
+ * counter shape costs nothing and removes a footgun for future callers.
+ */
+let selfTriggeredModelSetDepth = 0;
+
+/**
+ * In-memory result from applying a preset.
+ *
+ * Refusal kinds:
+ * - `no-key`: the preset is unavailable because its provider key is missing.
+ * - `no-model`: the preset is unavailable because its model is not installed.
+ * - `unknown-model`: the preset references a provider/model not in the registry.
+ * - `key-revoked`: the model resolved, but `setModel` refused it at apply time.
+ */
+export type ApplyResult =
+  | { ok: true }
+  | {
+      ok: false;
+      kind: "key-revoked" | "no-key" | "no-model" | "unknown-model";
+      reason: string;
+    };
+
+/**
+ * Apply `preset` to Pi state and return a structured refusal on expected
+ * activation failures. Callers surface refusal `reason` through the channel
+ * appropriate to their context; this function still emits non-refusal warning
+ * or informational accompaniments inline for successful activation.
+ */
+export async function apply(
+  preset: LoadedPreset,
+  ctx: ExtensionContext,
+  pi: ExtensionAPI,
+): Promise<ApplyResult> {
+  if (preset.unavailable) {
+    const kind = preset.unavailable;
+
+    return { ok: false, kind, reason: failureReason(kind, preset) };
+  }
+
+  const current = getActive();
+
+  if (
+    current?.name === preset.name &&
+    current.scope === preset.scope &&
+    current.restore.kind === "baseline" &&
+    stateMatches(preset, pi, ctx)
+  ) {
+    if (current.dirty) await markClean(ctx);
+
+    return { ok: true };
+  }
+
+  const model = ctx.modelRegistry.find(preset.provider, preset.model);
+
+  if (!model) {
+    return {
+      ok: false,
+      kind: "unknown-model",
+      reason: failureReason("unknown-model", preset),
+    };
+  }
+
+  const previousBaseline =
+    current?.restore.kind === "baseline" ? current.restore : undefined;
+  const baseline = previousBaseline?.baseline ?? captureBaseline(pi, ctx);
+  const applyCount = (previousBaseline?.applyCount ?? 0) + 1;
+  const previousAppliedTools = previousBaseline?.lastApplied.tools;
+  const previousOwnedTools = previousBaseline?.owned.tools ?? false;
+
+  if (!(await setModelGuarded(pi, model))) {
+    return {
+      ok: false,
+      kind: "key-revoked",
+      reason: failureReason("key-revoked", preset),
+    };
+  }
+
+  const effective = effectiveThinkingLevel(preset, model);
+  const declared = preset.thinkingLevel ?? "off";
+
+  pi.setThinkingLevel(effective);
+
+  if (effective !== declared) {
+    ctx.ui.notify(
+      `Preset "${preset.name}" requested thinking level "${declared}" for ${preset.provider}/${preset.model}. Applied "${effective}" instead.`,
+      "info",
+    );
+  }
+
+  let appliedTools = previousAppliedTools;
+  let ownedTools = previousOwnedTools;
+
+  if (preset.tools && preset.tools.length > 0) {
+    const validTools = filterValidTools(preset.tools, pi.getAllTools());
+    const dropped = preset.tools.filter(
+      (toolName) => !validTools.includes(toolName),
+    );
+
+    if (dropped.length > 0) {
+      ctx.ui.notify(
+        `Preset "${preset.name}" references unknown tools: ${dropped.join(", ")}. They were ignored.`,
+        "warning",
+      );
+    }
+
+    pi.setActiveTools(validTools);
+    appliedTools = validTools;
+    ownedTools = true;
+  }
+
+  setActive({
+    declared: snapshotPresetForDrift({ ...preset, tools: appliedTools }),
+    dirty: false,
+    name: preset.name,
+    restore: {
+      applyCount,
+      baseline,
+      kind: "baseline",
+      lastApplied: {
+        ...(appliedTools !== undefined ? { tools: appliedTools } : {}),
+        model: { id: preset.model, provider: preset.provider },
+        thinkingLevel: effective,
+      },
+      owned: { model: true, thinkingLevel: true, tools: ownedTools },
+    },
+    scope: preset.scope,
+  });
+
+  pi.appendEntry("presets-plus:active", {
+    name: preset.name,
+    scope: preset.scope,
+  });
+
+  pi.sendMessage({
+    customType: ACTIVATED_MESSAGE_TYPE,
+    content: `Preset ${preset.name} applied`,
+    display: true,
+    details: {
+      name: preset.name,
+      model: `${preset.provider}/${preset.model}`,
+      thinkingLevel: effective,
+    },
+  });
+
+  updateStatus(ctx, getActive(), (name, scope) =>
+    name === preset.name && scope === preset.scope ? preset : undefined,
+  );
+
+  return { ok: true };
+}
+
+export function isSelfTriggeredModelSet(): boolean {
+  return selfTriggeredModelSetDepth > 0;
+}
+
+/**
+ * Run `fn` with the self-call counter raised so a `model_select` event
+ * triggered by `pi.setModel` inside `fn` is recognized as our own write
+ * and ignored by the drift-detection handler. The counter shape (vs. a
+ * boolean) keeps nested or concurrent calls from accidentally lowering the
+ * guard while an outer call is still in flight.
+ */
+export async function withSelfTriggeredModelSet<T>(
+  fn: () => Promise<T>,
+): Promise<T> {
+  selfTriggeredModelSetDepth++;
+
+  try {
+    return await fn();
+  } finally {
+    selfTriggeredModelSetDepth--;
+  }
+}
+
+function failureReason(
+  kind: Exclude<ApplyResult, { ok: true }>["kind"],
+  preset: Pick<LoadedPreset, "model" | "name" | "provider">,
+): string {
+  switch (kind) {
+    case "no-key":
+      return `Preset "${preset.name}" is unavailable: missing API key. Activation skipped.`;
+    case "no-model":
+      return `Preset "${preset.name}" is unavailable: model not installed. Activation skipped.`;
+    case "unknown-model":
+      return `Preset "${preset.name}" references unknown model ${preset.provider}/${preset.model}.`;
+    case "key-revoked":
+      return `No API key configured for ${preset.provider}/${preset.model}.`;
+
+    default: {
+      const exhaustive: never = kind;
+
+      return exhaustive;
+    }
+  }
+}
+
+function filterValidTools(
+  desired: readonly string[],
+  allTools: readonly { name: string }[],
+): string[] {
+  const available = new Set(allTools.map((tool) => tool.name));
+
+  return desired.filter((toolName) => available.has(toolName));
+}
+
+async function setModelGuarded(
+  pi: Pick<ExtensionAPI, "setModel">,
+  model: NonNullable<ReturnType<ExtensionContext["modelRegistry"]["find"]>>,
+): Promise<boolean> {
+  return withSelfTriggeredModelSet(() => pi.setModel(model));
+}

package/src/activation/baseline.ts

@@ -0,0 +1,32 @@
+/**
+ * Baseline capture for preset activation overlays.
+ *
+ * Owns reading the current pi state so a preset can later be cleared back
+ * to its pre-activation values; it does NOT apply presets or restore
+ * state.
+ */
+import type { PresetOverlayBaseline } from "../types.js";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+
+/** Minimal context surface needed to capture the current model. */
+type BaselineContext = Pick<ExtensionContext, "model">;
+
+/** Minimal pi surface needed to capture restorable state. */
+type BaselinePi = Pick<ExtensionAPI, "getActiveTools" | "getThinkingLevel">;
+
+/** Capture the current Pi state as an overlay restore baseline. */
+export function captureBaseline(
+  pi: BaselinePi,
+  ctx: BaselineContext,
+): PresetOverlayBaseline {
+  return {
+    model: ctx.model
+      ? { provider: ctx.model.provider, id: ctx.model.id }
+      : null,
+    thinkingLevel: pi.getThinkingLevel(),
+    tools: pi.getActiveTools(),
+  };
+}