
zellij-workflow
Zellij workflow: tab status indicators, issue development tabs, Claude session tabs
- GitHub stars
- 17
Install
/plugin install zellij-workflow@dapiRun it inside Claude Code after adding the marketplace with /plugin marketplace add dapi/claude-code-marketplace.
Contents
Discovered from sourceSkills 1
Zellij Tab/Pane Skill
Open a tab or pane in zellij -- empty, with a shell command, with a Claude session, or with a GitHub issue.
Decision Tree
Step 1: Container
"pane"/"panel"/"панель" -> PANE
"tab"/"вкладка"/default -> TAB
Step 2: Mode
nothing to run -> A (empty)
shell command -> B (command)
Claude prompt/plan/task -> C (claude session)
GitHub issue (#N / URL) -> D (issue dev via start-issue)
Mode A: Empty Tab/Pane
User just wants a new tab or pane, nothing to run.
Tab name: user-specified or shell-HH:MM (e.g. shell-14:35).
TAB
timeout 5 zellij action new-tab --name "$TAB_NAME" || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
PANE
timeout 5 zellij action new-pane || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
Mode B: Command in Tab/Pane
User wants to run a shell command (npm test, make build, etc.) in a new tab or pane.
Tab name: derived from command (e.g. npm-test, make-build). Max 20 chars.
TAB
TAB_NAME="<from-command>"
timeout 5 zellij action new-tab --name "$TAB_NAME" -- $CMD || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
PANE
timeout 5 zellij run -- $CMD || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
Mode C: Claude Session in Tab/Pane
User wants an interactive Claude Code session with instructions/plan/task.
Tab name: auto-generated from context (1-2 words, max 20 chars):
- Has issue reference ->
#123 - Has plan file ->
plan-audit - General task ->
refactor,fix-tests - Fallback ->
claude-HH:MM
Step 1: Write bash launch script
SCRIPT=$(mktemp /tmp/claude-tab-XXXXXX.sh)
cat > "$SCRIPT" << 'SCRIPT_EOF'
#!/bin/bash
cd '<PROJECT_DIR>'
PROMPT='<escaped prompt -- single quotes escaped as '"'"'>'
clear
echo "Launching claude with prompt: $PROMPT"
echo ""
exec claude --dangerously-skip-permissions "$PROMPT"
SCRIPT_EOF
chmod +x "$SCRIPT"
Why a script: Prompts can be multi-line with quotes and special characters; a heredoc in a temp script avoids complex escaping in command arguments.
Step 2: Launch
TAB
TAB_NAME="<auto-generated>"
timeout 5 zellij action new-tab --name "$TAB_NAME" -- bash "$SCRIPT" || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
elif ! command -v claude &>/dev/null; then echo "claude not found in PATH"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
PANE
timeout 5 zellij run -- bash "$SCRIPT" || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
elif ! command -v claude &>/dev/null; then echo "claude not found in PATH"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
Mode D: Issue Development in Tab/Pane
User wants to start development on a GitHub issue. Recognized when request contains an issue reference (number, #number, or GitHub URL).
Tab name: always #NUMBER.
Issue Number Parsing
parse_issue_number() {
local arg="$1"
if [[ "$arg" =~ github\.com/.*/issues/([0-9]+) ]]; then
echo "${BASH_REMATCH[1]}"
elif [[ "$arg" =~ ^#?([0-9]+)$ ]]; then
echo "${BASH_REMATCH[1]}"
else
echo ""
fi
}
Issue Argument Format
| Format | Example | Result |
|---|---|---|
| Number | 123 | Issue #123 |
| With hash | #123 | Issue #123 |
| URL | https://github.com/owner/repo/issues/123 | Issue #123 |
TAB
ISSUE_NUMBER=$(parse_issue_number "$ARG")
timeout 5 zellij action new-tab --name "#${ISSUE_NUMBER}" -- start-issue $ISSUE_NUMBER || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
elif ! command -v start-issue &>/dev/null; then echo "start-issue not found in PATH"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
PANE
timeout 5 zellij run -- start-issue $ISSUE_NUMBER || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
elif ! command -v start-issue &>/dev/null; then echo "start-issue not found in PATH"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
Examples
Example 1: Empty tab
User: "open a new zellij tab"
timeout 5 zellij action new-tab --name "shell-14:35"
Example 2: Command in pane
User: "run npm test in a pane"
timeout 5 zellij run -- npm test
Example 3: Command in tab
User: "run make build in new tab"
timeout 5 zellij action new-tab --name "make-build" -- make build
Example 4: Claude session in tab
User: "execute the plan from docs/plans/audit.md in new tab"
SCRIPT=$(mktemp /tmp/claude-tab-XXXXXX.sh)
cat > "$SCRIPT" << 'SCRIPT_EOF'
#!/bin/bash
cd '/home/danil/code/project'
PROMPT='Execute the plan from docs/plans/audit.md. Use superpowers:executing-plans.'
clear
echo "Launching claude with prompt: $PROMPT"
echo ""
exec claude --dangerously-skip-permissions "$PROMPT"
SCRIPT_EOF
chmod +x "$SCRIPT"
timeout 5 zellij action new-tab --name "plan-audit" -- bash "$SCRIPT"
Example 5: Delegate to pane
User: "delegate this refactoring to a pane"
SCRIPT=$(mktemp /tmp/claude-tab-XXXXXX.sh)
cat > "$SCRIPT" << 'SCRIPT_EOF'
#!/bin/bash
cd '/home/danil/code/project'
PROMPT='Refactor the auth module: extract JWT validation into separate service'
clear
echo "Launching claude with prompt: $PROMPT"
echo ""
exec claude --dangerously-skip-permissions "$PROMPT"
SCRIPT_EOF
chmod +x "$SCRIPT"
timeout 5 zellij run -- bash "$SCRIPT"
Example 6: Issue in tab
User: "start issue #45 in a new tab"
timeout 5 zellij action new-tab --name "#45" -- start-issue 45
Example 7: Issue URL in pane
User: "start https://github.com/org/repo/issues/123 in a pane"
timeout 5 zellij run -- start-issue https://github.com/org/repo/issues/123
Dependencies
- zellij -- terminal multiplexer (must be running)
- claude -- Claude Code CLI (for Mode C only)
- start-issue -- issue development command (for Mode D only)
Errors
| Error | Cause | Solution |
|---|---|---|
Timed out | zellij hanging (exit code 124) | Restart zellij |
Not in zellij session | Running outside zellij | Start zellij first |
claude not found | Claude CLI not in PATH | Install Claude Code |
start-issue not found | start-issue not in PATH | Install or add to PATH |
Invalid issue format | Bad argument | Use number, #number, or URL |
| Script not created | /tmp not writable | Check disk space |
Important
- Skill works only inside zellij session
- TAB modes use
new-tab -- CMD(atomic, no race conditions) - PANE modes use
zellij run -- CMD - For Mode C, session is interactive (not -p print mode) -- remains a working chat
Commands 2
Run in New Tab
Launch an interactive Claude Code session in a new zellij tab or pane.
Input
- INSTRUCTIONS:
$ARGUMENTS-- prompt text or path to a plan file
Steps
1. Determine tab name and prompt
If $ARGUMENTS is a file path (ends with .md), the prompt should be:
Execute the plan from <plan-file-path>. Use superpowers:executing-plans.
Otherwise use $ARGUMENTS directly as the prompt.
Generate a short tab name (1-2 words) from the content.
Fallback: claude-<HH:MM>.
2. Write bash launch script
SCRIPT=$(mktemp /tmp/claude-tab-XXXXXX.sh)
cat > "$SCRIPT" << 'SCRIPT_EOF'
#!/bin/bash
cd '<PROJECT_DIR>'
PROMPT='<escaped prompt -- single quotes escaped as '"'"'>'
clear
echo "Launching claude with prompt: $PROMPT"
echo ""
exec claude --dangerously-skip-permissions "$PROMPT"
SCRIPT_EOF
chmod +x "$SCRIPT"
3. Create tab and launch
In a new tab (default):
TAB_NAME="<auto-generated>"
timeout 5 zellij action new-tab --name "$TAB_NAME" && \
sleep 0.3 && \
timeout 5 zellij action write-chars "bash '$SCRIPT'
" || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
elif ! command -v claude &>/dev/null; then echo "claude not found in PATH"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
In a new pane:
timeout 5 zellij run -- bash "$SCRIPT" || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
elif ! command -v claude &>/dev/null; then echo "claude not found in PATH"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
Examples
/run-in-new-tab Execute plan from docs/plans/skill-audit-plan.md. Use executing-plans.
/run-in-new-tab Refactor auth module following DRY principles
/run-in-new-tab Fix all failing tests in spec-reviewer plugin
Result
- New zellij tab or pane created
- Interactive Claude Code session running with the given instructions
- Session remains a working chat after initial prompt
Start Issue in New Tab
Launch issue development in a new zellij tab or pane.
Input
- ISSUE:
$ARGUMENTS-- issue number, #number, or full GitHub URL
Steps
1. Parse issue number
parse_issue_number() {
local arg="$1"
# URL: https://github.com/.../issues/123
if [[ "$arg" =~ github\.com/.*/issues/([0-9]+) ]]; then
echo "${BASH_REMATCH[1]}"
# #123 or 123
elif [[ "$arg" =~ ^#?([0-9]+)$ ]]; then
echo "${BASH_REMATCH[1]}"
else
echo ""
fi
}
ISSUE_NUMBER=$(parse_issue_number "$ARGUMENTS")
2. Create tab and launch start-issue
In a new tab (default):
timeout 5 zellij action new-tab --name "#${ISSUE_NUMBER}" && \
sleep 0.3 && \
timeout 5 zellij action write-chars "start-issue $ISSUE_NUMBER
" || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
elif ! command -v start-issue &>/dev/null; then echo "start-issue not found in PATH"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
In a new pane:
timeout 5 zellij run -- start-issue $ISSUE_NUMBER || {
_rc=$?
echo "Command failed. Diagnosing..."
if [ -z "$ZELLIJ" ]; then echo "Not in zellij session"
elif [ $_rc -eq 124 ]; then echo "Timed out -- zellij may be hanging"
elif ! command -v start-issue &>/dev/null; then echo "start-issue not found in PATH"
else echo "Unknown error (exit code: $_rc)"
fi
exit $_rc
}
Examples
/start-issue-in-new-tab 123
/start-issue-in-new-tab #45
/start-issue-in-new-tab https://github.com/owner/repo/issues/78
Result
- New zellij tab created with name
#123 start-issueruns and:- Creates git worktree
- Renames tab
- Launches Claude Code session
Sponsors
Details
- Marketplace
- dapi/claude-code-marketplace
- Source
- zellij-workflow
- Category
- Community