@xynogen/pix-optimizer 1.1.7 → 1.1.9

package/README.md

@@ -1,7 +1,7 @@
 # pix-optimizer
 
-Token-optimization suite for Pi Coding Agent. Three tools wired into one
-extension via `src/index.ts`, fronted by a single `/opt` command and one
+Token-optimization suite for Pi Coding Agent. Four tools wired into one
+extension via `src/index.ts`, fronted by a single `/optimizer` command and one
 shared status-bar cell:
 
 - **Caveman** (`󰜐`) — terse-output system prompt
@@ -11,20 +11,45 @@ shared status-bar cell:
 
 ## Command
 
-One command routes to every tool:
+One command opens an interactive overlay that fronts every tool:
 
 ```text
-/opt                  → status + help
-/opt caveman <level>  → set caveman level (1/2/3/lite/full/ultra/micro/off/config)
-/opt rtk [on|off]     → toggle RTK rewriting
-/opt toon [on|off]    → toggle jq+TOON guidance
-/opt ponytail <level> → set ponytail level (1/2/3/lite/full/ultra/off/config)
+/optimizer                 → open the overlay (←→ cycle value, ↑↓ move, esc close)
 ```
 
+There is no text-arg form: the overlay is the only UI. Selecting a value calls
+the tool's `run()` handler, which persists the new value and repaints the
+shared status cell. Headless/test fallbacks print a plain status summary.
+
+State persists to `~/.pi/agent/optimizer.json` (caveman/rtk/toon/ponytail).
+
 ## Status bar
 
-A single cell always shows the enabled icons in a fixed order (`󰜐 󰓥 󰗀 󰆐`), color-
-coded by state: **accent** when the tool is enabled, **dim** when disabled.
+A single cell always shows all four tool icons in a fixed order, color-coded by
+state: **accent** when the tool is enabled, **dim** when disabled.
+
+### Icon style (Nerd Font, Unicode, or ASCII)
+
+The default glyphs (`󰜐 󰓥 󰗀 󰆐`) are **Nerd Font** symbols and require a patched
+font (e.g. MesloLGS NF). Terminals without one render them as missing-glyph
+“tofu” boxes. Two font-independent fallbacks are available:
+
+| Mode | Glyphs | Needs Nerd Font? |
+|---|---|---|
+| `nerd` (default) | `󰜐 󰓥 󰗀 󰆐` | yes |
+| `unicode` | `♤ ♡ ♢ ♧` (outline card suits) | no |
+| `ascii` | `Cv Rk Tn Pt` | no |
+
+Switch the style live from the **`/optimizer` overlay** — a fifth `icons` row
+at the bottom cycles `nerd → unicode → ascii` with `←→`; the choice persists to
+`~/.pi/agent/optimizer.json`.
+
+Or set it via env var (a persisted menu choice takes precedence):
+
+```bash
+export OPTIMIZER_ICONS=unicode   # nerd | unicode | ascii
+export PRETTY_ICONS=none         # stack-wide: also maps the cell to ASCII
+```
 
 ## Features
 
@@ -32,15 +57,15 @@ coded by state: **accent** when the tool is enabled, **dim** when disabled.
 
 Cuts ~75% of output tokens while keeping full technical accuracy.
 
-| # | Name  | Description                  |
-|---|-------|------------------------------|
-| 1 | lite  | Professional, no fluff       |
-| 2 | full  | Classic caveman              |
-| 3 | ultra | Maximum compression          |
-| – | micro | Experimental prompt-minimized |
+| Level | Description                  |
+|-------|------------------------------|
+| lite  | Professional, no fluff       |
+| full  | Classic caveman              |
+| ultra | Maximum compression          |
+| micro | Experimental prompt-minimized |
 
-`/opt caveman config` opens a settings dialog. Default level for new sessions
-and status-bar visibility are saved to `~/.pi/agent/caveman.json`.
+The `/optimizer` overlay opens a settings dialog when needed. Default level
+for new sessions is restored from `~/.pi/agent/optimizer.json`.
 
 ### RTK Tool Rewriting (`󰓥`)
 
@@ -88,14 +113,11 @@ writing code the agent stops at the first rung that holds: does this need to
 exist → stdlib → native platform → installed dep → one line → minimum that
 works. Validation, error handling, security, and accessibility are never cut.
 
-| # | Name  | Description                          |
-|---|-------|--------------------------------------|
-| 1 | lite  | Name the lazier alternative, you pick |
-| 2 | full  | The ladder enforced (default)        |
-| 3 | ultra | YAGNI extremist                      |
-
-`/opt ponytail config` opens a settings dialog. Default level for new sessions
-and status-bar visibility are saved to `~/.pi/agent/ponytail.json`.
+| Level | Description                          |
+|-------|--------------------------------------|
+| lite  | Name the lazier alternative, you pick |
+| full  | The ladder enforced (default)        |
+| ultra | YAGNI extremist                      |
 
 **No install required** — pure prompt injection, no external binary or PATH
 dependency (unlike RTK and TOON).
@@ -116,16 +138,18 @@ pi install npm:@xynogen/pix-optimizer
 
 | File              | Role                                                      |
 |-------------------|-----------------------------------------------------------|
-| `src/index.ts`    | Wires the four tools + shared status, registers `/opt`    |
-| `src/opt.ts`      | The `/opt` router: parse, complete, dispatch              |
+| `src/index.ts`    | Wires the four tools + shared status, registers `/optimizer` |
+| `src/opt.ts`      | The `/optimizer` overlay UI (keyboard nav + cycling)     |
 | `src/status.ts`   | Shared status-bar cell + `OptimizerHandle` contract       |
-| `src/caveman.ts`  | Caveman logic, levels, prompt, settings dialog            |
+| `src/caveman.ts`  | Caveman logic, levels, prompt                            |
 | `src/rtk.ts`      | RTK prompt + bash command rewriting                       |
 | `src/json.ts`     | jq+TOON guidance, heuristics, system-prompt injection     |
-| `src/ponytail.ts` | Ponytail logic, levels, prompt, settings dialog           |
+| `src/ponytail.ts` | Ponytail logic, levels, prompt                            |
+| `src/persist.ts`  | Disk-backed `~/.pi/agent/optimizer.json` persistence      |
+| `src/tool-result-filter.ts` | Strips model-guidance warnings from tool_result |
 
 Each tool registers its own lifecycle hooks and exposes an `OptimizerHandle`
-that `/opt` dispatches to. All four share one `OptimizerStatus`.
+that `/optimizer` dispatches to. All four share one `OptimizerStatus`.
 
 ## Development
 
@@ -137,22 +161,22 @@ bun test
 
 This package was built by merging two upstream Pi community packages:
 
-- **Caveman mode** — merged from [`git:github.com/jonjonrankin/pi-caveman`](https://github.com/jonjonrankin/pi-caveman)
-  (itself a fork of `npm:pi-caveman`). Reimplemented here with multiple compression levels,
-  a settings dialog, per-session persistence, and integration with the shared `/opt` command.
+- **Caveman mode** — merged from `npm:pi-caveman`. Reimplemented here with
+  multiple compression levels and integration with the shared `/optimizer`
+  command.
 
-- **RTK rewriting** — merged from `npm:pi-rtk-optimizer`. Reimplemented here with a two-layer
-  approach: prompt injection + live bash command rewriting that handles chained commands
-  (`&&`, `||`, `;`, `|`).
+- **RTK rewriting** — merged from `npm:pi-rtk-optimizer`. Reimplemented here
+  with a two-layer approach: prompt injection + live bash command rewriting
+  that handles chained commands (`&&`, `||`, `;`, `|`).
 
 - **Ponytail mode** — ruleset adapted from [`git:github.com/DietrichGebert/ponytail`](https://github.com/DietrichGebert/ponytail),
-  the "lazy senior dev" skill. Reimplemented here as a native `/opt` tool with three intensity
-  levels, a settings dialog, and per-session persistence — no external hooks or files. The
+  the "lazy senior dev" skill. Reimplemented here as a native `/optimizer`
+  tool with three intensity levels — no external hooks or files. The
   ruleset (the YAGNI ladder + safety carve-outs) is rewritten as a system-prompt fragment.
 
 All upstreams are MIT licensed. No codebase was copied directly — the logic was
-rewritten and combined into a single extension with a unified `/opt` command and shared status bar.
-This package does not sync back to any upstream.
+rewritten and combined into a single extension with a unified `/optimizer`
+command and shared status bar. This package does not sync back to any upstream.
 
 ## Full distro
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-optimizer",
-	"version": "1.1.7",
+	"version": "1.1.9",
 	"description": "Performance optimization suite for Pi Coding Agent - caveman mode + RTK tool rewriting + jq/TOON JSON compression + ponytail lazy-dev mode",
 	"type": "module",
 	"main": "src/index.ts",

package/src/index.ts

@@ -1,24 +1,27 @@
 /**
  * pix-optimizer — token-optimization suite for Pi Coding Agent.
  *
- * Three tools, combined into one extension + one command:
+ * Four tools, combined into one extension + one command:
  *   - caveman:  terse-output system prompt
  *   - rtk:      prefixes shell commands with `rtk` + injects RTK prompt
  *   - toon:     jq + TOON guidance for dense JSON (+ bundled skill)
  *   - ponytail: lazy-senior-dev system prompt (minimal code, YAGNI)
  *
- * They share ONE status-bar cell (󰜐 󰓥 󰗀 󰆐, only enabled tools shown) and ONE
- * command (/optimizer — an interactive overlay). index.ts wires lifecycle hooks
- * via each module, then registers the overlay command from their handles.
+ * They share ONE status-bar cell (all four icons always shown — dimmed when
+ * off, accented when on; icon style is nerd/unicode/ascii, set via /optimizer)
+ * and ONE command (/optimizer — an interactive overlay). index.ts wires
+ * lifecycle hooks via each module, then registers the overlay command.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { caveman } from "./caveman.ts";
 import { json } from "./json.ts";
 import { registerOptCommand } from "./opt.ts";
+import { loadIconMode } from "./persist.ts";
 import { ponytail } from "./ponytail.ts";
 import { rtk } from "./rtk.ts";
 import {
+	envIconMode,
 	type OptimizerHandle,
 	OptimizerStatus,
 	type OptimizerTool,
@@ -26,7 +29,8 @@ import {
 import { filterModelWarnings } from "./tool-result-filter.ts";
 
 export default function optimizer(pi: ExtensionAPI) {
-	const status = new OptimizerStatus();
+	// Persisted menu choice wins; otherwise fall back to the env default.
+	const status = new OptimizerStatus(loadIconMode() ?? envIconMode());
 
 	// Each module registers its own lifecycle hooks and returns a handle the
 	// /optimizer overlay renders + drives.

package/src/opt.ts

@@ -16,13 +16,23 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { frameLines } from "@xynogen/pix-pretty/modal-frame";
+import { saveIconMode } from "./persist.ts";
 import {
+	getIcons,
+	ICON_MODES,
+	type IconMode,
 	type OptimizerHandle,
 	type OptimizerStatus,
 	type OptimizerTool,
-	TOOL_ICONS,
 } from "./status.ts";
 
+/** Glyph for the icon-mode row itself (uses the active mode's diamond/Tn). */
+const ICON_ROW_GLYPH: Record<IconMode, string> = {
+	nerd: "󰆐", // gear-ish; distinct from the four tool glyphs
+	unicode: "\u25C8\uFE0E", // ◈ diamond-in-diamond
+	ascii: "Ic",
+};
+
 /** Min/max content width for the overlay box (excludes 4 cols of chrome). */
 const MIN_CONTENT = 28;
 const MAX_CONTENT = 60;
@@ -76,7 +86,7 @@ export function buildOptHelp(
 export function registerOptCommand(
 	pi: ExtensionAPI,
 	handles: Record<OptimizerTool, OptimizerHandle>,
-	_status: OptimizerStatus,
+	status: OptimizerStatus,
 ): void {
 	pi.registerCommand("optimizer", {
 		description: "pix-optimizer: caveman / rtk / toon / ponytail tools",
@@ -129,9 +139,26 @@ export function registerOptCommand(
 					_kb: unknown,
 					done: (v: null) => void,
 				) => {
+					// Rows = 4 tools + 1 icon-mode row at index TOOL_ORDER.length.
+					const ICON_ROW = TOOL_ORDER.length;
+					const ROW_COUNT = TOOL_ORDER.length + 1;
+					const ICON_HELP = "status-cell icon style (nerd needs a Nerd Font)";
 					let selected = 0;
 
+					const cycleIconMode = (direction: -1 | 1) => {
+						const cur = ICON_MODES.indexOf(status.mode);
+						const next =
+							(cur + direction + ICON_MODES.length) % ICON_MODES.length;
+						const mode = ICON_MODES[next]!;
+						status.setMode(mode, ctx);
+						saveIconMode(mode);
+					};
+
 					const cycle = (direction: -1 | 1) => {
+						if (selected === ICON_ROW) {
+							cycleIconMode(direction);
+							return;
+						}
 						const tool = TOOL_ORDER[selected]!;
 						const values = handles[tool].values;
 						const cur = values.indexOf(handles[tool].current());
@@ -140,17 +167,17 @@ export function registerOptCommand(
 					};
 
 					const move = (direction: -1 | 1) => {
-						selected =
-							(selected + direction + TOOL_ORDER.length) % TOOL_ORDER.length;
+						selected = (selected + direction + ROW_COUNT) % ROW_COUNT;
 					};
 
 					return {
 						render: () => {
+							const icons = getIcons(status.mode);
 							const rows = TOOL_ORDER.map((tool, i) => {
 								const on = handles[tool].current() !== "off";
 								const sel = i === selected;
 								const cursor = sel ? theme.fg("accent", "→") : " ";
-								const icon = theme.fg(on ? "accent" : "dim", TOOL_ICONS[tool]);
+								const icon = theme.fg(on ? "accent" : "dim", icons[tool]);
 								const name = theme.fg(
 									sel ? "accent" : on ? "text" : "muted",
 									tool.padEnd(nameWidth),
@@ -166,15 +193,29 @@ export function registerOptCommand(
 								);
 								return `${cursor} ${icon}  ${name}  ${value}  ${bar}`;
 							});
+							// Icon-mode row: glyph + "icons" + current mode name.
+							const iconSel = selected === ICON_ROW;
+							const iconCursor = iconSel ? theme.fg("accent", "→") : " ";
+							const iconGlyph = theme.fg("accent", ICON_ROW_GLYPH[status.mode]);
+							const iconName = theme.fg(
+								iconSel ? "accent" : "text",
+								"icons".padEnd(nameWidth),
+							);
+							const iconValue = theme.fg(
+								"success",
+								status.mode.padEnd(valueWidth),
+							);
+							const iconRow = `${iconCursor} ${iconGlyph}  ${iconName}  ${iconValue}`;
+							const helpText = iconSel
+								? ICON_HELP
+								: helpSummary(handles[TOOL_ORDER[selected]!].help);
 							const lines = [
 								theme.fg("accent", theme.bold("󱎫  Optimizer")),
 								"",
 								...rows,
+								iconRow,
 								"",
-								theme.fg(
-									"dim",
-									helpSummary(handles[TOOL_ORDER[selected]!].help),
-								),
+								theme.fg("dim", helpText),
 								"",
 								theme.fg("dim", "←→ change · ↑↓ move · esc close"),
 							];

package/src/persist.test.ts

@@ -9,7 +9,12 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { loadOptValue, saveOptValue } from "./persist.ts";
+import {
+	loadIconMode,
+	loadOptValue,
+	saveIconMode,
+	saveOptValue,
+} from "./persist.ts";
 
 let tmpAgentDir: string;
 
@@ -53,4 +58,21 @@ describe("optimizer persistence", () => {
 		expect(loadOptValue("caveman")).toBe("ultra");
 		expect(loadOptValue("ponytail")).toBe("full");
 	});
+
+	test("icon mode round-trips and is independent of tool values", () => {
+		expect(loadIconMode()).toBeUndefined();
+		saveIconMode("unicode");
+		expect(loadIconMode()).toBe("unicode");
+		// Did not disturb existing tool state…
+		expect(loadOptValue("caveman")).toBe("ultra");
+		// …and a later tool write does not disturb the icon mode.
+		saveOptValue("rtk", "on");
+		expect(loadIconMode()).toBe("unicode");
+	});
+
+	test("rejects an invalid persisted icon mode", () => {
+		saveOptValue("caveman", "lite"); // unrelated write
+		saveIconMode("ascii");
+		expect(loadIconMode()).toBe("ascii");
+	});
 });

package/src/persist.ts

@@ -7,14 +7,21 @@
  * restart. Each tool reads its value on session_start and writes on run().
  *
  *   ~/.pi/agent/optimizer.json  →  { "caveman": "lite", "rtk": "on", ... }
+ *
+ * A reserved "iconMode" key (not a tool) stores the status-cell icon style.
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import type { OptimizerTool } from "./status.ts";
+import { ICON_MODES, type IconMode, type OptimizerTool } from "./status.ts";
+
+/** Reserved (non-tool) key holding the icon presentation mode. */
+const ICON_MODE_KEY = "iconMode";
 
-type OptimizerConfig = Partial<Record<OptimizerTool, string>>;
+type OptimizerConfig = Partial<Record<OptimizerTool, string>> & {
+	[ICON_MODE_KEY]?: string;
+};
 
 function getStatePath(): string {
 	return join(getAgentDir(), "optimizer.json");
@@ -48,3 +55,21 @@ export function saveOptValue(tool: OptimizerTool, value: string): void {
 		console.warn(`optimizer: persist ${tool} failed:`, err);
 	}
 }
+
+/** Read the persisted icon mode, or undefined if unset/invalid. */
+export function loadIconMode(): IconMode | undefined {
+	const raw = readAll()[ICON_MODE_KEY];
+	return ICON_MODES.includes(raw as IconMode) ? (raw as IconMode) : undefined;
+}
+
+/** Persist the icon mode, merging into the shared config file. */
+export function saveIconMode(mode: IconMode): void {
+	try {
+		const sp = getStatePath();
+		mkdirSync(dirname(sp), { recursive: true });
+		const next = { ...readAll(), [ICON_MODE_KEY]: mode };
+		writeFileSync(sp, JSON.stringify(next, null, 2), "utf-8");
+	} catch (err) {
+		console.warn("optimizer: persist iconMode failed:", err);
+	}
+}

package/src/status.test.ts

@@ -1,5 +1,8 @@
-import { describe, expect, it } from "bun:test";
+import { afterEach, describe, expect, it } from "bun:test";
 import {
+	envIconMode,
+	getIcons,
+	ICON_MODES,
 	OptimizerStatus,
 	renderStatus,
 	STATUS_KEY,
@@ -45,6 +48,66 @@ describe("renderStatus", () => {
 	});
 });
 
+describe("icon modes", () => {
+	it("nerd is the default mode used by renderStatus", () => {
+		expect(renderStatus({ rtk: true }, tag)).toContain(TOOL_ICONS.rtk);
+	});
+
+	it("renders the unicode (outline-suit) set when mode=unicode", () => {
+		const icons = getIcons("unicode");
+		const out = renderStatus({ caveman: true }, tag, "unicode");
+		expect(out).toContain(icons.caveman);
+		// outline white spade + text variation selector
+		expect(icons.caveman).toBe("\u2664\uFE0E");
+	});
+
+	it("renders the ascii set when mode=ascii", () => {
+		const out = renderStatus(
+			{ caveman: true, rtk: false, toon: true, ponytail: false },
+			tag,
+			"ascii",
+		);
+		expect(out).toBe(
+			`<accent>Cv</accent>  <dim>Rk</dim>  <accent>Tn</accent>  <dim>Pt</dim> `,
+		);
+	});
+
+	it("falls back to nerd for an unknown mode", () => {
+		// @ts-expect-error exercising the runtime guard in getIcons
+		expect(getIcons("bogus")).toBe(getIcons("nerd"));
+	});
+
+	it("exposes exactly nerd/unicode/ascii in cycle order", () => {
+		expect([...ICON_MODES]).toEqual(["nerd", "unicode", "ascii"]);
+	});
+});
+
+describe("envIconMode", () => {
+	const saved = { ...process.env };
+	afterEach(() => {
+		process.env.OPTIMIZER_ICONS = saved.OPTIMIZER_ICONS;
+		process.env.PRETTY_ICONS = saved.PRETTY_ICONS;
+	});
+
+	it("defaults to nerd when nothing set", () => {
+		process.env.OPTIMIZER_ICONS = undefined;
+		process.env.PRETTY_ICONS = undefined;
+		expect(envIconMode()).toBe("nerd");
+	});
+
+	it("OPTIMIZER_ICONS wins over PRETTY_ICONS", () => {
+		process.env.OPTIMIZER_ICONS = "unicode";
+		process.env.PRETTY_ICONS = "none";
+		expect(envIconMode()).toBe("unicode");
+	});
+
+	it("PRETTY_ICONS=none maps to ascii", () => {
+		process.env.OPTIMIZER_ICONS = undefined;
+		process.env.PRETTY_ICONS = "none";
+		expect(envIconMode()).toBe("ascii");
+	});
+});
+
 describe("OptimizerStatus", () => {
 	/** Minimal ui stub capturing setStatus calls. */
 	function fakeCtx() {
@@ -92,4 +155,24 @@ describe("OptimizerStatus", () => {
 			`<dim>${TOOL_ICONS.caveman}</dim>  <dim>${TOOL_ICONS.rtk}</dim>  <dim>${TOOL_ICONS.toon}</dim>  <dim>${TOOL_ICONS.ponytail}</dim> `,
 		);
 	});
+
+	it("seeds icon mode from the constructor", () => {
+		const status = new OptimizerStatus("ascii");
+		expect(status.mode).toBe("ascii");
+		const ctx = fakeCtx();
+		status.set("caveman", true, ctx as never);
+		expect(ctx.calls.at(-1)!.text).toContain("Cv");
+	});
+
+	it("setMode switches the rendered glyph set and repaints", () => {
+		const status = new OptimizerStatus("nerd");
+		const ctx = fakeCtx();
+		status.set("rtk", true, ctx as never);
+		expect(ctx.calls.at(-1)!.text).toContain(TOOL_ICONS.rtk);
+		status.setMode("ascii", ctx as never);
+		const last = ctx.calls.at(-1)!;
+		expect(last.key).toBe(STATUS_KEY);
+		expect(last.text).toContain("Rk");
+		expect(last.text).not.toContain(TOOL_ICONS.rtk);
+	});
 });

package/src/status.ts

@@ -4,12 +4,12 @@
  * caveman / rtk / toon / ponytail each toggle independently, but they're all the same
  * class of thing (token-optimization tools), so they share ONE status cell
  * instead of three. Each tool reports its on/off state into a single registry;
- * the cell renders only the icons whose tool is currently enabled, in a fixed
- * order, accent-colored. When everything is off the cell is empty.
+ * the cell renders ALL four icons in a fixed order — accent-colored when the
+ * tool is enabled, dim when disabled. The cell is never empty.
  *
- *   all on:        󰜐 󰓥 󰗀 󰆐
- *   caveman off:   󰓥 󰗀 󰆐
- *   all off:       (empty)
+ *   all on:        all four accent
+ *   caveman off:   caveman dim, rest accent
+ *   all off:       all four dim
  */
 
 import type {
@@ -42,13 +42,72 @@ export const STATUS_KEY = "pix-optimizer";
 /** Tools that participate in the shared indicator, in render order. */
 export type OptimizerTool = "caveman" | "rtk" | "toon" | "ponytail";
 
-export const TOOL_ICONS: Record<OptimizerTool, string> = {
-	caveman: "󰜐",
-	rtk: "󰓥",
-	toon: "󰗀",
-	ponytail: "󰆐",
+/**
+ * Icon presentation modes. The optimizer cell defaults to Nerd Font glyphs,
+ * which require a patched font (e.g. MesloLGS NF). Terminals without one show
+ * missing-glyph tofu, so two font-independent fallbacks are offered:
+ *   - `unicode`: outline playing-card suits (standard BMP, ships with virtually
+ *     every monospace font) + U+FE0E to force text (non-emoji) presentation.
+ *   - `ascii`: two-letter labels, renders on literally any terminal.
+ * Mode is chosen via the /optimizer menu (persisted) or the OPTIMIZER_ICONS /
+ * PRETTY_ICONS env vars.
+ */
+export type IconMode = "nerd" | "unicode" | "ascii";
+
+/** All selectable icon modes, in /optimizer cycle order. */
+export const ICON_MODES: readonly IconMode[] = ["nerd", "unicode", "ascii"];
+
+/** Force text (non-emoji) presentation for symbols that default to emoji. */
+const VS_TEXT = "\uFE0E";
+
+/** Per-mode glyph table for each tool. */
+const ICON_SETS: Record<IconMode, Record<OptimizerTool, string>> = {
+	nerd: {
+		caveman: "󰜐",
+		rtk: "󰓥",
+		toon: "󰗀",
+		ponytail: "󰆐",
+	},
+	unicode: {
+		caveman: `\u2664${VS_TEXT}`, // ♤ white spade
+		rtk: `\u2661${VS_TEXT}`, // ♡ white heart
+		toon: `\u2662${VS_TEXT}`, // ♢ white diamond
+		ponytail: `\u2667${VS_TEXT}`, // ♧ white club
+	},
+	ascii: {
+		caveman: "Cv",
+		rtk: "Rk",
+		toon: "Tn",
+		ponytail: "Pt",
+	},
 };
 
+/** Resolve the glyph table for a mode. */
+export function getIcons(mode: IconMode): Record<OptimizerTool, string> {
+	return ICON_SETS[mode] ?? ICON_SETS.nerd;
+}
+
+/**
+ * Default icon mode from the environment. OPTIMIZER_ICONS takes precedence;
+ * PRETTY_ICONS=none|off maps to ascii so one stack-wide var disables glyphs.
+ * Anything unrecognized (or unset) falls back to `nerd`. A persisted menu
+ * choice overrides this at load time (see persist.loadIconMode).
+ */
+export function envIconMode(): IconMode {
+	const raw = (process.env.OPTIMIZER_ICONS ?? "").toLowerCase();
+	if (raw === "nerd" || raw === "unicode" || raw === "ascii") return raw;
+	const pretty = (process.env.PRETTY_ICONS ?? "").toLowerCase();
+	if (pretty === "none" || pretty === "off") return "ascii";
+	return "nerd";
+}
+
+/**
+ * Default Nerd Font glyph table. Kept as a named export for back-compat with
+ * callers/tests that reference the nerd set directly; equivalent to
+ * getIcons("nerd").
+ */
+export const TOOL_ICONS: Record<OptimizerTool, string> = ICON_SETS.nerd;
+
 /** Fixed left-to-right order of icons in the cell. */
 const TOOL_ORDER: readonly OptimizerTool[] = [
 	"caveman",
@@ -69,6 +128,7 @@ export type Colorize = (color: ThemeColor, text: string) => string;
  * Build the colored status string for a set of tool states. ALL tool icons are
  * always shown, in TOOL_ORDER; each is accent-colored when its tool is enabled
  * and dim when disabled. `color` applies the theme color (e.g. theme.fg).
+ * `mode` selects the glyph table (nerd / unicode / ascii); defaults to nerd.
  *
  * Pure + exported for tests (pass a tagging colorizer to assert per-icon color).
  * A trailing space separates the cell from the next status segment.
@@ -76,9 +136,11 @@ export type Colorize = (color: ThemeColor, text: string) => string;
 export function renderStatus(
 	states: Partial<Record<OptimizerTool, boolean>>,
 	color: Colorize,
+	mode: IconMode = "nerd",
 ): string {
+	const icons = getIcons(mode);
 	return `${TOOL_ORDER.map((t) =>
-		color(states[t] === true ? ENABLED_COLOR : DISABLED_COLOR, TOOL_ICONS[t]),
+		color(states[t] === true ? ENABLED_COLOR : DISABLED_COLOR, icons[t]),
 	).join("  ")} `;
 }
 
@@ -89,12 +151,29 @@ export function renderStatus(
  */
 export class OptimizerStatus {
 	private states: Partial<Record<OptimizerTool, boolean>> = {};
+	private iconMode: IconMode;
+
+	/** `mode` seeds the icon set (persisted choice or env default). */
+	constructor(mode: IconMode = "nerd") {
+		this.iconMode = mode;
+	}
 
 	/** Current enabled state for one tool (undefined until first set). */
 	get(tool: OptimizerTool): boolean | undefined {
 		return this.states[tool];
 	}
 
+	/** Current icon presentation mode. */
+	get mode(): IconMode {
+		return this.iconMode;
+	}
+
+	/** Switch icon mode and repaint the shared cell. */
+	setMode(mode: IconMode, ctx: Pick<ExtensionContext, "ui">): void {
+		this.iconMode = mode;
+		this.paint(ctx);
+	}
+
 	/** Update one tool's enabled state and repaint the shared cell. */
 	set(
 		tool: OptimizerTool,
@@ -107,7 +186,11 @@ export class OptimizerStatus {
 
 	/** Repaint the shared cell from current states. */
 	paint(ctx: Pick<ExtensionContext, "ui">): void {
-		const text = renderStatus(this.states, (c, t) => ctx.ui.theme.fg(c, t));
+		const text = renderStatus(
+			this.states,
+			(c, t) => ctx.ui.theme.fg(c, t),
+			this.iconMode,
+		);
 		ctx.ui.setStatus(STATUS_KEY, text);
 	}
 }