fix: prevent plugin from hanging when opened in home directory

Add requireProjectMarker config option (default: true) that checks for
project markers (.git, package.json, Cargo.toml, etc.) before enabling
file watching and auto-indexing. This prevents the plugin from trying
to watch/index large non-project directories like the home directory.

- Add hasProjectMarker() utility to detect project directories
- Guard file watcher and auto-indexing with project marker check
- Log warning when skipping due to missing project marker
- Add tests for hasProjectMarker function
- Update README, AGENTS.md, and TROUBLESHOOTING.md with new option

Author: Helweg

AGENTS.md

@@ -219,6 +219,7 @@ Key options:
 - `embeddingProvider`: `auto` | `github-copilot` | `openai` | `google` | `ollama`
 - `indexing.watchFiles`: Auto-reindex on file changes
 - `indexing.semanticOnly`: Skip generic blocks, only index functions/classes
+- `indexing.requireProjectMarker`: Require `.git`/`package.json` etc. to enable watching (prevents hanging in home dir)
 - `search.hybridWeight`: 0.0 (semantic) to 1.0 (keyword)
 - `debug.enabled`: Enable debug logging and metrics collection
 - `debug.metrics`: Enable performance metrics (use with `index_metrics` tool)

README.md

@@ -246,7 +246,8 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
     "semanticOnly": false,
     "autoGc": true,
     "gcIntervalDays": 7,
-    "gcOrphanThreshold": 100
+    "gcOrphanThreshold": 100,
+    "requireProjectMarker": true
   },
   "search": {
     "maxResults": 20,
@@ -279,6 +280,7 @@ Zero-config by default (uses `auto` mode). Customize in `.opencode/codebase-inde
 | `autoGc` | `true` | Automatically run garbage collection to remove orphaned embeddings/chunks |
 | `gcIntervalDays` | `7` | Run GC on initialization if last GC was more than N days ago |
 | `gcOrphanThreshold` | `100` | Run GC after indexing if orphan count exceeds this threshold |
+| `requireProjectMarker` | `true` | Require a project marker (`.git`, `package.json`, etc.) to enable file watching and auto-indexing. Prevents accidentally indexing large directories like home. Set to `false` to index any directory. |
 | **search** | | |
 | `maxResults` | `20` | Maximum results to return |
 | `minScore` | `0.1` | Minimum similarity score (0-1). Lower = more results |

TROUBLESHOOTING.md

@@ -4,6 +4,7 @@ Common issues and solutions for opencode-codebase-index.
 
 ## Table of Contents
 
+- [OpenCode Hangs in Home Directory](#opencode-hangs-in-home-directory)
 - [No Embedding Provider Available](#no-embedding-provider-available)
 - [Rate Limiting Errors](#rate-limiting-errors)
 - [Index Corruption / Stale Results](#index-corruption--stale-results)
@@ -14,6 +15,54 @@ Common issues and solutions for opencode-codebase-index.
 
 ---
 
+## OpenCode Hangs in Home Directory
+
+**Symptoms:**
+- OpenCode becomes unresponsive when opened in home directory (`~`)
+- New session starts but nothing happens when typing
+- High CPU or memory usage
+
+**Cause:** The plugin's file watcher attempts to watch the entire home directory, which contains hundreds of thousands of files.
+
+**Solutions:**
+
+### Default Behavior (v0.4.1+)
+The plugin now requires a project marker (`.git`, `package.json`, `Cargo.toml`, etc.) by default. If no marker is found, file watching and auto-indexing are disabled. You'll see this warning:
+```
+[codebase-index] Skipping file watching and auto-indexing: no project marker found
+```
+
+### If You Need to Index a Non-Project Directory
+Set `requireProjectMarker` to `false` in your config:
+```json
+{
+  "indexing": {
+    "requireProjectMarker": false
+  }
+}
+```
+
+**Warning:** Only do this for specific directories you intend to index. Never disable this for your home directory.
+
+### Recognized Project Markers
+The plugin looks for any of these files/directories:
+- `.git`
+- `package.json`
+- `Cargo.toml`
+- `go.mod`
+- `pyproject.toml`
+- `setup.py`
+- `requirements.txt`
+- `Gemfile`
+- `composer.json`
+- `pom.xml`
+- `build.gradle`
+- `CMakeLists.txt`
+- `Makefile`
+- `.opencode`
+
+---
+
 ## No Embedding Provider Available
 
 **Error message:**
@@ -342,6 +391,7 @@ If none of these solutions work:
 
 | Problem | Quick Fix |
 |---------|-----------|
+| Hangs in home dir | Update to v0.4.1+ (auto-detects non-project dirs) |
 | No provider | `export OPENAI_API_KEY=...` or use Ollama |
 | Rate limited | Switch to Ollama for large codebases |
 | Stale results | `rm -rf .opencode/index/` and re-index |

src/config/schema.ts

@@ -15,6 +15,13 @@ export interface IndexingConfig {
   autoGc: boolean;
   gcIntervalDays: number;
   gcOrphanThreshold: number;
+  /** 
+   * When true (default), requires a project marker (.git, package.json, Cargo.toml, etc.) 
+   * to be present before enabling file watching and auto-indexing.
+   * This prevents accidentally watching/indexing large non-project directories like home.
+   * Set to false to allow indexing any directory.
+   */
+  requireProjectMarker: boolean;
 }
 
 export interface SearchConfig {
@@ -96,6 +103,7 @@ function getDefaultIndexingConfig(): IndexingConfig {
     autoGc: true,
     gcIntervalDays: 7,
     gcOrphanThreshold: 100,
+    requireProjectMarker: true,
   };
 }
 
@@ -161,6 +169,7 @@ export function parseConfig(raw: unknown): ParsedCodebaseIndexConfig {
     autoGc: typeof rawIndexing.autoGc === "boolean" ? rawIndexing.autoGc : defaultIndexing.autoGc,
     gcIntervalDays: typeof rawIndexing.gcIntervalDays === "number" ? Math.max(1, rawIndexing.gcIntervalDays) : defaultIndexing.gcIntervalDays,
     gcOrphanThreshold: typeof rawIndexing.gcOrphanThreshold === "number" ? Math.max(0, rawIndexing.gcOrphanThreshold) : defaultIndexing.gcOrphanThreshold,
+    requireProjectMarker: typeof rawIndexing.requireProjectMarker === "boolean" ? rawIndexing.requireProjectMarker : defaultIndexing.requireProjectMarker,
   };
 
   const rawSearch = (input.search && typeof input.search === "object" ? input.search : {}) as Record<string, unknown>;

src/index.ts

@@ -19,6 +19,7 @@ import {
   initializeTools,
 } from "./tools/index.js";
 import { loadCommandsFromDirectory } from "./commands/loader.js";
+import { hasProjectMarker } from "./utils/files.js";
 
 function getCommandsDir(): string {
   let currentDir = process.cwd();
@@ -64,13 +65,22 @@ const plugin: Plugin = async ({ directory }) => {
 
   const indexer = new Indexer(projectRoot, config);
 
-  if (config.indexing.autoIndex) {
+  const isValidProject = !config.indexing.requireProjectMarker || hasProjectMarker(projectRoot);
+
+  if (!isValidProject) {
+    console.warn(
+      `[codebase-index] Skipping file watching and auto-indexing: no project marker found in "${projectRoot}". ` +
+      `Set "indexing.requireProjectMarker": false in config to override.`
+    );
+  }
+
+  if (config.indexing.autoIndex && isValidProject) {
     indexer.initialize().then(() => {
       indexer.index().catch(() => {});
     }).catch(() => {});
   }
 
-  if (config.indexing.watchFiles) {
+  if (config.indexing.watchFiles && isValidProject) {
     createWatcherWithIndexer(indexer, projectRoot, config);
   }
 

src/utils/files.ts

@@ -2,6 +2,32 @@ import ignore, { Ignore } from "ignore";
 import { existsSync, readFileSync, promises as fsPromises } from "fs";
 import * as path from "path";
 
+const PROJECT_MARKERS = [
+  ".git",
+  "package.json",
+  "Cargo.toml",
+  "go.mod",
+  "pyproject.toml",
+  "setup.py",
+  "requirements.txt",
+  "Gemfile",
+  "composer.json",
+  "pom.xml",
+  "build.gradle",
+  "CMakeLists.txt",
+  "Makefile",
+  ".opencode",
+];
+
+export function hasProjectMarker(projectRoot: string): boolean {
+  for (const marker of PROJECT_MARKERS) {
+    if (existsSync(path.join(projectRoot, marker))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 export interface SkippedFile {
   path: string;
   reason: "too_large" | "excluded" | "gitignore" | "no_match";

tests/files.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
-import { collectFiles, createIgnoreFilter, shouldIncludeFile } from "../src/utils/files.js";
+import { collectFiles, createIgnoreFilter, shouldIncludeFile, hasProjectMarker } from "../src/utils/files.js";
 
 describe("files utilities", () => {
   let tempDir: string;
@@ -166,4 +166,46 @@ describe("files utilities", () => {
       expect(result.files.some((f) => f.path.endsWith("nested.js"))).toBe(true);
     });
   });
+
+  describe("hasProjectMarker", () => {
+    it("should return true when .git exists", () => {
+      fs.mkdirSync(path.join(tempDir, ".git"), { recursive: true });
+      expect(hasProjectMarker(tempDir)).toBe(true);
+    });
+
+    it("should return true when package.json exists", () => {
+      fs.writeFileSync(path.join(tempDir, "package.json"), "{}");
+      expect(hasProjectMarker(tempDir)).toBe(true);
+    });
+
+    it("should return true when Cargo.toml exists", () => {
+      fs.writeFileSync(path.join(tempDir, "Cargo.toml"), "[package]");
+      expect(hasProjectMarker(tempDir)).toBe(true);
+    });
+
+    it("should return true when go.mod exists", () => {
+      fs.writeFileSync(path.join(tempDir, "go.mod"), "module test");
+      expect(hasProjectMarker(tempDir)).toBe(true);
+    });
+
+    it("should return true when pyproject.toml exists", () => {
+      fs.writeFileSync(path.join(tempDir, "pyproject.toml"), "[project]");
+      expect(hasProjectMarker(tempDir)).toBe(true);
+    });
+
+    it("should return true when .opencode exists", () => {
+      fs.mkdirSync(path.join(tempDir, ".opencode"), { recursive: true });
+      expect(hasProjectMarker(tempDir)).toBe(true);
+    });
+
+    it("should return false for empty directory", () => {
+      expect(hasProjectMarker(tempDir)).toBe(false);
+    });
+
+    it("should return false for directory with only regular files", () => {
+      fs.writeFileSync(path.join(tempDir, "readme.txt"), "hello");
+      fs.writeFileSync(path.join(tempDir, "data.json"), "{}");
+      expect(hasProjectMarker(tempDir)).toBe(false);
+    });
+  });
 });