feat: add PLANNOTATOR_GLIMPSE env var to disable Glimpse native window

Add glimpse config option to PlannotatorConfig and resolveUseGlimpse()
resolver. Wire into both Bun and Pi browser-opening paths. Document
PLANNOTATOR_GLIMPSE, PLANNOTATOR_GLIMPSE_WIDTH, and
PLANNOTATOR_GLIMPSE_HEIGHT in env var reference and AGENTS.md.

For provenance purposes, this commit was AI assisted.

AGENTS.md

@@ -135,6 +135,9 @@ claude --plugin-dir ./apps/hook
 | `PLANNOTATOR_JINA` | Set to `0` / `false` to disable Jina Reader for URL annotation, or `1` / `true` to enable. Default: enabled. Can also be set via `~/.plannotator/config.json` (`{ "jina": false }`) or per-invocation via `--no-jina`. |
 | `JINA_API_KEY` | Optional Jina Reader API key for higher rate limits (500 RPM vs 20 RPM unauthenticated). Free keys include 10M tokens. |
 | `PLANNOTATOR_DATA_DIR` | Override the base data directory. Supports `~` expansion. Default: `~/.plannotator`. All data (plans, history, drafts, config, hooks, sessions, debug logs, IPC registry) is stored under this directory. |
+| `PLANNOTATOR_GLIMPSE` | Set to `0` / `false` to disable the Glimpse native window even when `glimpseui` is installed. Default: enabled. Can also be set via `~/.plannotator/config.json` (`{ "glimpse": false }`). |
+| `PLANNOTATOR_GLIMPSE_WIDTH` | Width in pixels for the Glimpse native window. Default: `1280`. |
+| `PLANNOTATOR_GLIMPSE_HEIGHT` | Height in pixels for the Glimpse native window. Default: `900`. |
 | `PLANNOTATOR_VERIFY_ATTESTATION` | **Read by the install scripts only**, not by the runtime binary. Set to `1` / `true` to have `scripts/install.sh` / `install.ps1` / `install.cmd` run `gh attestation verify` on every install. Off by default. Can also be set persistently via `~/.plannotator/config.json` (`{ "verifyAttestation": true }`) or per-invocation via `--verify-attestation`. Requires `gh` installed and authenticated. |
 
 **Config-only settings (`~/.plannotator/config.json`)**: Some settings have no env-var equivalent and are toggled by editing the config file directly:

apps/marketing/src/content/docs/reference/environment-variables.md

@@ -26,6 +26,14 @@ All Plannotator environment variables and their defaults.
 
 \* If you use the VS Code extension, make sure `PLANNOTATOR_DATA_DIR` is visible to both your terminal and VS Code. On macOS, apps launched from the Dock don't inherit shell env vars — launch VS Code from the terminal (`code .`) or set the variable via `launchctl setenv`.
 
+## Glimpse (native window)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PLANNOTATOR_GLIMPSE` | enabled | Set to `0` or `false` to disable the Glimpse native window even when `glimpseui` is installed. Set to `1` or `true` to enable (this is the default). Can also be set via `~/.plannotator/config.json` (`{ "glimpse": false }`). |
+| `PLANNOTATOR_GLIMPSE_WIDTH` | `1280` | Width in pixels for the Glimpse native window. |
+| `PLANNOTATOR_GLIMPSE_HEIGHT` | `900` | Height in pixels for the Glimpse native window. |
+
 ## Annotation variables
 
 | Variable | Default | Description |

apps/pi-extension/server/network.ts

@@ -8,6 +8,7 @@ import { existsSync } from "node:fs";
 import type { Server } from "node:http";
 import { release } from "node:os";
 import { delimiter, join } from "node:path";
+import { loadConfig, resolveUseGlimpse } from "../generated/config.js";
 
 const DEFAULT_REMOTE_PORT = 19432;
 const LOOPBACK_HOST = "127.0.0.1";
@@ -220,7 +221,7 @@ export async function openBrowser(url: string): Promise<{
 		return { opened: false, isRemote: true, url };
 	}
 
-	if (!browser) {
+	if (!browser && resolveUseGlimpse(loadConfig())) {
 		const openedViaGlimpse = await openGlimpse(url);
 		if (openedViaGlimpse) {
 			return { opened: true };

packages/server/browser.ts

@@ -8,6 +8,7 @@ import os from "node:os";
 import path from "node:path";
 import fs from "node:fs";
 import { getPlannotatorDataDir } from "@plannotator/shared/data-dir";
+import { loadConfig, resolveUseGlimpse } from "@plannotator/shared/config";
 
 const IPC_REGISTRY = path.join(getPlannotatorDataDir(), "vscode-ipc.json");
 
@@ -184,7 +185,7 @@ export async function openBrowser(
       }
     }
 
-    if (options?.useGlimpse && !browser && !isRemote) {
+    if (options?.useGlimpse && !browser && !isRemote && resolveUseGlimpse(loadConfig())) {
       const openedViaGlimpse = await openGlimpse(url);
       if (openedViaGlimpse) {
         return true;

packages/shared/config.ts

@@ -127,6 +127,13 @@ export interface PlannotatorConfig {
    * Read by the `improve-context` PreToolUse handler. Default: false.
    */
   pfmReminder?: boolean;
+  /**
+   * Open Plannotator in a Glimpse native window when available.
+   * When true (default), the server spawns `glimpseui` if it is on PATH,
+   * no explicit browser is configured, and the session is local.
+   * Set to false to always use the system browser even when Glimpse is installed.
+   */
+  glimpse?: boolean;
 }
 
 const CONFIG_DIR = getPlannotatorDataDir();
@@ -215,6 +222,21 @@ export function resolveDefaultDiffType(cfg?: PlannotatorConfig): DefaultDiffType
   return v === 'uncommitted' || v === 'unstaged' || v === 'staged' || v === 'merge-base' || v === 'all' ? v : 'unstaged';
 }
 
+/**
+ * Resolve whether to use Glimpse native window.
+ *
+ * Priority (highest wins):
+ *   PLANNOTATOR_GLIMPSE env var  →  config.glimpse  →  default true
+ */
+export function resolveUseGlimpse(config: PlannotatorConfig): boolean {
+  const envVal = process.env.PLANNOTATOR_GLIMPSE;
+  if (envVal !== undefined) {
+    return envVal === "1" || envVal.toLowerCase() === "true";
+  }
+  if (config.glimpse !== undefined) return config.glimpse;
+  return true;
+}
+
 /**
  * Resolve whether to use Jina Reader for URL annotation.
  *