gitnexus 1.6.13-rc.34 → 1.6.13-rc.36

package/README.md

@@ -2,7 +2,7 @@
 
 **Graph-powered code intelligence for AI agents.** Index any codebase into a knowledge graph, then query it via MCP or CLI.
 
-Works with **Cursor**, **Claude Code**, **Antigravity** (Google), **Codex**, **Windsurf**, **Cline**, **OpenCode**, **CodeBuddy** (Tencent), **Qoder** (Alibaba), and any MCP-compatible tool.
+Works with **Cursor**, **Claude Code**, **Antigravity** (Google), **Codex**, **Factory** (Droid), **Windsurf**, **Cline**, **OpenCode**, **CodeBuddy** (Tencent), **Qoder** (Alibaba), and any MCP-compatible tool.
 
 [![npm version](https://img.shields.io/npm/v/gitnexus.svg)](https://www.npmjs.com/package/gitnexus)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
@@ -44,12 +44,13 @@ To configure MCP for your editor, run `npx gitnexus setup` once — or set it up
 | **Cursor**               | Yes | Yes    | Yes (postToolUse, [manual install](../gitnexus-cursor-integration/README.md#hook-install)) | **Full**     |
 | **Antigravity** (Google) | Yes | Yes    | Yes (AfterTool, [Gemini CLI hooks schema](https://geminicli.com/docs/hooks/reference/))    | **Full**     |
 | **Codex**                | Yes | Yes    | Yes (PreToolUse + PostToolUse, [Codex hooks](https://developers.openai.com/codex/hooks))   | **Full**     |
+| **Factory** (Droid)      | Yes | Yes    | Yes (PostToolUse, [plugin](../gitnexus-factory-plugin/))                                   | **Full**     |
 | **OpenCode**             | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **CodeBuddy** (Tencent)  | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **Qoder** (Alibaba)      | Yes | Yes    | —                                                                                          | MCP + Skills |
 | **Windsurf**             | Yes | —      | —                                                                                          | MCP          |
 
-> **Claude Code** and **Codex** get the deepest integration: MCP tools + agent skills + PreToolUse hooks that automatically enrich grep/glob/bash calls with knowledge graph context + PostToolUse hooks that detect a stale index after commits and prompt the agent to reindex.
+> **Full** means MCP tools + agent skills + hooks that enrich searches with graph context. **Claude Code** and **Codex** go deepest: their PreToolUse hooks enrich the search before it runs, and their PostToolUse hooks also detect a stale index after commits and prompt the agent to reindex. **Cursor**, **Antigravity**, and **Factory** augment from a post-tool hook only, so they enrich the result rather than the query and do not carry the stale-index hint.
 
 ### Community Integrations
 
@@ -88,6 +89,33 @@ codex plugin marketplace add abhigyanpatwari/GitNexus
 
 > **Codex notes:** SessionStart is intentionally not registered — Codex reads [AGENTS.md natively](https://developers.openai.com/codex/guides/agents-md), which already carries the GitNexus context block. Newly installed hooks need a one-time approval in Codex via `/hooks` before they run. Pick **one** install route (`gitnexus setup -c codex` **or** the plugin): plugin hooks load alongside `~/.codex/hooks.json`, so installing both can fire duplicate hooks per tool call.
 
+### Factory (Droid) (full support — MCP + skills + hooks)
+
+`gitnexus setup -c droid` writes the MCP server to `~/.factory/mcp.json` and installs skills to
+`~/.factory/skills/`. To configure MCP by hand instead, add to `~/.factory/mcp.json`
+([user scope](https://docs.factory.ai/cli/configuration/mcp) — applies to all projects):
+
+```json
+{
+  "mcpServers": {
+    "gitnexus": {
+      "command": "npx",
+      "args": ["-y", "gitnexus@latest", "mcp"]
+    }
+  }
+}
+```
+
+For the PostToolUse search-augment hook, install the bundled
+[`gitnexus-factory-plugin/`](../gitnexus-factory-plugin/) with `droid plugin install gitnexus@<marketplace>`
+from a marketplace that includes this repo, or point Droid at it via `extraKnownMarketplaces` in
+`.factory/settings.json`.
+
+> **Factory notes:** Droid reads [AGENTS.md natively](https://docs.factory.ai/), which already carries the
+> GitNexus context block, so no SessionStart hook is registered. Pick **one** install route
+> (`gitnexus setup -c droid` **or** the plugin) — the plugin ships its own MCP entry, so installing both
+> can register the server twice.
+
 ### Cursor / Windsurf
 
 Add to `~/.cursor/mcp.json` (global — works for all projects):

package/dist/cli/ai-context.js

@@ -5,6 +5,8 @@
  * AGENTS.md is the standard read by Cursor, Windsurf, OpenCode, Codex, Cline, CodeBuddy, Qoder, etc.
  * CLAUDE.md is for Claude Code which only reads that file.
  */
+import { GITNEXUS_DIR } from '../storage/storage-constants.js';
+import { storeRootOfCheckoutSlot } from '../storage/shared-store.js';
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -470,11 +472,17 @@ export async function generateAIContextFiles(repoPath, storagePath, projectName,
     // CLI and hooks already share; failure to copy is non-fatal (docs carry a
     // bootstrap fallback). `runnerPath` is project-relative with POSIX separators
     // so the emitted command is identical across platforms.
-    const runnerPath = path.relative(repoPath, path.join(storagePath, 'run.cjs')).replace(/\\/g, '/');
+    // A shared-store slot (#3352) lives under the GitNexus home, so its path
+    // would be machine- and worktree-specific in committed docs; the runner goes
+    // next to the checkout's store pointer instead.
+    const runnerDir = storeRootOfCheckoutSlot(storagePath)
+        ? path.join(repoPath, GITNEXUS_DIR)
+        : storagePath;
+    const runnerPath = path.relative(repoPath, path.join(runnerDir, 'run.cjs')).replace(/\\/g, '/');
     try {
         const runnerSrc = path.join(__dirname, '..', '..', 'hooks', 'claude', 'resolve-analyze-cmd.cjs');
-        await fs.mkdir(storagePath, { recursive: true });
-        await fs.copyFile(runnerSrc, path.join(storagePath, 'run.cjs'));
+        await fs.mkdir(runnerDir, { recursive: true });
+        await fs.copyFile(runnerSrc, path.join(runnerDir, 'run.cjs'));
     }
     catch (err) {
         logger.warn(`Could not write GitNexus runner to ${runnerPath}: ${String(err)}`);

package/dist/cli/analyze-options.d.ts

@@ -103,6 +103,10 @@ export interface AnalyzeOptions {
      * `allowDuplicateName` option end-to-end.
      */
     allowDuplicateName?: boolean;
+    /** `--share-with <repo>`: join that checkout's shared store (#3352). */
+    shareWith?: string;
+    /** `--no-share` sets this to false: leave the shared store (#3352). */
+    share?: boolean;
     /**
      * Override the walker's large-file skip threshold (#991). Value in KB;
      * clamped downstream to the tree-sitter 32 MB ceiling. Sets

package/dist/cli/analyze.js

@@ -1128,6 +1128,8 @@ const analyzeCommandImpl = async (inputPath, cliOptions, runnerIdentityAtBootstr
             // be able to accept the duplicate name without also paying the
             // cost of a full pipeline re-index. See #829 review round 2.
             allowDuplicateName: options.allowDuplicateName,
+            shareWith: options.shareWith,
+            noShare: options.share === false,
             // Worker pool size threaded from --workers, replacing the previous
             // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
             // env / auto-formula fallback inside the pipeline.

package/dist/cli/clean.d.ts

@@ -10,4 +10,6 @@ export declare const cleanCommand: (options?: {
     lbugSidecars?: boolean;
     stale?: boolean;
     branch?: string;
+    gc?: boolean;
+    localIndex?: boolean;
 }) => Promise<void>;

package/dist/cli/clean.js

@@ -9,11 +9,14 @@ import path from 'path';
 import { logger } from '../core/logger.js';
 import { findRegistryEntryByRepoPath, findRepo, unregisterRepo, listRegisteredRepos, getStoragePaths, } from '../storage/repo-manager.js';
 import { requireDeletableStoragePath, StorageDeletionError } from '../storage/storage-resolver.js';
-import { formatStaleSlotLine } from './stale-branch-format.js';
+import { formatSlotSize, formatStaleSlotLine } from './stale-branch-format.js';
 import { listLocalHeads } from '../storage/git.js';
 import { isContainedBranchDir, isDeleteCandidate, listStaleBranchSlots, removeBranchSlot, staleListingBlock, } from '../storage/stale-branch-slots.js';
 import { cleanParkedLbugSidecars, inspectLbugSidecars, listParkedLbugSidecars, } from '../core/lbug/sidecar-recovery.js';
 import { t } from './i18n/index.js';
+import { getGlobalDir } from '../storage/global-dir.js';
+import { STORES_DIR } from '../storage/shared-store.js';
+import { findLegacyLocalIndex, reclaimAfterSlotRemoval, reclaimSharedStore, removeLegacyLocalIndex, removeCheckoutStorage, } from '../storage/shared-store-lifecycle.js';
 const resolveOwnedCwdStorage = async (refusePrefix) => {
     const repo = await findRepo(process.cwd());
     if (!repo) {
@@ -115,7 +118,91 @@ const cleanStaleBranchSlots = async (force) => {
         printStaleSlotLines(t('clean.stale.probeFailed'), probeFailed);
     }
 };
+const reportReclaim = (result) => {
+    if (!result)
+        return;
+    if (result.removed.length > 0) {
+        console.log(t('clean.shared.reclaimed', { count: result.removed.length }));
+    }
+    if (result.kept.length > 0)
+        console.log(t('clean.shared.kept', { count: result.kept.length }));
+};
+/** `clean --gc`: collect every shared store under GITNEXUS_HOME (#3352). */
+const collectSharedStores = async (force) => {
+    const storesDir = path.join(getGlobalDir(), STORES_DIR);
+    // Only a missing stores root means "nothing to collect"; an unreadable one
+    // must fail loudly rather than report success.
+    const names = await fs.readdir(storesDir).catch((err) => {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    });
+    // Stray files (`.DS_Store`) are not stores, and a symlink is not followed:
+    // reclaim deletes under the root it is given. A store another collector
+    // removed meanwhile is simply gone. The lstat skips a stray link; it is not
+    // a race guard, since stores/ belongs to the user running clean and anyone
+    // able to swap an entry there can already delete the store itself.
+    const roots = [];
+    for (const name of names) {
+        const root = path.join(storesDir, name);
+        const stat = await fs.lstat(root).catch((err) => {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        });
+        if (stat?.isDirectory())
+            roots.push(root);
+    }
+    if (roots.length === 0) {
+        console.log(t('clean.gc.none'));
+        return;
+    }
+    for (const root of roots) {
+        // Without --force this is a preview: same selection, nothing deleted.
+        const result = await reclaimSharedStore(root, { gc: true, dryRun: !force });
+        console.log(t(force ? 'clean.gc.store' : 'clean.gc.preview', {
+            path: root,
+            members: result.droppedMembers.length,
+            graphs: result.removed.length,
+        }));
+        if (result.keptMembers.length > 0) {
+            console.log(t('clean.gc.keptMembers', { count: result.keptMembers.length }));
+        }
+        if (result.kept.length > 0)
+            console.log(t('clean.shared.kept', { count: result.kept.length }));
+        if (result.storeRemoved)
+            console.log(t('clean.shared.storeRemoved', { path: root }));
+    }
+    if (!force)
+        console.log(`\n${t('common.runForceConfirm')}`);
+};
 export const cleanCommand = async (options) => {
+    if (options?.gc) {
+        await collectSharedStores(options.force === true);
+        return;
+    }
+    // --local-index: delete a pre-adoption index left in <checkout>/.gitnexus
+    // after the checkout moved into a shared store (#3352). Keeps the pointer.
+    if (options?.localIndex) {
+        const repo = await findRepo(process.cwd());
+        if (!repo) {
+            console.log(t('clean.notFoundHere'));
+            return;
+        }
+        const legacy = await findLegacyLocalIndex(repo.repoPath, repo.storagePath);
+        if (!legacy) {
+            console.log(t('clean.localIndex.none'));
+            return;
+        }
+        if (!options.force) {
+            console.log(t('clean.localIndex.preview', { path: legacy.dir, size: formatSlotSize(legacy.bytes) }));
+            console.log(`\n${t('common.runForceConfirm')}`);
+            return;
+        }
+        await removeLegacyLocalIndex(repo.repoPath, repo.storagePath);
+        console.log(t('clean.localIndex.deleted', { path: legacy.dir, size: formatSlotSize(legacy.bytes) }));
+        return;
+    }
     // --stale: reclaim leftover per-branch slots whose recorded branch is not
     // a live local head (#3331). Exclusive arm before --branch.
     if (options?.stale) {
@@ -246,9 +333,12 @@ export const cleanCommand = async (options) => {
         for (const entry of entries) {
             try {
                 const storagePath = await requireDeletableStoragePath(entry);
-                await fs.rm(storagePath, { recursive: true, force: true });
-                await unregisterRepo(entry.path);
+                // A shared slot is unregistered before it is deleted: its lock file
+                // lives inside it, so it must go last. A failed delete throws with the
+                // `clean --gc --force` recovery (shared-store-clean.test.ts).
+                await removeCheckoutStorage(storagePath, () => unregisterRepo(entry.path), entry.path);
                 console.log(t('clean.deletedRepo', { name: entry.name, storagePath }));
+                reportReclaim(await reclaimAfterSlotRemoval(storagePath));
             }
             catch (err) {
                 if (err instanceof StorageDeletionError) {
@@ -289,9 +379,9 @@ export const cleanCommand = async (options) => {
         return;
     }
     try {
-        await fs.rm(storagePath, { recursive: true, force: true });
-        await unregisterRepo(repo.repoPath);
+        await removeCheckoutStorage(storagePath, () => unregisterRepo(repo.repoPath), repo.repoPath);
         console.log(t('common.deleted', { target: storagePath }));
+        reportReclaim(await reclaimAfterSlotRemoval(storagePath));
     }
     catch (err) {
         logger.error({ err }, 'Failed to delete:');

package/dist/cli/doctor.js

@@ -1,4 +1,5 @@
 import { getRuntimeCapabilities, getRuntimeFingerprint } from '../core/platform/capabilities.js';
+import { findLegacyLocalIndex } from '../storage/shared-store-lifecycle.js';
 import { resolveEmbeddingConfig } from '../core/embeddings/config.js';
 import { isHttpMode } from '../core/embeddings/http-client.js';
 import { getLocalEmbeddingRuntimeBlocker, localEmbeddingPrefixUnloadableMessage, localEmbeddingStackMissingMessage, } from '../core/embeddings/runtime-support.js';
@@ -327,6 +328,12 @@ export const doctorCommand = async () => {
         branches: entry?.branches,
     });
     const leftoverLines = leftoverBranchSlotDoctorLines(slots);
+    // A pre-adoption index left in <repo>/.gitnexus after this checkout moved
+    // into a shared store (#3352).
+    const legacy = await findLegacyLocalIndex(cwdRepo.repoPath, cwdRepo.storagePath);
+    if (legacy) {
+        leftoverLines.push(t('status.legacyLocalIndex', { path: legacy.dir, size: formatSlotSize(legacy.bytes) }));
+    }
     if (leftoverLines.length === 0)
         return;
     console.log('');

package/dist/cli/editor-targets.d.ts

@@ -15,7 +15,7 @@
  * implementations remain behaviourally symmetrical on top of this shared
  * structure.
  */
-export type EditorId = 'cursor' | 'claude' | 'antigravity' | 'opencode' | 'codebuddy' | 'qoder' | 'codex';
+export type EditorId = 'cursor' | 'claude' | 'antigravity' | 'opencode' | 'codebuddy' | 'qoder' | 'codex' | 'droid';
 /** An editor whose MCP config is a JSONC document (server keyed by name). */
 export interface McpJsoncTarget {
     id: EditorId;

package/dist/cli/editor-targets.js

@@ -76,6 +76,15 @@ export function getEditorTargets(home = os.homedir()) {
             file: path.join(home, '.qoder.json'),
             keyPath: ['mcpServers', 'gitnexus'],
         },
+        {
+            id: 'droid',
+            label: 'Factory Droid',
+            // Factory's user-scope MCP config (https://docs.factory.ai/cli/configuration/mcp).
+            // Same `mcpServers` object shape as Cursor/Claude; user config takes
+            // precedence over project-level .factory/mcp.json.
+            file: path.join(home, '.factory', 'mcp.json'),
+            keyPath: ['mcpServers', 'gitnexus'],
+        },
     ];
     const codex = {
         id: 'codex',
@@ -98,6 +107,9 @@ export function getEditorTargets(home = os.homedir()) {
         { id: 'qoder', label: 'Qoder', dir: path.join(home, '.qoder', 'skills') },
         // Codex reads skills from ~/.agents/skills (not ~/.codex).
         { id: 'codex', label: 'Codex', dir: path.join(home, '.agents', 'skills') },
+        // Factory Droid reads user-scope skills from ~/.factory/skills/{name}/SKILL.md
+        // (https://docs.factory.ai/cli/configuration/skills).
+        { id: 'droid', label: 'Factory Droid', dir: path.join(home, '.factory', 'skills') },
     ];
     const hooks = [
         {

package/dist/cli/embeddings-sync.js

@@ -1,4 +1,6 @@
 import { lstat } from 'node:fs/promises';
+import { ensurePrivateSharedGraph } from '../core/shared-store-analyze.js';
+import { LBUG_DIRECTORY } from '../storage/storage-constants.js';
 import path from 'node:path';
 import { cliInfo } from './cli-message.js';
 import { getGitRoot } from '../storage/git.js';
@@ -17,11 +19,17 @@ export const embeddingsSyncCommand = async (inputPath) => {
     const repoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());
     if (!repoPath)
         throw new Error('Not inside a git repository. Pass a repository path.');
-    const { lbugPath, metaPath } = getStoragePaths(repoPath);
+    const { metaPath } = getStoragePaths(repoPath);
     const metaDir = path.dirname(metaPath);
+    // Writes go to the slot's own graph. A shared-store checkout that reads an
+    // immutable commit graph (#3352) takes a private copy first.
+    const lbugPath = path.join(metaDir, LBUG_DIRECTORY);
     const lock = await acquireIndexLock(metaDir);
     try {
         requireExclusiveIndexLock(lock, `Cannot acquire the index lock at ${metaDir}; refusing an unlocked embeddings sync.`);
+        if (!(await ensurePrivateSharedGraph(metaDir, (m) => console.log(`  ${m}`)))) {
+            throw new Error('The shared graph this checkout reads is gone. Run gitnexus analyze first.');
+        }
         const meta = await loadMeta(metaDir);
         if (!meta)
             throw new Error(`No GitNexus index found for ${repoPath}. Run gitnexus analyze first.`);

package/dist/cli/help-i18n.js

@@ -63,6 +63,8 @@ const OPTION_DESCRIPTION_KEYS = {
     'analyze|--skip-git': 'help.option.skipGit',
     'analyze|--name <alias>': 'help.option.analyze.name',
     'analyze|--allow-duplicate-name': 'help.option.analyze.allowDuplicateName',
+    'analyze|--share-with <repo>': 'help.option.analyze.shareWith',
+    'analyze|--no-share': 'help.option.analyze.noShare',
     'analyze|-v, --verbose': 'help.option.verbose',
     'analyze|--max-file-size <kb>': 'help.option.analyze.maxFileSize',
     'analyze|--worker-timeout <seconds>': 'help.option.analyze.workerTimeout',
@@ -93,6 +95,8 @@ const OPTION_DESCRIPTION_KEYS = {
     'clean|--branch <name>': 'help.option.clean.branch',
     'clean|--lbug-sidecars': 'help.option.clean.lbugSidecars',
     'clean|--stale': 'help.option.clean.stale',
+    'clean|--gc': 'help.option.clean.gc',
+    'clean|--local-index': 'help.option.clean.localIndex',
     'remove|-f, --force': 'help.option.force.confirmation',
     'wiki|-f, --force': 'help.option.wiki.force',
     'wiki|--provider <provider>': 'help.option.wiki.provider',

package/dist/cli/i18n/en.d.ts

@@ -25,6 +25,11 @@ export declare const en: {
     readonly 'list.clusters': 'Clusters';
     readonly 'list.processes': 'Processes';
     readonly 'list.unknown': 'unknown';
+    readonly 'status.sharedStoreShared': 'Shared index: store {{key}}, shared graph for commit {{commit}}';
+    readonly 'status.sharedStorePrivate': 'Shared index: store {{key}}, private graph (local changes or a pinned branch index)';
+    readonly 'status.sharedStoreCloneCow': '  Copied copy-on-write: unchanged pages are shared with the commit graph on disk';
+    readonly 'status.sharedStoreCloneCopy': '  Full copy: this filesystem cannot clone copy-on-write (APFS, btrfs and XFS can)';
+    readonly 'status.legacyLocalIndex': 'Leftover local index: {{path}} ({{size}}); remove it with `gitnexus clean --local-index --force`';
     readonly 'status.notGitRepo': 'Not a git repository.';
     readonly 'status.staleKuzu': 'Repository has a stale KuzuDB index from a previous version.';
     readonly 'status.rebuildLadybug': 'Run: gitnexus analyze   (rebuilds the index with LadybugDB)';
@@ -52,6 +57,16 @@ export declare const en: {
     readonly 'clean.deleteAll': 'This will delete GitNexus indexes for {{count}} repo(s):';
     readonly 'clean.deletedRepo': 'Deleted: {{name}} ({{storagePath}})';
     readonly 'clean.notFoundHere': 'No indexed repository found in this directory.';
+    readonly 'clean.shared.reclaimed': 'Shared store: removed {{count}} commit graph(s) no checkout references.';
+    readonly 'clean.shared.kept': 'Shared store: kept {{count}} unreferenced commit graph(s) that could not be removed (in use or not writable); run `gitnexus clean --gc` later.';
+    readonly 'clean.shared.storeRemoved': 'Shared store: removed {{path}} (no checkouts remain).';
+    readonly 'clean.gc.none': 'No shared stores to collect.';
+    readonly 'clean.gc.keptMembers': 'Shared store: kept {{count}} checkout(s) it could not delete; run `gitnexus clean --gc --force` later.';
+    readonly 'clean.gc.store': 'Shared store {{path}}: dropped {{members}} checkout(s), removed {{graphs}} commit graph(s).';
+    readonly 'clean.gc.preview': 'Shared store {{path}}: would drop {{members}} checkout(s) and remove {{graphs}} commit graph(s).';
+    readonly 'clean.localIndex.none': 'No leftover local index in this checkout.';
+    readonly 'clean.localIndex.preview': 'This will delete the leftover local index at {{path}} ({{size}}). The shared index is not affected.';
+    readonly 'clean.localIndex.deleted': 'Deleted the leftover local index at {{path}} ({{size}}).';
     readonly 'clean.deleteCurrent': 'This will delete the GitNexus index for: {{repoName}}';
     readonly 'clean.branchNotIndexed': 'No indexed branch named "{{branch}}" for this repository. Use `gitnexus clean --stale` to reclaim leftover branch indexes, or `gitnexus list` to see recorded names.';
     readonly 'clean.stale.none': 'No leftover branch indexes to reclaim.';
@@ -152,7 +167,7 @@ export declare const en: {
     readonly 'help.command.help.description': 'display help for command';
     readonly 'help.option.help': 'display help for command';
     readonly 'help.option.version': 'output the version number';
-    readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex';
+    readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid';
     readonly 'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors';
     readonly 'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml';
     readonly 'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.';
@@ -208,6 +223,8 @@ export declare const en: {
     readonly 'help.option.skipGit': 'Treat the provided path/cwd as the index root and skip parent git-root discovery';
     readonly 'help.option.analyze.name': 'Register this repo under a custom name in ~/.gitnexus/registry.json (disambiguates repos whose paths share a basename, e.g. two different .../app folders)';
     readonly 'help.option.analyze.allowDuplicateName': 'Register this repo even if another path already uses the same --name alias. Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.';
+    readonly 'help.option.analyze.shareWith': 'Join the shared index store of a registered checkout of the same repository (name or path); the remote URL must match. Clones join a sibling clone’s store automatically; this names one explicitly and clears a --no-share opt-out.';
+    readonly 'help.option.analyze.noShare': 'Clones only: leave the shared index store, index into <repo>/.gitnexus again, and stop joining sibling clones automatically until --share-with (linked worktrees always share; set GITNEXUS_SHARED_STORE=off instead)';
     readonly 'help.option.verbose': 'Enable verbose output';
     readonly 'help.option.analyze.maxFileSize': 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).';
     readonly 'help.option.analyze.workerTimeout': 'Worker sub-batch idle timeout before retry/fallback. Default: 30.';
@@ -236,6 +253,8 @@ export declare const en: {
     readonly 'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)';
     readonly 'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)';
     readonly 'help.option.clean.stale': 'Reclaim leftover branch indexes that are not a live local head';
+    readonly 'help.option.clean.gc': 'Drop shared-store checkouts no registry entry uses and delete commit graphs nothing references';
+    readonly 'help.option.clean.localIndex': 'Delete the index left in <repo>/.gitnexus after this checkout moved into a shared store';
     readonly 'help.option.wiki.force': 'Force full regeneration even if up to date';
     readonly 'help.option.wiki.provider': 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)';
     readonly 'help.option.wiki.model': 'LLM model or deployment name (default: MiniMax-M3)';

package/dist/cli/i18n/en.js

@@ -25,6 +25,11 @@ export const en = {
     'list.clusters': 'Clusters',
     'list.processes': 'Processes',
     'list.unknown': 'unknown',
+    'status.sharedStoreShared': 'Shared index: store {{key}}, shared graph for commit {{commit}}',
+    'status.sharedStorePrivate': 'Shared index: store {{key}}, private graph (local changes or a pinned branch index)',
+    'status.sharedStoreCloneCow': '  Copied copy-on-write: unchanged pages are shared with the commit graph on disk',
+    'status.sharedStoreCloneCopy': '  Full copy: this filesystem cannot clone copy-on-write (APFS, btrfs and XFS can)',
+    'status.legacyLocalIndex': 'Leftover local index: {{path}} ({{size}}); remove it with `gitnexus clean --local-index --force`',
     'status.notGitRepo': 'Not a git repository.',
     'status.staleKuzu': 'Repository has a stale KuzuDB index from a previous version.',
     'status.rebuildLadybug': 'Run: gitnexus analyze   (rebuilds the index with LadybugDB)',
@@ -52,6 +57,16 @@ export const en = {
     'clean.deleteAll': 'This will delete GitNexus indexes for {{count}} repo(s):',
     'clean.deletedRepo': 'Deleted: {{name}} ({{storagePath}})',
     'clean.notFoundHere': 'No indexed repository found in this directory.',
+    'clean.shared.reclaimed': 'Shared store: removed {{count}} commit graph(s) no checkout references.',
+    'clean.shared.kept': 'Shared store: kept {{count}} unreferenced commit graph(s) that could not be removed (in use or not writable); run `gitnexus clean --gc` later.',
+    'clean.shared.storeRemoved': 'Shared store: removed {{path}} (no checkouts remain).',
+    'clean.gc.none': 'No shared stores to collect.',
+    'clean.gc.keptMembers': 'Shared store: kept {{count}} checkout(s) it could not delete; run `gitnexus clean --gc --force` later.',
+    'clean.gc.store': 'Shared store {{path}}: dropped {{members}} checkout(s), removed {{graphs}} commit graph(s).',
+    'clean.gc.preview': 'Shared store {{path}}: would drop {{members}} checkout(s) and remove {{graphs}} commit graph(s).',
+    'clean.localIndex.none': 'No leftover local index in this checkout.',
+    'clean.localIndex.preview': 'This will delete the leftover local index at {{path}} ({{size}}). The shared index is not affected.',
+    'clean.localIndex.deleted': 'Deleted the leftover local index at {{path}} ({{size}}).',
     'clean.deleteCurrent': 'This will delete the GitNexus index for: {{repoName}}',
     'clean.branchNotIndexed': 'No indexed branch named "{{branch}}" for this repository. Use `gitnexus clean --stale` to reclaim leftover branch indexes, or `gitnexus list` to see recorded names.',
     'clean.stale.none': 'No leftover branch indexes to reclaim.',
@@ -154,7 +169,7 @@ export const en = {
     'help.command.help.description': 'display help for command',
     'help.option.help': 'display help for command',
     'help.option.version': 'output the version number',
-    'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex',
+    'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid',
     'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors',
     'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml',
     'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.',
@@ -210,6 +225,8 @@ export const en = {
     'help.option.skipGit': 'Treat the provided path/cwd as the index root and skip parent git-root discovery',
     'help.option.analyze.name': 'Register this repo under a custom name in ~/.gitnexus/registry.json (disambiguates repos whose paths share a basename, e.g. two different .../app folders)',
     'help.option.analyze.allowDuplicateName': 'Register this repo even if another path already uses the same --name alias. Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.',
+    'help.option.analyze.shareWith': 'Join the shared index store of a registered checkout of the same repository (name or path); the remote URL must match. Clones join a sibling clone’s store automatically; this names one explicitly and clears a --no-share opt-out.',
+    'help.option.analyze.noShare': 'Clones only: leave the shared index store, index into <repo>/.gitnexus again, and stop joining sibling clones automatically until --share-with (linked worktrees always share; set GITNEXUS_SHARED_STORE=off instead)',
     'help.option.verbose': 'Enable verbose output',
     'help.option.analyze.maxFileSize': 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).',
     'help.option.analyze.workerTimeout': 'Worker sub-batch idle timeout before retry/fallback. Default: 30.',
@@ -238,6 +255,8 @@ export const en = {
     'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)',
     'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)',
     'help.option.clean.stale': 'Reclaim leftover branch indexes that are not a live local head',
+    'help.option.clean.gc': 'Drop shared-store checkouts no registry entry uses and delete commit graphs nothing references',
+    'help.option.clean.localIndex': 'Delete the index left in <repo>/.gitnexus after this checkout moved into a shared store',
     'help.option.wiki.force': 'Force full regeneration even if up to date',
     'help.option.wiki.provider': 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)',
     'help.option.wiki.model': 'LLM model or deployment name (default: MiniMax-M3)',

package/dist/cli/i18n/resources.d.ts

@@ -26,6 +26,11 @@ export declare const cliResources: {
         readonly 'list.clusters': 'Clusters';
         readonly 'list.processes': 'Processes';
         readonly 'list.unknown': 'unknown';
+        readonly 'status.sharedStoreShared': 'Shared index: store {{key}}, shared graph for commit {{commit}}';
+        readonly 'status.sharedStorePrivate': 'Shared index: store {{key}}, private graph (local changes or a pinned branch index)';
+        readonly 'status.sharedStoreCloneCow': '  Copied copy-on-write: unchanged pages are shared with the commit graph on disk';
+        readonly 'status.sharedStoreCloneCopy': '  Full copy: this filesystem cannot clone copy-on-write (APFS, btrfs and XFS can)';
+        readonly 'status.legacyLocalIndex': 'Leftover local index: {{path}} ({{size}}); remove it with `gitnexus clean --local-index --force`';
         readonly 'status.notGitRepo': 'Not a git repository.';
         readonly 'status.staleKuzu': 'Repository has a stale KuzuDB index from a previous version.';
         readonly 'status.rebuildLadybug': 'Run: gitnexus analyze   (rebuilds the index with LadybugDB)';
@@ -53,6 +58,16 @@ export declare const cliResources: {
         readonly 'clean.deleteAll': 'This will delete GitNexus indexes for {{count}} repo(s):';
         readonly 'clean.deletedRepo': 'Deleted: {{name}} ({{storagePath}})';
         readonly 'clean.notFoundHere': 'No indexed repository found in this directory.';
+        readonly 'clean.shared.reclaimed': 'Shared store: removed {{count}} commit graph(s) no checkout references.';
+        readonly 'clean.shared.kept': 'Shared store: kept {{count}} unreferenced commit graph(s) that could not be removed (in use or not writable); run `gitnexus clean --gc` later.';
+        readonly 'clean.shared.storeRemoved': 'Shared store: removed {{path}} (no checkouts remain).';
+        readonly 'clean.gc.none': 'No shared stores to collect.';
+        readonly 'clean.gc.keptMembers': 'Shared store: kept {{count}} checkout(s) it could not delete; run `gitnexus clean --gc --force` later.';
+        readonly 'clean.gc.store': 'Shared store {{path}}: dropped {{members}} checkout(s), removed {{graphs}} commit graph(s).';
+        readonly 'clean.gc.preview': 'Shared store {{path}}: would drop {{members}} checkout(s) and remove {{graphs}} commit graph(s).';
+        readonly 'clean.localIndex.none': 'No leftover local index in this checkout.';
+        readonly 'clean.localIndex.preview': 'This will delete the leftover local index at {{path}} ({{size}}). The shared index is not affected.';
+        readonly 'clean.localIndex.deleted': 'Deleted the leftover local index at {{path}} ({{size}}).';
         readonly 'clean.deleteCurrent': 'This will delete the GitNexus index for: {{repoName}}';
         readonly 'clean.branchNotIndexed': 'No indexed branch named "{{branch}}" for this repository. Use `gitnexus clean --stale` to reclaim leftover branch indexes, or `gitnexus list` to see recorded names.';
         readonly 'clean.stale.none': 'No leftover branch indexes to reclaim.';
@@ -153,7 +168,7 @@ export declare const cliResources: {
         readonly 'help.command.help.description': 'display help for command';
         readonly 'help.option.help': 'display help for command';
         readonly 'help.option.version': 'output the version number';
-        readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex';
+        readonly 'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex, Factory Droid';
         readonly 'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors';
         readonly 'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml';
         readonly 'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.';
@@ -209,6 +224,8 @@ export declare const cliResources: {
         readonly 'help.option.skipGit': 'Treat the provided path/cwd as the index root and skip parent git-root discovery';
         readonly 'help.option.analyze.name': 'Register this repo under a custom name in ~/.gitnexus/registry.json (disambiguates repos whose paths share a basename, e.g. two different .../app folders)';
         readonly 'help.option.analyze.allowDuplicateName': 'Register this repo even if another path already uses the same --name alias. Leaves `-r <name>` ambiguous for the two paths; use -r <path> to disambiguate.';
+        readonly 'help.option.analyze.shareWith': 'Join the shared index store of a registered checkout of the same repository (name or path); the remote URL must match. Clones join a sibling clone’s store automatically; this names one explicitly and clears a --no-share opt-out.';
+        readonly 'help.option.analyze.noShare': 'Clones only: leave the shared index store, index into <repo>/.gitnexus again, and stop joining sibling clones automatically until --share-with (linked worktrees always share; set GITNEXUS_SHARED_STORE=off instead)';
         readonly 'help.option.verbose': 'Enable verbose output';
         readonly 'help.option.analyze.maxFileSize': 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).';
         readonly 'help.option.analyze.workerTimeout': 'Worker sub-batch idle timeout before retry/fallback. Default: 30.';
@@ -237,6 +254,8 @@ export declare const cliResources: {
         readonly 'help.option.clean.branch': 'Delete only the named branch index (not the workspace index)';
         readonly 'help.option.clean.lbugSidecars': 'Clean parked LadybugDB recovery sidecars (missing-shadow WAL quarantines and dirty-recovery parks)';
         readonly 'help.option.clean.stale': 'Reclaim leftover branch indexes that are not a live local head';
+        readonly 'help.option.clean.gc': 'Drop shared-store checkouts no registry entry uses and delete commit graphs nothing references';
+        readonly 'help.option.clean.localIndex': 'Delete the index left in <repo>/.gitnexus after this checkout moved into a shared store';
         readonly 'help.option.wiki.force': 'Force full regeneration even if up to date';
         readonly 'help.option.wiki.provider': 'LLM provider: minimax, openai, openrouter, azure, custom, cursor, claude, codex, opencode, or grok (default: minimax)';
         readonly 'help.option.wiki.model': 'LLM model or deployment name (default: MiniMax-M3)';
@@ -333,6 +352,11 @@ export declare const cliResources: {
         'list.clusters': string;
         'list.processes': string;
         'list.unknown': string;
+        'status.sharedStoreShared': string;
+        'status.sharedStorePrivate': string;
+        'status.sharedStoreCloneCow': string;
+        'status.sharedStoreCloneCopy': string;
+        'status.legacyLocalIndex': string;
         'status.notGitRepo': string;
         'status.staleKuzu': string;
         'status.rebuildLadybug': string;
@@ -360,6 +384,16 @@ export declare const cliResources: {
         'clean.deleteAll': string;
         'clean.deletedRepo': string;
         'clean.notFoundHere': string;
+        'clean.shared.reclaimed': string;
+        'clean.shared.kept': string;
+        'clean.shared.storeRemoved': string;
+        'clean.gc.none': string;
+        'clean.gc.keptMembers': string;
+        'clean.gc.store': string;
+        'clean.gc.preview': string;
+        'clean.localIndex.none': string;
+        'clean.localIndex.preview': string;
+        'clean.localIndex.deleted': string;
         'clean.deleteCurrent': string;
         'clean.branchNotIndexed': string;
         'clean.stale.none': string;
@@ -516,6 +550,8 @@ export declare const cliResources: {
         'help.option.skipGit': string;
         'help.option.analyze.name': string;
         'help.option.analyze.allowDuplicateName': string;
+        'help.option.analyze.shareWith': string;
+        'help.option.analyze.noShare': string;
         'help.option.verbose': string;
         'help.option.analyze.maxFileSize': string;
         'help.option.analyze.workerTimeout': string;
@@ -544,6 +580,8 @@ export declare const cliResources: {
         'help.option.clean.branch': string;
         'help.option.clean.lbugSidecars': string;
         'help.option.clean.stale': string;
+        'help.option.clean.gc': string;
+        'help.option.clean.localIndex': string;
         'help.option.wiki.force': string;
         'help.option.wiki.provider': string;
         'help.option.wiki.model': string;

package/dist/cli/i18n/zh-CN.d.ts

@@ -25,6 +25,11 @@ export declare const zhCN: {
     'list.clusters': string;
     'list.processes': string;
     'list.unknown': string;
+    'status.sharedStoreShared': string;
+    'status.sharedStorePrivate': string;
+    'status.sharedStoreCloneCow': string;
+    'status.sharedStoreCloneCopy': string;
+    'status.legacyLocalIndex': string;
     'status.notGitRepo': string;
     'status.staleKuzu': string;
     'status.rebuildLadybug': string;
@@ -52,6 +57,16 @@ export declare const zhCN: {
     'clean.deleteAll': string;
     'clean.deletedRepo': string;
     'clean.notFoundHere': string;
+    'clean.shared.reclaimed': string;
+    'clean.shared.kept': string;
+    'clean.shared.storeRemoved': string;
+    'clean.gc.none': string;
+    'clean.gc.keptMembers': string;
+    'clean.gc.store': string;
+    'clean.gc.preview': string;
+    'clean.localIndex.none': string;
+    'clean.localIndex.preview': string;
+    'clean.localIndex.deleted': string;
     'clean.deleteCurrent': string;
     'clean.branchNotIndexed': string;
     'clean.stale.none': string;
@@ -208,6 +223,8 @@ export declare const zhCN: {
     'help.option.skipGit': string;
     'help.option.analyze.name': string;
     'help.option.analyze.allowDuplicateName': string;
+    'help.option.analyze.shareWith': string;
+    'help.option.analyze.noShare': string;
     'help.option.verbose': string;
     'help.option.analyze.maxFileSize': string;
     'help.option.analyze.workerTimeout': string;
@@ -236,6 +253,8 @@ export declare const zhCN: {
     'help.option.clean.branch': string;
     'help.option.clean.lbugSidecars': string;
     'help.option.clean.stale': string;
+    'help.option.clean.gc': string;
+    'help.option.clean.localIndex': string;
     'help.option.wiki.force': string;
     'help.option.wiki.provider': string;
     'help.option.wiki.model': string;