Zellij MCP
Rust MCP daemon for safe agent interaction with Zellij panes through an in-repo backend.
Current release line: 0.1.0
What it provides
The daemon exposes these MCP tools:
zellij_spawnzellij_attachzellij_discoverzellij_sendzellij_waitzellij_capturezellij_closezellij_list
It keeps agent-facing handles stable, persists lightweight state, and adds capture semantics (full, delta, current) on top of raw pane access.
Recent spawn hardening:
zellij_spawn(wait_ready=true)may returnstatus="busy"when the pane is real but rendered-screen idle detection does not settle within the bounded wait window- the daemon now persists spawned handles before post-launch probing so a real launch is not lost just because follow-up readiness or capture work degrades
- default interactive
spawn_target="new_tab"now binds the new tab's default terminal pane instead of implicitly creating a second shell pane - default planner behavior prefers reusing the obvious single shell-like terminal pane in a requested tab and now rejects ambiguous multi-pane tabs instead of silently picking one
Wrapped command presentation:
- fish-backed wrapped submit flows use a clean
__zellij_mcp_run_b64entrypoint instead of printing the full inline interaction script into the pane - the daemon embeds the canonical fish wrapper implementation into the binary and lazily bootstraps it into fish panes when needed, so runtime does not depend on the repo checkout or dotfiles being present
scripts/__zellij_mcp_run_b64.fishremains the repo-owned source artifact for the wrapper contract and still supports-ppreview mode so users can inspect the decoded command without executing it- if wrapper validation, bootstrap, or clean invocation still fails at runtime, the daemon falls back to the legacy inline wrapper so the command still runs
Requirements
- Rust toolchain
- Zellij session with the required plugin approved for daemon RPC use
Normal daemon operation uses the in-repo backend directly. You do not need to install or invoke an external zjctl wrapper for the local MCP flow.
Build```bash
cargo build --release
cargo build-plugin
Binary path:```text
target/release/zellij_mcp
Plugin artifact path:```text
target/wasm32-wasip1/release/zrpc.wasm
## Run manually
The daemon serves MCP over stdio.```bash
ZELLIJ_MCP_STATE_DIR=/home/yang/.local/state/zellij-mcp-opencode \
./target/release/zellij_mcp
Manual smoke testing
mcp2cli is optional. It is useful for manual local verification, but OpenCode does not need it for normal usage.
Example:```bash
mcp2cli --mcp-stdio "./target/release/zellij_mcp" --list
## OpenCode setup on this machine
OpenCode is configured from:```text
/home/yang/dotfiles/opencode/opencode.json
This machine now uses a local MCP entry named zellij that launches the daemon on demand.
Important consequence:
- you do not need to pre-spawn the daemon before agent usage in OpenCode
- OpenCode starts it when the MCP tools are needed
mcp2cliis only for manual testing, not required for OpenCode agent use
Remote over SSH
The current model keeps a single local MCP daemon and lets selection tools opt into a remote target.
- omit
targetto use the local backend - set
targetonzellij_spawn,zellij_attach,zellij_discover, orzellij_listto select an SSH target alias such asaws - the target value can be a bare alias like
aws, and the daemon resolves it canonically tossh:aws - follow-up tools such as
zellij_send,zellij_wait,zellij_capture, andzellij_closedo not needtarget; the daemon routes them by the persisted handle binding - remote backend commands and
zellijare executed over SSH by the local daemon
Runtime configuration is daemon-side through ZELLIJ_MCP_TARGETS.
The current shape is layered, with shared defaults and optional per-alias partial overrides:
Example:```bash
ZELLIJ_MCP_TARGETS='{"defaults":{"remote_zjctl_bin":"zjctl","remote_zellij_bin":"zellij","remote_env":{"ZELLIJ_SESSION_NAME":"remote"},"ssh_options":["-o","BatchMode=yes"]},"overrides":{"aws":{"host":"aws","remote_env":{"ZELLIJ_SESSION_NAME":"aws"}},"a100":{"host":"a100","remote_env":{"ZELLIJ_SESSION_NAME":"a100"}}}}' \
./target/release/zellij_mcp
In that layered form, each alias starts from `defaults`, then only the fields present under its override replace or extend them. The daemon also keeps accepting the older legacy map shape for backward compatibility, but the layered `defaults` plus `overrides` form is the intended alias-only setup.
Readiness and remediation:
- the daemon checks remote SSH targets before it tries to use them, then classifies the target as `Ready`, `AutoFixable`, or `ManualActionRequired`
- `AutoFixable` means the daemon can safely apply bounded remediation, such as copying the repo-built `zrpc.wasm` into the standard plugin directory, starting a detached helper client, and retrying readiness exactly once
- `AutoFixable` is used specifically for missing binaries, helper-client absence, and RPC-not-ready drift that can still be recovered through deterministic user-space setup
- missing plugin artifacts are reported distinctly from those retryable states, because launching the plugin cannot repair a host that does not have the expected `zrpc.wasm` installed yet
- when the remote command path does not already include it, the daemon prepends `$HOME/.local/bin` for non-interactive SSH probing and execution so ordinary hosts do not need per-host binary paths
- `ManualActionRequired` covers the remaining non-auto-fixable cases, including unmanaged plugin approval prompts and daemon/plugin protocol-version skew that requires matching artifacts before retrying
- readiness does not claim zero-touch success for every host, it only fixes the safe, bounded cases automatically
Freshness and diagnosability:
- startup now logs daemon instance id, package version, build stamp, pid, and started-at timestamp to stderr
- every successful MCP tool response now includes `_daemon` metadata with the same identity fields so stale local processes are visible per request
- MCP error data now includes daemon identity as well, which makes mixed local/remote failures easier to attribute to the right running binary
Practical setup note:
- if a locally copied Linux binary fails on the remote host with a glibc version error, build it natively on the remote host in user space and install it into the remote `~/.local/bin`
- the daemon normalizes the remote HOME and PATH for non-interactive SSH probing and execution, so remote tools installed in `~/.local/bin` are found without per-host path overrides
- the plugin RPC path still needs an attached Zellij client, so a headless remote host may still need a user-space helper such as a detached `tmux` session running `zellij attach `
Bootstrap helper:```bash
./scripts/zellij-mcp-bootstrap-ssh a100 --session a100
The bootstrap helper stays entirely in user space. It installs Rust if needed, syncs this repo, clones or updates the compatibility helper repo, builds zellij_mcp, the optional compatibility zjctl binary used by the backend layer, and the repo-owned zrpc.wasm natively on the remote host, copies the plugin artifact into the standard Zellij plugin directory, starts a detached helper client, and finishes by running the current readiness check.
The final bootstrap output is repo-owned and intentionally compact:
readiness_state=READYmeans the remote host finished the current bootstrap path and the repo-owned RPC probe succeededreadiness_state=AUTO_FIXABLEmeans the host still needs bounded remediation such as helper-client or RPC recovery and the MCP-facing class is stillPLUGIN_NOT_READYreadiness_state=MANUAL_ACTION_REQUIREDmeans the host needs human action or matching artifacts before retrying;readiness_reasondistinguishes missing plugin, plugin approval, and protocol/version skewmcp_error_codemirrors the daemon-facing error family you should expect next:PLUGIN_NOT_READY,PROTOCOL_VERSION_MISMATCH, orZJCTL_UNAVAILABLE
The script no longer treats raw zjctl doctor text as the final source of truth. It ends with a bounded repo-owned readiness probe (zjctl panes ls --json plus this repo's readiness classification rules) so the bootstrap output matches the daemon's actual error model.
Operational helper note:
scripts/zellij-mcp-sshremains useful for smoke testing or fallback operations- it is no longer the primary remote architecture or the recommended OpenCode MCP shape
Path note:
- prefer absolute remote paths or plain executable names that already resolve on the remote non-interactive
PATH - do not rely on
~expansion in helper-script arguments; the wrapper intentionally quotes remote tokens before handing them to SSH
Important constraint:
- this does not create a detached network daemon on the remote host; the local daemon still initiates remote operations over SSH on demand
- if you later want the remote daemon to stay reachable without any SSH transport, that becomes a separate transport feature
- this also does not remove Zellij's own requirement for a connected client when the remote plugin RPC path is in use
zellij_discovernow degrades preview failures to metadata-only candidates instead of failing the whole call, but metadata-only discovery can still be the cleaner choice on very busy live panes
Target and handle semantics:
- the canonical target id stored in responses and bindings is
ssh: - selection tools accept the alias form from the user, while follow-up calls keep using the persisted handle binding
- that separation keeps the single local MCP architecture intact and avoids nested remote daemons
Configured runtime values on this machine:
ZELLIJ_MCP_STATE_DIR=/home/yang/.local/state/zellij-mcp-opencode
Recommended agent flow
For existing user panes:
zellij_discoverzellij_attachzellij_waitzellij_capturezellij_send
For new agent-owned panes:
zellij_spawn- if spawn returns
status="busy", keep the returned handle and follow withzellij_waitorzellij_capture zellij_capturezellij_sendzellij_close
Notes:
wait_ready=trueis a convenience idle probe, not a process-start or app-ready guarantee- a later
zellij_listrevalidation can upgrade a spawned handle frombusytoreadyonce the pane selector is reachable again; usezellij_capturewhen you need a fresh output baseline
Remote troubleshooting quick map
TARGET_NOT_FOUND: the selected alias is unknown or the remote pane selector no longer resolves; verifyZELLIJ_MCP_TARGETS, the session name, and whether the pane still existsCAPTURE_FAILED: the handle exists but the capture path degraded; retry with the same handle, then usezellij_listto revalidate ownership before assuming the pane is gonePLUGIN_NOT_READY: the host is reachable but plugin/runtime preconditions are missing; distinguish missing plugin artifacts, manual plugin approval, helper-client absence, and RPC-not-ready drift before retryingPROTOCOL_VERSION_MISMATCH: the daemon and loadedzrpcplugin disagree onPROTOCOL_VERSION; rebuild or reload matching artifacts before retrying because helper/plugin relaunch alone will not fix skewZJCTL_UNAVAILABLE: the transport or remote binary path is the problem; verify SSH reachability, native remote install, and that the required remote binaries resolve in the non-interactive remote PATH
When you use scripts/zellij-mcp-bootstrap-ssh, those same readiness families are surfaced explicitly as readiness_state, readiness_reason, and mcp_error_code, so shell bootstrap and MCP runtime diagnostics use the same repo-owned vocabulary.
More detail
docs/architecture.mddocs/mcp-contract.mddocs/ssh-remote-design.md
zellij_discoverreturns live pane metadata plus attach-readyselectorvalues.zellij_attachthen requires one exact selector so the daemon can bind one specific pane and return a stablehandlefor latersend,wait,capture, andclosecalls.
