Skill: zellij-subagents Skill

Skill: zellij-subagents

Use this skill to orchestrate parallel Pi subagents via Zellij.

What this is for

Typical use cases:

Parallel research (eg, one subagent per subsystem)
Multi-step workflows (recon → implementation → review)
Isolating subagent context windows in separate panes
Durable handoff artifacts (handoff.json) per subagent

Requirements

pi installed
zellij installed and on PATH
node installed and on PATH

Optional:

Custom subagent command via --cmd (overrides the default Pi execution)

Install / Setup

git clone git@github.com:e-beyene/zellij-pi-orchestrator.git
cd zellij-pi-orchestrator
pi

Inside Pi:

/reload

The project-local extension is auto-discovered from .pi/extensions/zellij-orchestrator/.

Data model

Runtime state is stored at: <cwd>/.orchestrator/<session>/subagents/<id>/

Key files:

inbox/<task_id>.task
prompts/<task_id>.md
done/<task_id>.out.txt
status
handoff.json

Notes

Timeout behavior: wrap-up steer once, grace period, then force-terminate.
If force-terminated, no synthetic handoff is created.
Targeted pane termination is limited by Zellij CLI capabilities; session-wide terminate is most reliable.

Interface (extension-native)

Use friendly extension commands:

/zj-start <session> [worker1 worker2 ...]
/zj-task <session> <worker|all> <taskId> <promptFile|promptText>
/zj-run <session> <worker> <promptFile|promptText>
/zj-wait <session> [worker|all] [timeoutSec] [--grace N]
/zj-results <session>
/zj-stop <session>
/zj-help

Or call the tool zellij_orchestrate directly.

Completion semantics

Treat a subagent as complete only when both:

worker status is idle
handoff.json exists and includes agent_end: true

Failure handling

On timeout:

assign _force_wrapup
wait grace period
force-terminate target

Agent Skills: Skill: zellij-subagents

Install this agent skill to your local

Skill Files