@dezkareid/ai-context-sync 1.0.0 → 1.2.0

package/README.md

@@ -8,6 +8,7 @@ A CLI utility to synchronize AI agent context files across different providers,
 - **Multi-provider support**:
   - **Claude**: Generates/updates `CLAUDE.md`.
   - **Gemini**: Configures `.gemini/settings.json` to use `AGENTS.md`.
+  - **Gemini Markdown**: Generates/updates `GEMINI.md`.
 - **Plugin Architecture**: Easily extendable to support other AI agents.
 
 ## Installation
@@ -23,15 +24,32 @@ pnpm install @dezkareid/ai-context-sync
 Run the sync command in your project root (where `AGENTS.md` is located):
 
 ```bash
-npx ai-context-sync sync
+npx @dezkareid/ai-context-sync sync
 ```
 
-Or specify a directory:
+You can select the strategy using the `--strategy` (or `-s`) option:
 
 ```bash
-npx ai-context-sync sync --dir ./my-package
+npx @dezkareid/ai-context-sync sync --strategy claude
+npx @dezkareid/ai-context-sync sync --strategy gemini
+npx @dezkareid/ai-context-sync sync --strategy all
+npx @dezkareid/ai-context-sync sync --strategy "claude, gemini"
 ```
 
+If no strategy is provided, an interactive checkbox menu will appear to let you toggle which strategies to run.
+
+### Configuration
+
+The tool can save your selected strategies in a `.ai-context-configrc` file in the project root. This avoids being prompted every time you run the command.
+
+To bypass reading or creating this configuration file, use the `--skip-config` flag:
+
+```bash
+npx @dezkareid/ai-context-sync sync --skip-config
+```
+
+### Directory option
+
 ## How it works
 
 1. The tool looks for an `AGENTS.md` file in the target directory.

package/dist/constants.js

@@ -1,4 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AGENTS_FILENAME = void 0;
+exports.CONFIG_FILENAME = exports.AGENTS_FILENAME = void 0;
 exports.AGENTS_FILENAME = 'AGENTS.md';
+exports.CONFIG_FILENAME = '.ai-context-configrc';

package/dist/engine.js

@@ -9,21 +9,41 @@ const path_1 = __importDefault(require("path"));
 const constants_js_1 = require("./constants.js");
 const claude_js_1 = require("./strategies/claude.js");
 const gemini_js_1 = require("./strategies/gemini.js");
+const gemini_md_js_1 = require("./strategies/gemini-md.js");
 class SyncEngine {
-    strategies = [];
-    constructor() {
-        this.strategies.push(new claude_js_1.ClaudeStrategy());
-        this.strategies.push(new gemini_js_1.GeminiStrategy());
-    }
-    async sync(projectRoot) {
+    allStrategies = [
+        new claude_js_1.ClaudeStrategy(),
+        new gemini_js_1.GeminiStrategy(),
+        new gemini_md_js_1.GeminiMdStrategy()
+    ];
+    async sync(projectRoot, selectedStrategies, targetDir) {
         const agentsPath = path_1.default.join(projectRoot, constants_js_1.AGENTS_FILENAME);
+        const outputDir = targetDir ?? projectRoot;
         if (!(await fs_extra_1.default.pathExists(agentsPath))) {
             throw new Error(`${constants_js_1.AGENTS_FILENAME} not found in ${projectRoot}`);
         }
         const context = await fs_extra_1.default.readFile(agentsPath, 'utf-8');
-        for (const strategy of this.strategies) {
+        let strategiesToRun;
+        if (!selectedStrategies || (Array.isArray(selectedStrategies) && selectedStrategies.length === 0)) {
+            strategiesToRun = this.allStrategies;
+        }
+        else {
+            const selectedList = Array.isArray(selectedStrategies) ? selectedStrategies : [selectedStrategies];
+            const normalizedList = selectedList.map(s => s.toLowerCase());
+            if (normalizedList.includes('all') || normalizedList.includes('both')) {
+                strategiesToRun = this.allStrategies;
+            }
+            else {
+                strategiesToRun = this.allStrategies.filter(s => normalizedList.includes(s.name.toLowerCase()));
+            }
+        }
+        const availableNames = this.allStrategies.map(s => s.name).join(', ');
+        if (strategiesToRun.length === 0 && selectedStrategies) {
+            throw new Error(`No valid strategies found for: ${selectedStrategies}. Available strategies: ${availableNames}`);
+        }
+        for (const strategy of strategiesToRun) {
             console.log(`Syncing for ${strategy.name}...`);
-            await strategy.sync(context, projectRoot);
+            await strategy.sync(context, projectRoot, outputDir);
         }
     }
 }

package/dist/engine.test.js

@@ -37,4 +37,114 @@ const os_1 = __importDefault(require("os"));
         const settings = await fs_extra_1.default.readJson(settingsPath);
         (0, vitest_1.expect)(settings.context.fileName).toContain(constants_js_1.AGENTS_FILENAME);
     });
+    (0, vitest_1.it)('should run only Claude strategy when selected', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, 'claude');
+        const claudePath = path_1.default.join(tempDir, 'CLAUDE.md');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(claudePath)).toBe(true);
+        const geminiDir = path_1.default.join(tempDir, '.gemini');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(geminiDir)).toBe(false);
+    });
+    (0, vitest_1.it)('should run only Gemini strategy when selected', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, 'gemini');
+        const claudePath = path_1.default.join(tempDir, 'CLAUDE.md');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(claudePath)).toBe(false);
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(settingsPath)).toBe(true);
+    });
+    (0, vitest_1.it)('should run Gemini Markdown strategy when selected', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, 'gemini-md');
+        const geminiMdPath = path_1.default.join(tempDir, 'GEMINI.md');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(geminiMdPath)).toBe(true);
+        const stats = await fs_extra_1.default.lstat(geminiMdPath);
+        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+    });
+    (0, vitest_1.it)('should run multiple selected strategies from array', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, ['claude', 'gemini']);
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(path_1.default.join(tempDir, 'CLAUDE.md'))).toBe(true);
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(path_1.default.join(tempDir, '.gemini', 'settings.json'))).toBe(true);
+    });
+    (0, vitest_1.it)('should run all strategies when "all" is selected', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await engine.sync(tempDir, 'all');
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(path_1.default.join(tempDir, 'CLAUDE.md'))).toBe(true);
+        (0, vitest_1.expect)(await fs_extra_1.default.pathExists(path_1.default.join(tempDir, '.gemini', 'settings.json'))).toBe(true);
+    });
+    (0, vitest_1.it)('should throw error for invalid strategy', async () => {
+        const engine = new engine_js_1.SyncEngine();
+        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+        await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+        await (0, vitest_1.expect)(engine.sync(tempDir, 'invalid')).rejects.toThrow('No valid strategies found for: invalid. Available strategies: claude, gemini, gemini-md');
+    });
+    (0, vitest_1.describe)('targetDir option', () => {
+        let targetDir;
+        (0, vitest_1.beforeEach)(async () => {
+            targetDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'sync-engine-target-'));
+        });
+        (0, vitest_1.afterEach)(async () => {
+            await fs_extra_1.default.remove(targetDir);
+        });
+        (0, vitest_1.it)('should write synced files to targetDir instead of projectRoot', async () => {
+            const engine = new engine_js_1.SyncEngine();
+            const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+            await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+            await engine.sync(tempDir, 'claude', targetDir);
+            // File should be in targetDir
+            const claudeInTarget = path_1.default.join(targetDir, 'CLAUDE.md');
+            (0, vitest_1.expect)(await fs_extra_1.default.pathExists(claudeInTarget)).toBe(true);
+            // File should NOT be in projectRoot (tempDir)
+            const claudeInSource = path_1.default.join(tempDir, 'CLAUDE.md');
+            (0, vitest_1.expect)(await fs_extra_1.default.pathExists(claudeInSource)).toBe(false);
+        });
+        (0, vitest_1.it)('should create symlink in targetDir pointing back to projectRoot AGENTS.md', async () => {
+            const engine = new engine_js_1.SyncEngine();
+            const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+            await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+            await engine.sync(tempDir, 'claude', targetDir);
+            const claudePath = path_1.default.join(targetDir, 'CLAUDE.md');
+            const stats = await fs_extra_1.default.lstat(claudePath);
+            (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+            // The symlink should resolve to the AGENTS.md in projectRoot
+            const resolvedPath = await fs_extra_1.default.realpath(claudePath);
+            const expectedPath = await fs_extra_1.default.realpath(agentsPath);
+            (0, vitest_1.expect)(resolvedPath).toBe(expectedPath);
+        });
+        (0, vitest_1.it)('should write .gemini/settings.json to targetDir when targetDir is specified', async () => {
+            const engine = new engine_js_1.SyncEngine();
+            const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+            await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+            await engine.sync(tempDir, 'gemini', targetDir);
+            // Settings should be in targetDir
+            const settingsInTarget = path_1.default.join(targetDir, '.gemini', 'settings.json');
+            (0, vitest_1.expect)(await fs_extra_1.default.pathExists(settingsInTarget)).toBe(true);
+            // Settings should NOT be in projectRoot
+            const settingsInSource = path_1.default.join(tempDir, '.gemini', 'settings.json');
+            (0, vitest_1.expect)(await fs_extra_1.default.pathExists(settingsInSource)).toBe(false);
+            // The stored path should be relative from targetDir to AGENTS.md
+            const settings = await fs_extra_1.default.readJson(settingsInTarget);
+            const expectedRelPath = path_1.default.relative(targetDir, agentsPath);
+            (0, vitest_1.expect)(settings.context.fileName).toContain(expectedRelPath);
+        });
+        (0, vitest_1.it)('should use projectRoot as targetDir when targetDir is not specified', async () => {
+            const engine = new engine_js_1.SyncEngine();
+            const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
+            await fs_extra_1.default.writeFile(agentsPath, '# Agent Context');
+            await engine.sync(tempDir, 'claude');
+            const claudeInSource = path_1.default.join(tempDir, 'CLAUDE.md');
+            (0, vitest_1.expect)(await fs_extra_1.default.pathExists(claudeInSource)).toBe(true);
+        });
+    });
 });

package/dist/index.js

@@ -7,6 +7,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
 const engine_js_1 = require("./engine.js");
 const path_1 = __importDefault(require("path"));
+const inquirer_1 = __importDefault(require("inquirer"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const constants_js_1 = require("./constants.js");
 const program = new commander_1.Command();
 program
     .name('ai-context-sync')
@@ -15,13 +18,63 @@ program
 program
     .command('sync')
     .description('Synchronize context files from AGENTS.md')
-    .option('-d, --dir <path>', 'Project directory', process.cwd())
+    .option('-d, --dir <path>', 'Project directory (where AGENTS.md lives)', process.cwd())
+    .option('-t, --target-dir <path>', 'Target directory where synced files will be written (defaults to --dir)')
+    .option('-s, --strategy <strategy>', 'Sync strategy (claude, gemini, all, or comma-separated list)')
+    .option('--skip-config', 'Avoid reading/creating the config file', false)
     .action(async (options) => {
     try {
-        const engine = new engine_js_1.SyncEngine();
         const projectRoot = path_1.default.resolve(options.dir);
-        await engine.sync(projectRoot);
-        console.log('Successfully synchronized context files!');
+        const targetDir = options.targetDir ? path_1.default.resolve(options.targetDir) : projectRoot;
+        const configPath = path_1.default.join(projectRoot, constants_js_1.CONFIG_FILENAME);
+        let strategy = options.strategy;
+        // 1. If no strategy provided, try to read from config
+        if (!strategy && !options.skipConfig) {
+            if (await fs_extra_1.default.pathExists(configPath)) {
+                try {
+                    const config = await fs_extra_1.default.readJson(configPath);
+                    if (config.strategies) {
+                        strategy = config.strategies;
+                    }
+                }
+                catch (e) {
+                    // Ignore corrupted config and proceed to prompt
+                }
+            }
+        }
+        // 2. If still no strategy, prompt user
+        if (!strategy) {
+            const answers = await inquirer_1.default.prompt([
+                {
+                    type: 'checkbox',
+                    name: 'strategies',
+                    message: 'Select the AI context files to sync:',
+                    choices: [
+                        { name: 'Claude (CLAUDE.md)', value: 'claude', checked: true },
+                        { name: 'Gemini (.gemini/settings.json)', value: 'gemini', checked: true },
+                        { name: 'Gemini Markdown (GEMINI.md)', value: 'gemini-md', checked: true }
+                    ],
+                    validate: (answer) => {
+                        if (answer.length < 1) {
+                            return 'You must choose at least one strategy.';
+                        }
+                        return true;
+                    }
+                }
+            ]);
+            strategy = answers.strategies;
+        }
+        else if (typeof strategy === 'string') {
+            strategy = strategy.split(',').map(s => s.trim());
+        }
+        // 3. Save strategy to config if not skipping
+        if (!options.skipConfig) {
+            await fs_extra_1.default.writeJson(configPath, { strategies: strategy }, { spaces: 2 });
+        }
+        const engine = new engine_js_1.SyncEngine();
+        await engine.sync(projectRoot, strategy, targetDir);
+        const strategyMsg = Array.isArray(strategy) ? strategy.join(', ') : strategy;
+        console.log(`Successfully synchronized context files using "${strategyMsg}"!`);
     }
     catch (error) {
         console.error(`Error: ${error.message}`);

package/dist/strategies/claude.js

@@ -1,31 +1,9 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClaudeStrategy = void 0;
-const index_js_1 = require("./index.js");
-const fs_extra_1 = __importDefault(require("fs-extra"));
-const path_1 = __importDefault(require("path"));
-class ClaudeStrategy {
+const symlink_js_1 = require("./symlink.js");
+class ClaudeStrategy extends symlink_js_1.SymlinkStrategy {
     name = 'claude';
-    async sync(_context, projectRoot) {
-        const claudePath = path_1.default.join(projectRoot, 'CLAUDE.md');
-        // Check if it exists and what type it is
-        if (await fs_extra_1.default.pathExists(claudePath)) {
-            const stats = await fs_extra_1.default.lstat(claudePath);
-            if (stats.isSymbolicLink()) {
-                const target = await fs_extra_1.default.readlink(claudePath);
-                if (target === index_js_1.AGENTS_FILE) {
-                    // Already points to AGENTS.md, nothing to do
-                    return;
-                }
-            }
-            // If it's a file or a link to somewhere else, remove it
-            await fs_extra_1.default.remove(claudePath);
-        }
-        // Create relative symlink
-        await fs_extra_1.default.ensureSymlink(index_js_1.AGENTS_FILE, claudePath);
-    }
+    targetFilename = 'CLAUDE.md';
 }
 exports.ClaudeStrategy = ClaudeStrategy;

package/dist/strategies/claude.test.js

@@ -28,26 +28,4 @@ const os_1 = __importDefault(require("os"));
         const target = await fs_extra_1.default.readlink(claudePath);
         (0, vitest_1.expect)(target).toBe(constants_js_1.AGENTS_FILENAME);
     });
-    (0, vitest_1.it)('should replace existing file with a symbolic link', async () => {
-        const strategy = new claude_js_1.ClaudeStrategy();
-        const claudePath = path_1.default.join(tempDir, 'CLAUDE.md');
-        await fs_extra_1.default.writeFile(claudePath, 'old content');
-        await strategy.sync('# Agents', tempDir);
-        const stats = await fs_extra_1.default.lstat(claudePath);
-        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
-    });
-    (0, vitest_1.it)('should not recreate the link if it already exists and points to AGENTS.md', async () => {
-        const strategy = new claude_js_1.ClaudeStrategy();
-        const claudePath = path_1.default.join(tempDir, 'CLAUDE.md');
-        const agentsPath = path_1.default.join(tempDir, constants_js_1.AGENTS_FILENAME);
-        await fs_extra_1.default.writeFile(agentsPath, '# Agents');
-        await fs_extra_1.default.ensureSymlink(constants_js_1.AGENTS_FILENAME, claudePath);
-        const statsBefore = await fs_extra_1.default.lstat(claudePath);
-        const mtimeBefore = statsBefore.mtimeMs;
-        await new Promise(resolve => setTimeout(resolve, 10));
-        await strategy.sync('# Agents', tempDir);
-        const statsAfter = await fs_extra_1.default.lstat(claudePath);
-        const mtimeAfter = statsAfter.mtimeMs;
-        (0, vitest_1.expect)(mtimeAfter).toBe(mtimeBefore);
-    });
 });

package/dist/strategies/gemini-md.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeminiMdStrategy = void 0;
+const symlink_js_1 = require("./symlink.js");
+class GeminiMdStrategy extends symlink_js_1.SymlinkStrategy {
+    name = 'gemini-md';
+    targetFilename = 'GEMINI.md';
+}
+exports.GeminiMdStrategy = GeminiMdStrategy;

package/dist/strategies/gemini-md.test.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const gemini_md_js_1 = require("./gemini-md.js");
+const index_js_1 = require("./index.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+(0, vitest_1.describe)('GeminiMdStrategy', () => {
+    let tempDir;
+    let strategy;
+    (0, vitest_1.beforeEach)(async () => {
+        tempDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'gemini-md-strategy-test-'));
+        await fs_extra_1.default.writeFile(path_1.default.join(tempDir, index_js_1.AGENTS_FILE), '# Agents');
+        strategy = new gemini_md_js_1.GeminiMdStrategy();
+    });
+    (0, vitest_1.afterEach)(async () => {
+        await fs_extra_1.default.remove(tempDir);
+    });
+    (0, vitest_1.it)('should create a symbolic link GEMINI.md pointing to AGENTS.md', async () => {
+        await strategy.sync('', tempDir);
+        const targetPath = path_1.default.join(tempDir, 'GEMINI.md');
+        const stats = await fs_extra_1.default.lstat(targetPath);
+        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        (0, vitest_1.expect)(target).toBe(index_js_1.AGENTS_FILE);
+    });
+});

package/dist/strategies/gemini.js

@@ -9,9 +9,13 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 class GeminiStrategy {
     name = 'gemini';
-    async sync(_context, projectRoot) {
-        const geminiDir = path_1.default.join(projectRoot, '.gemini');
+    async sync(_context, projectRoot, targetDir) {
+        const outputDir = targetDir ?? projectRoot;
+        const geminiDir = path_1.default.join(outputDir, '.gemini');
         const settingsPath = path_1.default.join(geminiDir, 'settings.json');
+        // Compute the path to AGENTS.md relative to the target .gemini directory
+        const agentsAbsPath = path_1.default.join(projectRoot, index_js_1.AGENTS_FILE);
+        const agentsRelativePath = path_1.default.relative(outputDir, agentsAbsPath);
         await fs_extra_1.default.ensureDir(geminiDir);
         let settings = {};
         let exists = false;
@@ -30,19 +34,19 @@ class GeminiStrategy {
         const currentFiles = settings.context.fileName;
         let modified = false;
         if (Array.isArray(currentFiles)) {
-            if (!currentFiles.includes(index_js_1.AGENTS_FILE)) {
-                settings.context.fileName = [...currentFiles, index_js_1.AGENTS_FILE];
+            if (!currentFiles.includes(agentsRelativePath)) {
+                settings.context.fileName = [...currentFiles, agentsRelativePath];
                 modified = true;
             }
         }
         else if (typeof currentFiles === 'string') {
-            if (currentFiles !== index_js_1.AGENTS_FILE) {
-                settings.context.fileName = [currentFiles, index_js_1.AGENTS_FILE];
+            if (currentFiles !== agentsRelativePath) {
+                settings.context.fileName = [currentFiles, agentsRelativePath];
                 modified = true;
             }
         }
         else {
-            settings.context.fileName = [index_js_1.AGENTS_FILE];
+            settings.context.fileName = [agentsRelativePath];
             modified = true;
         }
         if (modified || !exists) {

package/dist/strategies/gemini.test.js

@@ -83,6 +83,21 @@ const os_1 = __importDefault(require("os"));
         const mtimeAfter = (await fs_extra_1.default.stat(settingsPath)).mtimeMs;
         (0, vitest_1.expect)(mtimeAfter).toBe(mtimeBefore);
     });
+    (0, vitest_1.it)('should not write to settings.json if fileName is already AGENTS.md as a string', async () => {
+        const strategy = new gemini_js_1.GeminiStrategy();
+        const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');
+        await fs_extra_1.default.ensureDir(path_1.default.dirname(settingsPath));
+        await fs_extra_1.default.writeJson(settingsPath, {
+            context: {
+                fileName: constants_js_1.AGENTS_FILENAME
+            }
+        });
+        const mtimeBefore = (await fs_extra_1.default.stat(settingsPath)).mtimeMs;
+        await new Promise(resolve => setTimeout(resolve, 10));
+        await strategy.sync('context', tempDir);
+        const mtimeAfter = (await fs_extra_1.default.stat(settingsPath)).mtimeMs;
+        (0, vitest_1.expect)(mtimeAfter).toBe(mtimeBefore);
+    });
     (0, vitest_1.it)('should handle invalid JSON in settings.json by starting fresh', async () => {
         const strategy = new gemini_js_1.GeminiStrategy();
         const settingsPath = path_1.default.join(tempDir, '.gemini', 'settings.json');

package/dist/strategies/symlink.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SymlinkStrategy = void 0;
+const index_js_1 = require("./index.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+class SymlinkStrategy {
+    async sync(_context, projectRoot, targetDir) {
+        const outputDir = targetDir ?? projectRoot;
+        const targetPath = path_1.default.join(outputDir, this.targetFilename);
+        // Compute the symlink value: relative path from outputDir to the AGENTS.md in projectRoot
+        const agentsAbsPath = path_1.default.join(projectRoot, index_js_1.AGENTS_FILE);
+        const symlinkTarget = path_1.default.relative(outputDir, agentsAbsPath);
+        // Check if it exists and what type it is
+        if (await fs_extra_1.default.pathExists(targetPath)) {
+            const stats = await fs_extra_1.default.lstat(targetPath);
+            if (stats.isSymbolicLink()) {
+                const existingTarget = await fs_extra_1.default.readlink(targetPath);
+                if (existingTarget === symlinkTarget) {
+                    // Already points to the correct location, nothing to do
+                    return;
+                }
+            }
+            // If it's a file or a link to somewhere else, remove it
+            await fs_extra_1.default.remove(targetPath);
+        }
+        // Create symlink pointing to AGENTS.md
+        await fs_extra_1.default.ensureSymlink(symlinkTarget, targetPath);
+    }
+}
+exports.SymlinkStrategy = SymlinkStrategy;

package/dist/strategies/symlink.test.js

@@ -0,0 +1,101 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const symlink_js_1 = require("./symlink.js");
+const index_js_1 = require("./index.js");
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+class TestSymlinkStrategy extends symlink_js_1.SymlinkStrategy {
+    name = 'test';
+    targetFilename = 'TEST.md';
+}
+(0, vitest_1.describe)('SymlinkStrategy', () => {
+    let tempDir;
+    let strategy;
+    (0, vitest_1.beforeEach)(async () => {
+        tempDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'symlink-strategy-test-'));
+        await fs_extra_1.default.writeFile(path_1.default.join(tempDir, index_js_1.AGENTS_FILE), '# Agents');
+        strategy = new TestSymlinkStrategy();
+    });
+    (0, vitest_1.afterEach)(async () => {
+        await fs_extra_1.default.remove(tempDir);
+    });
+    (0, vitest_1.it)('should create a symlink to AGENTS.md', async () => {
+        await strategy.sync('', tempDir);
+        const targetPath = path_1.default.join(tempDir, 'TEST.md');
+        const stats = await fs_extra_1.default.lstat(targetPath);
+        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        // It might be absolute or relative depending on environment/implementation
+        (0, vitest_1.expect)(target).toContain(index_js_1.AGENTS_FILE);
+    });
+    (0, vitest_1.it)('should not recreate symlink if it already points to AGENTS.md', async () => {
+        const targetPath = path_1.default.join(tempDir, 'TEST.md');
+        await fs_extra_1.default.ensureSymlink(index_js_1.AGENTS_FILE, targetPath);
+        // Get initial mtime
+        const initialStats = await fs_extra_1.default.lstat(targetPath);
+        await strategy.sync('', tempDir);
+        const finalStats = await fs_extra_1.default.lstat(targetPath);
+        (0, vitest_1.expect)(finalStats.mtimeMs).toBe(initialStats.mtimeMs);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        (0, vitest_1.expect)(target).toBe(index_js_1.AGENTS_FILE);
+    });
+    (0, vitest_1.it)('should recreate symlink if it points elsewhere', async () => {
+        const targetPath = path_1.default.join(tempDir, 'TEST.md');
+        const otherFile = path_1.default.join(tempDir, 'OTHER.md');
+        await fs_extra_1.default.writeFile(otherFile, 'other content');
+        await fs_extra_1.default.ensureSymlink('OTHER.md', targetPath);
+        await strategy.sync('', tempDir);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        (0, vitest_1.expect)(target).toBe(index_js_1.AGENTS_FILE);
+    });
+    (0, vitest_1.it)('should replace existing file with a symlink', async () => {
+        const targetPath = path_1.default.join(tempDir, 'TEST.md');
+        await fs_extra_1.default.writeFile(targetPath, 'existing file');
+        await strategy.sync('', tempDir);
+        const stats = await fs_extra_1.default.lstat(targetPath);
+        (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+        const target = await fs_extra_1.default.readlink(targetPath);
+        (0, vitest_1.expect)(target).toBe(index_js_1.AGENTS_FILE);
+    });
+    (0, vitest_1.describe)('targetDir option', () => {
+        let targetDir;
+        (0, vitest_1.beforeEach)(async () => {
+            targetDir = await fs_extra_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), 'symlink-strategy-target-'));
+        });
+        (0, vitest_1.afterEach)(async () => {
+            await fs_extra_1.default.remove(targetDir);
+        });
+        (0, vitest_1.it)('should create symlink in targetDir pointing to AGENTS.md in projectRoot', async () => {
+            await strategy.sync('', tempDir, targetDir);
+            const targetPath = path_1.default.join(targetDir, 'TEST.md');
+            const stats = await fs_extra_1.default.lstat(targetPath);
+            (0, vitest_1.expect)(stats.isSymbolicLink()).toBe(true);
+            // Symlink should resolve to the actual AGENTS.md in projectRoot
+            const resolvedPath = await fs_extra_1.default.realpath(targetPath);
+            const expectedPath = await fs_extra_1.default.realpath(path_1.default.join(tempDir, index_js_1.AGENTS_FILE));
+            (0, vitest_1.expect)(resolvedPath).toBe(expectedPath);
+        });
+        (0, vitest_1.it)('should not recreate symlink if it already points to the correct location', async () => {
+            const targetPath = path_1.default.join(targetDir, 'TEST.md');
+            const agentsAbsPath = path_1.default.join(tempDir, index_js_1.AGENTS_FILE);
+            const symlinkTarget = path_1.default.relative(targetDir, agentsAbsPath);
+            await fs_extra_1.default.ensureSymlink(symlinkTarget, targetPath);
+            const initialStats = await fs_extra_1.default.lstat(targetPath);
+            await strategy.sync('', tempDir, targetDir);
+            const finalStats = await fs_extra_1.default.lstat(targetPath);
+            (0, vitest_1.expect)(finalStats.mtimeMs).toBe(initialStats.mtimeMs);
+        });
+        (0, vitest_1.it)('should write to projectRoot when targetDir is not provided', async () => {
+            await strategy.sync('', tempDir);
+            const targetPath = path_1.default.join(tempDir, 'TEST.md');
+            (0, vitest_1.expect)(await fs_extra_1.default.pathExists(targetPath)).toBe(true);
+            const targetPathInTargetDir = path_1.default.join(targetDir, 'TEST.md');
+            (0, vitest_1.expect)(await fs_extra_1.default.pathExists(targetPathInTargetDir)).toBe(false);
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dezkareid/ai-context-sync",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "CLI utility to synchronize AI agent context files from AGENTS.md",
   "main": "dist/index.js",
   "bin": {
@@ -36,10 +36,12 @@
   "dependencies": {
     "commander": "12.0.0",
     "fs-extra": "11.2.0",
-    "globby": "14.0.1"
+    "globby": "14.0.1",
+    "inquirer": "9.2.12"
   },
   "devDependencies": {
     "@types/fs-extra": "11.0.4",
+    "@types/inquirer": "9.0.7",
     "@types/node": "25.0.10",
     "@vitest/coverage-v8": "4.0.18",
     "typescript": "5.9.3",