feat: multi-machines supported

chore

chore: add author info to package.json files

test: add test cases for muti-machines

chore

Author: dinhanhthi

README.md

@@ -14,6 +14,7 @@ Centralized management tool for AI configuration files across Git repositories a
 - A **central store** (a separate git repo you choose) holds all AI config files, organized by repository and service
 - A **sync engine** watches for changes on both sides and syncs automatically using **git 3-way merge** — non-conflicting changes are auto-merged
 - **AI service configs** (e.g., Claude Code's `~/.claude/`) can be synced with predefined file patterns — no manual path browsing needed
+- **Multi-machine support** — each machine gets a unique identity; a git-tracked `machines.json` maps repo paths per machine, so the same store works across machines with different directory layouts. Repos are auto-linked on startup
 - A **web UI** lets you manage repos, services, edit files, and resolve conflicts
 - AI files are automatically **git-ignored** and **removed from git tracking** in target repos
 - **App code and user data are fully separated** — update the tool without affecting your data
@@ -50,6 +51,7 @@ Open http://localhost:2703
 
 ```
 <your-data-dir>/              # Git repo (you chose this path)
+├── machines.json             # Machine-to-path mappings (git-tracked)
 ├── repos/
 │   ├── _default/             # Template for new repos
 │   ├── my-project/           # AI files for my-project
@@ -74,7 +76,9 @@ cd ai-sync
 pnpm install && pnpm build && pnpm start
 ```
 
-On the setup screen, point to your existing data directory (clone your store repo first if needed). Attach your locally-cloned repos via the UI — files sync automatically.
+On the setup screen, point to your existing data directory (clone your store repo first if needed).
+
+The app will automatically assign a machine identity and **auto-link** any repos that already have a path mapping for this machine in `machines.json`. Repos that can't be auto-linked appear as **Unlinked Repositories** on the dashboard — click **Link** to map them to local paths, **Auto-link All** to link everything at once, or the **trash icon** to remove repos you no longer need.
 
 ## Development
 

docs/changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## v1.6.0 - Multi-machine support
+
+- **New:** Multi-machine support — each machine gets a unique ID and name, stored in local config (`~/.ai-sync/config.json`)
+- **New:** Git-tracked `machines.json` in the store repo maps repo/service paths per machine, enabling cross-machine sync with different absolute paths
+- **New:** Auto-link on startup — repos with valid path mappings for the current machine are automatically registered in the local database
+- **New:** Unlinked repos detection — dashboard shows store repos that exist but aren't linked on the current machine, with manual link and auto-link options
+- **New:** Machine name displayed in the footer alongside the data directory
+- **New:** Settings "Machine" tab — edit machine name, view machine ID, see all known machines
+
 ## v1.5.1
 
 - **New:** Right-click "Delete" on file tree — deletes files/folders from both store and target repo, with empty parent directory cleanup

docs/how-to.md

@@ -118,11 +118,12 @@ The **Templates** page lets you define default AI config files for new repositor
 
 ## Configuring Settings
 
-The **Settings** page has three tabs:
+The **Settings** page has four tabs:
 
 - **General** — Sync interval, watch debounce, auto sync, and auto-commit options
 - **AI File Patterns** — Glob patterns that detect AI config files (add, remove, or toggle)
 - **Ignore Patterns** — Glob patterns to exclude files from sync (e.g., `.DS_Store`, `node_modules/**`). Use the **Clean** button to remove already-tracked files that match ignore patterns
+- **Machine** — View/edit machine name, copy machine ID, and see all known machines that share this store
 
 ### Per-Repository Settings
 
@@ -137,7 +138,38 @@ If your data directory is connected to a remote git repository, use the **Push c
 1. Clone this tool repository then run `pnpm install && pnpm build && pnpm start`, the app will start at [http://localhost:2703](http://localhost:2703) in your browser.
 2. Clone your store repository (data directory)
 3. On the setup screen, point to the cloned store directory
-4. Add your locally-cloned repos via the UI — files sync automatically
+4. The app will automatically:
+   - Assign a unique machine ID and name (based on hostname)
+   - Register this machine in `machines.json`
+   - Auto-link any repos that have known paths for this machine
+5. Repos that couldn't be auto-linked will appear as **Unlinked Repositories** on the dashboard — click **Link** to map them to local paths, or **Auto-link All** if paths are already mapped from another machine
+6. To remove an unlinked repo you no longer need, click the **trash icon** on its card to delete it from the store
+
+## Multi-Machine Workflow
+
+AI Sync supports using the same store across multiple machines, even when repos live at different paths on each machine.
+
+### How It Works
+
+- Each machine gets a **unique ID** (UUID) and a **name** (defaults to your hostname), stored locally in `~/.ai-sync/config.json`
+- A **`machines.json`** file in the store repo tracks which machine has which repo at which local path
+- When you add a repo on Machine A, the path mapping is saved in `machines.json`. When Machine B pulls the store, it can use that mapping to auto-link or manually link the repo
+
+### Managing Unlinked Repos
+
+When the store contains repos that aren't linked on the current machine, they appear in the **Unlinked Repositories** section on the dashboard:
+
+- **Auto-link All** — Automatically link all repos that have a valid path mapping for this machine
+- **Link** — Manually specify the local path for a specific repo
+- **Delete** — Remove the repo from the store entirely (trash icon on each card)
+
+### Machine Settings
+
+Go to **Settings → Machine** to:
+
+- **Edit machine name** — Change the display name for this machine
+- **View machine ID** — Copy the unique identifier for debugging
+- **See all machines** — List every machine that has ever connected to this store, with last-seen dates
 
 ## Keyboard Shortcuts
 

docs/intro.md

@@ -27,11 +27,12 @@ AI Sync provides a single-source-of-truth approach:
 1. **Central Store** — All AI config files are stored in a user-chosen directory (a separate git repo)
 2. **Automatic Sync** — A background service watches for file changes and syncs bidirectionally between the store and target repositories
 3. **AI Service Configs** — Sync local AI service settings (e.g., `~/.claude/` for Claude Code) with predefined file patterns — no manual path browsing needed
-4. **Web Admin UI** — A local web interface for managing repositories, editing files, resolving conflicts, and monitoring sync status
-5. **Portable** — Clone this tool on any machine, point it to your store directory, attach your repositories, and all AI configs sync automatically
-6. **Separated Data** — App code and user data live in different directories — update the tool without affecting your data
-7. **Symbolic Link Support** — Symlinks are properly detected, tracked, and synced between store and target repositories
-8. **Ignore Patterns** — Configurable glob patterns to exclude unwanted files (e.g., `.DS_Store`, `node_modules/**`) from sync
+4. **Multi-Machine Support** — Each machine gets a unique identity. A git-tracked `machines.json` maps repo paths per machine, so the same store works across machines with different directory structures. Repos are auto-linked on startup when valid path mappings exist
+5. **Web Admin UI** — A local web interface for managing repositories, editing files, resolving conflicts, and monitoring sync status
+6. **Portable** — Clone this tool on any machine, point it to your store directory, and repos with known paths are auto-linked. Unlinked repos can be manually linked via the dashboard
+7. **Separated Data** — App code and user data live in different directories — update the tool without affecting your data
+8. **Symbolic Link Support** — Symlinks are properly detected, tracked, and synced between store and target repositories
+9. **Ignore Patterns** — Configurable glob patterns to exclude unwanted files (e.g., `.DS_Store`, `node_modules/**`) from sync
 
 ## How Sync Works
 
@@ -57,6 +58,18 @@ When both sides changed:
 
 A checksum fast-path ensures git is only invoked when files actually differ, keeping the common case fast.
 
+## Multi-Machine Support
+
+When multiple machines share the same store repository (data directory) via git, each machine may have different absolute paths for the same repository (e.g., `/Users/thi/git/project` on a Mac vs `/home/thi/code/project` on Linux).
+
+AI Sync handles this with:
+
+- **Machine Identity** — Each machine gets a unique UUID and a human-readable name (defaults to hostname), stored in the local config (`~/.ai-sync/config.json`)
+- **`machines.json`** — A git-tracked file in the store repo that maps each repo/service to each machine's local path. All machines see each other's mappings through git sync
+- **Auto-linking** — On startup, if the store contains repos with known paths for the current machine, they are automatically registered in the local database and start syncing
+- **Unlinked repos** — The dashboard shows store repos that exist but aren't linked on the current machine, with options to link manually, auto-link, or delete from the store
+- **Machine settings** — View and edit the machine name, see the machine ID, and list all known machines in the Settings page
+
 ## Architecture Overview
 
 ```
@@ -75,7 +88,7 @@ A checksum fast-path ensures git is only invoked when files actually differ, kee
 │  └──────────────┘  └──────────────┘  └───────────────┘  │
 └─────────────────────────────────────────────────────────┘
             │                    │                │
-    ┌───────┴───────┐  ┌────────┴────────┐  ┌────┴────────────┐
+    ┌───────┴───────┐  ┌───-─────┴───────┐  ┌──-──┴───────────┐
     │     Store     │  │  Target Repos   │  │  AI Services    │
     │ (user chosen) │  │ /path/to/repo-1 │  │ ~/.claude/      │
     └───────────────┘  │ /path/to/repo-2 │  │ (Claude Code)   │

package.json

@@ -1,6 +1,8 @@
 {
   "name": "ai-sync",
-  "version": "1.5.1",
+  "author": "Anh-Thi Dinh",
+  "version": "1.6.0",
+  "repository": "https://github.com/anhthiding/ai-sync",
   "private": true,
   "license": "MIT",
   "description": "Centralized management tool for AI configuration files across Git repositories",

packages/server/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@ai-sync/server",
-  "version": "1.5.1",
+  "author": "Anh-Thi Dinh",
+  "version": "1.6.0",
+  "repository": "https://github.com/anhthiding/ai-sync",
   "private": true,
   "license": "MIT",
   "type": "module",

packages/server/src/app.ts

@@ -14,6 +14,7 @@ import { registerCloneRoutes } from './routes/clone.js';
 import { registerServiceRoutes } from './routes/services.js';
 import { registerSetupRoutes } from './routes/setup.js';
 import { registerVersionRoutes } from './routes/version.js';
+import { registerMachineRoutes } from './routes/machines.js';
 import { registerWsHandlers } from './ws/handlers.js';
 import type { AppState } from './app-state.js';
 
@@ -35,6 +36,7 @@ export async function buildApp(state: AppState) {
   registerTemplateRoutes(app, state);
   registerCloneRoutes(app, state);
   registerServiceRoutes(app, state);
+  registerMachineRoutes(app, state);
   registerVersionRoutes(app);
   registerWsHandlers(app, state);
 

packages/server/src/config.ts

@@ -2,6 +2,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import os from 'node:os';
+import { v4 as uuid } from 'uuid';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const projectRoot = path.resolve(__dirname, '..', '..', '..');
@@ -17,6 +18,8 @@ const LEGACY_CONFIG_FILE = path.join(LEGACY_CONFIG_DIR, 'config.json');
 
 interface AppConfig {
   dataDir: string;
+  machineId?: string;
+  machineName?: string;
 }
 
 function readAppConfig(): AppConfig | null {
@@ -29,7 +32,11 @@ function readAppConfig(): AppConfig | null {
       const raw = fs.readFileSync(configFile, 'utf-8');
       const parsed = JSON.parse(raw);
       if (parsed.dataDir && typeof parsed.dataDir === 'string') {
-        return { dataDir: parsed.dataDir };
+        return {
+          dataDir: parsed.dataDir,
+          machineId: parsed.machineId,
+          machineName: parsed.machineName,
+        };
       }
     } catch {
       // Config file doesn't exist, try next
@@ -38,6 +45,11 @@ function readAppConfig(): AppConfig | null {
   return null;
 }
 
+function writeAppConfig(appCfg: AppConfig): void {
+  fs.mkdirSync(APP_CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(APP_CONFIG_FILE, JSON.stringify(appCfg, null, 2), 'utf-8');
+}
+
 function buildDataPaths(dataDir: string) {
   // Use legacy DB name if it exists, otherwise use new name
   const legacyDbPath = path.join(dataDir, '.db', 'local-ai-stuffs.db');
@@ -68,6 +80,8 @@ export const config = {
   storeReposPath: dataPaths?.storeReposPath || '',
   storeServicesPath: dataPaths?.storeServicesPath || '',
   dbPath: dataPaths?.dbPath || '',
+  machineId: appConfig?.machineId || '',
+  machineName: appConfig?.machineName || '',
 };
 
 export function isConfigured(): boolean {
@@ -79,8 +93,13 @@ export function getDataDir(): string | null {
 }
 
 export function configure(dataDir: string): void {
-  fs.mkdirSync(APP_CONFIG_DIR, { recursive: true });
-  fs.writeFileSync(APP_CONFIG_FILE, JSON.stringify({ dataDir }, null, 2), 'utf-8');
+  const existing = readAppConfig();
+  const appCfg: AppConfig = {
+    dataDir,
+    machineId: existing?.machineId,
+    machineName: existing?.machineName,
+  };
+  writeAppConfig(appCfg);
 
   const paths = buildDataPaths(dataDir);
   config.dataDir = dataDir;
@@ -101,4 +120,34 @@ export function resetConfig(): void {
   config.storeReposPath = '';
   config.storeServicesPath = '';
   config.dbPath = '';
+  config.machineId = '';
+  config.machineName = '';
+}
+
+export function ensureMachineId(): void {
+  const appCfg = readAppConfig();
+  if (!appCfg) return;
+
+  let changed = false;
+  if (!appCfg.machineId) {
+    appCfg.machineId = uuid();
+    changed = true;
+  }
+  if (!appCfg.machineName) {
+    appCfg.machineName = os.hostname();
+    changed = true;
+  }
+  if (changed) {
+    writeAppConfig(appCfg);
+  }
+  config.machineId = appCfg.machineId;
+  config.machineName = appCfg.machineName!;
+}
+
+export function updateMachineName(name: string): void {
+  const appCfg = readAppConfig();
+  if (!appCfg) return;
+  appCfg.machineName = name;
+  writeAppConfig(appCfg);
+  config.machineName = name;
 }

packages/server/src/index.ts

@@ -1,8 +1,9 @@
 import { buildApp } from './app.js';
 import { initDb } from './db/index.js';
-import { config, isConfigured } from './config.js';
-import { initStoreRepo } from './services/store-git.js';
+import { config, isConfigured, ensureMachineId } from './config.js';
+import { initStoreRepo, commitStoreChanges } from './services/store-git.js';
 import { SyncEngine } from './services/sync-engine.js';
+import { registerCurrentMachine, seedMachinesFile, autoLinkRepos } from './services/machines.js';
 import type { AppState } from './app-state.js';
 
 async function main() {
@@ -11,12 +12,24 @@ async function main() {
   const state: AppState = { db: null, syncEngine: null };
 
   if (isConfigured()) {
+    ensureMachineId();
+
     state.db = initDb(config.dbPath);
     console.log(`Database initialized at ${config.dbPath}`);
 
     await initStoreRepo();
     console.log(`Store initialized at ${config.storePath}`);
 
+    // Register this machine and seed/auto-link repos
+    registerCurrentMachine();
+    seedMachinesFile(state.db);
+    const linkResults = await autoLinkRepos(state.db);
+    const linked = linkResults.filter((r) => r.status === 'linked');
+    if (linked.length > 0) {
+      console.log(`Auto-linked ${linked.length} repo(s) from machines.json`);
+    }
+    await commitStoreChanges(`Machine ${config.machineName} startup`);
+
     state.syncEngine = new SyncEngine(state.db);
   } else {
     console.log('Not configured yet — starting in setup mode');