Zellij Plugin Development Skill

Comprehensive assistance for developing Zellij terminal multiplexer plugins using Rust and WebAssembly.

When to Use This Skill

Trigger this skill when:

Developing Zellij plugins in Rust/WASM
Implementing plugin UI, rendering, or event handling
Working with the Zellij plugin API
Integrating external systems (Docker, Git, etc.)
Building status bars, navigation tools, or workflow automation
Debugging plugin issues or understanding plugin lifecycle
Learning plugin development patterns and best practices

Quick Reference

Core Plugin Structure

use zellij_tile::prelude::*;

#[derive(Default)]
struct State {
    // Your plugin state
}

impl ZellijPlugin for State {
    fn load(&mut self, configuration: BTreeMap<String, String>) {
        request_permission(&[PermissionType::ReadApplicationState]);
        subscribe(&[EventType::Key, EventType::PaneUpdate]);
    }

    fn update(&mut self, event: Event) -> bool {
        // Handle events, return true to re-render
        false
    }

    fn render(&mut self, rows: usize, cols: usize) {
        // Render UI
    }
}

Building

# Add WASM target
rustup target add wasm32-wasi

# Build
cargo build --release

# Location: target/wasm32-wasi/release/<PLUGIN_NAME>.wasm

Loading Plugins

# Temporary load
zellij plugin -- file://<PATH_TO_FILE>

# Floating
zellij plugin --floating -- file://<PATH>

# With configuration
zellij plugin -- file://<PATH> --configuration key=value

Reference Files

Official Documentation

plugin-development-tutorial.md - Complete tutorial from scaffolding to distribution
plugin-api-commands.md - All 100+ plugin API commands organized by category
plugin-api-events.md - Event system, subscription patterns, and event handling

Real-World Plugin Examples

plugin-examples-ui-navigation.md - Monocle (fuzzy finder) and Room (tab switcher)
plugin-examples-status-theming.md - zjstatus (configurable status bar)
plugin-examples-external-integration.md - zj-docker (Docker integration)

Development Workflow

1. Project Setup

Use the official scaffolding tool:

zellij plugin -f -- https://github.com/zellij-org/create-rust-plugin/releases/latest/download/create-rust-plugin.wasm

This launches develop-rust-plugin for real-time iteration (Ctrl+Shift+R to rebuild).

2. Core Implementation

Load Phase:

Request permissions
Subscribe to events
Initialize state

Update Phase:

Handle events
Update state
Return true to trigger re-render

Render Phase:

Draw UI based on state
Use color indices (0-3) for theme compatibility

3. Testing & Distribution

Local Testing:

zellij plugin -- file:./target/wasm32-wasi/release/plugin.wasm

Release:

cargo build --release
# Share via awesome-zellij repository

Common Patterns

Modal UI (Floating Windows)

bind "Ctrl t" {
    LaunchOrFocusPlugin "file:path/to/plugin.wasm" {
        floating true
    }
}

Command Execution with Context

let context = BTreeMap::from([
    ("operation".to_string(), "git_status".to_string())
]);
run_command(vec!["git", "status"], context);

// Handle result
Event::RunCommandResult(exit_code, stdout, stderr, context) => {
    if context.get("operation") == Some(&"git_status".to_string()) {
        self.process_result(stdout);
    }
}

Configuration-Driven Widgets

plugin location="path/to/plugin.wasm" {
    format_left  "{widget1} {widget2}"
    format_right "{widget3}"

    widget1_param1 "value"
    widget1_param2 "value"
}

State Synchronization

fn load(&mut self, _config: BTreeMap<String, String>) {
    subscribe(&[EventType::PaneUpdate]);
}

fn update(&mut self, event: Event) -> bool {
    match event {
        Event::PaneUpdate(panes) => {
            self.sync_pane_state(panes);
            true
        }
        _ => false
    }
}

Permission Categories

Read-Only:

ReadApplicationState - Access mode, tabs, panes, sessions

Write Operations:

ChangeApplicationState - Modify panes, tabs, navigation
OpenFiles - Open files in $EDITOR
OpenTerminalsOrPlugins - Create terminal/plugin panes
WriteToStdin - Write to pane stdin

Advanced:

RunCommands - Execute background commands
Reconfigure - Modify configuration
WebAccess - HTTP requests
FullHdAccess - Host filesystem access

Plugin Categories & Examples

UI & Navigation

monocle - Fuzzy file finder with gitignore support
room - Tab search and switcher
harpoon - Quick pane navigation

Status & Display

zjstatus - Configurable status bar with theming
zellij-datetime - Date/time display
zjframes - Pane frame management

Development Tools

multitask - Mini-CI system
grab - Rust code fuzzy finder
zellij-bookmarks - Command bookmarks

External Integration

zj-docker - Docker container management
zj-git-branch - Git branch operations

Session Management

zellij-sessionizer - Folder-based sessions
zsm - Session switcher with zoxide

Resources

Documentation

Official Docs: https://zellij.dev/documentation/plugins
Rust API: https://docs.rs/zellij-tile/latest/zellij_tile/
Tutorial: https://zellij.dev/tutorials/developing-a-rust-plugin/

Community

awesome-zellij: https://github.com/zellij-org/awesome-zellij
Discord: Zellij community for developer support
GitHub Topic: https://github.com/topics/zellij-plugin

Tools

create-rust-plugin: Scaffolding tool (plugin)
develop-rust-plugin: Live development helper (plugin)
rust-plugin-example: Official example repository

Working with This Skill

For Beginners

Start with plugin-development-tutorial.md for foundational concepts and step-by-step guidance.

For Specific Features

UI/Navigation: See plugin-examples-ui-navigation.md
Status Bars/Theming: See plugin-examples-status-theming.md
External Integration: See plugin-examples-external-integration.md
API Commands: See plugin-api-commands.md
Events: See plugin-api-events.md

For Code Examples

Each example file contains real-world patterns extracted from production plugins.

Advanced Topics

Widget Systems

Build configurable, composable UI components (see zjstatus example).

External Process Management

Spawn and manage long-running processes (see zj-docker example).

Multi-Agent Patterns

Coordinate multiple plugins via message passing.

Performance Optimization

Static vs dynamic rendering modes
Efficient state updates
Resource-conscious command execution

Notes

Plugins compile to WASM (wasm32-wasi target)
Use color indices (0-3) instead of hex for theme compatibility
Always check exit codes for command execution
Leverage Zellij's pane system for long-running processes
Use context maps to route command results
Request permissions during load() phase

File Organization

references/
  ├── plugin-development-tutorial.md      # Complete tutorial
  ├── plugin-api-commands.md              # API reference
  ├── plugin-api-events.md                # Event system
  ├── plugin-examples-ui-navigation.md    # UI patterns
  ├── plugin-examples-status-theming.md   # Configuration & theming
  └── plugin-examples-external-integration.md  # External systems

scripts/
  # Helper scripts for development automation

assets/
  # Templates, boilerplate, example projects

Updating

To refresh this skill with updated documentation:

Re-run the scraper with the same configuration
Add new plugin examples as they emerge
Update patterns based on community best practices

zellij-plugin-dev