docs: improve CLAUDE.md structure and discoverability

- Move COM shorthand to prominent position after safety warning
- Add version sync note (must match package.json)
- Consolidate Key Files into 4 logical categories
- Clarify next available test port (3128)

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

src/subagent-watcher.ts

@@ -102,7 +102,7 @@ export class SubagentWatcher extends EventEmitter {
   private idleTimers = new Map<string, NodeJS.Timeout>();
   private pollInterval: NodeJS.Timeout | null = null;
   private livenessInterval: NodeJS.Timeout | null = null;
-  private isRunning = false;
+  private _isRunning = false;
   private knownSubagentDirs = new Set<string>();
 
   constructor() {
@@ -115,8 +115,8 @@ export class SubagentWatcher extends EventEmitter {
    * Start watching for subagent activity
    */
   start(): void {
-    if (this.isRunning) return;
-    this.isRunning = true;
+    if (this._isRunning) return;
+    this._isRunning = true;
 
     // Initial scan
     this.scanForSubagents();
@@ -177,11 +177,18 @@ export class SubagentWatcher extends EventEmitter {
     return false;
   }
 
+  /**
+   * Check if the watcher is currently running
+   */
+  isRunning(): boolean {
+    return this._isRunning;
+  }
+
   /**
    * Stop watching
    */
   stop(): void {
-    this.isRunning = false;
+    this._isRunning = false;
 
     if (this.pollInterval) {
       clearInterval(this.pollInterval);

src/web/public/app.js

@@ -2964,6 +2964,7 @@ class ClaudemanApp {
     document.getElementById('appSettingsShowSystemStats').checked = settings.showSystemStats ?? true;
     document.getElementById('appSettingsShowTokenCount').checked = settings.showTokenCount ?? true;
     document.getElementById('appSettingsShowMonitor').checked = settings.showMonitor ?? true;
+    document.getElementById('appSettingsSubagentTracking').checked = settings.subagentTrackingEnabled ?? true;
     // Claude CLI settings
     const claudeModeSelect = document.getElementById('appSettingsClaudeMode');
     const allowedToolsRow = document.getElementById('allowedToolsRow');
@@ -3023,6 +3024,7 @@ class ClaudemanApp {
       showSystemStats: document.getElementById('appSettingsShowSystemStats').checked,
       showTokenCount: document.getElementById('appSettingsShowTokenCount').checked,
       showMonitor: document.getElementById('appSettingsShowMonitor').checked,
+      subagentTrackingEnabled: document.getElementById('appSettingsSubagentTracking').checked,
       // Claude CLI settings
       claudeMode: document.getElementById('appSettingsClaudeMode').value,
       allowedTools: document.getElementById('appSettingsAllowedTools').value.trim(),

src/web/public/index.html

@@ -536,6 +536,22 @@
               </label>
               <span class="form-hint">Show Monitor panel at bottom right</span>
             </div>
+            <div class="form-row form-row-switch">
+              <label>Enable Subagent Tracking</label>
+              <label class="switch">
+                <input type="checkbox" id="appSettingsSubagentTracking" checked>
+                <span class="slider"></span>
+              </label>
+              <span class="form-hint">Monitor Claude Code background agents in real-time</span>
+            </div>
+            <div class="form-row form-row-switch">
+              <label>Show Subagents Panel</label>
+              <label class="switch">
+                <input type="checkbox" id="appSettingsShowSubagents" checked>
+                <span class="slider"></span>
+              </label>
+              <span class="form-hint">Show the Subagents panel (independent from Monitor)</span>
+            </div>
           </div>
           <!-- Claude CLI Tab -->
           <div class="modal-tab-content hidden" id="settings-claude">

src/web/server.ts

@@ -1454,6 +1454,17 @@ export class WebServer extends EventEmitter {
           mkdirSync(dir, { recursive: true });
         }
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
+
+        // Handle subagent tracking toggle dynamically
+        const subagentEnabled = settings.subagentTrackingEnabled ?? true;
+        if (subagentEnabled && !subagentWatcher.isRunning()) {
+          subagentWatcher.start();
+          console.log('Subagent watcher started via settings change');
+        } else if (!subagentEnabled && subagentWatcher.isRunning()) {
+          subagentWatcher.stop();
+          console.log('Subagent watcher stopped via settings change');
+        }
+
         return { success: true };
       } catch (err) {
         return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
@@ -2627,9 +2638,31 @@ export class WebServer extends EventEmitter {
     // Restore screen sessions from previous run
     await this.restoreScreenSessions();
 
-    // Start subagent watcher for Claude Code background agent visibility
-    subagentWatcher.start();
-    console.log('Subagent watcher started - monitoring ~/.claude/projects for background agent activity');
+    // Start subagent watcher for Claude Code background agent visibility (if enabled)
+    if (this.isSubagentTrackingEnabled()) {
+      subagentWatcher.start();
+      console.log('Subagent watcher started - monitoring ~/.claude/projects for background agent activity');
+    } else {
+      console.log('Subagent watcher disabled by user settings');
+    }
+  }
+
+  /**
+   * Check if subagent tracking is enabled in settings (default: true)
+   */
+  private isSubagentTrackingEnabled(): boolean {
+    const settingsPath = join(homedir(), '.claudeman', 'settings.json');
+    try {
+      if (existsSync(settingsPath)) {
+        const content = readFileSync(settingsPath, 'utf-8');
+        const settings = JSON.parse(content);
+        // Default to true if not explicitly set
+        return settings.subagentTrackingEnabled ?? true;
+      }
+    } catch (err) {
+      console.error('Failed to read subagent tracking setting:', err);
+    }
+    return true; // Default enabled
   }
 
   private async restoreScreenSessions(): Promise<void> {