pi-zen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roshvan
+
+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,48 @@
+# pi-zen
+
+I built `pi-zen` because I wanted a minimal interface that made it easier to stay present in an agent session. I did not want to keep scrolling through long stretches of context to find the few details I needed; I wanted a clean way to follow along, ask questions, and steer and ride the loop.
+
+For real knowledge work, I like being an active participant. I want to understand what is happening between the AI and me so we can be good partners in making decisions. `pi-zen` gives me that space: clear responses, visible progress, and the useful parts of the session in a calm, visually appealing interface.
+
+`pi-zen` is a presentation extension for the [Pi](https://pi.dev) terminal interface. It removes visual clutter while preserving conversations, tool activity, reasoning, and session data. It adds compact tool summaries and diffs, a minimal editor rail, a quieter startup, and a calmer working indicator without changing tool execution or model prompts.
+
+## Showcase
+
+### Light mode
+
+![Pi Zen in light mode](screenshots/pi-zen-light.png)
+
+### Dark mode
+
+![Pi Zen in dark mode](screenshots/pi-zen-dark.png)
+
+### Coding cat demo
+
+![Pi Zen coding cat demo](screenshots/pi-zen-coding-cat.gif)
+
+## Quick start
+
+Install the extension from npm:
+
+```sh
+pi install npm:pi-zen
+```
+
+You can also install the latest version directly from GitHub with `pi install git:github.com/Roshvan/pi-zen`. Start Pi as usual, then run `/zen` to toggle Zen mode.
+
+## Development
+
+You will need Node.js 22.19 or newer and pnpm. Clone the repository, install the dependencies, and start Pi with the local extension:
+
+```sh
+git clone https://github.com/Roshvan/pi-zen.git
+cd pi-zen
+pnpm install
+pnpm dev
+```
+
+Before submitting a change, run `pnpm check` and `pnpm pack:check`.
+
+## Issues and contributions
+
+Issues and pull requests are welcome. If you have an idea, find a bug, or want to improve something, feel free to open an issue or create a pull request. I am happy to look it over.

package/extensions/zen.ts

@@ -0,0 +1,200 @@
+import {
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+	SettingsManager,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+	BACKGROUNDLESS_THEME_NAME,
+	snapshotTheme,
+	withoutContentBackgrounds,
+} from "../src/backgroundless-theme.ts";
+import { CallGrouper } from "../src/call-group.ts";
+import { type BuiltinToolOptions, registerCompactTools } from "../src/compact-tools.ts";
+import { squeezeBlankLines } from "../src/markdown-compaction.ts";
+import { installBlankHeader } from "../src/silent-header.ts";
+import { thinkingTail, thinkingTailLineBudget } from "../src/thinking-tail.ts";
+import { installQuietIndicator, restoreDefaultIndicator } from "../src/working-indicator.ts";
+import { ZenEditor } from "../src/zen-editor.ts";
+
+/** What Zen is doing in the current session. */
+type ZenState =
+	| { readonly kind: "off" }
+	| {
+			readonly kind: "on";
+			readonly previousEditor: ReturnType<ExtensionContext["ui"]["getEditorComponent"]>;
+			/** The active theme before Zen removed its content backgrounds. */
+			readonly previousTheme: Theme;
+			/** What `quietStartup` was set to before Zen claimed it. */
+			readonly previousQuietStartup: boolean;
+	  };
+
+function settingsFor(ctx: ExtensionContext): SettingsManager {
+	return SettingsManager.create(ctx.cwd, undefined, { projectTrusted: ctx.isProjectTrusted() });
+}
+
+function toolOptions(ctx: ExtensionContext): BuiltinToolOptions {
+	const settings = settingsFor(ctx);
+	return {
+		autoResizeImages: settings.getImageAutoResize(),
+		shellCommandPrefix: settings.getShellCommandPrefix(),
+		shellPath: settings.getShellPath(),
+	};
+}
+
+/**
+ * Zen: a quieter Pi TUI.
+ *
+ * The extension owns the presentation layer only — chrome, editor frame, working
+ * indicator, and how tool calls read. Nothing here changes what Pi executes,
+ * what the model sees, or what a session records.
+ *
+ * There is one switch. `/zen on` is every part of it and `/zen off` is none of
+ * it, because a quiet interface you have to configure is not one.
+ *
+ * @param pi - The extension API.
+ */
+export default function zen(pi: ExtensionAPI): void {
+	let state: ZenState = { kind: "off" };
+	let toolsRegistered = false;
+	let deferredReloadInstall: ReturnType<typeof setTimeout> | undefined;
+	let deferredThemeProjection: ReturnType<typeof setTimeout> | undefined;
+	let activeContext: ExtensionContext | undefined;
+	const grouper = new CallGrouper();
+
+	// Installing is idempotent on purpose: another extension can take the header
+	// or the editor at any time, so `/zen on` has to be able to claim them back.
+	const install = (ctx: ExtensionContext) => {
+		if (ctx.mode !== "tui") return;
+
+		const previousEditor = state.kind === "on" ? state.previousEditor : ctx.ui.getEditorComponent();
+		let previousTheme = state.kind === "on" ? state.previousTheme : snapshotTheme(ctx.ui.theme);
+		if (ctx.ui.theme.name !== BACKGROUNDLESS_THEME_NAME) {
+			previousTheme = snapshotTheme(ctx.ui.theme);
+			ctx.ui.setTheme(withoutContentBackgrounds(ctx.ui.theme));
+		}
+
+		// Pi reads quietStartup before extensions load, so this is the one thing Zen
+		// cannot do for the session it is asked in — it takes effect next launch.
+		const settings = settingsFor(ctx);
+		const previousQuietStartup = state.kind === "on" ? state.previousQuietStartup : settings.getQuietStartup();
+		if (!settings.getQuietStartup()) settings.setQuietStartup(true);
+
+		installBlankHeader(ctx);
+		ctx.ui.setEditorComponent((tui, theme, keybindings) => new ZenEditor(tui, theme, keybindings));
+		installQuietIndicator(ctx.ui);
+		state = { kind: "on", previousEditor, previousTheme, previousQuietStartup };
+	};
+
+	// Pi has no public theme-change event for extensions. Markdown transformers
+	// do rerun when the transcript redraws, so they can notice a newly selected
+	// theme and project it on the next task without touching content.
+	const projectChangedThemeSoon = () => {
+		const ctx = activeContext;
+		if (ctx === undefined || state.kind === "off" || ctx.ui.theme.name === BACKGROUNDLESS_THEME_NAME) return;
+		if (deferredThemeProjection !== undefined) return;
+
+		deferredThemeProjection = setTimeout(() => {
+			deferredThemeProjection = undefined;
+			if (state.kind === "off" || activeContext !== ctx || ctx.ui.theme.name === BACKGROUNDLESS_THEME_NAME) return;
+
+			const previousTheme = snapshotTheme(ctx.ui.theme);
+			ctx.ui.setTheme(withoutContentBackgrounds(ctx.ui.theme));
+			installQuietIndicator(ctx.ui);
+			state = { ...state, previousTheme };
+		}, 0);
+	};
+
+	// `settings` is only given back when the user asks for Zen off. Shutting down is
+	// not a change of mind, and reverting quietStartup there would undo it every
+	// time pi closed.
+	const restore = (ctx: ExtensionContext, give: "chrome" | "chrome and settings") => {
+		if (state.kind === "off") return;
+		if (give === "chrome and settings") {
+			const settings = settingsFor(ctx);
+			if (settings.getQuietStartup() !== state.previousQuietStartup) {
+				settings.setQuietStartup(state.previousQuietStartup);
+			}
+		}
+		if (ctx.ui.theme.name === BACKGROUNDLESS_THEME_NAME) ctx.ui.setTheme(state.previousTheme);
+		ctx.ui.setHeader(undefined);
+		ctx.ui.setEditorComponent(state.previousEditor);
+		restoreDefaultIndicator(ctx.ui);
+		state = { kind: "off" };
+	};
+
+	pi.on("session_start", (event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		activeContext = ctx;
+
+		// Tool overrides are registered once per process: re-registering the same
+		// names on a later session_start would stack duplicate definitions.
+		if (!toolsRegistered) {
+			registerCompactTools(pi, ctx.cwd, toolOptions(ctx), grouper, () => state.kind === "on");
+			toolsRegistered = true;
+		}
+		install(ctx);
+
+		// During /reload, Pi reapplies the saved theme after session_start. Reclaim
+		// it on the next task so newly submitted messages stay backgroundless too.
+		if (event.reason === "reload") {
+			deferredReloadInstall = setTimeout(() => {
+				deferredReloadInstall = undefined;
+				if (state.kind === "on") install(ctx);
+			}, 0);
+		}
+	});
+
+	pi.on("turn_end", () => {
+		// The next turn's reads belong to their own line, not to this turn's.
+		grouper.close();
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		if (deferredReloadInstall !== undefined) {
+			clearTimeout(deferredReloadInstall);
+			deferredReloadInstall = undefined;
+		}
+		if (deferredThemeProjection !== undefined) {
+			clearTimeout(deferredThemeProjection);
+			deferredThemeProjection = undefined;
+		}
+		activeContext = undefined;
+		restore(ctx, "chrome");
+	});
+
+	// Display-only: the session and the model keep the original markdown.
+	pi.registerMarkdownTransformer((markdown, context) => {
+		if (state.kind === "off") return markdown;
+		projectChangedThemeSoon();
+		if (context.messageType === "assistant-thinking" && context.isStreaming) {
+			return thinkingTail(squeezeBlankLines(markdown), thinkingTailLineBudget(process.stdout.rows));
+		}
+		return squeezeBlankLines(markdown);
+	});
+
+	pi.registerCommand("zen", {
+		description: "Quiet the TUI: on or off",
+		getArgumentCompletions: (prefix) =>
+			["on", "off"].filter((option) => option.startsWith(prefix)).map((option) => ({ value: option, label: option })),
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			const request = args.trim().toLowerCase();
+			const wanted = request === "" ? state.kind === "off" : request !== "off";
+
+			if (wanted) {
+				const wasQuiet = settingsFor(ctx).getQuietStartup();
+				install(ctx);
+				ctx.ui.notify(wasQuiet ? "Zen on" : "Zen on · quiet startup from the next launch", "info");
+				return;
+			}
+			if (deferredThemeProjection !== undefined) {
+				clearTimeout(deferredThemeProjection);
+				deferredThemeProjection = undefined;
+			}
+			restore(ctx, "chrome and settings");
+			ctx.ui.notify("Zen off · tool frames return after Zen is disabled and Pi reloads", "info");
+		},
+	});
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+	"name": "pi-zen",
+	"version": "0.1.0",
+	"description": "A quiet Pi TUI on one switch: backgroundless messages, a rail editor, compact tool calls, and restrained reasoning",
+	"type": "module",
+	"packageManager": "pnpm@11.21.0",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Roshvan/pi-zen.git"
+	},
+	"bugs": {
+		"url": "https://github.com/Roshvan/pi-zen/issues"
+	},
+	"homepage": "https://github.com/Roshvan/pi-zen#readme",
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	},
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"coding-agent",
+		"tui",
+		"minimal",
+		"zen"
+	],
+	"files": [
+		"extensions",
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"check": "tsc --noEmit && oxlint",
+		"dev": "pi -e ./extensions/zen.ts",
+		"lint": "oxlint",
+		"pack:check": "pnpm pack --dry-run",
+		"prepublishOnly": "pnpm check && pnpm pack:check"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/zen.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "0.84.3",
+		"@earendil-works/pi-tui": "0.84.3",
+		"@oxlint/plugins": "^1.79.0",
+		"@types/node": "^24.10.0",
+		"oxlint": "^1.79.0",
+		"typescript": "7.0.2"
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}

package/src/backgroundless-theme.ts

@@ -0,0 +1,158 @@
+import { Theme, type ThemeColor } from "@earendil-works/pi-coding-agent";
+
+/** Name used only while Zen's backgroundless projection is active. */
+export const BACKGROUNDLESS_THEME_NAME = "pi-zen:backgroundless";
+
+const THEME_COLORS = [
+	"accent",
+	"border",
+	"borderAccent",
+	"borderMuted",
+	"success",
+	"error",
+	"warning",
+	"muted",
+	"dim",
+	"text",
+	"thinkingText",
+	"searchMatchText",
+	"userMessageText",
+	"customMessageText",
+	"customMessageLabel",
+	"toolTitle",
+	"toolOutput",
+	"mdHeading",
+	"mdLink",
+	"mdLinkUrl",
+	"mdCode",
+	"mdCodeBlock",
+	"mdCodeBlockBorder",
+	"mdQuote",
+	"mdQuoteBorder",
+	"mdHr",
+	"mdListBullet",
+	"toolDiffAdded",
+	"toolDiffRemoved",
+	"toolDiffContext",
+	"syntaxComment",
+	"syntaxKeyword",
+	"syntaxFunction",
+	"syntaxVariable",
+	"syntaxString",
+	"syntaxNumber",
+	"syntaxType",
+	"syntaxOperator",
+	"syntaxPunctuation",
+	"thinkingOff",
+	"thinkingMinimal",
+	"thinkingLow",
+	"thinkingMedium",
+	"thinkingHigh",
+	"thinkingXhigh",
+	"thinkingMax",
+	"bashMode",
+] as const satisfies ReadonlyArray<ThemeColor>;
+
+type ThemeBackground = Parameters<Theme["bg"]>[0];
+
+const THEME_BACKGROUNDS = [
+	"selectedBg",
+	"scrollbarThumb",
+	"searchMatchBg",
+	"userMessageBg",
+	"customMessageBg",
+	"toolPendingBg",
+	"toolSuccessBg",
+	"toolErrorBg",
+] as const satisfies ReadonlyArray<ThemeBackground>;
+
+const CONTENT_BACKGROUNDS: ReadonlySet<ThemeBackground> = new Set([
+	"userMessageBg",
+	"customMessageBg",
+	"toolPendingBg",
+	"toolSuccessBg",
+	"toolErrorBg",
+]);
+
+/** Foregrounds designed for a colored surface need a terminal-safe counterpart once that surface is gone. */
+function backgroundlessForeground(color: ThemeColor): ThemeColor {
+	if (color === "userMessageText" || color === "customMessageText" || color === "toolOutput") return "text";
+	return color;
+}
+
+type ForegroundInput = ConstructorParameters<typeof Theme>[0];
+type BackgroundInput = ConstructorParameters<typeof Theme>[1];
+
+type ThemeSnapshotOptions = {
+	readonly name: string | undefined;
+	readonly suppressContentBackgrounds: boolean;
+};
+
+function emptyForegrounds(): ForegroundInput {
+	// SAFETY: THEME_COLORS is checked against ThemeColor and contains every required key exactly once.
+	return Object.fromEntries(THEME_COLORS.map((color) => [color, ""])) as ForegroundInput;
+}
+
+function emptyBackgrounds(): BackgroundInput {
+	// SAFETY: THEME_BACKGROUNDS is checked against ThemeBackground and contains every required key exactly once.
+	return Object.fromEntries(THEME_BACKGROUNDS.map((color) => [color, ""])) as BackgroundInput;
+}
+
+function makeThemeSnapshot(source: Theme, options: ThemeSnapshotOptions): Theme {
+	const foregroundAnsi = new Map<ThemeColor, string>();
+	const backgroundAnsi = new Map<ThemeBackground, string>();
+	for (const color of THEME_COLORS) foregroundAnsi.set(color, source.getFgAnsi(color));
+	for (const color of THEME_BACKGROUNDS) backgroundAnsi.set(color, source.getBgAnsi(color));
+
+	// SAFETY: Pi created source, so its constructor is the runtime's Theme constructor. Using that exact constructor
+	// keeps instanceof checks valid when this source package has a different development copy of Pi installed.
+	const RuntimeTheme = source.constructor as typeof Theme;
+	const snapshot = new RuntimeTheme(
+		emptyForegrounds(),
+		emptyBackgrounds(),
+		source.getColorMode(),
+		options.name === undefined ? {} : { name: options.name },
+	);
+
+	snapshot.getFgAnsi = (color: ThemeColor): string => {
+		const projectedColor = options.suppressContentBackgrounds ? backgroundlessForeground(color) : color;
+		const ansi = foregroundAnsi.get(projectedColor);
+		if (ansi === undefined) throw new Error(`Unknown theme color: ${color}`);
+		return ansi;
+	};
+	snapshot.getBgAnsi = (color: ThemeBackground): string => {
+		if (options.suppressContentBackgrounds && CONTENT_BACKGROUNDS.has(color)) return "\x1b[49m";
+		const ansi = backgroundAnsi.get(color);
+		if (ansi === undefined) throw new Error(`Unknown theme background: ${color}`);
+		return ansi;
+	};
+	snapshot.fg = (color: ThemeColor, text: string): string => `${snapshot.getFgAnsi(color)}${text}\x1b[39m`;
+	snapshot.bg = (color: ThemeBackground, text: string): string => {
+		if (options.suppressContentBackgrounds && CONTENT_BACKGROUNDS.has(color)) return text;
+		return `${snapshot.getBgAnsi(color)}${text}\x1b[49m`;
+	};
+
+	return snapshot;
+}
+
+/**
+ * Capture the active theme so Zen can restore it without depending on mutable global theme state.
+ *
+ * @param source - Pi's currently active theme.
+ * @returns An in-memory copy of the active theme.
+ */
+export function snapshotTheme(source: Theme): Theme {
+	return makeThemeSnapshot(source, { name: source.name, suppressContentBackgrounds: false });
+}
+
+/**
+ * Keep the active theme while removing message and tool backgrounds.
+ * Surface-specific body text falls back to the theme's terminal-safe base text;
+ * selection, search, and scrollbar backgrounds remain as affordances.
+ *
+ * @param source - Pi's currently active theme.
+ * @returns A backgroundless projection of the active theme.
+ */
+export function withoutContentBackgrounds(source: Theme): Theme {
+	return makeThemeSnapshot(source, { name: BACKGROUNDLESS_THEME_NAME, suppressContentBackgrounds: true });
+}

package/src/builtin-render.ts

@@ -0,0 +1,69 @@
+import type { AgentToolResult, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import type { Component } from "@earendil-works/pi-tui";
+
+/**
+ * The render context Pi hands to a tool's render slots.
+ *
+ * Pi does not export `ToolRenderContext`, and each built-in tool keeps a
+ * private render state on it, so an expanded row forwards the context object it
+ * was given rather than rebuilding one.
+ */
+// oxlint-disable-next-line no-explicit-any -- SAFETY: the forwarded value is always the context object Pi just passed in, with only the cached component replaced. Naming its type would mean restating Pi's private per-tool render state.
+export type ForwardedRenderContext = any;
+
+/** A built-in `renderCall` slot. */
+export type BuiltinCallSlot<TArgs> = (args: TArgs, theme: Theme, context: ForwardedRenderContext) => Component;
+
+/** A built-in `renderResult` slot. */
+export type BuiltinResultSlot<TDetails> = (
+	result: AgentToolResult<TDetails>,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	context: ForwardedRenderContext,
+) => Component;
+
+/**
+ * Render a built-in tool's call slot, reusing the component it returned last time.
+ *
+ * @template TArgs - The tool's argument type.
+ * @param slot - The built-in `renderCall`, when the tool has one.
+ * @param args - Arguments for this tool call.
+ * @param theme - The active theme.
+ * @param context - The context Pi passed to our own renderer.
+ * @param lastComponent - The component this slot returned on the previous render.
+ * @returns The built-in component, or undefined when the tool has no call slot.
+ */
+export function forwardCall<TArgs>(
+	slot: BuiltinCallSlot<TArgs> | undefined,
+	args: TArgs,
+	theme: Theme,
+	context: ForwardedRenderContext,
+	lastComponent: Component | undefined,
+): Component | undefined {
+	if (slot === undefined) return undefined;
+	return slot(args, theme, { ...context, lastComponent });
+}
+
+/**
+ * Render a built-in tool's result slot, reusing the component it returned last time.
+ *
+ * @template TDetails - The tool's result detail type.
+ * @param slot - The built-in `renderResult`, when the tool has one.
+ * @param result - The settled tool result.
+ * @param options - Pi's render options for this result.
+ * @param theme - The active theme.
+ * @param context - The context Pi passed to our own renderer.
+ * @param lastComponent - The component this slot returned on the previous render.
+ * @returns The built-in component, or undefined when the tool has no result slot.
+ */
+export function forwardResult<TDetails>(
+	slot: BuiltinResultSlot<TDetails> | undefined,
+	result: AgentToolResult<TDetails>,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	context: ForwardedRenderContext,
+	lastComponent: Component | undefined,
+): Component | undefined {
+	if (slot === undefined) return undefined;
+	return slot(result, options, theme, { ...context, lastComponent });
+}