Agent skill
zellij-driver
Programmatic Zellij terminal workspace management for agentic workflows. Use when orchestrating parallel development tasks, creating tabs/panes, tracking developer intent, or managing terminal layouts. Triggers include: (1) Creating tabs with specific naming conventions, (2) Spawning multiple panes for parallel work, (3) Logging and retrieving developer intent/context, (4) Workspace layout organization for agent coordination, (5) Integration with iMi worktrees for branch-per-pane workflows.
Install this agent skill to your Project
npx add-skill https://github.com/delorenj/zellij-driver/tree/main/skill
SKILL.md
Zellij Driver (znav)
Overview
znav is a Redis-backed Zellij pane manager that tracks developer intent and cognitive context across terminal sessions. It enables programmatic control of Zellij tabs and panes, making it ideal for orchestrating parallel agentic workflows.
Core Philosophy: Capture what you're working on, not just what you typed. znav bridges the gap between terminal activity and developer intent, enabling AI agents to understand and resume work context.
Core Capabilities
1. Tab and Pane Management
Create Named Tabs:
znav tab my-feature # Switch to or create tab
znav tab create myapp --correlation-id pr-42 # Tab with correlation ID
znav pane my-task --tab my-feature # Create pane in specific tab
Pane Operations:
znav pane api-refactor # Create/open pane (auto-creates tab if needed)
znav pane info api-refactor # Get pane metadata
znav list # Tree view of all sessions/tabs/panes
znav reconcile # Sync Redis state with Zellij layout
Batch Pane Creation:
# Create multiple panes in a single command
znav pane batch --tab "myapp(fixes)" --panes fix-auth,fix-errors,fix-docs
# With working directories for each pane
znav pane batch --tab "myapp(fixes)" \
--panes fix-auth,fix-errors,fix-docs \
--cwd ../fix-auth,../fix-errors,../fix-docs
# Horizontal layout (stacked instead of side-by-side)
znav pane batch --tab "myapp(fixes)" --panes a,b,c --layout horizontal
2. Intent Tracking (znav v2.0)
Track what you're working on, not just commands:
Log Intent Entries:
# Simple checkpoint
znav pane log my-feature "Fixed authentication bug"
# Milestone with artifacts
znav pane log api-refactor "Completed REST API redesign" \
--type milestone --artifacts src/api.rs docs/api.md
# Exploration session
znav pane log research "Investigated caching strategies" --type exploration
# Agent-generated entry
znav pane log my-feature "Completed task analysis" --source agent
Entry Types:
checkpoint(default): Regular progress markersmilestone: Major accomplishments worth highlightingexploration: Research or investigative work
Entry Sources:
manual(default): Human-created entriesagent: Created by AI during assisted workflowautomated: System-generated from activity detection
3. History Retrieval
Multiple output formats for different use cases:
# Human-readable (default)
znav pane history my-feature
# JSON for programmatic access
znav pane history my-feature --format json
# Compact JSON for piping
znav pane history my-feature --format json-compact | jq '.entries[0]'
# Markdown export (Obsidian-compatible)
znav pane history my-feature --format markdown > session.md
# LLM-optimized context for agent integration (~1000 tokens)
znav pane history my-feature --format context
4. LLM-Powered Snapshots
Auto-generate intent summaries from recent work:
# Generate AI summary of recent activity
znav pane snapshot my-feature
# Requires LLM configuration and consent
znav config set llm.provider anthropic
znav config consent --grant
Supported Providers:
anthropic(Claude) - default model: claude-sonnet-4-20250514openai(GPT) - default model: gpt-4o-miniollama(local) - default model: llama3.2none- disabled
5. Configuration Management
znav config show # View all settings
znav config set redis_url redis://... # Update Redis connection
znav config consent --grant # Allow LLM data sharing
znav config consent --revoke # Revoke LLM consent
Agentic Workflow Patterns
Pattern 1: Parallel PR Fixes
When implementing multiple fixes from a PR in parallel:
# 1. Create a tab for the fixes with correlation ID for traceability
znav tab create "myapp(fixes)" --correlation-id pr-42
# 2. Create all panes in one batch command
znav pane batch --tab "myapp(fixes)-pr-42" --panes fix-auth,fix-errors,fix-docs
# 3. Each pane can be worked on by a separate agent
# Agent in fix-auth pane:
znav pane log fix-auth "Starting auth token refresh fix" --source agent
# ... agent does work ...
znav pane log fix-auth "Completed auth fix" --type milestone --source agent
Pattern 2: iMi Integration
Combine with iMi worktrees for branch-per-pane isolation:
# 1. Create worktrees with iMi
imi add fix auth-refresh
imi add fix error-handling
imi add fix api-docs
# 2. Create Zellij workspace with all panes and working directories in one command
znav tab create "myapp(fixes)"
znav pane batch --tab "myapp(fixes)" \
--panes fix-auth,fix-errors,fix-docs \
--cwd ~/code/myapp/fix-auth-refresh,~/code/myapp/fix-error-handling,~/code/myapp/fix-api-docs
Pattern 3: Session Resumption
When returning to a pane, znav displays the last intent:
# First session
znav pane my-feature
znav pane log my-feature "Implementing user authentication flow"
# ... work happens ...
# Later session (shows resume context)
znav pane my-feature
# Output: "Resuming: ● Implementing user authentication flow (2 hours ago)"
Pattern 4: Agent Context Injection
Get condensed context for LLM prompts:
# Get ~1000 token context summary
CONTEXT=$(znav pane history my-feature --format context)
# Inject into agent prompt
echo "Continue this work session:\n$CONTEXT"
Tab Naming Conventions
For agentic workflows, use consistent naming:
| Pattern | Example | Use Case |
|---|---|---|
{repo}(fixes) |
myapp(fixes) |
PR fix batch |
{repo}({branch}) |
myapp(feat-auth) |
Feature branch work |
{repo}({context})-{id} |
myapp(fixes)-abc123 |
Bloodbank correlation |
{task} |
research-caching |
Exploration work |
Current Limitations
Not Yet Implemented (Sprint 5/6 backlog):
- Bloodbank event publishing
- MCP tool exposure
- Session restoration/snapshotting
Zellij Version:
- Requires Zellij >= 0.39.0
Data Model
IntentEntry:
{
"id": "uuid",
"timestamp": "2025-01-06T12:00:00Z",
"summary": "What you were working on",
"entry_type": "checkpoint|milestone|exploration",
"source": "manual|agent|automated",
"artifacts": ["file1.rs", "file2.ts"],
"commands_run": 15,
"goal_delta": "Progress description"
}
PaneRecord:
- Tracks session, tab, pane name, position
- Stores metadata for navigation
- Marks stale panes after reconciliation
Redis Keyspace
znav v2.0 uses the znav: keyspace:
znav:pane:{name} # Pane metadata hash
znav:intent:{name} # Intent history list (LPUSH/LRANGE)
Migration from v1.0 (znav:) keyspace:
znav migrate --dry-run # Preview migration
znav migrate # Execute migration
Quick Reference
| Command | Description |
|---|---|
znav pane <name> |
Create/open pane |
znav pane --tab <tab> <name> |
Pane in specific tab |
znav pane batch --tab <tab> --panes a,b,c |
Create multiple panes |
znav pane log <name> "<summary>" |
Log intent entry |
znav pane history <name> |
View history |
znav pane history <name> --format context |
LLM-ready context |
znav pane snapshot <name> |
AI-generate summary |
znav pane info <name> |
Pane metadata |
znav tab <name> |
Switch/create tab |
znav tab create <name> --correlation-id <id> |
Tab with correlation ID |
znav list |
Tree view of workspace |
znav reconcile |
Sync state with layout |
znav config show |
View configuration |
znav config consent --grant |
Allow LLM sharing |
Developer Resources
For contributors and agents extending znav:
- Developer Guidelines: See
skill/DEVELOPER.mdfor P0 requirements and standards. - Architecture: See
docs/ENGINEERING_STANDARDS.mdfor anti-patterns and patterns.
Integration Points
33GOD Ecosystem:
- iMi: Worktree management for branch isolation
- Bloodbank: Event publishing for workflow triggers (planned)
- Jelmore: Session correlation tracking (planned)
- Flume: Task coordination across panes (planned)
Claude Code:
- Use
--format contextfor prompt injection - Use
--source agentfor agent-created entries - Use
--format jsonfor programmatic processing
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
openclaw-upgrade
Upgrade OpenClaw installations to the latest version. Handles global npm installs, local development setups, release channels (stable/beta/dev), configuration preservation, and platform-specific requirements. Use when updating OpenClaw, switching release channels, or troubleshooting update issues.
vercel-composition-patterns
React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.
security-monitor
Real-time security monitoring for Clawdbot. Detects intrusions, unusual API calls, credential usage patterns, and alerts on breaches.
event-driven-architecture
Kafka, RabbitMQ, SQS/SNS, event sourcing, CQRS, saga patterns, dead letter queues, and idempotency. Use when designing asynchronous systems, implementing message-driven workflows, or building event streaming pipelines.
shadcn-ui
Expert guidance for integrating and building applications with shadcn/ui components, including component discovery, installation, customization, and best practices.
just-fucking-cancel
Find and cancel unwanted subscriptions by analyzing bank transactions. Detects recurring charges, calculates annual waste, and helps you cancel with direct URLs and browser automation. Use when: 'cancel subscriptions', 'audit subscriptions', 'find recurring charges', 'what am I paying for', 'save money', 'subscription cleanup', 'stop wasting money'. Supports CSV import (Apple Card, Chase, Amex, Citi, Bank of America, Capital One, Mint, Copilot) OR Plaid API for automatic transaction pull. Outputs interactive HTML audit with one-click cancel workflow. Pairs with Plaid integration for real-time transaction access without CSV exports.
Didn't find tool you were looking for?