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

| Tool | Description | |------|-------------| | zellij_list_sessions | List all active Zellij sessions with caching | | zellij_new_session | Create a new session with optional layout | | zellij_attach_session | Attach to an existing session | | zellij_kill_session | Kill a specific session | | zellij_delete_session | Delete a specific session | | zellij_get_session_info | Get detailed session information | | zellij_export_session | Export session configuration to JSON | | zellij_import_session | Import session from JSON export | | zellij_clone_session | Clone an existing session | | zellij_rename_session | Rename a session | | zellij_switch_session | Switch to a different session |

Pane Management Tools

| Tool | Description | |------|-------------| | zellij_new_pane | Create a new pane with advanced options | | zellij_close_pane | Close the currently focused pane | | zellij_focus_pane | Focus pane in specific direction | | zellij_resize_pane | Resize the focused pane | | zellij_swap_panes | Move/swap pane in specified direction | | zellij_stack_panes | Stack multiple panes by their IDs | | zellij_toggle_floating | Toggle floating panes visibility | | zellij_toggle_fullscreen | Toggle fullscreen mode for focused pane | | zellij_pin_pane | Pin/unpin floating pane | | zellij_clear_pane | Clear the focused pane buffer | | zellij_dump_screen | Dump pane screen content to file | | zellij_edit_scrollback | Edit pane scrollback in default editor | | zellij_rename_pane | Rename the focused pane | | zellij_scroll | Scroll in focused pane | | zellij_exec_in_pane | Execute command in current pane | | zellij_write_to_pane | Write text to current pane | | zellij_get_pane_info | Get current pane layout information |

Tab Management Tools

| Tool | Description | |------|-------------| | zellij_new_tab | Create a new tab | | zellij_close_tab | Close the current tab | | zellij_rename_tab | Rename the current tab | | zellij_go_to_tab | Go to tab by index | | zellij_go_to_tab_name | Go to tab by name | | zellij_move_tab | Move tab left or right | | zellij_query_tab_names | Get all tab names in current session | | zellij_toggle_sync_tab | Toggle synchronized input across panes | | zellij_go_to_next_tab | Switch to next tab | | zellij_go_to_previous_tab | Switch to previous tab |

Plugin Management Tools

| Tool | Description | |------|-------------| | zellij_launch_plugin | Launch a plugin with full configuration | | zellij_action_launch_plugin | Launch plugin using action command | | zellij_launch_or_focus_plugin | Smart plugin activation | | zellij_start_or_reload_plugin | Start or reload a plugin | | zellij_list_aliases | List available plugin aliases | | zellij_get_plugin_info | Get information about a plugin | | zellij_list_running_plugins | List currently running plugins |

Layout Management Tools

| Tool | Description | |------|-------------| | zellij_dump_layout | Dump current layout to stdout or file | | zellij_save_layout | Save current layout to layouts directory | | zellij_apply_layout | Apply a layout to current or new session | | zellij_list_layouts | List available layouts | | zellij_load_layout | Load and display layout content | | zellij_new_tab_with_layout | Create new tab with specific layout | | zellij_validate_layout | Validate layout file syntax |

Piping System Tools

| Tool | Description | |------|-------------| | zellij_pipe | Send data to plugins via pipe with advanced options | | zellij_pipe_to_plugin | Send data to a specific plugin | | zellij_pipe_broadcast | Broadcast data to all listening plugins | | zellij_action_pipe | Advanced piping with action-level options | | zellij_pipe_with_response | Send data and capture plugin response | | zellij_pipe_from_file | Pipe file content to plugins |

LLM Detection Tools

| Tool | Description | |------|-------------| | zellij_watch_pipe | Watch a pipe for specific patterns with timeout | | zellij_create_named_pipe | Create a named pipe for bidirectional communication | | zellij_pipe_with_timeout | Pipe command output with automatic timeout | | zellij_poll_process | Poll process status by PID | | zellij_watch_file | Watch file for changes with pattern matching | | zellij_create_llm_wrapper | Create LLM completion detector wrapper script | | zellij_cleanup_detection | Clean up detection resources |

System Tools

| Tool | Description | |------|-------------| | zellij_run_command | Run command in new pane | | zellij_edit_file | Edit file in new Zellij pane | | zellij_switch_mode | Switch input mode for all connected clients | | zellij_kill_all_sessions | Kill all active sessions | | zellij_delete_all_sessions | Delete all sessions | | zellij_clear_cache | Clear MCP server cache | | zellij_get_cache_stats | Get cache statistics | | zellij_health_check | Perform system health check |

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 LICENSE 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.