zellij-mcp

zellij-mcp

Terminal orchestration for Claude Code. 57 tools. Tab-based workspaces.

---

Why zellij-mcp?

Focus-free pane control. Native Zellij plugin writes to panes without stealing focus. Your cursor stays where it is while Claude works in the background.

Claude pane protection. Auto-detects the agent's pane and prevents accidental closure. No more killing yourself mid-task.

Tab-based workspaces. Agent work is organized into dedicated tabs (e.g., "agents", "analysis", "hpc"). Switch tabs to observe agent progress, or stay in your own tab.

Named pane targeting. Address any pane by name, not just the focused one. create_named_pane("worker"), read_pane("worker"), run_in_pane("worker", "make test").

Complete terminal control. 57 MCP tools for panes, tabs, output monitoring, REPL interaction, SSH connections, and HPC job management.

---

Install

Via Claude Code Plugin System (Recommended)

/plugin genomewalker/zellij-mcp

Then restart Claude Code.

Manual Install

curl -fsSL https://raw.githubusercontent.com/genomewalker/zellij-mcp/main/scripts/install.sh | bash

To update: cd ~/.local/share/zellij-mcp && git pull && ./scripts/install.sh

---

Quick Start

"create a pane called worker"
"run npm test in worker"
"wait for the tests to finish"
"show me the output"

---

Key Features

Tab-Based Workspaces

Agent operations are organized into dedicated tabs within your session:

create_named_pane(name="analysis", command="ipython3", tab="work")
# → Created in "work" tab, switch tabs to observe progress

Named Pane Operations

Target panes by name across tabs and sessions:

create_named_pane(name="tests", command="bash", tab="dev")
run_in_pane(pane_name="tests", command="pytest -v")
wait_for_output(pane_name="tests", pattern="passed|failed")
read_pane(pane_name="tests")

Output Monitoring

wait_for_output(pane_name="worker", pattern=r"Done|Error", timeout=300)
wait_for_idle(pane_name="worker", stable_seconds=3)
tail_pane(pane_name="worker")  # Get new output since last read

REPL Interaction

create_named_pane(name="ipython", command="ipython3")
repl_execute(pane_name="ipython", code="import pandas as pd\ndf.describe()")
repl_interrupt(pane_name="ipython")  # Ctrl+C

SSH & HPC Workflows

ssh_connect(name="hpc", host="[email protected]")
ssh_run(name="hpc", command="squeue -u $USER")
job_submit(ssh_name="hpc", script="analysis.sh", scheduler="slurm")
job_status(job_id="12345")

Agent Spawning

spawn_agents(agents=[
    {"name": "researcher", "task": "Find API documentation"},
    {"name": "implementer", "task": "Write the integration"}
])
list_spawned_agents()
agent_output(name="researcher")

---

Tools Reference

Pane Management (12 tools)

new_pane close_pane focus_pane focus_next_pane focus_previous_pane move_pane move_pane_backwards resize_pane rename_pane toggle_floating toggle_fullscreen toggle_embed_or_floating

Named Panes (7 tools)

create_named_pane destroy_named_pane list_named_panes focus_pane_by_name read_pane write_to_pane run_in_pane

Monitoring (5 tools)

wait_for_output wait_for_idle tail_pane search_pane send_keys

REPL (2 tools)

repl_execute repl_interrupt

SSH & HPC (4 tools)

ssh_connect ssh_run job_submit job_status

Tab Management (8 tools)

new_tab close_tab focus_tab move_tab rename_tab query_tab_names go_to_next_tab go_to_previous_tab

Session & Layout (6 tools)

list_sessions list_panes session_info dump_layout swap_layout session_map

Workspace & Agent Management (5 tools)

agent_session spawn_agents list_spawned_agents agent_output stop_agent

Other (8 tools)

write_chars clear_pane scroll edit_scrollback switch_mode stack_panes launch_plugin pipe

---

Cross-Session Control

All tools support session parameter to target other Zellij sessions:

list_sessions()
read_pane(session="other-session", pane_name="worker")
run_in_pane(session="dev", pane_name="tests", command="make check")

---

Combining with prism.nvim