Zellij Plugin Dev

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-wasip1

# Build
cargo build --release

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

On big-chungus, cargo build will fail with can't find crate for core. /usr/bin/rustc precedes rustup on PATH and carries no wasm32-wasip1 std. The error reads exactly like a missing target, so rustup target add looks like the fix and does nothing — the target is installed. Pin RUSTC instead:

T=~/.rustup/toolchains/1.95.0-x86_64-unknown-linux-gnu
RUSTC="$T/bin/rustc" "$T/bin/cargo" build --release --target wasm32-wasip1

Related: rustc --print sysroot returns empty when RUSTUP_TOOLCHAIN is set, which sends the diagnosis further astray.

Do not rebuild a plugin just because zellij was upgraded. There is no plugin API version gate in 0.44.3 — a plugin built against zellij-tile 0.41.1 loads fine. The only cost of an old build is cosmetic (pre-0.43 knows Style.palette but not Style.styling, so 16-colour approximation). See the zellij-workspace-ops skill.

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-wasip1/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-wasip1 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