Iris MCP - MCP Server

Model Context Protocol server for cross-project Claude Code coordination

Iris MCP enables Claude Code instances across different project directories to communicate and coordinate. Stay in one project while orchestrating teams across your entire codebase ecosystem.

🎯 What is Iris MCP?

Iris MCP is a groundbreaking Model Context Protocol server that enables direct communication between Claude Code instances across different project directories, machines, and networks, creating the first true cross-codebase AI collaboration system with remote orchestration.

The Problem

Modern software development involves multiple codebases (frontend, backend, mobile, infrastructure) that must stay synchronized. Currently, when you need to coordinate changes across projects:

Context Switch: Stop work, manually navigate to other project
Launch New Claude: Start fresh Claude Code session, losing context
Explain Everything: Re-explain what changed and why
Copy/Paste: Manually transfer information between projects
Repeat: Do this for every affected project

This workflow is slow, error-prone, and breaks your flow state. Studies show developers lose 23 minutes of productivity on average when context switching.

The Iris Solution

Stay in your current project while Claude coordinates with other teams automatically:

You (in frontend project):
"Ask the backend team what their API versioning strategy is"

Claude (frontend) → Iris MCP → Claude (backend) → analyzes backend code → responds
                                                                          ↓
"The backend team uses semantic versioning with /api/v1, /api/v2 prefixes"

You never left the frontend project. Iris handled the coordination automatically.

What Makes Iris Revolutionary

Iris fills critical gaps that no existing multi-agent system addresses:

Feature	Iris MCP	Symphony of One	Claude-Flow	Agent-MCP	Others
Cross-Project Communication	✅	❌	❌	❌	❌
Independent Team Contexts	✅	❌	❌	❌	❌
Direct Agent-to-Agent Messaging	✅	❌	❌	❌	❌
Per-Team MCP Server Access	✅	❌	❌	❌	❌
Zero Shared State	✅	❌	❌	❌	❌
Natural Language Coordination	✅	❌	❌	❌	❌
Remote Execution via SSH	✅	❌	❌	❌	❌
Bidirectional SSH Tunneling	✅	❌	❌	❌	❌
Session Persistence	✅	❌	❌	❌	❌

All existing solutions work within a single project boundary. Iris breaks this limitation by enabling communication between completely independent codebases, each with their own:

Directory structure and dependencies
.claude/ configuration
Session/Context
MCP servers and tools
Git repositories
Team-specific context

Context Isolation = Better Results

Each team's Claude instance maintains complete context isolation, meaning more accurate, specialized responses:

Team Frontend Claude knows:
✅ React components, Tailwind classes, Redux patterns
✅ Frontend-specific MCP servers (Figma, Storybook)
✅ Frontend CLAUDE.md instructions
❌ Backend database schemas (not needed!)
❌ Mobile iOS/Android specifics (not needed!)

Team Backend Claude knows:
✅ Database schemas, API endpoints, migrations
✅ Backend-specific MCP servers (PostgreSQL, Redis)
✅ Backend CLAUDE.md instructions
❌ Frontend component structure (not needed!)

Your frontend in TypeScript/React can coordinate with your backend in Python/Django, and your mobile app in Swift—all simultaneously, all with perfect context.

Real Developer Pain Solved

From GitHub Issue #2929:

"Use cases are infinite. I could have a specialist claude run on my specific server answering to natural language requests, while a local generalist claude call it, having no clue of the specific API."

Developers are already asking for this! Iris MCP delivers it.

✨ Key Features

Core MCP Server (Phase 1) ✅

17 MCP Tools for comprehensive team coordination
Process Pooling with LRU eviction (10-20x performance improvement)
Session Persistence with SQLite database
Transport Abstraction (Local, SSH, RemoteSSH2)
Remote Execution via OpenSSH client or ssh2 library
Reverse MCP Tunneling for bidirectional communication
Session MCP Configuration with sessionId-based routing
Permission Approval System (yes/no/ask/forward modes)
Hot-Reloadable Configuration with environment variable interpolation
Wonder Logger with OpenTelemetry integration
Event-Driven Architecture with RxJS observables

Web Dashboard (Phase 2) ✅

React SPA with real-time monitoring
WebSocket Integration for live updates
Permission Approval Modal for interactive approval
Log Viewer with filtering and search
Process Monitoring with health metrics
Configuration Editor for team management

Remote Teams

Execute Claude Code on remote machines via SSH while maintaining local orchestration:

teams:
  team-production:
    remote: "ssh user@prod-server"
    claudePath: "~/.local/bin/claude"
    path: "/opt/production/app"
    enableReverseMcp: true  # Enable bidirectional tunneling

Capabilities:

Execute on remote servers without local codebase
Automatic SSH tunnel establishment
Reverse MCP tunneling for remote→local communication
Dual SSH implementation (OpenSSH client + ssh2 library)
Session persistence across SSH connections

Reverse MCP Tunneling

Bidirectional orchestration where remote teams can coordinate local teams:

Local Machine ←────SSH Tunnel────→ Remote Machine
  (Iris MCP)      -R 1615:...         (Claude Code)
      ↑                                      │
      └──────── HTTP via tunnel ─────────────┘

Remote Claude instances can use Iris MCP tools to:

Wake local teams
Send messages to local teams
Fork local sessions for debugging
List all configured teams

Security: SSH-encrypted tunneling, permission approval system, localhost-only binding.

🚀 Quick Start

New to Iris? Check out GETTING_STARTED.md for a complete setup guide!

One-Command Installation

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/jenova-marie/iris-mcp/main/setup.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/jenova-marie/iris-mcp/main/setup.ps1 | iex

Note: The PowerShell script is untested on real Windows systems. If you encounter errors, please open an issue with error details or submit a PR with fixes. We appreciate your help! 🙏

These interactive scripts will:

✓ Check prerequisites (Node.js 18+)
✓ Install Iris MCP globally
✓ Guide you through team configuration
✓ Connect to Claude Code
✓ Start the server

That's it! You'll be coordinating AI teams in under 5 minutes. 🚀

Manual Installation

# Install globally from npm
npm install -g @jenova-marie/iris-mcp

# Verify installation
iris-mcp --version

# Add your projects as teams
iris-mcp add-team frontend ~/code/my-frontend
iris-mcp add-team backend ~/code/my-backend

# Connect to Claude Code
iris-mcp install

# Start the server
iris-mcp

See GETTING_STARTED.md for detailed usage examples and troubleshooting.

🛠️ MCP Tools

Iris MCP provides 17 comprehensive tools for team coordination:

Communication Tools

`send_message`

Send a message to a team and wait for response.

{
  fromTeam: "team-frontend",
  toTeam: "team-backend",
  message: "What authentication strategy do you use?",
  timeout: 30000  // optional, default 30s
}

Modes:

timeout > 0: Wait for response (default)
timeout: -1: Fire-and-forget (async)
persist: true: Queue in database for later

Example prompts:

"Tell the backend team about the breaking API change"
"Ask mobile team if they support push notifications"

`ask_message`

Semantic alias for send_message emphasizing questions.

{
  fromTeam: "team-frontend",
  toTeam: "team-backend",
  message: "What database migration system do you use?",
  timeout: 30000
}

Example prompts:

"Ask the backend team about their authentication strategy"
"Find out from mobile team what iOS version they target"

`quick_message`

Fire-and-forget messaging without waiting for response.

{
  fromTeam: "team-backend",
  toTeam: "team-frontend",
  message: "New API endpoint deployed: GET /api/v2/users"
}

Example prompts:

"Quickly tell frontend team the deployment is complete"
"Notify all teams about the maintenance window"

Session Management Tools

`session_reboot`

Create a brand new session with fresh UUID.

{
  fromTeam: "team-iris",
  toTeam: "team-backend"
}

Terminates existing process and creates new session with clean slate.

`session_delete`

Permanently delete a session without creating replacement.

{
  fromTeam: "team-iris",
  toTeam: "team-backend"
}

`session_fork`

Launch interactive terminal window for manual interaction.

{
  fromTeam: "team-iris",
  toTeam: "team-backend"
}

Opens separate terminal with claude --resume --fork-session for direct interaction.

`session_cancel`

Cancel a running session operation.

{
  fromTeam: "team-iris",
  team: "team-backend"
}

Attempts to interrupt long-running operations by sending ESC to stdin.

`session_report`

View conversation history for a session.

{
  fromTeam: "team-iris",
  team: "team-backend"
}

Returns complete conversation cache including all messages and protocol responses.

Process Management Tools

`team_wake`

Wake up a team by ensuring its process is active.

{
  fromTeam: "team-iris",
  team: "team-backend"
}

Creates session-specific process (e.g., iris->backend) for conversation isolation.

`team_launch`

Semantic alias for team_wake emphasizing activation.

{
  fromTeam: "team-iris",
  team: "team-backend"
}

`team_sleep`

Put a team to sleep by terminating its process.

{
  fromTeam: "team-iris",
  team: "team-backend",
  force: false  // optional
}

`team_wake_all`

Wake all configured teams sequentially.

{
  fromTeam: "team-iris",
  parallel: false  // NOT RECOMMENDED - unstable
}

Warning: Parallel mode causes timeouts due to simultaneous Claude spawning.

`team_status`

Get status of teams, processes, and notifications.

{
  fromTeam: "team-iris",
  team: "team-backend",  // optional, omit for all teams
  includeNotifications: true  // optional, default true
}

Response:

{
  "teams": [{
    "name": "team-backend",
    "path": "/Users/you/projects/backend",
    "active": true,
    "processInfo": {
      "status": "idle",
      "pid": 12345,
      "uptime": 180000
    },
    "sessionInfo": {
      "sessionId": "abc-123",
      "messageCount": 47,
      "lastUsed": 1704067200000
    }
  }],
  "pool": {
    "totalProcesses": 3,
    "maxProcesses": 10
  }
}

Utility Tools

`list_teams`

List all configured teams.

{}

Returns team names with configuration details (path, description, color, settings).

`get_logs`

Query in-memory logs from Iris MCP server.

{
  logs_since: 1704067200000,  // optional timestamp
  level: "error",             // optional: 'trace'|'debug'|'info'|'warn'|'error'|'fatal'
  format: "parsed"            // optional: 'raw'|'parsed'
}

`get_date`

Get current system date and time.

{}

Returns ISO 8601, UTC string, Unix timestamp, and detailed components.

`permissions__approve`

Permission approval handler for Claude Code's --permission-prompt-tool.

{
  tool_name: "mcp__iris__team_wake",
  input: { team: "team-backend" },
  reason: "Need to coordinate deployment"
}

Auto-approves all mcp__iris__* tools, denies everything else.

📁 Project Structure

iris-mcp/
├── src/
│   ├── index.ts                      # MCP server entry point
│   ├── iris.ts                       # IrisOrchestrator (Business Logic Layer)
│   ├── config/
│   │   ├── teams-config.ts           # Configuration with Zod validation
│   │   └── iris-config.ts            # Config schema and types
│   ├── session/
│   │   ├── session-manager.ts        # Session database and file management
│   │   ├── session-store.ts          # SQLite session store
│   │   ├── path-utils.ts             # Session file path utilities
│   │   └── types.ts                  # Session interfaces
│   ├── process-pool/
│   │   ├── pool-manager.ts           # Process pool with LRU eviction
│   │   ├── claude-process.ts         # Claude process wrapper
│   │   └── types.ts                  # Process interfaces
│   ├── transport/
│   │   ├── base-transport.ts         # Transport abstraction interface
│   │   ├── local-transport.ts        # Local process execution
│   │   ├── ssh-transport.ts          # OpenSSH client execution
│   │   └── remote-ssh2-transport.ts  # ssh2 library execution
│   ├── actions/
│   │   ├── send-message.ts           # send_message tool
│   │   ├── ask-message.ts            # ask_message tool
│   │   ├── quick-message.ts          # quick_message tool
│   │   ├── session-reboot.ts         # session_reboot tool
│   │   ├── session-delete.ts         # session_delete tool
│   │   ├── session-fork.ts           # session_fork tool
│   │   ├── session-cancel.ts         # session_cancel tool
│   │   ├── team-wake.ts              # team_wake tool
│   │   ├── team-launch.ts            # team_launch tool
│   │   ├── team-sleep.ts             # team_sleep tool
│   │   ├── team-wake-all.ts          # team_wake_all tool
│   │   ├── team-status.ts            # team_status tool
│   │   ├── session-report.ts         # session_report tool
│   │   ├── list-teams.ts             # list_teams tool
│   │   ├── get-logs.ts               # get_logs tool
│   │   ├── get-date.ts               # get_date tool
│   │   └── grant-permission.ts       # permissions__approve tool
│   ├── dashboard/
│   │   ├── app.tsx                   # React SPA entry point
│   │   ├── components/               # React components
│   │   └── server.ts                 # Express + WebSocket backend
│   ├── notifications/
│   │   ├── queue.ts                  # SQLite notification queue
│   │   └── schema.sql                # Database schema
│   ├── logging/
│   │   ├── wonder-logger.ts          # Wonder Logger implementation
│   │   └── opentelemetry.ts          # OpenTelemetry integration
│   └── utils/
│       ├── logger.ts                 # Structured logging to stderr
│       ├── errors.ts                 # Custom error hierarchy
│       ├── validation.ts             # Input validation
│       └── env-interpolation.ts      # Environment variable interpolation
├── docs/
│   ├── CONCEPT.md                    # Vision and conceptual overview
│   ├── ARCHITECTURE.md               # System design and components
│   ├── ACTIONS.md                    # All 17 MCP tools documentation
│   ├── CONFIG.md                     # Configuration management
│   ├── SESSION.md                    # Session management deep dive
│   ├── REMOTE.md                     # Remote execution via SSH
│   ├── REVERSE_MCP.md                # Bidirectional SSH tunneling
│   ├── DASHBOARD.md                  # Web dashboard documentation
│   ├── FEATURES.md                   # Comprehensive feature inventory
│   └── NOMENCLATURE.md               # Core concepts and terminology
├── data/
│   ├── team-sessions.db              # Session database (auto-created)
│   └── notifications.db              # Notification queue (auto-created)
├── config.yaml                       # Your team configuration
└── package.json

🏗️ Architecture

Three-Layer Design

Iris uses a clean three-layer architecture with strict separation of concerns:

┌─────────────────────────────────────────────┐
│        IrisOrchestrator (BLL)              │
│  Coordinates SessionManager + PoolManager   │
└──────────────┬──────────────────────────────┘
               │
       ┌───────┴────────┐
       │                │
       ▼                ▼
┌──────────────┐  ┌─────────────────────┐
│SessionManager│  │ClaudeProcessPool    │
│              │  │                     │
│DB + Files    │  │Process Lifecycle    │
│              │  │                     │
│NO processes  │  │NO session lookup    │
└──────┬───────┘  └──────────┬──────────┘
       │                     │
       ▼                     ▼
┌──────────────┐  ┌─────────────────────┐
│SessionStore  │  │ClaudeProcess        │
│SQLite        │  │Transport Abstraction│
└──────────────┘  └─────────────────────┘
                          │
              ┌───────────┴───────────┐
              │                       │
              ▼                       ▼
       ┌─────────────┐        ┌──────────────┐
       │LocalTransport│        │SSHTransport  │
       └─────────────┘        └──────────────┘

Layer 1: IrisOrchestrator (Business Logic Layer)

Coordinates SessionManager + ClaudeProcessPool
Implements complete message flow
Provides API for MCP tools
RxJS-based reactive architecture

Layer 2: SessionManager + ClaudeProcessPool

SessionManager: Session database management, file validation, 60s caching
ClaudeProcessPool: Process lifecycle, LRU eviction, health monitoring
Strict separation: SessionManager does NOT spawn processes, Pool does NOT manage sessions

Layer 3: SessionStore + ClaudeProcess

SessionStore: SQLite persistence with WAL mode
ClaudeProcess: Transport abstraction (Local, SSH, RemoteSSH2)

Transport Abstraction

Iris supports multiple execution modes via pluggable transports:

LocalTransport:

Direct child process execution via Node.js spawn()
Lowest latency, highest reliability
Used for local teams

SSHTransport (OpenSSH client):

Execute remote Claude via ssh user@host
Requires OpenSSH client installed
Best performance for remote execution
Production-ready, battle-tested

RemoteSSH2Transport (ssh2 library):

Pure Node.js SSH implementation
No external dependencies
Platform-independent
Experimental, for environments without SSH client

Session Persistence

Persistent team-to-team sessions maintain conversation continuity:

Each (fromTeam, toTeam) pair has exactly one session (e.g., iris→backend, backend→frontend)
ALL sessions require both fromTeam and toTeam (no null sessions)
Sessions stored at ~/.claude/projects/{escaped-path}/{sessionId}.jsonl
Database tracks metadata (message count, last used, status)
Sessions resume across process restarts

Schema:

CREATE TABLE sessions (
  pool_key TEXT PRIMARY KEY,
  session_id TEXT NOT NULL,
  message_count INTEGER DEFAULT 0,
  last_used_at INTEGER,
  status TEXT DEFAULT 'active',
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
);

Process Pool Management

Iris maintains a pool of Claude Code processes with:

LRU Eviction: When pool is full, least recently used process is terminated
Idle Timeout: Processes automatically terminate after 1 hour of inactivity (configurable)
Health Checks: Regular monitoring ensures processes stay healthy (every 30s)
Warm Starts: Reuses existing processes for 10-20x faster responses
Session Resumption: Each process resumes its specific session via --resume <sessionId>

Two-Timeout Architecture:

responseTimeout: How long to wait for Claude to respond (default: 2 minutes)
mcpTimeout: Maximum time for MCP server communication (default: 5 seconds)

Reactive Architecture

Iris uses RxJS observables for event-driven communication:

// Process events as Observable streams
process.events$
  .pipe(
    filter(event => event.type === 'message-response'),
    timeout(responseTimeout),
    catchError(err => of({ type: 'error', error: err }))
  )
  .subscribe(handleResponse);

Benefits:

Composable event handling
Automatic timeout management
Error recovery with retry logic
Backpressure handling

Session MCP Configuration

Remote teams can be configured with Session MCP - per-session MCP configuration:

teams:
  team-remote:
    remote: "ssh user@remote-host"
    sessionMcpEnabled: true
    sessionMcpPath: "/path/to/session-mcp-server"

Each session gets its own MCP server instance with session-specific context.

Wonder Logger

OpenTelemetry-based observability with structured logging:

logger.info('Process spawned', {
  poolKey: 'iris->backend',
  sessionId: 'abc-123',
  pid: 12345,
  transport: 'ssh'
});

Features:

Structured JSON logging to stderr
OpenTelemetry spans and traces
Context propagation across async boundaries
Log aggregation support (Grafana, Datadog, etc.)

Permission Approval System

Four modes for controlling team actions:

yes: Auto-approve all actions (default)
no: Auto-deny all actions (read-only mode)
ask: Prompt user for each action (via Dashboard)
forward: Forward permission request to calling team

teams:
  team-production:
    grantPermission: ask  # Require approval for all actions

🎯 Configuration

Example Configuration

settings:
  # Process Timeouts
  sessionInitTimeout: 30000     # 30 seconds for session creation
  spawnTimeout: 20000           # 20 seconds for process spawn
  responseTimeout: 120000       # 2 minutes for Claude response
  mcpTimeout: 5000              # 5 seconds for MCP server communication

  # Process Pool
  idleTimeout: 3600000          # 1 hour idle before termination
  maxProcesses: 10              # Max concurrent processes
  healthCheckInterval: 30000    # 30 seconds health check

  # Server
  httpPort: ${IRIS_HTTP_PORT:-1615}
  defaultTransport: http        # stdio or http

teams:
  # Local Team
  team-frontend:
    path: /Users/you/projects/frontend
    description: React frontend application
    idleTimeout: 600000         # 10 minutes (override)
    grantPermission: yes
    color: "#61DAFB"

  # Remote Team with Reverse MCP
  team-production:
    remote: "ssh user@prod-server"
    claudePath: "~/.local/bin/claude"
    path: "/opt/production/app"
    description: Production backend server
    enableReverseMcp: true      # Enable bidirectional tunneling
    reverseMcpPort: 1615        # Port to tunnel
    allowHttp: false            # Use HTTPS for production
    grantPermission: ask        # Require approval for actions
    color: "#E34F26"

  # Remote Team with Session MCP
  team-mobile:
    remote: "ssh user@mobile-server"
    path: "/home/user/mobile-app"
    sessionMcpEnabled: true
    sessionMcpPath: "/usr/local/bin/session-mcp"
    color: "#3DDC84"

Environment Variable Interpolation

Use ${VAR:-default} syntax for dynamic configuration:

settings:
  httpPort: ${IRIS_HTTP_PORT:-1615}
  idleTimeout: ${IRIS_IDLE_TIMEOUT:-3600000}
  maxProcesses: ${IRIS_MAX_PROCESSES:-10}

teams:
  team-production:
    path: ${PROD_PATH}          # Required (throws if not set)
    idleTimeout: ${PROD_TIMEOUT:-1800000}

Example .env file:

IRIS_HTTP_PORT=1615
IRIS_MAX_PROCESSES=20
PROD_PATH=/opt/production/app
PROD_TIMEOUT=3600000

Configuration Hot-Reload

Iris watches config.yaml with fs.watchFile() (1s interval) and automatically reloads configuration changes without server restart.

🔧 Development

Build

pnpm build

Watch Mode

pnpm dev

Testing

# Run all tests
pnpm test

# Unit tests only (fast, mocked)
pnpm test:unit

# Integration tests only (slow, real Claude processes)
pnpm test:integration

# Run specific test file
pnpm test:run path/to/test.ts

# Watch mode with UI
pnpm test:ui

Run MCP Inspector

pnpm inspector

This opens the MCP inspector at http://localhost:5173 to test tools interactively.

Logs

All logs go to stderr in JSON format:

{"level":"info","context":"server","message":"Iris MCP Server initialized","teams":["frontend","backend"],"timestamp":"2025-01-15T10:30:00.000Z"}
{"level":"info","context":"pool","message":"Process spawned","poolKey":"iris->backend","sessionId":"abc-123","pid":12345,"timestamp":"2025-01-15T10:30:15.000Z"}

Log Contexts:

server: MCP server lifecycle
config: Configuration loading
session-manager: Session operations
session-store: Database operations
pool: Process pool management
process:teamName: Individual process logs
transport:ssh: SSH transport operations

⚡ Performance

Process Pooling Benefits

Cold Start (first request to a team):

Session creation: ~7-12 seconds
Process spawn: ~1-2 seconds
Total: ~8-14 seconds

Warm Start (subsequent requests):

Session lookup: ~1ms (cache hit)
Process reuse: ~1ms (pool hit)
Total: ~500ms-2s (Claude API time only)

Speedup: 10-20x faster with pooling!

Session Persistence

Without Iris (each request):

New conversation context every time
No memory of previous interactions
Lost context between teams

With Iris:

Persistent (fromTeam, toTeam) sessions
Full conversation history maintained
Claude remembers previous exchanges

Resource Efficiency

Process Pool Management:

LRU eviction keeps memory bounded
Idle timeout (1 hour) terminates unused processes
Health checks (30s) detect and clean unhealthy processes
Max 10 concurrent processes (configurable)

Memory Usage (typical):

10 processes: ~600 MB - 1.25 GB
Session database: ~2 MB per 10,000 sessions
Notification queue: ~5 MB per 10,000 notifications

Test Suite Performance

Test Optimizations:

Unit tests: 203 passing in <2 seconds
Integration tests: 85% faster (7min → 1min) with beforeAll optimization
Timeout handling: Fixed spurious errors 20s after completion

🚨 Troubleshooting

"Team not found" error

Symptom: TeamNotFoundError when using tools

Solutions:

Check that team name in config.yaml matches exactly (case-sensitive)
Verify the path exists and is absolute
Restart Iris after modifying config.yaml (or wait for hot-reload)

"Process failed to spawn"

Symptom: Error during process creation

Solutions:

Ensure Claude CLI is installed: which claude
Check that the team's project directory exists and is accessible
Try running claude --session-id test-$(uuidgen) --print ping manually in the team directory
Check logs for detailed error: context:"process:teamName"
For remote teams, verify SSH connectivity: ssh user@host 'which claude'

"Timeout exceeded"

Symptom: Message takes longer than configured timeout

Solutions:

Increase responseTimeout in settings: responseTimeout: 180000 (3 minutes)
Check if the target team's Claude process is stuck (view logs)
Verify Claude API is responding (not rate-limited)
For session initialization timeouts, increase sessionInitTimeout in config

"Session file was not created"

Symptom: Session initialization fails

Solutions:

Verify ~/.claude/projects/ directory exists: mkdir -p ~/.claude/projects
Check permissions: ls -la ~/.claude
Ensure team path is correct and accessible
Check available disk space: df -h

SSH Connection Issues

Symptom: Remote team execution fails

Solutions:

Test SSH manually: ssh user@host 'echo hello'
Check SSH key authentication is configured
Verify claudePath is correct on remote machine
For reverse MCP, ensure port 1615 is not blocked
Check SSH logs: ssh -v user@host

Database Locked

Symptom: SQLite errors about locked database

Solutions:

Close other Iris MCP instances
Delete WAL files: rm data/*.db-wal data/*.db-shm
Check for zombie processes: ps aux | grep iris

Process Pool Full

Symptom: All process slots occupied

Solutions:

Increase maxProcesses in config.yaml settings
Reduce idleTimeout to free processes faster
Check health check logs to see which processes are active

🗺️ Roadmap

Phase 1: Core MCP Server ✅

17 MCP Tools for team coordination
Process Pool with LRU eviction
Session Persistence with SQLite
Transport Abstraction (Local, SSH, RemoteSSH2)
Remote Execution via SSH
Reverse MCP Tunneling
Session MCP Configuration
Wonder Logger with OpenTelemetry
Permission Approval System
Hot-Reloadable Configuration
Event-Driven Architecture with RxJS

Phase 2: Web Dashboard ✅

React SPA with real-time monitoring
WebSocket Integration for live updates
Permission Approval Modal
Log Viewer with filtering
Process Monitoring with health metrics
Configuration Editor

Status: Fully implemented and production-ready!

Phase 3: Programmatic API 🔮

RESTful HTTP endpoints
WebSocket streaming
API key authentication
Official SDKs (TypeScript, Python)

See src/api/README.md

Phase 4: CLI Interface 🔮

iris ask command
iris status monitoring
Interactive shell mode
Built with Ink (React for terminals)

See src/cli/README.md

Phase 5: Intelligence Layer 🔮

Loop detection
Destructive action prevention
Pattern recognition
Self-aware coordination
Autonomous multi-team orchestration

See src/intelligence/README.md

📚 Documentation

Core Documentation

Getting Started - Installation and quick start guide
Concept - Vision and conceptual overview
Architecture - System design and component interaction
Actions - All 17 MCP tools documentation
Configuration - Complete YAML config reference
Features - Comprehensive feature inventory
Nomenclature - Core concepts and terminology

Advanced Topics

Session Management - Session database and file management
Remote Execution - SSH transport and remote teams
Reverse MCP - Bidirectional SSH tunneling
Dashboard - Web dashboard documentation

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

How to Contribute

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/your-username/iris-mcp
cd iris-mcp

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run in watch mode
pnpm dev

# Build the project
pnpm build

Please ensure all tests pass before submitting a PR.

📄 License

MIT License - see LICENSE file for details

🌟 Why "Iris"?

Iris was the Greek goddess of the rainbow and messenger of the gods, bridging heaven and earth. Similarly, Iris MCP bridges your AI agents across project boundaries.

One messenger. Many teams. Infinite coordination.

Built with ❤️ by Jenova Marie

Model Context Protocol server for cross-project Claude Code coordination

Iris MCP enables Claude Code instances across different project directories to communicate and coordinate. Stay in one project while orchestrating teams across your entire codebase ecosystem.

🎯 What is Iris MCP?

The Problem

Modern software development involves multiple codebases (frontend, backend, mobile, infrastructure) that must stay synchronized. Currently, when you need to coordinate changes across projects:

Context Switch: Stop work, manually navigate to other project
Launch New Claude: Start fresh Claude Code session, losing context
Explain Everything: Re-explain what changed and why
Copy/Paste: Manually transfer information between projects
Repeat: Do this for every affected project

This workflow is slow, error-prone, and breaks your flow state. Studies show developers lose 23 minutes of productivity on average when context switching.

The Iris Solution

Stay in your current project while Claude coordinates with other teams automatically:

You (in frontend project):
"Ask the backend team what their API versioning strategy is"

Claude (frontend) → Iris MCP → Claude (backend) → analyzes backend code → responds
                                                                          ↓
"The backend team uses semantic versioning with /api/v1, /api/v2 prefixes"

You never left the frontend project. Iris handled the coordination automatically.

What Makes Iris Revolutionary

Iris fills critical gaps that no existing multi-agent system addresses:

Feature	Iris MCP	Symphony of One	Claude-Flow	Agent-MCP	Others
Cross-Project Communication	✅	❌	❌	❌	❌
Independent Team Contexts	✅	❌	❌	❌	❌
Direct Agent-to-Agent Messaging	✅	❌	❌	❌	❌
Per-Team MCP Server Access	✅	❌	❌	❌	❌
Zero Shared State	✅	❌	❌	❌	❌
Natural Language Coordination	✅	❌	❌	❌	❌
Remote Execution via SSH	✅	❌	❌	❌	❌
Bidirectional SSH Tunneling	✅	❌	❌	❌	❌
Session Persistence	✅	❌	❌	❌	❌

All existing solutions work within a single project boundary. Iris breaks this limitation by enabling communication between completely independent codebases, each with their own:

Directory structure and dependencies
.claude/ configuration
Session/Context
MCP servers and tools
Git repositories
Team-specific context

Context Isolation = Better Results

Each team's Claude instance maintains complete context isolation, meaning more accurate, specialized responses:

Team Frontend Claude knows:
✅ React components, Tailwind classes, Redux patterns
✅ Frontend-specific MCP servers (Figma, Storybook)
✅ Frontend CLAUDE.md instructions
❌ Backend database schemas (not needed!)
❌ Mobile iOS/Android specifics (not needed!)

Team Backend Claude knows:
✅ Database schemas, API endpoints, migrations
✅ Backend-specific MCP servers (PostgreSQL, Redis)
✅ Backend CLAUDE.md instructions
❌ Frontend component structure (not needed!)

Your frontend in TypeScript/React can coordinate with your backend in Python/Django, and your mobile app in Swift—all simultaneously, all with perfect context.

Real Developer Pain Solved

From GitHub Issue #2929:

"Use cases are infinite. I could have a specialist claude run on my specific server answering to natural language requests, while a local generalist claude call it, having no clue of the specific API."

Developers are already asking for this! Iris MCP delivers it.

✨ Key Features

Core MCP Server (Phase 1) ✅

17 MCP Tools for comprehensive team coordination
Process Pooling with LRU eviction (10-20x performance improvement)
Session Persistence with SQLite database
Transport Abstraction (Local, SSH, RemoteSSH2)
Remote Execution via OpenSSH client or ssh2 library
Reverse MCP Tunneling for bidirectional communication
Session MCP Configuration with sessionId-based routing
Permission Approval System (yes/no/ask/forward modes)
Hot-Reloadable Configuration with environment variable interpolation
Wonder Logger with OpenTelemetry integration
Event-Driven Architecture with RxJS observables

Web Dashboard (Phase 2) ✅

React SPA with real-time monitoring
WebSocket Integration for live updates
Permission Approval Modal for interactive approval
Log Viewer with filtering and search
Process Monitoring with health metrics
Configuration Editor for team management

Remote Teams

Execute Claude Code on remote machines via SSH while maintaining local orchestration:

teams:
  team-production:
    remote: "ssh user@prod-server"
    claudePath: "~/.local/bin/claude"
    path: "/opt/production/app"
    enableReverseMcp: true  # Enable bidirectional tunneling

Capabilities:

Execute on remote servers without local codebase
Automatic SSH tunnel establishment
Reverse MCP tunneling for remote→local communication
Dual SSH implementation (OpenSSH client + ssh2 library)
Session persistence across SSH connections

Reverse MCP Tunneling

Bidirectional orchestration where remote teams can coordinate local teams:

Local Machine ←────SSH Tunnel────→ Remote Machine
  (Iris MCP)      -R 1615:...         (Claude Code)
      ↑                                      │
      └──────── HTTP via tunnel ─────────────┘

Remote Claude instances can use Iris MCP tools to:

Wake local teams
Send messages to local teams
Fork local sessions for debugging
List all configured teams

Security: SSH-encrypted tunneling, permission approval system, localhost-only binding.

🚀 Quick Start

New to Iris? Check out GETTING_STARTED.md for a complete setup guide!

One-Command Installation

Linux/macOS:

curl -fsSL https://raw.githubusercontent.com/jenova-marie/iris-mcp/main/setup.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/jenova-marie/iris-mcp/main/setup.ps1 | iex

Note: The PowerShell script is untested on real Windows systems. If you encounter errors, please open an issue with error details or submit a PR with fixes. We appreciate your help! 🙏

These interactive scripts will:

✓ Check prerequisites (Node.js 18+)
✓ Install Iris MCP globally
✓ Guide you through team configuration
✓ Connect to Claude Code
✓ Start the server

That's it! You'll be coordinating AI teams in under 5 minutes. 🚀

Manual Installation

# Install globally from npm
npm install -g @jenova-marie/iris-mcp

# Verify installation
iris-mcp --version

# Add your projects as teams
iris-mcp add-team frontend ~/code/my-frontend
iris-mcp add-team backend ~/code/my-backend

# Connect to Claude Code
iris-mcp install

# Start the server
iris-mcp

See GETTING_STARTED.md for detailed usage examples and troubleshooting.

🛠️ MCP Tools

Iris MCP provides 17 comprehensive tools for team coordination:

Communication Tools

`send_message`

Send a message to a team and wait for response.

{
  fromTeam: "team-frontend",
  toTeam: "team-backend",
  message: "What authentication strategy do you use?",
  timeout: 30000  // optional, default 30s
}

Modes:

timeout > 0: Wait for response (default)
timeout: -1: Fire-and-forget (async)
persist: true: Queue in database for later

Example prompts:

"Tell the backend team about the breaking API change"
"Ask mobile team if they support push notifications"

`ask_message`

Semantic alias for send_message emphasizing questions.

{
  fromTeam: "team-frontend",
  toTeam: "team-backend",
  message: "What database migration system do you use?",
  timeout: 30000
}

Example prompts:

"Ask the backend team about their authentication strategy"
"Find out from mobile team what iOS version they target"

`quick_message`

Fire-and-forget messaging without waiting for response.

{
  fromTeam: "team-backend",
  toTeam: "team-frontend",
  message: "New API endpoint deployed: GET /api/v2/users"
}

Example prompts:

"Quickly tell frontend team the deployment is complete"
"Notify all teams about the maintenance window"

Session Management Tools

`session_reboot`

Create a brand new session with fresh UUID.

{
  fromTeam: "team-iris",
  toTeam: "team-backend"
}

Terminates existing process and creates new session with clean slate.

`session_delete`

Permanently delete a session without creating replacement.

{
  fromTeam: "team-iris",
  toTeam: "team-backend"
}

`session_fork`

Launch interactive terminal window for manual interaction.

{
  fromTeam: "team-iris",
  toTeam: "team-backend"
}

Opens separate terminal with claude --resume --fork-session for direct interaction.

`session_cancel`

Cancel a running session operation.

{
  fromTeam: "team-iris",
  team: "team-backend"
}

Attempts to interrupt long-running operations by sending ESC to stdin.

`session_report`

View conversation history for a session.

{
  fromTeam: "team-iris",
  team: "team-backend"
}

Returns complete conversation cache including all messages and protocol responses.

Process Management Tools

`team_wake`

Wake up a team by ensuring its process is active.

{
  fromTeam: "team-iris",
  team: "team-backend"
}

Creates session-specific process (e.g., iris->backend) for conversation isolation.

`team_launch`

Semantic alias for team_wake emphasizing activation.

{
  fromTeam: "team-iris",
  team: "team-backend"
}

`team_sleep`

Put a team to sleep by terminating its process.

{
  fromTeam: "team-iris",
  team: "team-backend",
  force: false  // optional
}

`team_wake_all`

Wake all configured teams sequentially.

{
  fromTeam: "team-iris",
  parallel: false  // NOT RECOMMENDED - unstable
}

Warning: Parallel mode causes timeouts due to simultaneous Claude spawning.

`team_status`

Get status of teams, processes, and notifications.

{
  fromTeam: "team-iris",
  team: "team-backend",  // optional, omit for all teams
  includeNotifications: true  // optional, default true
}

Response:

{
  "teams": [{
    "name": "team-backend",
    "path": "/Users/you/projects/backend",
    "active": true,
    "processInfo": {
      "status": "idle",
      "pid": 12345,
      "uptime": 180000
    },
    "sessionInfo": {
      "sessionId": "abc-123",
      "messageCount": 47,
      "lastUsed": 1704067200000
    }
  }],
  "pool": {
    "totalProcesses": 3,
    "maxProcesses": 10
  }
}

Utility Tools

`list_teams`

List all configured teams.

{}

Returns team names with configuration details (path, description, color, settings).

`get_logs`

Query in-memory logs from Iris MCP server.

{
  logs_since: 1704067200000,  // optional timestamp
  level: "error",             // optional: 'trace'|'debug'|'info'|'warn'|'error'|'fatal'
  format: "parsed"            // optional: 'raw'|'parsed'
}

`get_date`

Get current system date and time.

{}

Returns ISO 8601, UTC string, Unix timestamp, and detailed components.

`permissions__approve`

Permission approval handler for Claude Code's --permission-prompt-tool.

{
  tool_name: "mcp__iris__team_wake",
  input: { team: "team-backend" },
  reason: "Need to coordinate deployment"
}

Auto-approves all mcp__iris__* tools, denies everything else.

📁 Project Structure

iris-mcp/
├── src/
│   ├── index.ts                      # MCP server entry point
│   ├── iris.ts                       # IrisOrchestrator (Business Logic Layer)
│   ├── config/
│   │   ├── teams-config.ts           # Configuration with Zod validation
│   │   └── iris-config.ts            # Config schema and types
│   ├── session/
│   │   ├── session-manager.ts        # Session database and file management
│   │   ├── session-store.ts          # SQLite session store
│   │   ├── path-utils.ts             # Session file path utilities
│   │   └── types.ts                  # Session interfaces
│   ├── process-pool/
│   │   ├── pool-manager.ts           # Process pool with LRU eviction
│   │   ├── claude-process.ts         # Claude process wrapper
│   │   └── types.ts                  # Process interfaces
│   ├── transport/
│   │   ├── base-transport.ts         # Transport abstraction interface
│   │   ├── local-transport.ts        # Local process execution
│   │   ├── ssh-transport.ts          # OpenSSH client execution
│   │   └── remote-ssh2-transport.ts  # ssh2 library execution
│   ├── actions/
│   │   ├── send-message.ts           # send_message tool
│   │   ├── ask-message.ts            # ask_message tool
│   │   ├── quick-message.ts          # quick_message tool
│   │   ├── session-reboot.ts         # session_reboot tool
│   │   ├── session-delete.ts         # session_delete tool
│   │   ├── session-fork.ts           # session_fork tool
│   │   ├── session-cancel.ts         # session_cancel tool
│   │   ├── team-wake.ts              # team_wake tool
│   │   ├── team-launch.ts            # team_launch tool
│   │   ├── team-sleep.ts             # team_sleep tool
│   │   ├── team-wake-all.ts          # team_wake_all tool
│   │   ├── team-status.ts            # team_status tool
│   │   ├── session-report.ts         # session_report tool
│   │   ├── list-teams.ts             # list_teams tool
│   │   ├── get-logs.ts               # get_logs tool
│   │   ├── get-date.ts               # get_date tool
│   │   └── grant-permission.ts       # permissions__approve tool
│   ├── dashboard/
│   │   ├── app.tsx                   # React SPA entry point
│   │   ├── components/               # React components
│   │   └── server.ts                 # Express + WebSocket backend
│   ├── notifications/
│   │   ├── queue.ts                  # SQLite notification queue
│   │   └── schema.sql                # Database schema
│   ├── logging/
│   │   ├── wonder-logger.ts          # Wonder Logger implementation
│   │   └── opentelemetry.ts          # OpenTelemetry integration
│   └── utils/
│       ├── logger.ts                 # Structured logging to stderr
│       ├── errors.ts                 # Custom error hierarchy
│       ├── validation.ts             # Input validation
│       └── env-interpolation.ts      # Environment variable interpolation
├── docs/
│   ├── CONCEPT.md                    # Vision and conceptual overview
│   ├── ARCHITECTURE.md               # System design and components
│   ├── ACTIONS.md                    # All 17 MCP tools documentation
│   ├── CONFIG.md                     # Configuration management
│   ├── SESSION.md                    # Session management deep dive
│   ├── REMOTE.md                     # Remote execution via SSH
│   ├── REVERSE_MCP.md                # Bidirectional SSH tunneling
│   ├── DASHBOARD.md                  # Web dashboard documentation
│   ├── FEATURES.md                   # Comprehensive feature inventory
│   └── NOMENCLATURE.md               # Core concepts and terminology
├── data/
│   ├── team-sessions.db              # Session database (auto-created)
│   └── notifications.db              # Notification queue (auto-created)
├── config.yaml                       # Your team configuration
└── package.json

🏗️ Architecture

Three-Layer Design

Iris uses a clean three-layer architecture with strict separation of concerns:

┌─────────────────────────────────────────────┐
│        IrisOrchestrator (BLL)              │
│  Coordinates SessionManager + PoolManager   │
└──────────────┬──────────────────────────────┘
               │
       ┌───────┴────────┐
       │                │
       ▼                ▼
┌──────────────┐  ┌─────────────────────┐
│SessionManager│  │ClaudeProcessPool    │
│              │  │                     │
│DB + Files    │  │Process Lifecycle    │
│              │  │                     │
│NO processes  │  │NO session lookup    │
└──────┬───────┘  └──────────┬──────────┘
       │                     │
       ▼                     ▼
┌──────────────┐  ┌─────────────────────┐
│SessionStore  │  │ClaudeProcess        │
│SQLite        │  │Transport Abstraction│
└──────────────┘  └─────────────────────┘
                          │
              ┌───────────┴───────────┐
              │                       │
              ▼                       ▼
       ┌─────────────┐        ┌──────────────┐
       │LocalTransport│        │SSHTransport  │
       └─────────────┘        └──────────────┘

Layer 1: IrisOrchestrator (Business Logic Layer)

Coordinates SessionManager + ClaudeProcessPool
Implements complete message flow
Provides API for MCP tools
RxJS-based reactive architecture

Layer 2: SessionManager + ClaudeProcessPool

SessionManager: Session database management, file validation, 60s caching
ClaudeProcessPool: Process lifecycle, LRU eviction, health monitoring
Strict separation: SessionManager does NOT spawn processes, Pool does NOT manage sessions

Layer 3: SessionStore + ClaudeProcess

SessionStore: SQLite persistence with WAL mode
ClaudeProcess: Transport abstraction (Local, SSH, RemoteSSH2)

Transport Abstraction

Iris supports multiple execution modes via pluggable transports:

LocalTransport:

Direct child process execution via Node.js spawn()
Lowest latency, highest reliability
Used for local teams

SSHTransport (OpenSSH client):

Execute remote Claude via ssh user@host
Requires OpenSSH client installed
Best performance for remote execution
Production-ready, battle-tested

RemoteSSH2Transport (ssh2 library):

Pure Node.js SSH implementation
No external dependencies
Platform-independent
Experimental, for environments without SSH client

Session Persistence

Persistent team-to-team sessions maintain conversation continuity:

Each (fromTeam, toTeam) pair has exactly one session (e.g., iris→backend, backend→frontend)
ALL sessions require both fromTeam and toTeam (no null sessions)
Sessions stored at ~/.claude/projects/{escaped-path}/{sessionId}.jsonl
Database tracks metadata (message count, last used, status)
Sessions resume across process restarts

Schema:

CREATE TABLE sessions (
  pool_key TEXT PRIMARY KEY,
  session_id TEXT NOT NULL,
  message_count INTEGER DEFAULT 0,
  last_used_at INTEGER,
  status TEXT DEFAULT 'active',
  created_at INTEGER NOT NULL,
  updated_at INTEGER NOT NULL
);

Process Pool Management

Iris maintains a pool of Claude Code processes with:

LRU Eviction: When pool is full, least recently used process is terminated
Idle Timeout: Processes automatically terminate after 1 hour of inactivity (configurable)
Health Checks: Regular monitoring ensures processes stay healthy (every 30s)
Warm Starts: Reuses existing processes for 10-20x faster responses
Session Resumption: Each process resumes its specific session via --resume <sessionId>

Two-Timeout Architecture:

responseTimeout: How long to wait for Claude to respond (default: 2 minutes)
mcpTimeout: Maximum time for MCP server communication (default: 5 seconds)

Reactive Architecture

Iris uses RxJS observables for event-driven communication:

// Process events as Observable streams
process.events$
  .pipe(
    filter(event => event.type === 'message-response'),
    timeout(responseTimeout),
    catchError(err => of({ type: 'error', error: err }))
  )
  .subscribe(handleResponse);

Benefits:

Composable event handling
Automatic timeout management
Error recovery with retry logic
Backpressure handling

Session MCP Configuration

Remote teams can be configured with Session MCP - per-session MCP configuration:

teams:
  team-remote:
    remote: "ssh user@remote-host"
    sessionMcpEnabled: true
    sessionMcpPath: "/path/to/session-mcp-server"

Each session gets its own MCP server instance with session-specific context.

Wonder Logger

OpenTelemetry-based observability with structured logging:

logger.info('Process spawned', {
  poolKey: 'iris->backend',
  sessionId: 'abc-123',
  pid: 12345,
  transport: 'ssh'
});

Features:

Structured JSON logging to stderr
OpenTelemetry spans and traces
Context propagation across async boundaries
Log aggregation support (Grafana, Datadog, etc.)

Permission Approval System

Four modes for controlling team actions:

yes: Auto-approve all actions (default)
no: Auto-deny all actions (read-only mode)
ask: Prompt user for each action (via Dashboard)
forward: Forward permission request to calling team

teams:
  team-production:
    grantPermission: ask  # Require approval for all actions

🎯 Configuration

Example Configuration

settings:
  # Process Timeouts
  sessionInitTimeout: 30000     # 30 seconds for session creation
  spawnTimeout: 20000           # 20 seconds for process spawn
  responseTimeout: 120000       # 2 minutes for Claude response
  mcpTimeout: 5000              # 5 seconds for MCP server communication

  # Process Pool
  idleTimeout: 3600000          # 1 hour idle before termination
  maxProcesses: 10              # Max concurrent processes
  healthCheckInterval: 30000    # 30 seconds health check

  # Server
  httpPort: ${IRIS_HTTP_PORT:-1615}
  defaultTransport: http        # stdio or http

teams:
  # Local Team
  team-frontend:
    path: /Users/you/projects/frontend
    description: React frontend application
    idleTimeout: 600000         # 10 minutes (override)
    grantPermission: yes
    color: "#61DAFB"

  # Remote Team with Reverse MCP
  team-production:
    remote: "ssh user@prod-server"
    claudePath: "~/.local/bin/claude"
    path: "/opt/production/app"
    description: Production backend server
    enableReverseMcp: true      # Enable bidirectional tunneling
    reverseMcpPort: 1615        # Port to tunnel
    allowHttp: false            # Use HTTPS for production
    grantPermission: ask        # Require approval for actions
    color: "#E34F26"

  # Remote Team with Session MCP
  team-mobile:
    remote: "ssh user@mobile-server"
    path: "/home/user/mobile-app"
    sessionMcpEnabled: true
    sessionMcpPath: "/usr/local/bin/session-mcp"
    color: "#3DDC84"

Environment Variable Interpolation

Use ${VAR:-default} syntax for dynamic configuration:

settings:
  httpPort: ${IRIS_HTTP_PORT:-1615}
  idleTimeout: ${IRIS_IDLE_TIMEOUT:-3600000}
  maxProcesses: ${IRIS_MAX_PROCESSES:-10}

teams:
  team-production:
    path: ${PROD_PATH}          # Required (throws if not set)
    idleTimeout: ${PROD_TIMEOUT:-1800000}

Example .env file:

IRIS_HTTP_PORT=1615
IRIS_MAX_PROCESSES=20
PROD_PATH=/opt/production/app
PROD_TIMEOUT=3600000

Configuration Hot-Reload

Iris watches config.yaml with fs.watchFile() (1s interval) and automatically reloads configuration changes without server restart.

🔧 Development

Build

pnpm build

Watch Mode

pnpm dev

Testing

# Run all tests
pnpm test

# Unit tests only (fast, mocked)
pnpm test:unit

# Integration tests only (slow, real Claude processes)
pnpm test:integration

# Run specific test file
pnpm test:run path/to/test.ts

# Watch mode with UI
pnpm test:ui

Run MCP Inspector

pnpm inspector

This opens the MCP inspector at http://localhost:5173 to test tools interactively.

Logs

All logs go to stderr in JSON format:

{"level":"info","context":"server","message":"Iris MCP Server initialized","teams":["frontend","backend"],"timestamp":"2025-01-15T10:30:00.000Z"}
{"level":"info","context":"pool","message":"Process spawned","poolKey":"iris->backend","sessionId":"abc-123","pid":12345,"timestamp":"2025-01-15T10:30:15.000Z"}

Log Contexts:

server: MCP server lifecycle
config: Configuration loading
session-manager: Session operations
session-store: Database operations
pool: Process pool management
process:teamName: Individual process logs
transport:ssh: SSH transport operations

⚡ Performance

Process Pooling Benefits

Cold Start (first request to a team):

Session creation: ~7-12 seconds
Process spawn: ~1-2 seconds
Total: ~8-14 seconds

Warm Start (subsequent requests):

Session lookup: ~1ms (cache hit)
Process reuse: ~1ms (pool hit)
Total: ~500ms-2s (Claude API time only)

Speedup: 10-20x faster with pooling!

Session Persistence

Without Iris (each request):

New conversation context every time
No memory of previous interactions
Lost context between teams

With Iris:

Persistent (fromTeam, toTeam) sessions
Full conversation history maintained
Claude remembers previous exchanges

Resource Efficiency

Process Pool Management:

LRU eviction keeps memory bounded
Idle timeout (1 hour) terminates unused processes
Health checks (30s) detect and clean unhealthy processes
Max 10 concurrent processes (configurable)

Memory Usage (typical):

10 processes: ~600 MB - 1.25 GB
Session database: ~2 MB per 10,000 sessions
Notification queue: ~5 MB per 10,000 notifications

Test Suite Performance

Test Optimizations:

Unit tests: 203 passing in <2 seconds
Integration tests: 85% faster (7min → 1min) with beforeAll optimization
Timeout handling: Fixed spurious errors 20s after completion

🚨 Troubleshooting

"Team not found" error

Symptom: TeamNotFoundError when using tools

Solutions:

Check that team name in config.yaml matches exactly (case-sensitive)
Verify the path exists and is absolute
Restart Iris after modifying config.yaml (or wait for hot-reload)

"Process failed to spawn"

Symptom: Error during process creation

Solutions:

Ensure Claude CLI is installed: which claude
Check that the team's project directory exists and is accessible
Try running claude --session-id test-$(uuidgen) --print ping manually in the team directory
Check logs for detailed error: context:"process:teamName"
For remote teams, verify SSH connectivity: ssh user@host 'which claude'

"Timeout exceeded"

Symptom: Message takes longer than configured timeout

Solutions:

Increase responseTimeout in settings: responseTimeout: 180000 (3 minutes)
Check if the target team's Claude process is stuck (view logs)
Verify Claude API is responding (not rate-limited)
For session initialization timeouts, increase sessionInitTimeout in config

"Session file was not created"

Symptom: Session initialization fails

Solutions:

Verify ~/.claude/projects/ directory exists: mkdir -p ~/.claude/projects
Check permissions: ls -la ~/.claude
Ensure team path is correct and accessible
Check available disk space: df -h

SSH Connection Issues

Symptom: Remote team execution fails

Solutions:

Test SSH manually: ssh user@host 'echo hello'
Check SSH key authentication is configured
Verify claudePath is correct on remote machine
For reverse MCP, ensure port 1615 is not blocked
Check SSH logs: ssh -v user@host

Database Locked

Symptom: SQLite errors about locked database

Solutions:

Close other Iris MCP instances
Delete WAL files: rm data/*.db-wal data/*.db-shm
Check for zombie processes: ps aux | grep iris

Process Pool Full

Symptom: All process slots occupied

Solutions:

Increase maxProcesses in config.yaml settings
Reduce idleTimeout to free processes faster
Check health check logs to see which processes are active

🗺️ Roadmap

Phase 1: Core MCP Server ✅

17 MCP Tools for team coordination
Process Pool with LRU eviction
Session Persistence with SQLite
Transport Abstraction (Local, SSH, RemoteSSH2)
Remote Execution via SSH
Reverse MCP Tunneling
Session MCP Configuration
Wonder Logger with OpenTelemetry
Permission Approval System
Hot-Reloadable Configuration
Event-Driven Architecture with RxJS

Phase 2: Web Dashboard ✅

React SPA with real-time monitoring
WebSocket Integration for live updates
Permission Approval Modal
Log Viewer with filtering
Process Monitoring with health metrics
Configuration Editor

Status: Fully implemented and production-ready!

Phase 3: Programmatic API 🔮

RESTful HTTP endpoints
WebSocket streaming
API key authentication
Official SDKs (TypeScript, Python)

See src/api/README.md

Phase 4: CLI Interface 🔮

iris ask command
iris status monitoring
Interactive shell mode
Built with Ink (React for terminals)

See src/cli/README.md

Phase 5: Intelligence Layer 🔮

Loop detection
Destructive action prevention
Pattern recognition
Self-aware coordination
Autonomous multi-team orchestration

See src/intelligence/README.md

📚 Documentation

Core Documentation

Getting Started - Installation and quick start guide
Concept - Vision and conceptual overview
Architecture - System design and component interaction
Actions - All 17 MCP tools documentation
Configuration - Complete YAML config reference
Features - Comprehensive feature inventory
Nomenclature - Core concepts and terminology

Advanced Topics

Session Management - Session database and file management
Remote Execution - SSH transport and remote teams
Reverse MCP - Bidirectional SSH tunneling
Dashboard - Web dashboard documentation

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

How to Contribute

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/your-username/iris-mcp
cd iris-mcp

# Install dependencies
pnpm install

# Run tests
pnpm test

# Run in watch mode
pnpm dev

# Build the project
pnpm build

Please ensure all tests pass before submitting a PR.

📄 License

MIT License - see LICENSE file for details

🌟 Why "Iris"?

Iris was the Greek goddess of the rainbow and messenger of the gods, bridging heaven and earth. Similarly, Iris MCP bridges your AI agents across project boundaries.

One messenger. Many teams. Infinite coordination.

Built with ❤️ by Jenova Marie