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:

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