name: monitor
description: Real-time monitoring dashboard - system metrics, process monitoring, and resource tracking
agent: engineer
version: 1.0
classification: public
last_updated: 2026-01-26
effort_default: QUICK

⛔ DUAL-PATH ROUTING GATE - READ THIS FIRST

This skill requires the engineer agent. If you are NOT the engineer agent → STOP and delegate.

This skill has two paths based on request complexity.

PATH 1 - SIMPLE REQUESTS (Base Claude, Tier 1):
If user asks for: monitoring setup questions, dashboard configuration, monitoring best practices, metrics explanations
- ✅ You can handle this directly
- Provide setup guidance and monitoring strategies
- Do NOT delegate

Examples of Path 1:
- "How do I set up system monitoring?"
- "What metrics should I track?"
- "Explain CPU vs memory monitoring"
- "What's the best monitoring strategy?"

---

PATH 2 - COMPLEX REQUESTS (Engineer Agent, Tier 2b):
If user asks for: monitoring system deployment, multi-component setup, real-time dashboard configuration, integrated monitoring design
- ⛔ STOP and DELEGATE NOW

typescript Task(subagent_type="engineer", prompt="Execute monitor skill. Request: {user_request}")

Examples of Path 2:
- "Deploy monitoring across my infrastructure"
- "Set up real-time dashboards with alerts"
- "Configure monitoring for production systems"
- "Build comprehensive observability system"

---

DO NOT (BOTH PATHS):
- Read files beyond this SKILL.md
- Search web or external resources
- Create todos or project files
- Execute workflows or scripts (Path 1 only)
- Load other skills

If you ARE the engineer agent:
- ✅ Proceed to read this SKILL.md
- ✅ Load workflow phases below
- ✅ Execute with provided context

name: monitor
description: Real-time monitoring dashboard with activity timeline, file browser, markdown editor, and auto-refresh
agent: base
version: 1.5
classification: public
last_updated: 2026-01-20

FOR AI AGENTS: Real-time observability dashboard for framework monitoring and document review.
Load when: user wants to "monitor activity", "view dashboard", "start observability", "review documents"

Monitor - Real-Time Monitoring Skill

Real-time dashboard for monitoring Claude Code activity with integrated document viewer and markdown editor.

Pre-flight Checklist (MANDATORY)

STOP! Before executing this skill, complete this checklist:

• [ ] I have read this SKILL.md completely
• [ ] I understand the server start/stop workflow
• [ ] Dashboard runs on port 4000

USE WHEN

Invoke this skill when:
- User says "start monitoring" or "view dashboard"
- User wants real-time activity visibility
- User wants to edit framework files via web UI

DO NOT use when:
- Just reading files → Use Read tool directly
- Session tracking questions → Check sessions/ directly

Quick Start

/mon-start    # Start monitor server (port 4000)
/mon-stop     # Stop monitor server

Dashboard: http://localhost:4000

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Observability Server                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Claude Code ──> PostToolUse Hook ──> JSONL Events             │
│                                           │                     │
│  File Watcher ─────────────────────────────┤                    │
│                                           ▼                     │
│                                    WebSocket Hub ──> Clients    │
│                                           │                     │
│  REST API (read/write files) <────────────┘                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Framework Path Resolution

The monitor uses shared path resolution logic (library/framework-path-resolver.ts) to ensure consistency with session hooks:

Resolution Priority:
1. IA_FRAMEWORK_ROOT environment variable
2. Resolve via ~/.claude/CLAUDE.md symlink (follows symlink to actual framework location)
3. Fall back to ~/.claude

This ensures the monitor dashboard and session tracking always use the same framework root directory.

State Persistence

The dashboard preserves user interface state across refreshes using localStorage:

Preserved State:
- Expanded directory paths (ia-obs-expanded-dirs)
- Currently opened file (ia-obs-current-file)
- Selected file highlighting
- Theme preference (ia-obs-theme)

Benefits:
- Auto-refresh on file changes doesn't collapse the file tree
- Current file stays highlighted during refreshes
- State persists across browser sessions

Features

Allowed Paths

Read/Write Access:
- sessions/ - Session tracking files
- plans/ - Design documents
- skills/ - Skill definitions
- agents/ - Agent configurations
- commands/ - Slash commands
- docs/ - Documentation
- CLAUDE.md - Main navigation

No Write Access:
- hooks/ - Protected system hooks
- tools/ - Protected utilities
- servers/ - Protected infrastructure

Commands

Implementation Details:
- Commands are defined in skills/monitor/commands/ and symlinked to /commands/
- /mon-start checks for dependencies and installs them if missing before starting
- Uses scripts/manage.sh for server lifecycle management

API Endpoints

Scripts

Directory Structure

skills/monitor/
├── SKILL.md              # This file
├── STATUS.md             # Readiness tracking
├── README.md             # Quick reference
├── VERIFY.md             # Verification checklist
├── commands/
│   ├── mon-start.md      # /mon-start command
│   └── mon-stop.md       # /mon-stop command
├── scripts/
│   ├── server.ts
│   ├── watcher.ts
│   ├── events.ts
│   ├── types.ts
│   ├── manage.sh
│   └── hooks/
│       └── observe-events.ts
├── client/
│   ├── index.html
│   ├── app.ts
│   ├── components/
│   └── styles/
├── docs/
│   ├── architecture.md
│   └── api-reference.md
└── output/
    └── events/           # JSONL logs (gitignored)

Security

✅ Secure for localhost development use

The monitor dashboard has been thoroughly security reviewed and hardened:

Security Features

• Localhost-only binding - Server binds to 127.0.0.1 (network isolated)
• Path traversal prevention - Canonicalization with boundary checks
• Pattern-based file access - Automatic permissions for framework files (see below)
• Origin validation - WebSocket and CORS restricted to localhost
• Security logging - Access attempts logged for audit

Security Status

• 7 vulnerabilities identified - All critical issues fixed
• OWASP Top 10 reviewed - Compliant for localhost use
• CWE Top 25 analyzed - Key weaknesses mitigated
• Penetration tested - Path traversal, session attacks verified blocked

Documentation

• Security Overview: docs/security.md
• Vulnerability Analysis: docs/SECURITY-REVIEW.md
• Fix Documentation: docs/SECURITY-FIXES-APPLIED.md

Usage Guidelines

✅ Safe to use for:
- Local development monitoring
- Debugging Claude sessions
- Document review and exploration
- File viewing and editing
- Tracking real-time activity

❌ Do NOT use for:
- Network exposure without additional hardening
- Multi-user environments
- Production deployments
- Shared development servers

Network Exposure Requirements:
If you need to expose the dashboard to a network, you must implement:
- Authentication (JWT, OAuth, or basic auth)
- HTTPS/TLS encryption
- Rate limiting and DoS protection
- Session management and timeouts
- Full penetration testing
- Security team approval

See docs/security.md for complete security documentation.

File Permissions (Automated)

The monitor uses pattern-based permissions - new framework files are automatically accessible without code changes.

Auto-Allowed Files

Root-level files (no manual configuration needed):
- Any .md file at framework root (README.md, SECURITY.md, CHANGELOG.md, etc.)
- Any .pdf file at framework root
- Any .docx file at framework root
- Any .txt file at framework root

Example: Adding CONTRIBUTING.md to the framework root makes it instantly visible in the dashboard - no code changes required.

Auto-Allowed Directories

Full read/write access:
- sessions/ - Session metadata
- plans/ - Design documents
- skills/ - Skill implementations
- agents/ - Agent definitions
- commands/ - Command definitions
- docs/ - Documentation
- tools/ - Framework utilities
- hooks/ - Git hooks
- library/ - Shared resources

Always Blocked

• .env - Credentials
• .git/ - Git internals

Adding New File Types

To allow additional file extensions at framework root:

Edit: skills/monitor/scripts/types.ts

export const ALLOWED_ROOT_FILE_EXTENSIONS = {
  read: ['.md', '.pdf', '.docx', '.txt', '.json'], // Add .json
  write: ['.pdf', '.docx'],
};

Restart: /mon-start (restarts automatically if running)

Test: bun run skills/monitor/scripts/test-permissions.ts

Documentation

Complete details: docs/file-permissions.md

Verification Checklist

• [ ] Server starts without errors
• [ ] Dashboard loads at http://localhost:4000
• [ ] Events appear in real-time
• [ ] File browser shows allowed directories
• [ ] File browser auto-refreshes when files change
• [ ] Copy path button works in toolbar and file tree (hover to reveal)
• [ ] Sidebar can be resized horizontally by dragging the edge
• [ ] Delete operations work for both files and folders
• [ ] Close all tabs and close other tabs buttons appear when tabs are open
• [ ] Document viewers work (PDF, images, code, text)
• [ ] Editor saves files correctly
• [ ] Theme switching works

Version: 1.5
Last Updated: 2026-01-20
Status: Active - Core infrastructure skill for monitoring and document review