# Zellij Plugin Dev

> Develop Zellij plugins with Rust/WASM, API reference, event system, UI rendering, plugin lifecycle, and real-world examples from diverse open source plugins

- Skill: `delorenj/zellij-plugin-dev` (Agent Skill, multi-file: 10 files)
- Install (CLI): `npx skillmds@latest add delorenj/zellij-plugin-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/delorenj/zellij-plugin-dev/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: delorenj (https://skillmd.com/u/delorenj)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/delorenj/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

```rust
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

```bash
# 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:
>
> ```bash
> 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

```bash
# 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:

```bash
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:**

```bash
zellij plugin -- file:./target/wasm32-wasip1/release/plugin.wasm
```

**Release:**

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

## Common Patterns

### Modal UI (Floating Windows)

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

### Command Execution with Context

```rust
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

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

    widget1_param1 "value"
    widget1_param2 "value"
}
```

### State Synchronization

```rust
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