@chinchillaenterprises/mcp-dev-logger 2.3.3 → 3.0.0

package/README.md

@@ -1,592 +1,225 @@
-# MCP Dev Logger v2.3.3
+# MCP Dev Logger v3.0.0
 
-A Model Context Protocol (MCP) server for capturing and streaming development server output with browser console logging, enhanced organization, and automatic cleanup. Perfect for monitoring `npm run dev`, `yarn dev`, `pnpm dev`, or any other development server commands across all frameworks (Next.js, Vite, Create React App, etc.).
+**Simplified Amplify Gen2 Sandbox Logger**
 
-## 🎉 New in v2.3.3
+A streamlined Model Context Protocol (MCP) server that does one thing well: runs `npx ampx sandbox --stream-function-logs` and captures output to `resources/sandbox.log`.
 
-- **Larger Default Viewport**: Test browser now defaults to 1920x1080 (was 1280x800)
-- **Modern Screen Support**: Better for dashboard layouts, admin interfaces, and component showcases
-- **Improved Development Experience**: More realistic modern browser experience out of the box
-- **Dev Tools Friendly**: Adequate space for dev tools + content simultaneously
+## 🎯 What Changed in v3.0.0
 
-## Previous Features (v2.3.2)
+**MAJOR SIMPLIFICATION**: Removed all complex features to focus on the single use case that matters.
 
-- **Fixed React Hydration Errors**: Test browser banner now uses shadow DOM and waits for React hydration to complete
-- **Hydration-Safe Banner**: Banner injection no longer interferes with Next.js/React hydration process
-- **Improved Stability**: Better detection of React readiness before DOM modifications
-- **Shadow DOM Isolation**: Test browser banner completely isolated from application DOM
+**What's Gone:**
+- ❌ Browser console capture (Playwright)
+- ❌ Multi-process management
+- ❌ Date-based log organization
+- ❌ Process IDs and state persistence
+- ❌ Custom commands and parameters
+- ❌ Frontend/backend/custom process types
+- ❌ All the complexity you never needed
 
-## Previous Features (v2.3.1)
+**What Remains:**
+- ✅ Single hardcoded command: `npx ampx sandbox --stream-function-logs`
+- ✅ Single log file: `resources/sandbox/sandbox.log` (overwrites each time)
+- ✅ Simple start/stop/tail interface
+- ✅ Smart multi-project detection (kills existing sandbox for THIS project only)
 
-- **Enhanced Error Capture**: Now captures JavaScript errors that don't trigger console.error, including:
-  - React hydration errors
-  - Unhandled promise rejections
-  - Page-level JavaScript errors
-  - Network request failures (4xx/5xx responses)
-- **Visual Error Alerts**: Red banner notification when JavaScript errors occur
-- **Better Error Context**: Full stack traces for all JavaScript errors
+## Why This Exists
 
-## Previous Features (v2.3.0)
+After two months of usage, the pattern was clear:
+- Only ever used for Amplify sandbox streaming logs
+- Never looked at old logs
+- All the organization features were unused overhead
 
-- **One-Click Student Workflow**: New `dev_start_frontend_with_browser` tool that starts server AND launches browser automatically
-- **Smart Port Detection**: Automatically detects which port your dev server is using
-- **Server Ready Detection**: Waits for server to be fully ready before launching browser
-- **Simplified Teaching**: Reduces student setup from 3 commands to just 1
+So we stripped it down to the essentials.
 
-## Previous Features (v2.2.0)
+## Smart Multi-Project Support
 
-- **Browser Console Capture**: Capture browser console.log, console.error, and other console outputs alongside server logs
-- **Unified Log Stream**: See both server-side and client-side logs in one place
-- **Student-Friendly Browser**: TEST BROWSER with visual indicators for teaching
+The tool intelligently handles multiple projects with running sandboxes:
 
-## Previous Features (v2.1.0)
+**How it works:**
+1. Checks if a sandbox is already running in the current project directory
+2. If found, **kills it** and starts fresh (prevents stuck sandboxes)
+3. Only affects the sandbox for THIS project - other projects' sandboxes are untouched
 
-- **Organized Log Structure**: Logs are now organized by process type (frontend/backend/amplify/custom)
-- **Automatic Cleanup**: Keeps only the last 3 days of logs to prevent disk space issues
-- **Improved File Naming**: Cleaner log file names without redundant prefixes
-
-## Features
-
-- **Universal Dev Server Logging**: Works with any development server command
-- **Browser Console Capture**: Capture console.log, console.error, console.warn from the browser
-- **Multi-Process Support**: Run multiple dev servers simultaneously (frontend + backend)
-- **Real-time Log Streaming**: Capture build errors, TypeScript errors, hot reload events
-- **Organized Log Storage**: Structured as `logs/YYYY-MM-DD/processType/logfile.log`
-- **Automatic Log Cleanup**: Removes logs older than 3 days automatically
-- **Smart Process Management**: Start, stop, and restart individual dev servers by ID
-- **Log Filtering**: Search through logs with grep patterns
-- **Framework Agnostic**: One tool for all development servers
-- **Auto-Generated Process IDs**: Intelligent process ID generation based on command and output file
-- **Process State Persistence**: Maintains process state across server restarts (where possible)
-- **Signal Handling**: Proper cleanup with SIGTERM for graceful shutdowns
-- **Unified Server + Browser Logs**: See both frontend and backend logs in one stream
+**Why kill instead of reuse?**
+- Sandboxes can get stuck after running a long time
+- File change detection might stop working
+- Fresh start ensures clean deployment state
 
 ## Installation
 
-### From NPM (Recommended)
 ```bash
 claude mcp add dev-logger -s user -- npx @chinchillaenterprises/mcp-dev-logger
 ```
 
-### For Development/Testing
-```bash
-# Clone and build locally
-git clone <repository-url>
-cd mcp-dev-logger
-npm install
-npm run build
-
-# Add to Claude Code (local development)
-claude mcp add dev-logger-local -s user -- node $(pwd)/dist/index.js
-```
-
 ## Tools Provided
 
-**Important Note:** When using these tools through Claude Code's MCP integration, the tool names will be prefixed with `mcp__dev-logger__`. For example:
-- `dev_start_log_streaming` becomes `mcp__dev-logger__dev_start_log_streaming`
-- `dev_tail_logs` becomes `mcp__dev-logger__dev_tail_logs`
-- And so on for all tools
+### 1. `dev_start_sandbox`
+Start Amplify Gen2 sandbox with streaming function logs. No parameters needed.
 
-This prefix pattern applies to all MCP servers and helps Claude distinguish between different servers' tools.
+**What it does:**
+- Checks if a sandbox is already running in THIS project directory
+- If found, kills it first (prevents stuck sandboxes)
+- Starts `npx ampx sandbox --stream-function-logs`
+- Clears/overwrites `resources/sandbox/sandbox.log`
+- Streams all output (stdout + stderr) to the log file
+- Adds timestamps to every log line
 
-### 1. dev_start_log_streaming
-Start a development server and stream its output to a log file. **Supports multiple concurrent processes.**
-
-**Parameters:**
-- `command` (optional): Dev command to run (default: "npm run dev")
-- `outputFile` (optional): File to write logs to (default: "dev-server-logs.txt")
-- `processId` (optional): Custom process ID (auto-generated if not provided)
-- `cwd` (optional): Working directory
-- `env` (optional): Environment variables to pass
+**Multi-project safe:** Only kills/affects sandboxes running in the current directory
 
-**Example:**
-```json
-{
-  "command": "npm run dev",
-  "outputFile": "frontend-logs.txt",
-  "cwd": "/path/to/project",
-  "env": {
-    "PORT": "3001",
-    "NODE_ENV": "development"
-  }
-}
+**Usage:**
+```typescript
+dev_start_sandbox()
 ```
 
-### 2. dev_list_processes
-List all running development processes with their status and details.
-
-**No parameters required.**
-
-### 3. dev_stop_log_streaming
-Stop development server(s) and logging.
-
-**Parameters:**
-- `processId` (optional): Process ID to stop (if not provided, stops all processes)
-
-### 4. dev_restart_log_streaming
-Restart a specific development server (useful when it crashes or hangs).
-
-**Parameters:**
-- `processId` (required): Process ID to restart
-- `clearLogs` (optional): Whether to clear the log file on restart (default: false)
-
-### 5. dev_get_status
-Check if development server(s) are running and get their status.
-
-**Parameters:**
-- `processId` (optional): Process ID to get status for (if not provided, shows all processes)
-
 **Returns:**
-- Running status
-- Process ID(s)
-- PID(s)
-- Uptime
-- Current command(s)
-- Log file location(s)
-
-### 6. dev_tail_logs
-Get the last N lines from the log file.
-
-**Parameters:**
-- `processId` (optional): Process ID to tail logs from (smart fallback for single process)
-- `lines` (optional): Number of lines to return (default: 50)
-- `filter` (optional): Grep pattern to filter logs
-
-**Example:**
 ```json
 {
-  "processId": "npm-frontend",
-  "lines": 100,
-  "filter": "ERROR"
+  "success": true,
+  "message": "Amplify sandbox started. Logs are being written to /path/to/project/resources/sandbox/sandbox.log",
+  "logFile": "/path/to/project/resources/sandbox/sandbox.log"
 }
 ```
 
-### 7. dev_clear_logs
-Clear the log file.
-
-**Parameters:**
-- `processId` (optional): Process ID to clear logs for (smart fallback for single process)
-- `backup` (optional): Whether to backup logs before clearing (default: false)
-
-### 8. dev_launch_test_browser
-Launch a TEST BROWSER for students to interact with. All console logs from this browser are captured automatically. Students should use THIS browser (not their regular browser) to test their app.
-
-**Parameters:**
-- `processId` (optional): Process ID to attach browser console to
-- `browserUrl` (optional): URL to open in test browser (default: http://localhost:3000)
-- `teachingMode` (optional): Enable teaching mode with DevTools open and slower actions (default: true)
-- `viewport` (optional): Browser window size (default: { width: 1280, height: 800 })
-- `highlightErrors` (optional): Add visual indicator when console errors occur (default: true)
-
-**Key Features:**
-- 🪟 Always visible browser window (not headless)
-- 🔍 DevTools automatically open in teaching mode
-- 🐌 Slower actions for easier teaching/learning
-- ⚡ Red flash on console errors
-- 📝 Green banner showing "TEST BROWSER" status
-- 🎯 All console logs captured to the same log file as server logs
-
-**Example:**
+Or if it killed an existing sandbox:
 ```json
 {
-  "processId": "npm-frontend",
-  "browserUrl": "http://localhost:3000",
-  "teachingMode": true,
-  "highlightErrors": true
+  "success": true,
+  "message": "Killed existing sandbox (PID: 12345) and started fresh. Logs are being written to /path/to/project/resources/sandbox/sandbox.log",
+  "logFile": "/path/to/project/resources/sandbox/sandbox.log",
+  "killedPid": 12345
 }
 ```
 
-### 9. dev_stop_browser_console
-Stop browser console capture for a specific process.
-
-**Parameters:**
-- `processId` (optional): Process ID to stop browser console capture for
+### 2. `dev_stop_sandbox`
+Stop the running Amplify sandbox process. No parameters needed.
 
-### 10. dev_start_frontend_with_browser 🚀 NEW in v2.3.0!
-**ONE-CLICK STUDENT WORKFLOW**: Start frontend server AND automatically launch test browser when ready. Perfect for teaching environments - reduces setup from 3 commands to 1!
+**Usage:**
+```typescript
+dev_stop_sandbox()
+```
 
-**Parameters:**
-- `command` (optional): Dev command to run (default: "npm run dev")
-- `port` (optional): Port to wait for (default: auto-detect from output)
-- `waitTimeout` (optional): Max time to wait for server in ms (default: 30000)
-- `browserDelay` (optional): Delay after server ready in ms (default: 1000)
-- `teachingMode` (optional): Enable teaching features (default: true)
-- `processId` (optional): Custom process ID (default: "frontend-with-browser")
-- `env` (optional): Environment variables
-- `cwd` (optional): Working directory
-
-**Key Features:**
-- 🎯 Automatically detects when server is ready
-- 🪟 Launches test browser with DevTools open
-- 📝 Captures both server AND browser console logs
-- ⚡ Red flash on browser errors
-- 🧪 Green "TEST BROWSER" banner
-- ⏱️ Single command instead of multiple steps
-
-**Example:**
+**Returns:**
 ```json
 {
-  "command": "npm run dev",
-  "teachingMode": true,
-  "processId": "student-project"
+  "success": true,
+  "message": "Amplify sandbox stopped successfully."
 }
 ```
 
-**Success Output:**
-```
-✅ Starting development server...
-✅ Server ready on http://localhost:3000
-✅ Launching test browser...
-
-🎯 TEST BROWSER LAUNCHED!
-
-👉 Use the browser window that just opened (with green banner)
-📝 All console logs are being saved
-🔍 DevTools is open for debugging
-⚠️  Errors will flash red on screen
-
-Happy debugging! 🚀
-```
+### 3. `dev_tail_sandbox_logs`
+Get the last N lines from the sandbox log file.
 
-## Usage Examples
+**Parameters:**
+- `lines` (optional): Number of lines to return (default: 50)
 
-### Multi-Process Development (v2.0.0)
+**Usage:**
 ```typescript
-// Start frontend and backend simultaneously
-dev_start_log_streaming({
-  "command": "npm run dev",
-  "outputFile": "frontend.log",
-  "processId": "frontend"
-})
+// Get last 50 lines (default)
+dev_tail_sandbox_logs()
 
-dev_start_log_streaming({
-  "command": "npx ampx sandbox --stream-function-logs",
-  "outputFile": "backend.log", 
-  "processId": "backend"
-})
-
-// List all running processes
-dev_list_processes()
-
-// Stop just the frontend
-dev_stop_log_streaming({ "processId": "frontend" })
-
-// Restart backend with clean logs
-dev_restart_log_streaming({ 
-  "processId": "backend", 
-  "clearLogs": true 
-})
+// Get last 100 lines
+dev_tail_sandbox_logs({ "lines": 100 })
 ```
 
-### Start Next.js Development Server
-```typescript
-// Start Next.js dev server
+**Returns:**
+```json
 {
-  "command": "npm run dev",
-  "outputFile": "nextjs-dev.log"
+  "success": true,
+  "logs": "[2025-10-02T12:34:56.789Z] Starting Amplify sandbox: npx ampx sandbox --stream-function-logs\n[2025-10-02T12:34:57.890Z] Amplify Gen 2 sandbox starting...\n..."
 }
 ```
 
-### Monitor Vite Dev Server
-```typescript
-// Start Vite with custom port
-{
-  "command": "vite --port 3001",
-  "outputFile": "vite-dev.log",
-  "env": {
-    "NODE_ENV": "development"
-  }
-}
-```
+## Typical Workflow
 
-### Check for TypeScript Errors
 ```typescript
-// Tail logs filtering for TypeScript errors
-{
-  "lines": 200,
-  "filter": "TS\\d+"
-}
-```
-
-### Debug Build Errors
-```typescript
-// Get recent errors from build process
-{
-  "lines": 100,
-  "filter": "ERROR|FAILED|error"
-}
-```
+// 1. Start the sandbox
+dev_start_sandbox()
 
-## Log Organization (v2.1.0+)
+// 2. Work on your code...
+// Sandbox is running and streaming logs to resources/sandbox/sandbox.log
 
-Logs are organized in a structured directory hierarchy:
+// 3. Check recent logs when something goes wrong
+dev_tail_sandbox_logs({ "lines": 100 })
 
+// 4. Stop when done
+dev_stop_sandbox()
 ```
-logs/
-├── 2025-07-10/              # Date folder (YYYY-MM-DD)
-│   ├── frontend/            # Process type folder
-│   │   ├── nextjs-14-32-15.log
-│   │   └── vite-16-45-22.log
-│   ├── backend/
-│   │   ├── express-14-33-01.log
-│   │   └── api-15-22-11.log
-│   └── amplify/
-│       └── sandbox-14-35-22.log
-└── 2025-07-09/              # Older logs (auto-removed after 3 days)
-    └── ...
-```
-
-## Log Format
-
-Logs are written with timestamps, process IDs, and error markers. Browser console logs are prefixed with [BROWSER]:
 
-```
-[2024-01-15T10:30:45.123Z] Starting: npm run dev (Process ID: npm-frontend)
-[2024-01-15T10:30:46.456Z] [npm-frontend] > my-app@1.0.0 dev
-[2024-01-15T10:30:46.457Z] [npm-frontend] > next dev
-[2024-01-15T10:30:47.123Z] [npm-frontend] ▲ Next.js 14.0.0
-[2024-01-15T10:30:47.124Z] [npm-frontend] - Local: http://localhost:3000
-[2024-01-15T10:30:48.789Z] [npm-frontend] [ERROR] Error: Cannot find module './components/Header'
-[2024-01-15T10:30:49.123Z] [npm-frontend] [BROWSER] Console capture started for http://localhost:3000
-[2024-01-15T10:30:49.456Z] [npm-frontend] [BROWSER] [LOG] React DevTools detected
-[2024-01-15T10:30:49.789Z] [npm-frontend] [BROWSER] [WARN] React: Each child should have a unique key prop
-[2024-01-15T10:30:50.123Z] [npm-frontend] [BROWSER] [ERROR] Failed to fetch /api/user: 404 Not Found
-[2024-01-15T10:30:50.456Z] [npm-frontend] [BROWSER] [LOG] { user: null, loading: false }
-
-[2024-01-15T10:30:50.123Z] Starting: npx ampx sandbox --stream-function-logs (Process ID: npx-backend)
-[2024-01-15T10:30:51.456Z] [npx-backend] [INFO] Amplify sandbox starting...
-[2024-01-15T10:30:52.123Z] [npx-backend] Process exited with code 0 and signal null
-```
+## AI Assistant Usage
 
-### Process ID Generation
-The server automatically generates intelligent process IDs based on the command and output file:
-- Command: `npm run dev` + Output: `frontend.log` → Process ID: `npm-frontend`
-- Command: `npx ampx sandbox --stream-function-logs` + Output: `backend.log` → Process ID: `npx-backend`
-- Duplicate IDs are automatically suffixed with `-1`, `-2`, etc.
+When you tell Claude Code to "use dev logger", it will:
+1. Call `dev_start_sandbox()` to start streaming (kills existing sandbox if found)
+2. Logs are captured automatically to `resources/sandbox/sandbox.log`
+3. Claude can call `dev_tail_sandbox_logs()` to check for errors
+4. Calls `dev_stop_sandbox()` when you're done
 
-## Common Use Cases
+## Log Format
 
-### 1. Debugging Build Failures
-```bash
-# Start dev server
-dev_start_log_streaming
+Logs are timestamped and include error markers:
 
-# When build fails, check recent errors
-dev_tail_logs { "filter": "ERROR", "lines": 100 }
 ```
-
-### 2. Monitoring TypeScript Compilation
-```bash
-# Start with TypeScript focus
-dev_start_log_streaming { "command": "npm run dev", "outputFile": "ts-errors.log" }
-
-# Check for TS errors
-dev_tail_logs { "filter": "TS\\d+|typescript", "lines": 50 }
+[2025-10-02T12:34:56.789Z] Starting Amplify sandbox: npx ampx sandbox --stream-function-logs
+[2025-10-02T12:34:57.890Z] Amplify Gen 2 sandbox starting...
+[2025-10-02T12:34:58.123Z] [INFO] Deploying stack...
+[2025-10-02T12:35:00.456Z] [ERROR] Failed to deploy: Invalid configuration
+[2025-10-02T12:35:01.789Z] Amplify sandbox exited with code 1 and signal null
 ```
 
-### 3. Port Conflicts
-```bash
-# Start on different port
-dev_start_log_streaming {
-  "command": "npm run dev",
-  "env": { "PORT": "3001" }
-}
-```
+## Requirements
 
-### 4. Clean Restart After Crash
-```bash
-# Restart and clear old logs
-dev_restart_log_streaming { "clearLogs": true }
-```
+- Node.js 18+
+- AWS Amplify Gen2 project
+- A `resources/` folder in your repo (created automatically if missing)
 
-### 5. Amplify Development Workflow
-```bash
-# Start Amplify backend logging
-dev_start_log_streaming {
-  "command": "npx ampx sandbox --stream-function-logs",
-  "outputFile": "backend-logs.txt",
-  "processId": "amplify-backend"
-}
+## Migration from v2.x
 
-# Monitor Lambda function logs
-dev_tail_logs { "processId": "amplify-backend", "filter": "ERROR|WARN", "lines": 100 }
-```
+If you were using the old version:
 
-### 6. Student Testing Workflow (v2.2.0)
+**Before (v2.x):**
 ```typescript
-// Step 1: Start the student's dev server
 dev_start_log_streaming({
-  "command": "npm run dev",
-  "processId": "student-app"
-})
-
-// Step 2: Launch the TEST BROWSER for the student
-dev_launch_test_browser({
-  "processId": "student-app",
-  "browserUrl": "http://localhost:3000",
-  "teachingMode": true  // DevTools open, slower actions
-})
-
-// Step 3: Tell student: "Use the TEST BROWSER window that just opened!"
-// They click buttons, fill forms, trigger errors - ALL console logs are captured
-
-// Step 4: When student says "I clicked submit and nothing happened"
-dev_tail_logs({ 
-  "processId": "student-app", 
-  "filter": "\\[BROWSER\\].*\\[ERROR\\]", 
-  "lines": 20 
-})
-// Shows: [BROWSER] [ERROR] Cannot read property 'name' of undefined
-
-// Step 5: Show all browser activity
-dev_tail_logs({ 
-  "processId": "student-app", 
-  "filter": "\\[BROWSER\\]", 
-  "lines": 50 
+  "command": "npx ampx sandbox --stream-function-logs",
+  "outputFile": "backend-logs.txt",
+  "processId": "amplify-backend",
+  "structuredLogging": true,
+  "sessionDate": "2025-10-02"
 })
-
-// Step 6: When done testing
-dev_stop_browser_console({ "processId": "student-app" })
 ```
 
-**What Students See:**
-- A browser window opens with "🧪 TEST BROWSER" banner
-- DevTools is already open to the Console tab
-- When errors occur, the browser flashes red
-- All their console.log() statements are captured
-- They can debug using the actual browser they're testing in
-
-### Tips for Instructors/TAs:
-1. **Always emphasize**: Students must use the TEST BROWSER, not their regular browser
-2. **Common mistake**: Students open localhost:3000 in their regular Chrome - no logs captured!
-3. **Quick check**: Look for [BROWSER] prefix in logs to confirm they're using test browser
-4. **Teaching moment**: Show how server errors appear without [BROWSER] prefix
-5. **Debugging together**: The red flash makes it easy to spot when errors occur
-
-### 7. Simplified One-Click Workflow (v2.3.0) 🎯
-The new `dev_start_frontend_with_browser` combines steps 1 and 2 above into a single command:
-
+**Now (v3.0):**
 ```typescript
-// BEFORE (v2.2.0): Two separate commands
-dev_start_log_streaming({ "command": "npm run dev", "processId": "student-app" })
-// Wait for server to start...
-dev_launch_test_browser({ "processId": "student-app" })
-
-// NOW (v2.3.0): Single command does everything!
-dev_start_frontend_with_browser({
-  "command": "npm run dev",
-  "processId": "student-project",
-  "teachingMode": true
-})
-// Server starts, waits for ready, then browser launches automatically!
+dev_start_sandbox()
 ```
 
-**Benefits for Students:**
-- 🚀 One command instead of two
-- ⏱️ No need to wait and guess when server is ready
-- 🎯 Browser launches at the perfect time
-- 📝 All logs in one place from the start
-- 🔧 Less chance for mistakes
-
-**Common Student Scenarios:**
-
-```typescript
-// Scenario 1: React app on default port
-dev_start_frontend_with_browser()
-// That's it! Uses all smart defaults
-
-// Scenario 2: Vite app with custom command
-dev_start_frontend_with_browser({
-  "command": "npm run dev -- --host",
-  "processId": "vite-project"
-})
-
-// Scenario 3: Next.js on different port
-dev_start_frontend_with_browser({
-  "command": "npm run dev",
-  "port": 3001,  // If auto-detect fails
-  "env": { "PORT": "3001" }
-})
-
-// Scenario 4: Quick demo mode (no DevTools)
-dev_start_frontend_with_browser({
-  "teachingMode": false  // Faster, no DevTools
-})
-```
+That's it. No parameters, no configuration, just works.
 
 ## Troubleshooting
 
-### Dev Server Not Starting
-1. Check the log file for error messages
-2. Verify the command works when run directly in terminal
-3. Check working directory is correct
-4. Ensure all dependencies are installed
-
-### Logs Not Appearing
-1. Check the output file path is writable
-2. Some frameworks buffer output - logs may appear in chunks
-3. Use `dev_get_status` to verify server is running
-
-### Process Won't Stop
-1. Use `dev_stop_log_streaming` first
-2. If that fails, the process may have crashed - check system process manager
-3. Restart Claude Code to clean up orphaned processes
-
-## Implementation Details
-
-### Process Management
-- Uses Node.js `spawn` with `detached: true` for proper process isolation
-- Implements graceful shutdown with SIGTERM signals
-- Automatically removes event listeners on process termination to prevent memory leaks
-- Attempts to kill process groups (`-pid`) to handle child processes
-
-### State Persistence
-- Saves process state to `${tmpdir}/mcp-dev-logger.json`
-- Restores process information on server restart (where possible)
-- Handles process cleanup on server shutdown
-
-### Log Streaming
-- Real-time streaming of both stdout and stderr
-- Timestamped log entries with process ID tagging
-- Error entries are clearly marked with `[ERROR]` prefix
-- Supports concurrent logging from multiple processes to different files
+### Sandbox won't start
+- Make sure you're in an Amplify Gen2 project directory
+- Check that `npx ampx` is available
+- Verify AWS credentials are configured
 
-## Limitations
+### Logs not appearing
+- Check that `resources/` folder exists (created automatically)
+- Use `dev_tail_sandbox_logs()` to verify logs are being written
 
-- Process management is best-effort - some processes may not respond to signals
-- Very large log files may impact performance of `dev_tail_logs`
-- Only captures server-side console output (not browser console logs)
-- Process state restoration is limited after server restarts (PIDs become invalid)
+### Process won't stop
+- Call `dev_stop_sandbox()` again
+- If still stuck, restart Claude Code
+- The process will be cleaned up automatically
 
 ## Development
 
-### Building
 ```bash
+# Build
 npm run build
-```
-
-### Watch Mode
-```bash
-npm run dev
-```
 
-### Testing
-```bash
-# Test with local installation
+# Install locally for testing
 claude mcp add dev-logger-test -s user -- node $(pwd)/dist/index.js
-
-# Start Claude and test tools
-claude
-> /mcp  # Check if server is connected
 ```
 
-## Contributing
-
-1. Fork the repository
-2. Create feature branch
-3. Make changes and test thoroughly
-4. Submit pull request with clear description
-
 ## License
 
 MIT License - see LICENSE file for details.
@@ -596,4 +229,3 @@ MIT License - see LICENSE file for details.
 For issues and questions:
 - Open an issue in the repository
 - Check existing issues for similar problems
-- Include log samples when reporting bugs