feat: portable settings sync across machines via GitHub

CLAUDE.md

@@ -20,7 +20,8 @@ src/
     jsonl-session-watcher.ts  # Polls JSONL to detect sub-agent spawns
     plan-task-detector.ts     # Regex-based plan/task extraction from terminal output
     claude-session-scanner.ts # Discovers sessions from ~/.claude
-    settings-manager.ts       # Persistent user preferences
+    settings-manager.ts       # Persistent user preferences (AppPreferences type)
+    sync-engine.ts            # Git-based settings sync (GitHub repo, profiles)
   preload/
     preload.ts           # Context bridge (window.agentPlex API)
   renderer/              # React app
@@ -34,6 +35,8 @@ src/
       TerminalPanel.tsx  # xterm.js terminal view
       SendDialog.tsx     # Cross-session messaging with optional AI summarization
       ProjectLauncher.tsx # Modal for discovering & resuming sessions
+      SettingsPanel.tsx  # JSON editor for settings, sync controls, profiles
+      SyncConflictDialog.tsx # Monaco diff for sync conflict resolution
       Toolbar.tsx        # Top menu bar
   shared/                # Shared between main & renderer
     ipc-channels.ts      # IPC channel constants & types
@@ -54,6 +57,8 @@ src/
 ```bash
 pnpm install    # Install dependencies
 pnpm start      # Dev mode with HMR
+pnpm test       # Run tests (vitest)
+pnpm test:watch # Run tests in watch mode
 pnpm lint       # ESLint
 pnpm package    # Package standalone app
 pnpm make       # Build installer (.exe/.dmg/.deb)
@@ -66,3 +71,31 @@ pnpm make       # Build installer (.exe/.dmg/.deb)
 - **Plan/Task**: Claude CLI plan mode with individual tasks, parsed from terminal output
 - **Group**: Container node created by dragging sessions together on the canvas
 - **External Session**: Claude CLI sessions running outside AgentPlex, discoverable and adoptable
+- **Settings Sync**: Git-based sync of preferences + Claude config across machines via a private GitHub repo, with profile support
+- **Profile**: A named set of preferences + Claude config (default, work, personal, etc.) stored as folders in the sync repo
+
+## Development Guidelines
+
+### Testing (TDD)
+- **All new features and bug fixes must have tests written first** (red-green-refactor).
+- Test framework: **vitest** (`pnpm test` / `pnpm test:watch`).
+- Test files live next to the module they test: `foo.ts` -> `foo.test.ts`.
+- Main process code (settings-manager, sync-engine, etc.) is tested with temp directories and mocked `os.homedir()` / `electron`.
+- Tests that interact with git use real bare repos in temp dirs — no mocking git itself.
+- Run `pnpm test` and `npx tsc --noEmit` before considering any change complete.
+
+### User-Configurable Settings
+- **All user preferences and configurable values must be stored in `~/.agentplex/settings.json`** via `settings-manager.ts` (`updateSettings` / `getAllSettings`).
+- Never hardcode user-facing defaults without a settings.json fallback. Read from `loadSettings()` first, fall back to a `DEFAULT_*` constant.
+- The `AppPreferences` interface in `settings-manager.ts` uses `[key: string]: unknown` for extensibility — new settings do not require a migration.
+- Settings are exposed to the renderer via the JSON editor in the Settings panel. Any new setting automatically appears there.
+- Sync-related config (repo URL, active profile, claude include list) also lives in settings.json under `sync*` keys.
+- The `syncClaudeIncludes` array controls which files/dirs from `~/.claude/` get synced. Default: `["CLAUDE.md", "settings.json", "agents", "commands", "plugins"]`.
+
+### IPC Pattern
+When adding a new feature that spans main + renderer:
+1. Add types to `shared/ipc-channels.ts`
+2. Add IPC channel constant to the `IPC` object
+3. Add handler in `main/ipc-handlers.ts`
+4. Add preload bridge method in `preload/preload.ts`
+5. Add type to `AgentPlexAPI` in `renderer/types.ts`

package.json

@@ -28,6 +28,8 @@
   "scripts": {
     "generate-icons": "node scripts/generate-icons.mjs",
     "postinstall": "node -e \"try{require('fs').chmodSync(require('path').join('node_modules','node-pty','prebuilds',process.platform+'-'+process.arch,'spawn-helper'),0o755)}catch{}\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "lint": "eslint src/",
     "start": "electron-forge start",
     "package": "pnpm generate-icons && electron-forge package",
@@ -66,6 +68,7 @@
     "sharp": "^0.34.5",
     "typescript": "^6.0.2",
     "typescript-eslint": "^8.57.2",
-    "vite": "^8.0.3"
+    "vite": "^8.0.3",
+    "vitest": "^4.1.2"
   }
 }