GitJuhb/zellij-mcp-server

Zellij MCP Server

A comprehensive Model Context Protocol (MCP) server for managing Zellij terminal workspace sessions. This server provides extensive tools for session management, pane operations, tab controls, plugin integration, layout management, and advanced LLM completion detection.

Features

🏗️ Session Management

Complete session lifecycle management with advanced operations:

• Basic Operations: List, create, attach, kill, delete sessions
• Advanced Operations: Clone, rename, switch, export/import session configurations
• Session Information: Detailed session info and health monitoring

🔧 Pane Management

Comprehensive pane control with advanced positioning:

• Basic Operations: Create, close, focus, resize, swap panes
• Advanced Features: Stack panes, floating pane controls, fullscreen toggle
• Content Operations: Clear, dump screen, edit scrollback, scroll controls
• Positioning: Precise floating coordinate control

📑 Tab Management

Full tab lifecycle with navigation and organization:

• Tab Operations: Create, close, rename, move tabs
• Navigation: Go to tab by index/name, next/previous navigation
• Advanced Features: Query tab names, synchronized input across panes

🔌 Plugin Management

Comprehensive plugin ecosystem integration:

• Plugin Lifecycle: Launch, focus, start/reload plugins
• Advanced Options: Floating, in-place, skip cache configurations
• Plugin Information: List aliases, running plugins, plugin info
• Configuration: Full plugin configuration support

📐 Layout Management

Complete layout system with validation:

• Layout Operations: Dump, save, apply, load layouts
• Advanced Features: New tab with layout, layout validation
• Layout Discovery: List available layouts with custom directory support

🔄 Piping System

Advanced inter-plugin communication:

• Basic Piping: Send data to plugins, broadcast to all plugins
• Advanced Piping: Response capture, file-based piping
• Action Piping: Force launch, skip cache, floating options
• Plugin Targeting: Specific plugin URL targeting

🤖 LLM Completion Detection

Specialized tools for LLM workflow integration:

• Process Monitoring: Watch pipes, poll processes, file watching
• Timeout Management: Automatic timeout completion
• Wrapper Scripts: LLM completion detector wrappers
• Resource Cleanup: Automated cleanup of detection resources

🛡️ Security & Performance

Enterprise-grade security and performance features:

• Input Validation: Comprehensive input sanitization and validation
• Rate Limiting: Configurable rate limiting per tool
• Caching: Intelligent caching with statistics
• Health Monitoring: System health checks and diagnostics

Installation

Prerequisites

• Node.js 18 or higher
• Zellij installed and available in PATH
• Active terminal environment

Setup

# Clone the repository
git clone https://github.com/yourusername/zellij-mcp-server.git
cd zellij-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Make the script executable
chmod +x dist/index.js

Usage

With Claude Desktop

Add this to your Claude Desktop configuration file:

{
  "mcpServers": {
    "zellij": {
      "command": "node",
      "args": ["/path/to/zellij-mcp-server/dist/index.js"]
    }
  }
}

Direct Usage

# Start the MCP server
npm start

# Development mode with watching
npm run dev

Tool Categories

Session Management Tools

Pane Management Tools

Tab Management Tools

Plugin Management Tools

Layout Management Tools

Piping System Tools

LLM Detection Tools

System Tools

Example Usage

Creating a Development Session

{
  "name": "zellij_new_session",
  "arguments": {
    "session_name": "development",
    "layout": "dev-layout"
  }
}

Running Commands in Panes

{
  "name": "zellij_run_command",
  "arguments": {
    "command": "npm run dev",
    "direction": "right"
  }
}

Plugin Management

{
  "name": "zellij_launch_plugin",
  "arguments": {
    "plugin_url": "file:~/.config/zellij/plugins/filepicker.wasm",
    "floating": true,
    "width": "50%",
    "height": "50%"
  }
}

Layout Operations

{
  "name": "zellij_save_layout",
  "arguments": {
    "layout_name": "my-dev-setup"
  }
}

LLM Integration

Creating LLM Wrapper Scripts

The zellij_create_llm_wrapper tool generates intelligent wrapper scripts that provide robust completion detection for any LLM command:

{
  "name": "zellij_create_llm_wrapper",
  "arguments": {
    "wrapper_name": "claude-wrapper",
    "llm_command": "claude chat",
    "detect_marker": "<<<COMPLETE>>>",
    "timeout_ms": 60000
  }
}

What the wrapper provides:

• Multi-signal detection: Exit codes, completion markers, and status files
• Automatic timeout handling: Configurable timeout with graceful cleanup
• Process monitoring: Real-time status tracking and logging
• Signal handling: Proper cleanup on interruption (SIGINT, SIGTERM)
• Timestamped logging: Detailed execution logs for debugging

Generated files:

• /tmp/llm-wrapper-{name}.sh - The executable wrapper script
• /tmp/llm-status-{name} - Real-time status file with timestamps
• /tmp/llm-output-{name}-{pid} - Captured output (temporary)

Usage example:

# After creating the wrapper, use it like:
/tmp/llm-wrapper-claude-wrapper.sh "Explain quantum computing"

# Monitor status in real-time:
tail -f /tmp/llm-status-claude-wrapper

# The wrapper handles timeouts, signals, and cleanup automatically

Status tracking:

• running - LLM query is in progress
• complete:0 - Successfully completed
• timeout - Query timed out
• error:N - Failed with exit code N

Architecture

Security Features

• Input Validation: All inputs are validated and sanitized
• Rate Limiting: Per-tool rate limiting (50 requests per minute)
• Path Traversal Protection: File path validation prevents directory traversal
• Command Injection Prevention: Command sanitization and validation

Performance Features

• Intelligent Caching: Session lists and other data are cached
• Async Operations: All operations are asynchronous
• Error Handling: Comprehensive error handling with specific error types
• Resource Cleanup: Automatic cleanup of temporary resources

Error Handling

The server includes comprehensive error handling with specific error types:

• ValidationError: Input validation failures
• SecurityError: Security-related errors (rate limiting, etc.)
• ZellijError: Zellij-specific command failures

Development

Project Structure

src/
├── index.ts              # Main MCP server implementation
├── tools/               # Tool modules
│   ├── detection.ts     # LLM completion detection tools
│   ├── layouts.ts       # Layout management tools
│   ├── panes.ts         # Pane management tools
│   ├── piping.ts        # Piping system tools
│   ├── plugins.ts       # Plugin management tools
│   └── sessions.ts      # Session management tools
├── types/
│   └── zellij.ts        # TypeScript type definitions
└── utils/
    ├── cache.ts         # Caching utilities
    ├── command.ts       # Command execution utilities
    └── validator.ts     # Input validation utilities

Building

# Development build with watching
npm run dev

# Production build
npm run build

# Start the built server
npm start

Testing

Run ./test-workflow.sh to validate the detection system functionality.

Contributing

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

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Zellij - The amazing terminal workspace manager
• Model Context Protocol - The protocol this server implements
• Claude Code - Integration with Claude AI

Support

For issues, questions, or contributions, please visit the GitHub repository.