From c199e1af86c5e920a7ef8d3aac34a5dca49532f6 Mon Sep 17 00:00:00 2001 From: gustav-fff <286169375+gustav-fff@users.noreply.github.com> Date: Fri, 21 Aug 2026 08:04:30 -0700 Subject: [PATCH 1/3] fix(pi-fff): allow muting the $HOME scan warning (#806) Indexing $HOME is a legitimate setup, but the warning fired on every session_start with no way to silence it short of disabling home scanning. Adds warnOnHomeDirScan (--fff-warn-home-scan / FFF_WARN_HOME_SCAN), default true, resolved through the existing flag > env > file > fallback order. The live indexing status footer is unaffected. Closes #806 --- packages/pi-fff/README.md | 5 +++- packages/pi-fff/pi-fff.schema.json | 5 ++++ packages/pi-fff/src/config.ts | 5 +++- packages/pi-fff/src/index.ts | 20 ++++++++++++++- packages/pi-fff/test/config.test.ts | 2 ++ packages/pi-fff/test/extension.test.ts | 35 ++++++++++++++++++++++++++ 6 files changed, 69 insertions(+), 3 deletions(-) diff --git a/packages/pi-fff/README.md b/packages/pi-fff/README.md index 92b672278..13aebf3c6 100644 --- a/packages/pi-fff/README.md +++ b/packages/pi-fff/README.md @@ -143,7 +143,8 @@ For persistent global configuration, create `pi-fff.json` in pi's agent director "frecencyDbPath": "/path/to/frecency", "historyDbPath": "/path/to/history", "enableFsRootScanning": false, - "enableHomeDirScanning": true + "enableHomeDirScanning": true, + "warnOnHomeDirScan": true } ``` @@ -157,6 +158,7 @@ All fields are optional: | `historyDbPath` | non-empty string | See [Data](#data) | | `enableFsRootScanning` | boolean | `false` | | `enableHomeDirScanning` | boolean | `true` | +| `warnOnHomeDirScan` | boolean | `true` | CLI flags take precedence over environment variables, which take precedence over this file. A missing file is ignored. Malformed JSON, unknown fields, and invalid values stop the extension from loading and report the file path and error. `/fff-mode` changes the current session; it does not edit this file. @@ -169,6 +171,7 @@ The file is global only. Project-level config cannot safely control tool names b - `--fff-history-db ` — path to query history database (also: `FFF_HISTORY_DB` env). Optional; see [Data](#data) for the default. - `--fff-enable-root-scan` — allow indexing when launched from `/` (also: `FFF_ENABLE_ROOT_SCAN=1` env). FFF refuses to init at the filesystem root by default. - `--fff-enable-home-scan` — index the home directory when launched from `$HOME` (also: `FFF_ENABLE_HOME_SCAN` env). Enabled by default. Disable with `--fff-enable-home-scan=false` or `FFF_ENABLE_HOME_SCAN=0` if your `$HOME` contains huge trees (toolchains, kernel sources, build outputs) that make the background index run for a long time. When launched from `$HOME` with this enabled, pi shows a warning that the whole home tree is being indexed. +- `--fff-warn-home-scan` — show the warning notification when `$HOME` is indexed (also: `FFF_WARN_HOME_SCAN` env). Enabled by default. Set `--fff-warn-home-scan=false` or `FFF_WARN_HOME_SCAN=0` if indexing `$HOME` is intentional and the notification is just noise. The live indexing status in the footer is unaffected. ## Data diff --git a/packages/pi-fff/pi-fff.schema.json b/packages/pi-fff/pi-fff.schema.json index 8a619ca03..56f1d25bf 100644 --- a/packages/pi-fff/pi-fff.schema.json +++ b/packages/pi-fff/pi-fff.schema.json @@ -36,6 +36,11 @@ "type": "boolean", "default": true, "description": "Allows indexing when pi is launched from the home directory." + }, + "warnOnHomeDirScan": { + "type": "boolean", + "default": true, + "description": "Shows a warning notification when the home directory is indexed." } } } diff --git a/packages/pi-fff/src/config.ts b/packages/pi-fff/src/config.ts index a463f97d5..f95d34f70 100644 --- a/packages/pi-fff/src/config.ts +++ b/packages/pi-fff/src/config.ts @@ -14,6 +14,7 @@ export interface FffConfig { historyDbPath?: string; enableFsRootScanning?: boolean; enableHomeDirScanning?: boolean; + warnOnHomeDirScan?: boolean; } const CONFIG_KEYS = new Set([ @@ -23,6 +24,7 @@ const CONFIG_KEYS = new Set([ "historyDbPath", "enableFsRootScanning", "enableHomeDirScanning", + "warnOnHomeDirScan", ]); export function loadConfig(agentDir = piDataDir()): FffConfig { @@ -64,6 +66,7 @@ export function loadConfig(agentDir = piDataDir()): FffConfig { validateString(configPath, parsed, "historyDbPath"); validateBoolean(configPath, parsed, "enableFsRootScanning"); validateBoolean(configPath, parsed, "enableHomeDirScanning"); + validateBoolean(configPath, parsed, "warnOnHomeDirScan"); return parsed as FffConfig; } @@ -94,7 +97,7 @@ function validateString( function validateBoolean( configPath: string, config: Record, - key: "enableFsRootScanning" | "enableHomeDirScanning", + key: "enableFsRootScanning" | "enableHomeDirScanning" | "warnOnHomeDirScan", ): void { const value = config[key]; if (value !== undefined && typeof value !== "boolean") { diff --git a/packages/pi-fff/src/index.ts b/packages/pi-fff/src/index.ts index 66578b564..c486924f5 100644 --- a/packages/pi-fff/src/index.ts +++ b/packages/pi-fff/src/index.ts @@ -50,7 +50,8 @@ const GREP_TIME_BUDGET_MS = 10_000; const HOME_SCAN_STATUS_KEY = "fff"; const HOME_SCAN_POLL_MS = 1_000; const HOME_SCAN_DISABLE_HINT = - "You can prevent home dir indexing with --fff-enable-home-scan=false, FFF_ENABLE_HOME_SCAN=0, or enableHomeDirScanning in pi-fff.json."; + "You can prevent home dir indexing with --fff-enable-home-scan=false, FFF_ENABLE_HOME_SCAN=0, or enableHomeDirScanning in pi-fff.json. " + + "To keep indexing but silence this warning use --fff-warn-home-scan=false, FFF_WARN_HOME_SCAN=0, or warnOnHomeDirScan in pi-fff.json."; interface ToolNames { grep: string; @@ -343,6 +344,7 @@ export default function fffExtension(pi: ExtensionAPI) { let resolvedDbPaths: ReturnType; let enableFsRootScanning = false; let enableHomeDirScanning = true; + let warnOnHomeDirScan = true; function setMode(mode: FffMode): void { currentMode = mode; @@ -385,6 +387,15 @@ export default function fffExtension(pi: ExtensionAPI) { true, parseBoolean, ); + // Users who intentionally index $HOME see the warning on every launch and + // can do nothing about it, so let them mute it (issue #806). + warnOnHomeDirScan = getConfigValue( + "fff-warn-home-scan", + "FFF_WARN_HOME_SCAN", + config.warnOnHomeDirScan, + true, + parseBoolean, + ); } function getMode(): FffMode { @@ -406,6 +417,7 @@ export default function fffExtension(pi: ExtensionAPI) { let homeScanTimer: ReturnType | null = null; function warnHomeDirScan(root: string): void { + if (!warnOnHomeDirScan) return; uiCtx?.ui.notify( `(fff): Your cwd (${root}) is too large. Indexing will take additional time and resources.\n${HOME_SCAN_DISABLE_HINT}`, "warning", @@ -667,6 +679,12 @@ export default function fffExtension(pi: ExtensionAPI) { type: "boolean", }); + pi.registerFlag("fff-warn-home-scan", { + description: + "Warn when indexing $HOME (default true; silence with --fff-warn-home-scan=false or FFF_WARN_HOME_SCAN=0)", + type: "boolean", + }); + function reportInitFailure(ctx: ExtensionContext, error: unknown): void { ctx.ui.notify( `FFF init failed: ${error instanceof Error ? error.message : String(error)}`, diff --git a/packages/pi-fff/test/config.test.ts b/packages/pi-fff/test/config.test.ts index 053aba1df..85ade4f84 100644 --- a/packages/pi-fff/test/config.test.ts +++ b/packages/pi-fff/test/config.test.ts @@ -31,6 +31,7 @@ describe("loadConfig", () => { historyDbPath: "/data/history", enableFsRootScanning: true, enableHomeDirScanning: false, + warnOnHomeDirScan: false, }; writeConfig(config); @@ -66,6 +67,7 @@ describe("loadConfig", () => { [{ historyDbPath: false }, '"historyDbPath" must be a non-empty string'], [{ enableFsRootScanning: 1 }, '"enableFsRootScanning" must be a boolean'], [{ enableHomeDirScanning: "false" }, '"enableHomeDirScanning" must be a boolean'], + [{ warnOnHomeDirScan: "false" }, '"warnOnHomeDirScan" must be a boolean'], ]; for (const [config, message] of cases) { diff --git a/packages/pi-fff/test/extension.test.ts b/packages/pi-fff/test/extension.test.ts index 4021c3c9d..f6fc6f928 100644 --- a/packages/pi-fff/test/extension.test.ts +++ b/packages/pi-fff/test/extension.test.ts @@ -190,6 +190,7 @@ const CONFIG_ENV_KEYS = [ "FFF_HISTORY_DB", "FFF_ENABLE_ROOT_SCAN", "FFF_ENABLE_HOME_SCAN", + "FFF_WARN_HOME_SCAN", ] as const; const savedEnv: Record = {}; @@ -425,6 +426,40 @@ describe("pi-fff $HOME scan warning", () => { expect(setup.ctx.ui.setStatus).not.toHaveBeenCalled(); await shutdown(setup); }); + + // #806: indexing $HOME can be intentional, so the warning must be mutable + // without turning the scan off. The progress footer stays. + test("FFF_WARN_HOME_SCAN=0 mutes the warning but keeps indexing", async () => { + process.env.FFF_WARN_HOME_SCAN = "0"; + const setup = await start(undefined, os.homedir()); + + expect(setup.ctx.ui.notify).not.toHaveBeenCalled(); + expect(setup.ctx.ui.setStatus).toHaveBeenCalledWith( + "fff", + "Agent is indexing $HOME, this can lead to high CPU", + ); + expect( + (createCalls[0] as { enableHomeDirScanning: boolean }).enableHomeDirScanning, + ).toBe(true); + await shutdown(setup); + }); + + test("--fff-warn-home-scan=false mutes the warning", async () => { + const setup = await start(undefined, os.homedir(), { + "fff-warn-home-scan": false, + }); + + expect(setup.ctx.ui.notify).not.toHaveBeenCalled(); + await shutdown(setup); + }); + + test("warnOnHomeDirScan in the config file mutes the warning", async () => { + writeConfig({ warnOnHomeDirScan: false }); + const setup = await start(undefined, os.homedir()); + + expect(setup.ctx.ui.notify).not.toHaveBeenCalled(); + await shutdown(setup); + }); }); describe("pi-fff autocomplete registration", () => { From 1693cd74147bc8d1df0cb79cb8c84850ff21c7c9 Mon Sep 17 00:00:00 2001 From: gustav-fff <286169375+gustav-fff@users.noreply.github.com> Date: Fri, 21 Aug 2026 09:35:10 -0700 Subject: [PATCH 2/3] docs(pi-fff): spell out the JSON values in the home scan hint --- packages/pi-fff/README.md | 2 +- packages/pi-fff/src/index.ts | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/pi-fff/README.md b/packages/pi-fff/README.md index 13aebf3c6..45cadf11a 100644 --- a/packages/pi-fff/README.md +++ b/packages/pi-fff/README.md @@ -171,7 +171,7 @@ The file is global only. Project-level config cannot safely control tool names b - `--fff-history-db ` — path to query history database (also: `FFF_HISTORY_DB` env). Optional; see [Data](#data) for the default. - `--fff-enable-root-scan` — allow indexing when launched from `/` (also: `FFF_ENABLE_ROOT_SCAN=1` env). FFF refuses to init at the filesystem root by default. - `--fff-enable-home-scan` — index the home directory when launched from `$HOME` (also: `FFF_ENABLE_HOME_SCAN` env). Enabled by default. Disable with `--fff-enable-home-scan=false` or `FFF_ENABLE_HOME_SCAN=0` if your `$HOME` contains huge trees (toolchains, kernel sources, build outputs) that make the background index run for a long time. When launched from `$HOME` with this enabled, pi shows a warning that the whole home tree is being indexed. -- `--fff-warn-home-scan` — show the warning notification when `$HOME` is indexed (also: `FFF_WARN_HOME_SCAN` env). Enabled by default. Set `--fff-warn-home-scan=false` or `FFF_WARN_HOME_SCAN=0` if indexing `$HOME` is intentional and the notification is just noise. The live indexing status in the footer is unaffected. +- `--fff-warn-home-scan` — show the warning notification when `$HOME` is indexed (also: `FFF_WARN_HOME_SCAN` env). Enabled by default. Set `--fff-warn-home-scan=false`, `FFF_WARN_HOME_SCAN=0`, or `"warnOnHomeDirScan": false` in `pi-fff.json` if indexing `$HOME` is intentional and the notification is just noise. The live indexing status in the footer is unaffected. ## Data diff --git a/packages/pi-fff/src/index.ts b/packages/pi-fff/src/index.ts index c486924f5..b80b6fc2e 100644 --- a/packages/pi-fff/src/index.ts +++ b/packages/pi-fff/src/index.ts @@ -50,8 +50,8 @@ const GREP_TIME_BUDGET_MS = 10_000; const HOME_SCAN_STATUS_KEY = "fff"; const HOME_SCAN_POLL_MS = 1_000; const HOME_SCAN_DISABLE_HINT = - "You can prevent home dir indexing with --fff-enable-home-scan=false, FFF_ENABLE_HOME_SCAN=0, or enableHomeDirScanning in pi-fff.json. " + - "To keep indexing but silence this warning use --fff-warn-home-scan=false, FFF_WARN_HOME_SCAN=0, or warnOnHomeDirScan in pi-fff.json."; + 'You can prevent home dir indexing with --fff-enable-home-scan=false, FFF_ENABLE_HOME_SCAN=0, or "enableHomeDirScanning": false in pi-fff.json. ' + + 'To keep indexing but silence this warning use --fff-warn-home-scan=false, FFF_WARN_HOME_SCAN=0, or "warnOnHomeDirScan": false in pi-fff.json.'; interface ToolNames { grep: string; From 261fc3519ea7c5a9d691840a274c6798b62b67db Mon Sep 17 00:00:00 2001 From: gustav-fff <286169375+gustav-fff@users.noreply.github.com> Date: Sun, 23 Aug 2026 06:56:54 -0700 Subject: [PATCH 3/3] chore(pi-fff): trim the home scan warning comments Drop the comment restating the flag names in resolveStartupConfig, cut the test comment to one line, and shorten the README bullet. --- packages/pi-fff/README.md | 2 +- packages/pi-fff/src/index.ts | 2 -- packages/pi-fff/test/extension.test.ts | 3 +-- 3 files changed, 2 insertions(+), 5 deletions(-) diff --git a/packages/pi-fff/README.md b/packages/pi-fff/README.md index 45cadf11a..7951206db 100644 --- a/packages/pi-fff/README.md +++ b/packages/pi-fff/README.md @@ -171,7 +171,7 @@ The file is global only. Project-level config cannot safely control tool names b - `--fff-history-db ` — path to query history database (also: `FFF_HISTORY_DB` env). Optional; see [Data](#data) for the default. - `--fff-enable-root-scan` — allow indexing when launched from `/` (also: `FFF_ENABLE_ROOT_SCAN=1` env). FFF refuses to init at the filesystem root by default. - `--fff-enable-home-scan` — index the home directory when launched from `$HOME` (also: `FFF_ENABLE_HOME_SCAN` env). Enabled by default. Disable with `--fff-enable-home-scan=false` or `FFF_ENABLE_HOME_SCAN=0` if your `$HOME` contains huge trees (toolchains, kernel sources, build outputs) that make the background index run for a long time. When launched from `$HOME` with this enabled, pi shows a warning that the whole home tree is being indexed. -- `--fff-warn-home-scan` — show the warning notification when `$HOME` is indexed (also: `FFF_WARN_HOME_SCAN` env). Enabled by default. Set `--fff-warn-home-scan=false`, `FFF_WARN_HOME_SCAN=0`, or `"warnOnHomeDirScan": false` in `pi-fff.json` if indexing `$HOME` is intentional and the notification is just noise. The live indexing status in the footer is unaffected. +- `--fff-warn-home-scan` — show the warning notification when `$HOME` is indexed (also: `FFF_WARN_HOME_SCAN` env). Enabled by default. Disable with `--fff-warn-home-scan=false`, `FFF_WARN_HOME_SCAN=0`, or `"warnOnHomeDirScan": false` in `pi-fff.json`. Indexing and the footer status are unaffected. ## Data diff --git a/packages/pi-fff/src/index.ts b/packages/pi-fff/src/index.ts index b80b6fc2e..5a7e64cca 100644 --- a/packages/pi-fff/src/index.ts +++ b/packages/pi-fff/src/index.ts @@ -387,8 +387,6 @@ export default function fffExtension(pi: ExtensionAPI) { true, parseBoolean, ); - // Users who intentionally index $HOME see the warning on every launch and - // can do nothing about it, so let them mute it (issue #806). warnOnHomeDirScan = getConfigValue( "fff-warn-home-scan", "FFF_WARN_HOME_SCAN", diff --git a/packages/pi-fff/test/extension.test.ts b/packages/pi-fff/test/extension.test.ts index f6fc6f928..c6820f207 100644 --- a/packages/pi-fff/test/extension.test.ts +++ b/packages/pi-fff/test/extension.test.ts @@ -427,8 +427,7 @@ describe("pi-fff $HOME scan warning", () => { await shutdown(setup); }); - // #806: indexing $HOME can be intentional, so the warning must be mutable - // without turning the scan off. The progress footer stays. + // #806: muting the warning must not turn the scan or the footer off. test("FFF_WARN_HOME_SCAN=0 mutes the warning but keeps indexing", async () => { process.env.FFF_WARN_HOME_SCAN = "0"; const setup = await start(undefined, os.homedir());