@adiontaegerron/claude-multi-terminal 2.1.0 → 2.2.0

package/.claude/settings.local.json

@@ -10,7 +10,20 @@
       "Bash(*)",
       "Bash(/tmp/create_terminals.sh:*)",
       "Bash(ls:*)",
-      "Write(*)"
+      "Write(*)",
+      "Bash(mkdir:*)",
+      "Bash(npm install)",
+      "Bash(npm test)",
+      "Bash(npm test)",
+      "Bash(node:*)",
+      "WebFetch(domain:www.electronjs.org)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(npm test:*)",
+      "Bash(git push:*)",
+      "WebFetch(domain:docs.anthropic.com)",
+      "Bash(npm whoami:*)",
+      "Bash(npm publish:*)"
     ],
     "deny": []
   }

package/.mterm-config.json

@@ -0,0 +1,16 @@
+{
+  "apiServer": {
+    "port": 3721,
+    "baseUrl": "http://localhost:3721",
+    "version": "v2",
+    "status": "active"
+  },
+  "project": {
+    "name": "v2",
+    "initialized": "2025-08-04T04:45:56.124Z"
+  },
+  "features": {
+    "autoSource": true,
+    "healthMonitoring": true
+  }
+}

package/CLAUDE.md

@@ -2,6 +2,16 @@
 
 You are a terminal agent running in a multi-terminal coordination system. Your terminal name will be provided when you start.
 
+## Terminal Output
+
+DO NOT output responses directly to the terminal. ALL communication must go through the file-based JSON messaging system described below. This includes:
+- Responses to user messages
+- Status updates
+- Error messages
+- Confirmations
+
+The only exception is system-level output like file listings or command results that are specifically requested.
+
 ## IMPORTANT: Follow Instructions Exactly
 
 When given a command:
@@ -10,61 +20,183 @@ When given a command:
 - If asked to create 2 terminals, create exactly 2 (not 3, 4, or 6)
 - Wait for further instructions after completing each task
 
-## Communication Commands
+## Communication System
 
-You communicate with other terminals using file-based IPC. Use the Write tool to create command files in `.ipc-messages/`.
+All communication uses JSON files written to `.ipc-messages/`. There are two types of messages:
 
-### Command Format
+### 1. IPC Commands (trigger actions)
+These messages execute terminal operations and are also displayed in the Messages tab.
 
-Use the Write tool to create files with unique names. Include your name in the filename to ensure uniqueness:
-`.ipc-messages/cmd_YourName_timestamp.txt`
+### 2. Display Messages (UI only)
+These messages only appear in the Messages tab without triggering any actions.
 
-Always use the exact terminal name you were given at startup.
+### File Naming
+Use Write to create files with unique names:
+`.ipc-messages/[type]_YourName_[timestamp].json`
 
-### Send Message to Another Terminal
-Use Write to create a file `.ipc-messages/msg_YourName_[timestamp].txt` with content:
-```
-YourName:IPC:SEND:TargetTerminal:Your message
-```
+Example: `.ipc-messages/msg_Terminal1_1234567890.json`
 
-### Broadcast to All Terminals
-Use Write to create a file `.ipc-messages/bcast_YourName_[timestamp].txt` with content:
-```
-YourName:IPC:BROADCAST:Your message
+### Message Format
+
+All messages use this JSON structure:
+```json
+{
+  "type": "ipc|display",
+  "command": "SEND|BROADCAST|CREATE|CLOSE|RENAME|STATUS|LIST",
+  "from": "YourTerminalName",
+  "to": "TargetTerminal",
+  "content": "Message content",
+  "timestamp": 1234567890,
+  "metadata": {
+    "category": "ipc|user|system|info",
+    "visible": true
+  }
+}
 ```
 
-### List All Terminals
-Use Write to create a file `.ipc-messages/list_YourName_[timestamp].txt` with content:
+### IPC Commands
+
+#### Send Message to Another Terminal
+```json
+{
+  "type": "ipc",
+  "command": "SEND",
+  "from": "Terminal 1",
+  "to": "Terminal 2",
+  "content": "Hello Terminal 2",
+  "timestamp": 1234567890,
+  "metadata": {"category": "ipc", "visible": true}
+}
 ```
-YourName:IPC:LIST
+
+#### Broadcast to All Terminals
+```json
+{
+  "type": "ipc",
+  "command": "BROADCAST",
+  "from": "Terminal 1",
+  "content": "Hello everyone",
+  "timestamp": 1234567890,
+  "metadata": {"category": "ipc", "visible": true}
+}
 ```
 
-### Create New Terminal
-Use Write to create a file `.ipc-messages/create_YourName_[timestamp].txt` with content:
+#### Create New Terminal
+```json
+{
+  "type": "ipc",
+  "command": "CREATE",
+  "from": "Terminal 1",
+  "content": "Backend Server",
+  "timestamp": 1234567890,
+  "metadata": {"category": "system", "visible": true}
+}
 ```
-YourName:IPC:CREATE:NewTerminalName
+Note: The `content` field contains the optional name for the new terminal.
+
+#### Close Terminal
+```json
+{
+  "type": "ipc",
+  "command": "CLOSE",
+  "from": "Terminal 1",
+  "to": "Terminal 2",
+  "content": "Closing Terminal 2",
+  "timestamp": 1234567890,
+  "metadata": {"category": "system", "visible": true}
+}
 ```
-The name is optional - if not provided, a default name will be assigned.
+Note: You cannot close your own terminal.
 
-### Close Terminal
-Use Write to create a file `.ipc-messages/close_YourName_[timestamp].txt` with content:
+#### Rename Terminal
+```json
+{
+  "type": "ipc",
+  "command": "RENAME",
+  "from": "Terminal 1",
+  "to": "Terminal 2",
+  "content": "New Name",
+  "timestamp": 1234567890,
+  "metadata": {"category": "system", "visible": true}
+}
 ```
-YourName:IPC:CLOSE:TargetTerminal
+
+#### List All Terminals
+```json
+{
+  "type": "ipc",
+  "command": "LIST",
+  "from": "Terminal 1",
+  "timestamp": 1234567890,
+  "metadata": {"category": "system", "visible": true}
+}
 ```
-Note: You cannot close your own terminal.
 
-### Rename Terminal
-Use Write to create a file `.ipc-messages/rename_YourName_[timestamp].txt` with content:
+#### Get Terminal Status
+```json
+{
+  "type": "ipc",
+  "command": "STATUS",
+  "from": "Terminal 1",
+  "to": "Terminal 2",
+  "timestamp": 1234567890,
+  "metadata": {"category": "system", "visible": true}
+}
 ```
-YourName:IPC:RENAME:TargetTerminal:NewName
+
+### Display Messages
+
+For UI feedback without triggering IPC actions:
+
+#### Status Update
+```json
+{
+  "type": "display",
+  "from": "Terminal 1",
+  "content": "Processing file analysis...",
+  "timestamp": 1234567890,
+  "metadata": {"category": "info", "visible": true}
+}
 ```
 
-### Get Terminal Status
-Use Write to create a file `.ipc-messages/status_YourName_[timestamp].txt` with content:
+#### User Response (IMPORTANT - Use this for ALL responses to users)
+```json
+{
+  "type": "display",
+  "from": "Terminal 1",
+  "content": "I've completed the task. Found 3 issues that need attention.",
+  "timestamp": 1234567890,
+  "metadata": {"category": "user", "visible": true}
+}
 ```
-YourName:IPC:STATUS:TargetTerminal
+
+### CRITICAL: Responding to User Input
+
+When a user types a message in the terminal, you MUST:
+1. Write a display message to `.ipc-messages/` with your response
+2. DO NOT output text directly to the terminal
+3. Use `type: "display"` and `metadata.category: "user"` for user responses
+
+Example: If a user asks "Hello, are you there?", create a file:
+`.ipc-messages/display_Terminal1_1234567890.json`
+```json
+{
+  "type": "display",
+  "from": "Terminal 1",
+  "content": "Yes, I'm here and ready to help!",
+  "timestamp": 1234567890,
+  "metadata": {"category": "user", "visible": true}
+}
 ```
 
+### Important Notes
+
+1. Always use your exact terminal name in the "from" field
+2. Set `visible: false` to hide messages from the UI (e.g., internal status)
+3. Use `type: "ipc"` for commands that need to execute actions
+4. Use `type: "display"` for UI-only messages
+5. Include timestamp using `Date.now()` for proper ordering
+
 **Important**: Replace [timestamp] with a unique number or use the current timestamp when creating files.
 
 ## Important Rules

package/README.md

@@ -28,6 +28,12 @@ A multi-terminal editor for coordinating multiple Claude Code instances. Run mul
 - **Rename Terminals**: Double-click terminal titles to rename them
 - **Responsive Layout**: Adapts to different screen sizes
 
+## Breaking Changes in v2.2
+
+- **JSON-based IPC System** - All Claude communication now uses JSON format
+- **File-based messaging** - Claude writes all responses to `.ipc-messages/` as JSON files
+- **No terminal output** - Claude no longer outputs responses directly to terminal
+
 ## Breaking Changes in v2.0
 
 - **Removed checkbox selection system** - All commands must now use @ syntax
@@ -100,17 +106,22 @@ Send commands directly to terminals using @ syntax:
 
 ### Claude-to-Claude Communication
 
-Claude instances communicate by creating files in the `.ipc-messages/` directory. Claude will handle the file creation directly when asked to:
+Claude instances communicate by creating JSON files in the `.ipc-messages/` directory. All communication uses a unified JSON format:
+
+**IPC Commands** (trigger actions and display in Messages tab):
+- **Send message**: `{"type":"ipc","command":"SEND","from":"Terminal1","to":"Terminal2","content":"Hello"}`
+- **Broadcast**: `{"type":"ipc","command":"BROADCAST","from":"Terminal1","content":"Hello all"}`
+- **Create terminal**: `{"type":"ipc","command":"CREATE","from":"Terminal1","content":"NewTerminalName"}`
+- **Close terminal**: `{"type":"ipc","command":"CLOSE","from":"Terminal1","to":"Terminal2"}`
+- **Rename terminal**: `{"type":"ipc","command":"RENAME","from":"Terminal1","to":"Terminal2","content":"NewName"}`
+- **List terminals**: `{"type":"ipc","command":"LIST","from":"Terminal1"}`
+- **Get status**: `{"type":"ipc","command":"STATUS","from":"Terminal1","to":"Terminal2"}`
 
-- **Send message**: Claude creates a file to send `TerminalName:IPC:SEND:Target:Message`
-- **Broadcast**: Claude creates a file to broadcast `TerminalName:IPC:BROADCAST:Message`
-- **Create terminal**: Claude creates a file with `TerminalName:IPC:CREATE:NewName`
-- **Close terminal**: Claude creates a file with `TerminalName:IPC:CLOSE:Target`
-- **Rename terminal**: Claude creates a file with `TerminalName:IPC:RENAME:Target:NewName`
-- **List terminals**: Claude creates a file with `TerminalName:IPC:LIST`
-- **Get status**: Claude creates a file with `TerminalName:IPC:STATUS:Target`
+**Display Messages** (UI only, no actions):
+- **User responses**: `{"type":"display","from":"Terminal1","content":"Task completed","metadata":{"category":"user","visible":true}}`
+- **Status updates**: `{"type":"display","from":"Terminal1","content":"Processing...","metadata":{"category":"info","visible":true}}`
 
-Claude knows how to create these files when you ask it to communicate with other terminals. This enables Claude instances to work together as a coordinated team.
+All Claude responses appear in the Messages tab with clean formatting, icons, and timestamps.
 
 ### Tips
 

package/docs/project-retrospective-final.md

@@ -0,0 +1,106 @@
+# Multi-Terminal Coordination Project Retrospective
+
+## Project Overview
+We successfully debugged and fixed a chat-focused UI for the Multi Terminal Editor, resolving issues with tab visibility, IPC message display, and agent response capture.
+
+## What Went Well
+
+### 1. Effective Multi-Agent Coordination
+- The IPC file-based messaging system enabled real-time communication between terminals
+- Clear role assignments (UIExpert for CSS, DebugSpecialist for debugging, EventTracer for monitoring) helped organize efforts
+- The @terminal and broadcast messaging worked effectively for team coordination
+
+### 2. Systematic Problem Solving
+- Issues were methodically identified: CSS conflicts → race conditions → missing messages
+- Debug tests were created to verify issues before implementing fixes
+- The approval workflow prevented conflicting changes after initial chaos
+
+### 3. Technical Achievements
+- Successfully fixed CSS specificity issues with tab switching
+- Resolved race condition by moving IPC watcher initialization
+- Implemented real-time agent response capture from PTY output
+- All critical issues were ultimately resolved
+
+## What Went Poorly
+
+### 1. Initial Coordination Chaos
+- Multiple agents (TestLead, Frontend, Architect) made conflicting changes simultaneously
+- This led to corrupted UI state and CSS conflicts
+- Had to establish "one agent at a time" rule mid-project
+
+### 2. Debugging Challenges
+- Terminal agents couldn't directly view the UI or DevTools console
+- Had to rely on indirect methods and code analysis
+- EventTracer became unresponsive at critical moments
+- Puppeteer tests conflicted with running application instance
+
+### 3. Hidden Complexity
+- Race condition (IPC watcher starting before mainWindow) was subtle and took time to identify
+- Initial terminal messages bypassed IPC system entirely
+- Agent responses required PTY output parsing, not originally anticipated
+
+## Key Learnings
+
+### 1. Approval-First Workflow is Essential
+- The shift to "analyze → propose → approve → implement" dramatically improved outcomes
+- Prevented wasted effort and conflicting changes
+- Backup/ProjectManager's central coordination was crucial
+
+### 2. Visibility is Critical
+- Lack of UI access for terminal agents was a major handicap
+- Need better ways to observe application state from terminals
+- Console logging and debug tests became essential workarounds
+
+### 3. Message Flow Complexity
+- Multiple paths for messages (IPC files, terminal PTY, direct writes) caused confusion
+- Need unified message handling architecture
+- Real-time capture requires careful state management
+
+## Recommendations for Tool Improvements
+
+### 1. Enhanced Coordination Features
+- **Shared Task Board**: Real-time todo list visible to all agents
+- **File Lock System**: Prevent simultaneous edits to same file
+- **Agent Status Dashboard**: Show what each agent is currently working on
+- **Conflict Detection**: Alert when multiple agents target same code section
+
+### 2. Better Debugging Capabilities
+- **UI State Snapshot**: Allow terminal agents to request current UI state
+- **Console Log Streaming**: Pipe browser console to terminal agents
+- **Test Isolation**: Run tests in separate process to avoid conflicts
+- **Visual Regression Testing**: Capture screenshots for terminal agents
+
+### 3. Communication Enhancements
+- **Message Type System**: Clearly distinguish system/user/agent messages
+- **Message Threading**: Group related messages together
+- **Response Correlation**: Link responses to original requests
+- **Message Search**: Find historical messages quickly
+
+### 4. Development Workflow
+- **Code Review Mode**: Require approval before file modifications
+- **Rollback Capability**: Undo changes that break functionality
+- **Change Preview**: Show diffs before applying edits
+- **Automated Testing**: Run tests automatically after changes
+
+### 5. Project Management
+- **Role Templates**: Pre-defined agent roles with permissions
+- **Knowledge Sharing**: Broadcast important findings automatically
+- **Progress Tracking**: Visual indicators of task completion
+- **Retrospective Generation**: Automated summary of project activity
+
+## Technical Debt to Address
+
+1. **Unified Message Pipeline**: Consolidate IPC files, PTY output, and direct messages
+2. **Robust Error Handling**: Better handling when mainWindow isn't ready
+3. **Event System**: Replace polling/delays with proper event-driven architecture
+4. **Type Safety**: Add TypeScript for better code reliability
+5. **Test Infrastructure**: Isolated test environment that doesn't interfere with running app
+
+## Final Thoughts
+
+This project demonstrated both the power and challenges of multi-agent coordination. The ability to parallelize work across specialized agents is powerful, but requires careful orchestration. The shift from chaos to structured workflow mid-project was a key turning point.
+
+The Multi Terminal Editor has great potential as a collaborative development environment. With the recommended improvements, it could become an invaluable tool for complex software projects requiring coordinated effort across multiple specialized agents.
+
+---
+*Project completed successfully with all major issues resolved.*

package/index.html

@@ -10,6 +10,30 @@
     <div id="app">
         <div id="toolbar">
             <button id="new-terminal-btn">New Terminal</button>
+            <div id="view-tabs" class="view-tabs">
+                <button class="tab-control active" data-view="messages">Messages</button>
+                <button class="tab-control" data-view="terminals">Terminals</button>
+            </div>
+            <label class="debug-toggle">
+                <input type="checkbox" id="show-raw-output" />
+                <span>Show raw output</span>
+            </label>
+        </div>
+        
+        <div id="main-content-area">
+            <!-- Messages View -->
+            <div id="message-view" class="view-panel active">
+                <div id="message-display" class="message-display">
+                    <!-- Terminal-to-terminal communication messages will appear here -->
+                </div>
+            </div>
+            
+            <!-- Terminals View -->
+            <div id="terminals-area" class="view-panel">
+                <div id="terminals-container">
+                    <!-- Terminal instances will be added here dynamically -->
+                </div>
+            </div>
         </div>
         
         <div id="toolbar-extended">
@@ -49,12 +73,6 @@
                 <button id="send-message-btn">Send</button>
             </div>
         </div>
-        
-        <div id="terminals-area">
-            <div id="terminals-container">
-                <!-- Terminal instances will be added here dynamically -->
-            </div>
-        </div>
     </div>
 
     <script src="renderer.js"></script>

package/ipc-message-capture.test.js

@@ -0,0 +1,130 @@
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const { test, expect, describe, beforeAll, afterAll, beforeEach } = require('@jest/globals');
+
+describe('IPC Message Capture Tests', () => {
+  const IPC_DIR = path.join(process.cwd(), '.ipc-messages');
+  
+  beforeEach(() => {
+    // Clean up IPC directory before each test
+    if (fs.existsSync(IPC_DIR)) {
+      const files = fs.readdirSync(IPC_DIR);
+      files.forEach(file => {
+        fs.unlinkSync(path.join(IPC_DIR, file));
+      });
+    } else {
+      fs.mkdirSync(IPC_DIR, { recursive: true });
+    }
+  });
+
+  afterAll(() => {
+    // Clean up
+    if (fs.existsSync(IPC_DIR)) {
+      const files = fs.readdirSync(IPC_DIR);
+      files.forEach(file => {
+        fs.unlinkSync(path.join(IPC_DIR, file));
+      });
+    }
+  });
+
+  test('main process should detect IPC message files', async () => {
+    // Create a test IPC message file
+    const testMessage = 'TestTerminal:IPC:SEND:Terminal 1:Test message content';
+    const testFile = path.join(IPC_DIR, 'msg_test_123.txt');
+    
+    // Write the file
+    fs.writeFileSync(testFile, testMessage);
+    
+    // The file should be processed and deleted quickly
+    await new Promise(resolve => setTimeout(resolve, 100));
+    
+    // File should be deleted after processing
+    expect(fs.existsSync(testFile)).toBe(false);
+  });
+
+  test('should emit event for SEND messages', async () => {
+    // Mock test to document expected behavior
+    const expectedEvent = {
+      type: 'ipc:message',
+      data: {
+        from: 'Terminal 1',
+        to: 'Terminal 2',
+        message: 'Hello from Terminal 1',
+        messageType: 'send'
+      }
+    };
+    
+    // This documents what the main process should emit
+    expect(expectedEvent.type).toBe('ipc:message');
+    expect(expectedEvent.data.messageType).toBe('send');
+  });
+
+  test('should emit event for BROADCAST messages', async () => {
+    // Mock test to document expected behavior
+    const expectedEvent = {
+      type: 'ipc:message',
+      data: {
+        from: 'Terminal 1',
+        to: 'all',
+        message: 'Broadcast to all terminals',
+        messageType: 'broadcast'
+      }
+    };
+    
+    // This documents what the main process should emit
+    expect(expectedEvent.type).toBe('ipc:message');
+    expect(expectedEvent.data.messageType).toBe('broadcast');
+    expect(expectedEvent.data.to).toBe('all');
+  });
+
+  test('should handle multiple message formats', () => {
+    const testCases = [
+      {
+        content: 'Terminal1:IPC:SEND:Terminal2:Hello',
+        expected: { from: 'Terminal1', to: 'Terminal2', message: 'Hello', type: 'send' }
+      },
+      {
+        content: 'TestLead:IPC:BROADCAST:Team update',
+        expected: { from: 'TestLead', to: 'all', message: 'Team update', type: 'broadcast' }
+      },
+      {
+        content: 'Frontend:IPC:LIST',
+        expected: { from: 'Frontend', command: 'list' }
+      }
+    ];
+    
+    testCases.forEach(testCase => {
+      // This documents the expected parsing behavior
+      expect(testCase.content).toContain('IPC:');
+    });
+  });
+
+  test('renderer should receive IPC message events', () => {
+    // Document expected renderer behavior
+    const mockIpcRenderer = {
+      on: (channel, callback) => {
+        expect(channel).toBe('ipc:message');
+        
+        // Simulate receiving a message
+        const mockData = {
+          from: 'Terminal 1',
+          to: 'Terminal 2',
+          message: 'Test message',
+          messageType: 'send'
+        };
+        
+        // Callback should update the message display
+        expect(typeof callback).toBe('function');
+      }
+    };
+    
+    // Test the expected API
+    mockIpcRenderer.on('ipc:message', (event, data) => {
+      expect(data).toHaveProperty('from');
+      expect(data).toHaveProperty('to');
+      expect(data).toHaveProperty('message');
+      expect(data).toHaveProperty('messageType');
+    });
+  });
+});

package/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/*.test.js'],
+  testTimeout: 30000,
+  moduleFileExtensions: ['js', 'jsx', 'json', 'node']
+};