Implement PR review feedback and add /track skill

Code improvements from Copilot review:
- history.ts: Scan workspace for changes when creating manual checkpoint
- track.ts: Use consistent ISO timestamp format, add mutex for race conditions, add Linux fs.watch warning
- stop.ts: Use more specific grep pattern to avoid false positives
- profile.ts: Remove unused variable
- profile-manager.ts: Add REALM_SERVER_URL derivation from MATRIX_URL
- index.ts: Add password security warning, clarify env var requirements, add track/stop examples

Documentation updates:
- Add new /track skill for Claude Code
- Update CLAUDE.md with /track skill and track→sync workflow
- Update README.md to emphasize that track requires sync to push changes

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: 2 people

.claude/CLAUDE.md

@@ -99,6 +99,12 @@ npx boxel profile switch username   # Switch by partial match
 
 ## Available Skills
 
+### `/track` - Track Local Edits
+Starts `boxel track` to auto-checkpoint local file changes:
+- Creates checkpoints as you save files in IDE
+- **IMPORTANT:** Track creates LOCAL checkpoints only
+- **After editing, run `boxel sync . --prefer-local` to push to server**
+
 ### `/watch` - Smart Watch
 Starts `boxel watch` with intelligent interval based on context:
 - **Active development** (5s interval, 3s debounce): When editing files
@@ -114,7 +120,7 @@ Complete restore workflow:
 
 ### `/sync` - Smart Sync
 Context-aware bidirectional sync:
-- After local edits → `--prefer-local`
+- After local edits or track → `--prefer-local`
 - After server changes → `--prefer-remote`
 - After restore → `--prefer-local` (essential for syncing deletions)
 
@@ -268,7 +274,19 @@ boxel skills --export .      # Re-export to .claude/commands/
 
 ## Key Workflows
 
-### Active Development Session
+### Local Development with Track (IDE/Agent Editing)
+```bash
+boxel track .                     # Start tracking local edits (auto-checkpoints)
+# ... edit files in IDE or with Claude ...
+# Track creates LOCAL checkpoints as you save
+
+# IMPORTANT: When ready to push changes to Boxel server:
+boxel sync . --prefer-local       # Push your local changes to server
+```
+
+**Remember:** Track does NOT sync to server automatically - it only creates local checkpoints. Always run `sync --prefer-local` when you want your changes live on the server.
+
+### Active Development Session (Watching Server)
 ```bash
 /watch                            # Starts with 5s interval
 # ... edit in Boxel UI or locally ...

.claude/commands/track.md

@@ -0,0 +1,84 @@
+# Track Skill
+
+Start `boxel track` to monitor local file changes and create checkpoints automatically.
+
+## When to Use Track
+
+Use **track** when you're editing files locally (in IDE, with AI agent, etc.) and want automatic backups:
+- Working in VS Code, Cursor, or other IDE
+- AI agent is editing files
+- You want checkpoint history of your work
+
+**Track vs Watch:**
+| Command | Symbol | Direction | Purpose |
+|---------|--------|-----------|---------|
+| `track` | ⇆ | Local edits → Checkpoints | Backup your work as you edit |
+| `watch` | ⇅ | Server → Local | Pull external changes from Boxel UI |
+
+## Commands
+
+```bash
+# Start tracking (default: 3s debounce, 10s min interval)
+boxel track .
+
+# Custom timing (5s debounce, 30s between checkpoints)
+boxel track . -d 5 -i 30
+
+# Quiet mode (only show checkpoints)
+boxel track . -q
+
+# Stop all track/watch processes
+boxel stop
+```
+
+## The Track → Sync Workflow
+
+**IMPORTANT:** Track only creates local checkpoints. To push changes to the Boxel server:
+
+```bash
+# 1. Track creates checkpoints as you edit
+boxel track .
+
+# 2. When ready to push to server, sync with --prefer-local
+boxel sync . --prefer-local
+```
+
+Track does NOT automatically sync to the server. This is intentional - it lets you:
+- Work offline with local backups
+- Batch multiple edits before pushing
+- Review changes before they go live
+
+## Context Detection
+
+When invoked, consider:
+
+### Standard Development (3s debounce, 10s interval)
+- Normal editing workflow
+- Balanced between checkpoint frequency and overhead
+
+### Fast Iteration (2s debounce, 5s interval)
+- Rapid prototyping
+- User says "track closely" or "capture everything"
+
+### Background Tracking (5s debounce, 30s interval)
+- Long editing sessions
+- User says "just backup" or "light tracking"
+
+## Response Format
+
+When invoked:
+1. Confirm workspace directory
+2. Start track with appropriate settings
+3. **Remind user to sync when ready to push changes**
+
+Example:
+```
+Starting track in the current workspace (3s debounce, 10s interval).
+Checkpoints will be created automatically as you save files.
+
+Remember: Track creates LOCAL checkpoints only.
+When ready to push changes to Boxel server:
+  boxel sync . --prefer-local
+
+Use Ctrl+C to stop tracking, or `boxel stop` from another terminal.
+```

README.md

@@ -301,9 +301,14 @@ boxel skills --export .           # Export to .claude/commands/
 boxel track .                     # Start tracking local edits
 # In another terminal or IDE, edit files...
 # Checkpoints created automatically as you save
+
+# IMPORTANT: Track creates LOCAL checkpoints only!
+# When ready to push changes to Boxel server:
 boxel sync . --prefer-local       # Push changes to server
 ```
 
+**Remember:** `track` does NOT sync to server - it only creates local checkpoints for safety. Always run `sync --prefer-local` when you want your changes live.
+
 ### Active Development (with edit lock)
 ```bash
 boxel edit . my-card.gts          # Lock file (if watch is running)

src/commands/history.ts

@@ -1,7 +1,38 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import * as readline from 'readline';
-import { CheckpointManager, Checkpoint } from '../lib/checkpoint-manager.js';
+import { CheckpointManager, Checkpoint, CheckpointChange } from '../lib/checkpoint-manager.js';
+
+/**
+ * Scan workspace directory to build a changes array for manual checkpoints.
+ * Marks all current files as 'modified' since we're snapshotting the current state.
+ */
+function scanWorkspaceForChanges(workspaceDir: string): CheckpointChange[] {
+  const changes: CheckpointChange[] = [];
+
+  const scan = (dir: string, prefix = '') => {
+    if (!fs.existsSync(dir)) return;
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      // Skip internal files
+      if (entry.name.startsWith('.boxel-') || entry.name === '.git') continue;
+      if (entry.name.startsWith('.') && entry.name !== '.realm.json') continue;
+
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+      if (entry.isDirectory()) {
+        scan(fullPath, relativePath);
+      } else {
+        changes.push({ file: relativePath, status: 'modified' });
+      }
+    }
+  };
+
+  scan(workspaceDir);
+  return changes;
+}
 
 // ANSI escape codes for terminal control
 const ESC = '\x1b';
@@ -43,8 +74,9 @@ export async function historyCommand(
       manager.init();
     }
 
-    // Get current files to create a checkpoint of current state
-    const checkpoint = manager.createCheckpoint('manual', [], options.message);
+    // Scan workspace to get current files for the checkpoint
+    const changes = scanWorkspaceForChanges(workspaceDir);
+    const checkpoint = manager.createCheckpoint('manual', changes, options.message);
 
     if (checkpoint) {
       console.log(`${FG_GREEN}✓${RESET} ${FG_YELLOW}📍${RESET} Checkpoint created: ${FG_YELLOW}${checkpoint.shortHash}${RESET}`);

src/commands/profile.ts

@@ -158,7 +158,6 @@ async function listProfiles(manager: ProfileManager): Promise<void> {
     const profile = manager.getProfile(id)!;
     const isActive = id === activeId;
     const env = getEnvironmentFromMatrixId(id);
-    const username = getUsernameFromMatrixId(id);
 
     const marker = isActive ? `${FG_GREEN}★${RESET} ` : '  ';
     const envLabel = getEnvironmentShortLabel(env);

src/commands/stop.ts

@@ -21,8 +21,9 @@ export async function stopCommand(): Promise<void> {
   try {
     // Find boxel watch and track processes
     // Match both development mode (tsx src/index.ts) and installed mode (boxel or node...boxel)
+    // Use more specific pattern with word boundaries to avoid false positives
     const result = execSync(
-      `ps aux | grep -E '(tsx.*src/index.ts|boxel|node.*boxel).*(watch|track)' | grep -v grep | grep -v 'stop'`,
+      `ps aux | grep -E '(tsx[[:space:]].*src/index\\.ts[[:space:]]+(watch|track)|[[:space:]]boxel[[:space:]]+(watch|track)|node[[:space:]].*boxel[[:space:]]+(watch|track))' | grep -v grep | grep -v '[[:space:]]stop'`,
       { encoding: 'utf-8' }
     ).trim();
 

src/commands/track.ts

@@ -40,6 +40,7 @@ export async function trackCommand(
   let debounceTimer: NodeJS.Timeout | null = null;
   let pendingChanges = new Map<string, 'added' | 'modified' | 'deleted'>();
   let lastCheckpointTime = Date.now();
+  let isCheckingChanges = false; // Mutex to prevent concurrent checkForChanges calls
 
   // Initialize file states
   const initializeFileStates = (dir: string, prefix = '') => {
@@ -131,6 +132,18 @@ export async function trackCommand(
   };
 
   const checkForChanges = () => {
+    // Prevent concurrent execution (fs.watch and setInterval can trigger simultaneously)
+    if (isCheckingChanges) return;
+    isCheckingChanges = true;
+
+    try {
+      checkForChangesImpl();
+    } finally {
+      isCheckingChanges = false;
+    }
+  };
+
+  const checkForChangesImpl = () => {
     const currentFiles = new Map<string, { mtime: number; size: number }>();
 
     const scanDir = (dir: string, prefix = '') => {
@@ -214,11 +227,18 @@ export async function trackCommand(
   };
 
   // Use fs.watch for efficient file watching
+  // Note: recursive option is only supported on macOS and Windows.
+  // On Linux, we rely on the polling fallback (setInterval) below.
   const watchers: fs.FSWatcher[] = [];
+  const isLinux = process.platform === 'linux';
+
+  if (isLinux && !options.quiet) {
+    console.log(`   Note: On Linux, file watching uses polling only (fs.watch recursive not supported)\n`);
+  }
 
   const watchDir = (dir: string) => {
     try {
-      const watcher = fs.watch(dir, { recursive: true }, (eventType, filename) => {
+      const watcher = fs.watch(dir, { recursive: !isLinux }, (eventType, filename) => {
         if (!filename) return;
 
         // Skip internal files
@@ -276,5 +296,6 @@ export async function trackCommand(
 }
 
 function timestamp(): string {
-  return new Date().toLocaleTimeString();
+  const now = new Date();
+  return now.toISOString().substring(11, 19); // HH:MM:SS in UTC
 }

src/index.ts

@@ -329,14 +329,21 @@ program
   .option('-p, --password <password>', 'Password (for add command)')
   .option('-n, --name <displayName>', 'Display name (for add command)')
   .action(async (subcommand?: string, arg?: string, options?: { user?: string; password?: string; name?: string }) => {
+    if (options?.password) {
+      console.warn(
+        'Warning: Supplying a password via -p/--password may expose it in shell history and process listings. ' +
+        'For non-interactive usage, prefer the BOXEL_PASSWORD environment variable or use "boxel profile add" interactively.',
+      );
+    }
     await profileCommand(subcommand, arg, options);
   });
 
 // Add help text for environment variables
 program.addHelpText('after', `
 Authentication:
   Use 'boxel profile' to manage saved credentials (recommended)
-  Or set environment variables: MATRIX_URL, MATRIX_USERNAME, MATRIX_PASSWORD, REALM_SERVER_URL
+  Or set all environment variables (all required):
+    MATRIX_URL, MATRIX_USERNAME, MATRIX_PASSWORD, REALM_SERVER_URL
 
 Workspace References:
   .                  Current directory (must have .boxel-sync.json)
@@ -364,6 +371,11 @@ Examples:
   boxel watch . -i 10              Check every 10 seconds
   boxel watch . -q                 Quiet mode (only show changes)
 
+  boxel track .                    Track local edits, auto-checkpoint
+  boxel track . -d 5 -i 30         5s debounce, 30s min between checkpoints
+
+  boxel stop                       Stop all running watch/track processes
+
   boxel pull https://... ./local   One-way pull (for read-only realms)
 
   boxel touch .                    Touch all files to force re-indexing

src/lib/profile-manager.ts

@@ -258,16 +258,36 @@ export class ProfileManager {
     const matrixUrl = process.env.MATRIX_URL;
     const username = process.env.MATRIX_USERNAME;
     const password = process.env.MATRIX_PASSWORD;
-    const realmServerUrl = process.env.REALM_SERVER_URL;
+    let realmServerUrl = process.env.REALM_SERVER_URL;
+
+    if (matrixUrl && username && password) {
+      // Derive realm server URL from Matrix URL if not explicitly set
+      if (!realmServerUrl) {
+        try {
+          const matrixUrlObj = new URL(matrixUrl);
+          // Common pattern: matrix.X.Y -> app.X.Y or matrix-staging.X.Y -> realms-staging.X.Y
+          if (matrixUrlObj.hostname.startsWith('matrix.')) {
+            realmServerUrl = `${matrixUrlObj.protocol}//app.${matrixUrlObj.hostname.slice(7)}/`;
+          } else if (matrixUrlObj.hostname.startsWith('matrix-staging.')) {
+            realmServerUrl = `${matrixUrlObj.protocol}//realms-staging.${matrixUrlObj.hostname.slice(15)}/`;
+          } else if (matrixUrlObj.hostname.startsWith('matrix-')) {
+            // matrix-X.Y.Z -> X.Y.Z (generic fallback)
+            realmServerUrl = `${matrixUrlObj.protocol}//${matrixUrlObj.hostname.slice(7)}/`;
+          }
+        } catch {
+          // Invalid URL, will return null below
+        }
+      }
 
-    if (matrixUrl && username && password && realmServerUrl) {
-      return {
-        matrixUrl,
-        username,
-        password,
-        realmServerUrl,
-        profileId: null,
-      };
+      if (realmServerUrl) {
+        return {
+          matrixUrl,
+          username,
+          password,
+          realmServerUrl,
+          profileId: null,
+        };
+      }
     }
 
     return null;