@raquezha/noheadroom 0.2.5 → 0.3.0

package/README.md

@@ -73,12 +73,14 @@ Settings are stored in `~/.pi/agent/headroom/settings.json`:
   "enabled": true,
   "baseUrl": "http://127.0.0.1:8788",
   "autoStart": false,
+  "mode": "normal",
   "minContextTokens": 10000,
   "minMessageChars": 2000
 }
 ```
 
 - **`autoStart`**: Set to `false` when using the Docker backend.
+- **`mode`**: `normal` (all output), `quiet` (suppress routine success), or `silent` (suppress all non-critical notices). Override with `PI_HEADROOM_MODE=quiet`.
 - **`minContextTokens`**: Compression kicks in once the context reaches this size.
 
 ## 🛡 Privacy & Security

package/dist/bridge.d.ts

@@ -8,4 +8,5 @@ export declare function buildCompressionPayload(messages: AgentMessage[], minMes
 export declare function applyCompressionResult(originalMessages: AgentMessage[], mappings: CompressionMapping[], compressedMessages: OpenAIMessage[], _options: ApplyCompressionOptions): ApplyCompressionResult;
 export declare function convertMessage(message: AnyMessage): OpenAIMessage | undefined;
 export declare function extractOpenAIText(message: OpenAIMessage): string;
+export declare function injectCompressionAwareness(messages: AgentMessage[]): AgentMessage[];
 export {};

package/dist/bridge.js

@@ -46,6 +46,8 @@ export function applyCompressionResult(originalMessages, mappings, compressedMes
         let nextText = extractOpenAIText(compressed);
         if (nextText === mapping.originalText)
             continue;
+        // Naturalize Headroom's native CCR markers to provide Pi-native tooling hints (Upstream #846)
+        nextText = naturalizeHeadroomMarkers(nextText);
         const target = nextMessages[mapping.sourceIndex];
         if (!hasContent(target) || !replaceTextContent(target, nextText)) {
             return { ok: false, reason: "target-content-unreplaceable" };
@@ -124,9 +126,8 @@ function convertToolCall(toolCall) {
         id: toolCall.id,
         type: "function",
         function: {
-            // Headroom may protect/exclude built-in agent tool names such as `read` and `bash`.
-            // This payload is only for compression alignment; Pi's original tool metadata is preserved
-            // in originalMessages and restored when applying the compressed toolResult text.
+            // Headroom protects exact tool names (read, bash) in its DEFAULT_EXCLUDE_TOOLS.
+            // Keep upstream bridge behavior until tests prove a better name changes routing/fidelity.
             name: "pi_tool_result",
             arguments: JSON.stringify({ originalToolName: toolCall.name }),
         },
@@ -220,3 +221,24 @@ function readStringProperty(value, key) {
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
+function naturalizeHeadroomMarkers(text) {
+    // Translate Headroom's "[X items compressed to Y. Retrieve more: hash=...]" 
+    // into a Pi-native instruction to use offset/limit instead of hallucinating a retrieve command.
+    return text.replace(/\[(.*?(?:compressed|omitted).*?)\.?\s*Retrieve more: hash=[a-f0-9]+\]/gi, "[$1. Hint: Do not re-read the whole file. Use the 'read' tool with 'offset' and 'limit' to inspect specific sections.]");
+}
+export function injectCompressionAwareness(messages) {
+    // If a system message already exists at the top, we append the hint to it.
+    // Otherwise, we inject a new system message at index 0.
+    const result = [...messages];
+    const hintText = "Environment Hint: Some tool results in this context have been automatically compressed by Headroom to optimize tokens. If you see '[X items compressed to Y]' or similar markers, do NOT attempt to re-read the entire file. Use the 'read' tool with 'offset' and 'limit' to query missing sections.";
+    const first = result[0];
+    if (first && first.role === "system" && typeof first.content === "string") {
+        if (!first.content.includes("automatically compressed by Headroom")) {
+            result[0] = { ...first, content: `${first.content}\n\n${hintText}` };
+        }
+    }
+    else {
+        result.unshift({ role: "system", content: hintText });
+    }
+    return result;
+}

package/dist/config.d.ts

@@ -7,12 +7,15 @@ export interface HeadroomSettings {
     url?: string;
     allowRemote?: boolean | string;
     autoStart?: boolean | string;
+    mode?: string;
+    silent?: boolean | string;
     command?: string;
     minContextTokens?: number | string;
     minMessageChars?: number | string;
     timeoutMs?: number | string;
 }
 export declare function loadHeadroomSettings(settingsPath?: string): HeadroomSettings;
+export declare function saveHeadroomSettings(patch: Partial<HeadroomSettings>, settingsPath?: string): void;
 export declare function loadHeadroomConfig(env?: NodeJS.ProcessEnv, settings?: HeadroomSettings): HeadroomConfig;
 export declare function isLocalHeadroomUrl(rawUrl: string): boolean;
 export declare function isRemoteBlocked(config: Pick<HeadroomConfig, "baseUrl" | "allowRemote">): boolean;

package/dist/config.js

@@ -19,6 +19,17 @@ export function loadHeadroomSettings(settingsPath = HEADROOM_SETTINGS_FILE) {
     }
     return {};
 }
+export function saveHeadroomSettings(patch, settingsPath = HEADROOM_SETTINGS_FILE) {
+    const current = loadHeadroomSettings(settingsPath);
+    const updated = { ...current, ...patch };
+    try {
+        fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+        fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+    }
+    catch (error) {
+        console.warn(`[noheadroom] Failed to save settings to ${settingsPath}:`, error);
+    }
+}
 export function loadHeadroomConfig(env = process.env, settings = env === process.env ? loadHeadroomSettings() : {}) {
     const envBaseUrl = env.PI_HEADROOM_URL || env.HEADROOM_URL || env.HEADROOM_BASE_URL || DEFAULT_BASE_URL;
     const baseUrl = normalizeBaseUrl(parseString(settings.baseUrl ?? settings.url, envBaseUrl));
@@ -27,6 +38,7 @@ export function loadHeadroomConfig(env = process.env, settings = env === process
         baseUrl,
         allowRemote: parseBoolean(settings.allowRemote, parseBoolean(env.PI_HEADROOM_ALLOW_REMOTE, false)),
         autoStart: parseBoolean(settings.autoStart, parseBoolean(env.PI_HEADROOM_AUTO_START, true)),
+        mode: parseMode(settings.mode, env.PI_HEADROOM_MODE, parseBoolean(settings.silent, parseBoolean(env.PI_HEADROOM_SILENT, false)) ? "silent" : "normal"),
         command: parseString(settings.command, env.PI_HEADROOM_COMMAND?.trim() || "headroom"),
         minContextTokens: parseInteger(settings.minContextTokens, parseInteger(env.PI_HEADROOM_MIN_CONTEXT_TOKENS, DEFAULT_MIN_CONTEXT_TOKENS, 0), 0),
         minMessageChars: parseInteger(settings.minMessageChars, parseInteger(env.PI_HEADROOM_MIN_MESSAGE_CHARS, DEFAULT_MIN_MESSAGE_CHARS, 1), 1),
@@ -76,3 +88,13 @@ function parseInteger(raw, fallback, min) {
         return fallback;
     return Math.trunc(parsed);
 }
+const HEADROOM_MODES = ["normal", "quiet", "silent"];
+function parseMode(raw, envRaw, fallback) {
+    const normalize = (v) => {
+        if (typeof v !== "string")
+            return null;
+        const s = v.trim().toLowerCase();
+        return HEADROOM_MODES.includes(s) ? s : null;
+    };
+    return normalize(raw) ?? normalize(envRaw) ?? fallback;
+}

package/dist/index.js

@@ -2,10 +2,11 @@ import { createHash } from "node:crypto";
 import { Box, Text } from "@earendil-works/pi-tui";
 import { applyCompressionResult, buildCompressionPayload, convertMessage, extractOpenAIText, } from "./bridge.js";
 import { HeadroomHttpClient } from "./client.js";
-import { isRemoteBlocked, loadHeadroomConfig } from "./config.js";
+import { isRemoteBlocked, loadHeadroomConfig, saveHeadroomSettings } from "./config.js";
 import { startPersistentHeadroomProxy } from "./proxy-manager.js";
 const STATUS_KEY = "headroom";
-const SUBCOMMANDS = ["status", "on", "off", "health", "stats"];
+const SUBCOMMANDS = ["status", "on", "off", "health", "stats", "mode"];
+const MODES = ["normal", "quiet", "silent"];
 const NOTRACE_TELEMETRY_CHANNEL = "notrace.telemetry.extension";
 const COMPRESSION_ENTRY_TYPE = "noheadroom.compression";
 export default function headroomExtension(pi) {
@@ -26,15 +27,30 @@ export default function headroomExtension(pi) {
     });
     pi.on("context", (event, ctx) => handleContextCompression(runtime, event, ctx));
     pi.registerCommand("headroom", {
-        description: "Headroom token compression. Usage: /headroom [on|off|status|health|stats]",
+        description: "Headroom token compression. Usage: /headroom [on|off|status|health|stats|mode <normal|quiet|silent>]",
         getArgumentCompletions(argumentPrefix) {
-            const prefix = argumentPrefix.trim().toLowerCase();
+            const parts = argumentPrefix.trim().toLowerCase().split(/\s+/);
+            if (parts[0] === "mode") {
+                const modePfx = parts[1] ?? "";
+                return MODES.filter((m) => m.startsWith(modePfx)).map((m) => ({
+                    value: `mode ${m}`,
+                    label: `mode ${m}`,
+                }));
+            }
+            const prefix = parts[0] ?? "";
             return SUBCOMMANDS.filter((command) => command.startsWith(prefix)).map((command) => ({
                 value: command,
                 label: command,
             }));
         },
-        handler: async (args, ctx) => handleCommand(runtime, parseSubcommand(args), ctx),
+        handler: async (args, ctx) => {
+            const parts = args.trim().split(/\s+/);
+            const first = (parts[0] ?? "").toLowerCase();
+            if (first === "mode") {
+                return handleModeChange(runtime, parts[1]?.toLowerCase() ?? "", ctx);
+            }
+            return handleCommand(runtime, parseSubcommand(first), ctx);
+        },
     });
     pi.registerCommand("headroom-health", {
         description: "Check Headroom proxy health",
@@ -241,7 +257,7 @@ async function handleContextCompression(runtime, event, ctx) {
             runtime.state.lastGuardSkipCandidateFingerprint = candidateFingerprint;
             recordGuardSkip(runtime.state.stats, applied.reason);
             emitNotraceTelemetry(runtime);
-            announceGuardSkip(ctx, applied.reason, result);
+            announceGuardSkip(ctx, applied.reason, result, runtime.config.mode);
             runtime.refreshStatus(ctx);
             return undefined;
         }
@@ -251,7 +267,7 @@ async function handleContextCompression(runtime, event, ctx) {
         runtime.state.lastGuardSkipCandidateFingerprint = null;
         recordAppliedCompression(runtime.state.stats, result, applied.appliedMessages);
         emitNotraceTelemetry(runtime);
-        announceAppliedCompression(runtime.pi, ctx, result, applied.appliedMessages);
+        announceAppliedCompression(runtime.pi, ctx, result, applied.appliedMessages, runtime.config.mode);
         runtime.refreshStatus(ctx);
         return { messages: applied.messages };
     }
@@ -381,7 +397,9 @@ function emitNotraceTelemetry(runtime) {
         // Telemetry should never break compression behavior.
     }
 }
-function announceAppliedCompression(pi, ctx, result, appliedMessages) {
+function announceAppliedCompression(pi, ctx, result, appliedMessages, mode = "normal") {
+    if (mode === "quiet" || mode === "silent")
+        return;
     const pct = Math.round((1 - result.compressionRatio) * 100);
     const summary = `compressed ${result.tokensBefore.toLocaleString()} → ${result.tokensAfter.toLocaleString()} tokens (-${pct}%, saved ${result.tokensSaved.toLocaleString()}, messages ${appliedMessages})`;
     const line = `noheadroom: ${summary}`;
@@ -393,7 +411,9 @@ function announceAppliedCompression(pi, ctx, result, appliedMessages) {
     if (!ctx.hasUI)
         process.stderr.write(`🗜 ${line}\n`);
 }
-function announceGuardSkip(ctx, reason, result) {
+function announceGuardSkip(ctx, reason, result, mode = "normal") {
+    if (mode === "silent")
+        return;
     const line = `noheadroom: compression skipped by guard (${reason}); Headroom reported ${result.tokensSaved.toLocaleString()} tokens saved but Pi context was left unchanged`;
     ctx.ui.notify(line, "warning");
     // In interactive Pi TUI, writing to stderr during the context hook can leave a stale "Working..." row.
@@ -462,6 +482,18 @@ async function handleCommand(runtime, command, ctx) {
     }
     ctx.ui.notify(renderStatus(runtime.config, runtime.state), "info");
 }
+async function handleModeChange(runtime, rawMode, ctx) {
+    const VALID_MODES = ["normal", "quiet", "silent"];
+    if (!VALID_MODES.includes(rawMode)) {
+        ctx.ui.notify(`Unknown mode "${rawMode}". Valid modes: ${VALID_MODES.join(", ")}\nUsage: /headroom mode <normal|quiet|silent>`, "warning");
+        return;
+    }
+    const mode = rawMode;
+    runtime.config.mode = mode;
+    saveHeadroomSettings({ mode });
+    emitNotraceTelemetry(runtime);
+    ctx.ui.notify(`Headroom output mode set to "${mode}" and saved to settings.`, "info");
+}
 function refreshStatus(ctx, config, state) {
     if (!ctx.hasUI)
         return;
@@ -515,6 +547,7 @@ function renderStatus(config, state) {
         `  Auto-start: ${config.autoStart ? `yes (${config.command})` : "no"}`,
         `  Shutdown: proxy is left running after Pi exits`,
         `  Remote:  ${isRemoteBlocked(config) ? "blocked" : config.allowRemote ? "allowed" : "local-only"}`,
+        `  Mode:    ${config.mode}`,
         `  Thresholds: context >= ${config.minContextTokens.toLocaleString()} tokens, toolResult >= ${config.minMessageChars.toLocaleString()} chars`,
         "",
         "Session stats:",

package/dist/types.d.ts

@@ -49,11 +49,13 @@ export interface CompressResult {
     ccrHashes: string[];
     compressed: boolean;
 }
+export type HeadroomMode = "normal" | "quiet" | "silent";
 export interface HeadroomConfig {
     enabled: boolean;
     baseUrl: string;
     allowRemote: boolean;
     autoStart: boolean;
+    mode: HeadroomMode;
     command: string;
     minContextTokens: number;
     minMessageChars: number;

package/extensions/bridge.ts

@@ -77,6 +77,9 @@ export function applyCompressionResult(
 		let nextText = extractOpenAIText(compressed);
 		if (nextText === mapping.originalText) continue;
 
+		// Naturalize Headroom's native CCR markers to provide Pi-native tooling hints (Upstream #846)
+		nextText = naturalizeHeadroomMarkers(nextText);
+
 		const target = nextMessages[mapping.sourceIndex] as AnyMessage;
 		if (!hasContent(target) || !replaceTextContent(target, nextText)) {
 			return { ok: false, reason: "target-content-unreplaceable" };
@@ -156,9 +159,8 @@ function convertToolCall(toolCall: ToolCall): OpenAIToolCall {
 		id: toolCall.id,
 		type: "function",
 		function: {
-			// Headroom may protect/exclude built-in agent tool names such as `read` and `bash`.
-			// This payload is only for compression alignment; Pi's original tool metadata is preserved
-			// in originalMessages and restored when applying the compressed toolResult text.
+			// Headroom protects exact tool names (read, bash) in its DEFAULT_EXCLUDE_TOOLS.
+			// Keep upstream bridge behavior until tests prove a better name changes routing/fidelity.
 			name: "pi_tool_result",
 			arguments: JSON.stringify({ originalToolName: toolCall.name }),
 		},
@@ -264,3 +266,30 @@ function readStringProperty(value: unknown, key: string): string | undefined {
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null;
 }
+
+function naturalizeHeadroomMarkers(text: string): string {
+	// Translate Headroom's "[X items compressed to Y. Retrieve more: hash=...]" 
+	// into a Pi-native instruction to use offset/limit instead of hallucinating a retrieve command.
+	return text.replace(
+		/\[(.*?(?:compressed|omitted).*?)\.?\s*Retrieve more: hash=[a-f0-9]+\]/gi,
+		"[$1. Hint: Do not re-read the whole file. Use the 'read' tool with 'offset' and 'limit' to inspect specific sections.]"
+	);
+}
+
+export function injectCompressionAwareness(messages: AgentMessage[]): AgentMessage[] {
+	// If a system message already exists at the top, we append the hint to it.
+	// Otherwise, we inject a new system message at index 0.
+	const result = [...messages];
+	const hintText = "Environment Hint: Some tool results in this context have been automatically compressed by Headroom to optimize tokens. If you see '[X items compressed to Y]' or similar markers, do NOT attempt to re-read the entire file. Use the 'read' tool with 'offset' and 'limit' to query missing sections.";
+
+	const first = result[0] as unknown as Record<string, unknown>;
+	if (first && first.role === "system" && typeof first.content === "string") {
+		if (!first.content.includes("automatically compressed by Headroom")) {
+			result[0] = { ...first, content: `${first.content}\n\n${hintText}` } as unknown as AgentMessage;
+		}
+	} else {
+		result.unshift({ role: "system", content: hintText } as unknown as AgentMessage);
+	}
+
+	return result;
+}

package/extensions/config.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { HeadroomConfig } from "./types.js";
+import type { HeadroomConfig, HeadroomMode } from "./types.js";
 
 const DEFAULT_BASE_URL = "http://127.0.0.1:8788";
 const DEFAULT_MIN_CONTEXT_TOKENS = 20_000;
@@ -17,6 +17,8 @@ export interface HeadroomSettings {
 	url?: string;
 	allowRemote?: boolean | string;
 	autoStart?: boolean | string;
+	mode?: string;
+	silent?: boolean | string;
 	command?: string;
 	minContextTokens?: number | string;
 	minMessageChars?: number | string;
@@ -34,6 +36,20 @@ export function loadHeadroomSettings(settingsPath: string = HEADROOM_SETTINGS_FI
 	return {};
 }
 
+export function saveHeadroomSettings(
+	patch: Partial<HeadroomSettings>,
+	settingsPath: string = HEADROOM_SETTINGS_FILE,
+): void {
+	const current = loadHeadroomSettings(settingsPath);
+	const updated = { ...current, ...patch };
+	try {
+		fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+		fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n", "utf-8");
+	} catch (error) {
+		console.warn(`[noheadroom] Failed to save settings to ${settingsPath}:`, error);
+	}
+}
+
 export function loadHeadroomConfig(
 	env: NodeJS.ProcessEnv = process.env,
 	settings: HeadroomSettings = env === process.env ? loadHeadroomSettings() : {},
@@ -45,6 +61,11 @@ export function loadHeadroomConfig(
 		baseUrl,
 		allowRemote: parseBoolean(settings.allowRemote, parseBoolean(env.PI_HEADROOM_ALLOW_REMOTE, false)),
 		autoStart: parseBoolean(settings.autoStart, parseBoolean(env.PI_HEADROOM_AUTO_START, true)),
+		mode: parseMode(
+			settings.mode,
+			env.PI_HEADROOM_MODE,
+			parseBoolean(settings.silent, parseBoolean(env.PI_HEADROOM_SILENT, false)) ? "silent" : "normal",
+		),
 		command: parseString(settings.command, env.PI_HEADROOM_COMMAND?.trim() || "headroom"),
 		minContextTokens: parseInteger(
 			settings.minContextTokens,
@@ -99,3 +120,14 @@ function parseInteger(raw: unknown, fallback: number, min: number): number {
 	if (!Number.isFinite(parsed) || parsed < min) return fallback;
 	return Math.trunc(parsed);
 }
+
+const HEADROOM_MODES: HeadroomMode[] = ["normal", "quiet", "silent"];
+
+function parseMode(raw: unknown, envRaw: string | undefined, fallback: HeadroomMode): HeadroomMode {
+	const normalize = (v: unknown): HeadroomMode | null => {
+		if (typeof v !== "string") return null;
+		const s = v.trim().toLowerCase() as HeadroomMode;
+		return HEADROOM_MODES.includes(s) ? s : null;
+	};
+	return normalize(raw) ?? normalize(envRaw) ?? fallback;
+}

package/extensions/index.ts

@@ -8,12 +8,13 @@ import {
 	extractOpenAIText,
 } from "./bridge.js";
 import { HeadroomHttpClient } from "./client.js";
-import { isRemoteBlocked, loadHeadroomConfig } from "./config.js";
+import { isRemoteBlocked, loadHeadroomConfig, saveHeadroomSettings } from "./config.js";
 import { startPersistentHeadroomProxy } from "./proxy-manager.js";
-import type { AgentMessage, CompressResult, CompressionPayload, HeadroomConfig, HeadroomStats } from "./types.js";
+import type { AgentMessage, CompressResult, CompressionPayload, HeadroomConfig, HeadroomMode, HeadroomStats } from "./types.js";
 
 const STATUS_KEY = "headroom";
-const SUBCOMMANDS = ["status", "on", "off", "health", "stats"] as const;
+const SUBCOMMANDS = ["status", "on", "off", "health", "stats", "mode"] as const;
+const MODES = ["normal", "quiet", "silent"] as const;
 const NOTRACE_TELEMETRY_CHANNEL = "notrace.telemetry.extension";
 
 type Subcommand = (typeof SUBCOMMANDS)[number];
@@ -78,15 +79,30 @@ export default function headroomExtension(pi: ExtensionAPI) {
 	pi.on("context", (event, ctx) => handleContextCompression(runtime, event, ctx));
 
 	pi.registerCommand("headroom", {
-		description: "Headroom token compression. Usage: /headroom [on|off|status|health|stats]",
+		description: "Headroom token compression. Usage: /headroom [on|off|status|health|stats|mode <normal|quiet|silent>]",
 		getArgumentCompletions(argumentPrefix) {
-			const prefix = argumentPrefix.trim().toLowerCase();
+			const parts = argumentPrefix.trim().toLowerCase().split(/\s+/);
+			if (parts[0] === "mode") {
+				const modePfx = parts[1] ?? "";
+				return MODES.filter((m) => m.startsWith(modePfx)).map((m) => ({
+					value: `mode ${m}`,
+					label: `mode ${m}`,
+				}));
+			}
+			const prefix = parts[0] ?? "";
 			return SUBCOMMANDS.filter((command) => command.startsWith(prefix)).map((command) => ({
 				value: command,
 				label: command,
 			}));
 		},
-		handler: async (args, ctx) => handleCommand(runtime, parseSubcommand(args), ctx),
+		handler: async (args, ctx) => {
+			const parts = args.trim().split(/\s+/);
+			const first = (parts[0] ?? "").toLowerCase();
+			if (first === "mode") {
+				return handleModeChange(runtime, parts[1]?.toLowerCase() ?? "", ctx);
+			}
+			return handleCommand(runtime, parseSubcommand(first), ctx);
+		},
 	});
 
 	pi.registerCommand("headroom-health", {
@@ -308,7 +324,7 @@ async function handleContextCompression(
 
 			recordGuardSkip(runtime.state.stats, applied.reason);
 			emitNotraceTelemetry(runtime);
-			announceGuardSkip(ctx, applied.reason, result);
+			announceGuardSkip(ctx, applied.reason, result, runtime.config.mode);
 			runtime.refreshStatus(ctx);
 			return undefined;
 		}
@@ -320,7 +336,7 @@ async function handleContextCompression(
 
 		recordAppliedCompression(runtime.state.stats, result, applied.appliedMessages);
 		emitNotraceTelemetry(runtime);
-		announceAppliedCompression(runtime.pi, ctx, result, applied.appliedMessages);
+		announceAppliedCompression(runtime.pi, ctx, result, applied.appliedMessages, runtime.config.mode);
 		runtime.refreshStatus(ctx);
 		return { messages: applied.messages };
 	} catch (error) {
@@ -458,7 +474,9 @@ function announceAppliedCompression(
 	ctx: ExtensionContext,
 	result: CompressResult,
 	appliedMessages: number,
+	mode: HeadroomMode = "normal",
 ): void {
+	if (mode === "quiet" || mode === "silent") return;
 	const pct = Math.round((1 - result.compressionRatio) * 100);
 	const summary = `compressed ${result.tokensBefore.toLocaleString()} → ${result.tokensAfter.toLocaleString()} tokens (-${pct}%, saved ${result.tokensSaved.toLocaleString()}, messages ${appliedMessages})`;
 	const line = `noheadroom: ${summary}`;
@@ -470,7 +488,8 @@ function announceAppliedCompression(
 	if (!ctx.hasUI) process.stderr.write(`🗜 ${line}\n`);
 }
 
-function announceGuardSkip(ctx: ExtensionContext, reason: string, result: CompressResult): void {
+function announceGuardSkip(ctx: ExtensionContext, reason: string, result: CompressResult, mode: HeadroomMode = "normal"): void {
+	if (mode === "silent") return;
 	const line = `noheadroom: compression skipped by guard (${reason}); Headroom reported ${result.tokensSaved.toLocaleString()} tokens saved but Pi context was left unchanged`;
 	ctx.ui.notify(line, "warning");
 	// In interactive Pi TUI, writing to stderr during the context hook can leave a stale "Working..." row.
@@ -553,6 +572,22 @@ async function handleCommand(runtime: HeadroomRuntime, command: Subcommand, ctx:
 	ctx.ui.notify(renderStatus(runtime.config, runtime.state), "info");
 }
 
+async function handleModeChange(runtime: HeadroomRuntime, rawMode: string, ctx: ExtensionContext): Promise<void> {
+	const VALID_MODES: HeadroomMode[] = ["normal", "quiet", "silent"];
+	if (!VALID_MODES.includes(rawMode as HeadroomMode)) {
+		ctx.ui.notify(
+			`Unknown mode "${rawMode}". Valid modes: ${VALID_MODES.join(", ")}\nUsage: /headroom mode <normal|quiet|silent>`,
+			"warning",
+		);
+		return;
+	}
+	const mode = rawMode as HeadroomMode;
+	runtime.config.mode = mode;
+	saveHeadroomSettings({ mode });
+	emitNotraceTelemetry(runtime);
+	ctx.ui.notify(`Headroom output mode set to "${mode}" and saved to settings.`, "info");
+}
+
 function refreshStatus(ctx: ExtensionContext, config: HeadroomConfig, state: HeadroomRuntimeState): void {
 	if (!ctx.hasUI) return;
 	ctx.ui.setStatus(STATUS_KEY, renderFooterStatus(ctx, config, state));
@@ -618,6 +653,7 @@ function renderStatus(config: HeadroomConfig, state: HeadroomRuntimeState): stri
 		`  Auto-start: ${config.autoStart ? `yes (${config.command})` : "no"}`,
 		`  Shutdown: proxy is left running after Pi exits`,
 		`  Remote:  ${isRemoteBlocked(config) ? "blocked" : config.allowRemote ? "allowed" : "local-only"}`,
+		`  Mode:    ${config.mode}`,
 		`  Thresholds: context >= ${config.minContextTokens.toLocaleString()} tokens, toolResult >= ${config.minMessageChars.toLocaleString()} chars`,
 		"",
 		"Session stats:",

package/extensions/types.ts

@@ -58,11 +58,14 @@ export interface CompressResult {
 	compressed: boolean;
 }
 
+export type HeadroomMode = "normal" | "quiet" | "silent";
+
 export interface HeadroomConfig {
 	enabled: boolean;
 	baseUrl: string;
 	allowRemote: boolean;
 	autoStart: boolean;
+	mode: HeadroomMode;
 	command: string;
 	minContextTokens: number;
 	minMessageChars: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raquezha/noheadroom",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "Personal Headroom compression bridge for Pi with Docker-first defaults and Pi tool-name adaptation",
   "main": "dist/index.js",
   "type": "module",