@grrrck/pi-clear 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-02
+
+### Added
+
+- `/clear` command that starts a fresh session while preserving the current model and thinking level.
+- Waits for the agent to become idle before clearing.
+- Warnings when clearing is cancelled, the model is no longer available, or its auth is missing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Garrick Aden-Buie
+
+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,73 @@
+# pi-clear
+
+A [pi](https://github.com/earendil-works/pi) extension that adds a `/clear` command: start a fresh session **without losing your model**.
+
+## Why?
+
+Pi's built-in `/new` command starts a new session, but the new session resolves its model from pi's defaults chain — CLI arguments, scoped models, the saved default in settings, then the first available model with auth.
+
+If you switched models mid-session — with `/model`, model cycling, or an extension — that choice is recorded as a `model_change` entry in the *current* session transcript, so `/new` never sees it. Your carefully chosen model quietly reverts to the default.
+
+`/clear` starts an equally fresh session, then restores the model and thinking level you were using.
+
+## Install
+
+```sh
+pi install npm:@gadenbuie/pi-clear
+```
+
+Or try it without installing:
+
+```sh
+pi -e npm:@gadenbuie/pi-clear
+```
+
+## Usage
+
+```text
+/clear
+```
+
+## Behavior
+
+When `/clear` runs, the extension:
+
+1. waits for the agent to become idle if needed
+2. captures the active model and thinking level
+3. starts a new session via `ctx.newSession()`
+4. restores the captured model and thinking level in the new session
+5. shows a warning if clearing is cancelled or the captured model can no longer be applied (e.g. its auth was removed)
+
+Because the model is applied with `pi.setModel()`, it's recorded in the new session's transcript — so it also survives `/resume`.
+
+## Notes
+
+- `/clear` only registers the slash command; it does not bind a keyboard shortcut, so it won't conflict with other extensions (such as `pi-mono-clear`, which uses `Ctrl+Shift+L`).
+- The model handoff is in-process only: it never touches the filesystem, is invisible to other pi processes, and is discarded if pi exits between clearing and restoring.
+- Like `/new`, `/clear` does not carry over conversation history, compaction summaries, or session name.
+
+## How it works
+
+pi tears down the current runtime when a session is replaced, and extension instances are recreated for the new session. Session-bound objects can't be reused across that boundary, and the post-switch context has no model setter — but the replacement happens within the same process. So `/clear` captures the model as plain data in a `globalThis` property, and the new session's extension instance consumes it on `session_start` (reason `new`) and applies it with `pi.setModel()`. The handoff is consumed exactly once, so it can never leak into a later session.
+
+## Development
+
+Load the extension directly for local testing:
+
+```sh
+pi -e ./index.ts
+```
+
+There's also an RPC smoke test that verifies the core behavior end-to-end: it starts pi in RPC mode, switches to a different model and thinking level, runs `/clear`, and asserts both survive the new session:
+
+```sh
+python3 scripts/rpc-smoke-test.py
+```
+
+## Related extensions
+
+- [`pi-mono-clear`](https://github.com/emanuelcasco/pi-mono-extensions) — a `/clear` alias for `/new` (does not preserve the model)
+
+## License
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1,129 @@
+/**
+ * pi-clear — `/clear` for pi: start a fresh session without losing your model.
+ *
+ * The built-in `/new` command starts a new session, but the new runtime
+ * resolves its model from the defaults chain (CLI args → scoped models →
+ * saved default in settings → first available model with auth). A model you
+ * switched to mid-session — via `/model`, `pi.setModel()`, or model cycling —
+ * is recorded as a `model_change` entry in the *current* session transcript,
+ * so it never reaches the new session.
+ *
+ * `/clear` starts an equally fresh session, then restores the model and
+ * thinking level that were active when you cleared.
+ *
+ * Usage:
+ *   /clear
+ *
+ * Mechanism:
+ *   1. The `/clear` handler captures the active model (provider + id) and
+ *      thinking level as plain data into a `globalThis` property. Session
+ *      replacement (`ctx.newSession()`) tears down the current runtime and
+ *      recreates extension instances, but stays within the same process, so
+ *      a `globalThis` property safely crosses that boundary while remaining
+ *      invisible to other pi processes and dying with crashes.
+ *   2. The new instance's `session_start` handler (reason: "new") consumes
+ *      the handoff and applies the captured model and thinking level via
+ *      `pi.setModel()` / `pi.setThinkingLevel()`, which record them in the
+ *      new session so they also survive `/resume`.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+interface ClearHandoff {
+	provider: string;
+	modelId: string;
+	thinkingLevel?: string;
+}
+
+const HANDOFF_KEY = "__pi_clear_handoff__";
+
+const THINKING_LEVELS = [
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max",
+] as const;
+type ThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+function isThinkingLevel(value: string): value is ThinkingLevel {
+	return (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+function writeHandoff(handoff: ClearHandoff): void {
+	(globalThis as Record<string, unknown>)[HANDOFF_KEY] = handoff;
+}
+
+/** Consume the handoff: read it and remove it so it can only apply once. */
+function takeHandoff(): ClearHandoff | undefined {
+	const store = globalThis as Record<string, unknown>;
+	const handoff = store[HANDOFF_KEY];
+	delete store[HANDOFF_KEY];
+	return handoff as ClearHandoff | undefined;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerCommand("clear", {
+		description: "Start a fresh session, keeping the current model and thinking level",
+		handler: async (_args, ctx) => {
+			try {
+				if (!ctx.isIdle()) {
+					await ctx.waitForIdle();
+				}
+
+				const { model } = ctx;
+				if (model) {
+					// Capture plain data only: it must survive session replacement.
+					writeHandoff({
+						provider: model.provider,
+						modelId: model.id,
+						thinkingLevel: ctx.thinkingLevel,
+					});
+				}
+
+				const result = await ctx.newSession();
+				// Normally session_start already consumed the handoff; clear any
+				// leftover so it can never apply to a later, unrelated /new.
+				takeHandoff();
+				if (result.cancelled) {
+					ctx.ui.notify("Clear cancelled by extension", "warning");
+				}
+			} catch (err) {
+				takeHandoff();
+				ctx.ui.notify(`Clear failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+			}
+		},
+	});
+
+	pi.on("session_start", async (event, ctx) => {
+		if (event.reason !== "new") return;
+
+		const handoff = takeHandoff();
+		if (!handoff) return;
+
+		try {
+			const model = ctx.modelRegistry.find(handoff.provider, handoff.modelId);
+			if (!model) {
+				ctx.ui.notify(`pi-clear: model ${handoff.provider}/${handoff.modelId} is no longer available`, "warning");
+				return;
+			}
+
+			const applied = await pi.setModel(model);
+			if (!applied) {
+				ctx.ui.notify(`pi-clear: no auth configured for ${handoff.provider}/${handoff.modelId}`, "warning");
+				return;
+			}
+
+			if (handoff.thinkingLevel && isThinkingLevel(handoff.thinkingLevel)) {
+				pi.setThinkingLevel(handoff.thinkingLevel);
+			}
+		} catch (err) {
+			ctx.ui.notify(
+				`pi-clear: could not restore model ${handoff.provider}/${handoff.modelId}: ${err instanceof Error ? err.message : String(err)}`,
+				"warning",
+			);
+		}
+	});
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+	"name": "@grrrck/pi-clear",
+	"version": "0.1.0",
+	"description": "Pi extension that starts a fresh session with /clear while keeping your current model and thinking level",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"clear",
+		"session",
+		"model"
+	],
+	"license": "MIT",
+	"author": "Garrick Aden-Buie (https://garrickadenbuie.com)",
+	"type": "module",
+	"peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+	},
+	"pi": {
+    "extensions": [
+      "./index.ts"
+		]
+	},
+	"repository": {
+    "type": "git",
+		"url": "git+https://github.com/gadenbuie/pi-clear.git"
+	},
+	"bugs": {
+    "url": "https://github.com/gadenbuie/pi-clear/issues"
+	},
+	"homepage": "https://github.com/gadenbuie/pi-clear#readme",
+  "files": ["index.ts", "README.md", "LICENSE", "CHANGELOG.md"]
+}