pi-zellij

Pi package with zellij-powered terminal integrations for Pi. Make your workflow agent driven.

Workflow

Why

Pi works well in the terminal, but pane orchestration is better handled by a terminal multiplexer. pi-zellij adds zellij-native split workflows for Pi.

It includes split and tab commands, generic tool launchers, agent-facing zellij tools, settings-driven floating app shortcuts, opt-in pane highlighting for completed agent turns, zoxide jumps, review workflows, and split-based task handoff.

Usage

Install with pi:

pi install npm:pi-zellij

Or with the installer:

npx pi-zellij

If pi is already running, use:

/reload

Requirements

• zellij must be installed
• pane, tab, and floating commands must be run from inside an active zellij session
• zoxide is required for the zoxide commands

Recommended zellij version

zellij version	status	notes
0.44.0+	recommended	pi-zellij can show created pane/tab IDs in success notifications, and /zt can launch its initial command directly via zellij action new-tab -- <command>
older versions	supported with fallback	commands still work, but zellij may not expose created IDs and /zt may fall back to the older typed-input startup path

Feature overview

Pane and tab workflows

• /zv, /zj, /zt
  • start a fresh Pi session in a new right pane, lower pane, or tab
• /zo <command...>, /zoh <command...>
  • run any shell command in a new right pane or lower pane
• /zz <query>, /zzh <query>
  • jump to a zoxide match or direct directory path and start Pi there

Floating tools

• pi-zellij.commands in settings.json
  • registers floating app shortcuts such as /zh for hx or /zg for lazygit
• pi-zellij.paneHighlight in settings.json
  • optionally tints the current zellij pane when Pi finishes a turn and is waiting for input

Review and handoff workflows

• /zcv, /zch
  • open continuation sessions in a split, optionally in a new git worktree
• /review <target>, /review-diff [focus-or-pr-url]
  • expand bundled review prompts in the current pane
• /zrv, /zrh, plus review flags
  • open review-focused Pi sessions in a split with built-in instructions or a configured skill

Bundled extensions and resources

Extensions:

• zv-split
• zv-open
• zv-highlight
• zv-zoxide
• zv-review
• zv-continue

Other bundled resources:

• /review prompt template
• /review-diff prompt template

Commands

Split and tab commands

• /zv
  • opens a new pane to the right
  • starts a fresh pi session in the same cwd
• /zj
  • opens a new pane below
  • starts a fresh pi session in the same cwd
• /zt
  • opens a new zellij tab
  • starts a fresh pi session in the same cwd

All three commands also accept optional initial prompt text.

Examples:

/zv Review the auth flow in this repo
/zt Investigate flaky tests in this repo

Tool split commands

• /zo <command...>
  • opens a new pane to the right
  • runs the given shell command in the same cwd
• /zoh <command...>
  • opens a new pane below
  • runs the given shell command in the same cwd

Examples:

/zo hx
/zo npm test
/zoh npm run dev
/zo watch -n 1 git status --short

Commands are executed via sh -lc in the current project directory.

Agent-opened Pi sessions and terminals

pi-zellij registers two agent-facing tools:

• zellij_start_pi starts another interactive Pi session with an optional initial prompt and model settings.
• zellij_open_terminal opens arbitrary interactive terminal commands.

Example requests:

start a fresh Pi agent in a right split and ask it to review the auth flow
continue this conversation in a lower Pi pane and focus on the failing tests
start Pi in a new tab using openai/gpt-4o with high thinking
open k9s in a new tab
open lazygit in a right split
open npm run dev below
open htop in a floating pane

zellij_start_pi supports tab, right, and down placements and defaults to tab. It starts a fresh session by default. The agent must set continueSession explicitly to inherit history; pi-zellij then clones the current active conversation into a separate session instead of opening the same session file in two processes. History inheritance requires a persisted source session with conversation history. The tool accepts prompt, provider, model, thinking, and title options, and handles the Pi command and shell quoting internally.

zellij_open_terminal supports tab, right, down, and floating placements and also defaults to tab. Floating terminals use the same 90% by 90% pane size as configured floating commands. Use it for TUIs, log tails, dev servers, watches, and other terminal views that should remain interactive instead of being captured through the normal shell tool.

Configured floating commands

You can register your own floating app shortcuts in Pi's main settings file under pi-zellij.commands.

Supported locations:

• ~/.pi/agent/settings.json for global commands
• .pi/settings.json for project-local commands

During the rename from pi-zv to pi-zellij, legacy pi-zv.commands is still accepted for compatibility. If both keys exist, pi-zellij.commands wins.

Simple form:

{
  "pi-zellij": {
    "commands": {
      "zh": "hx",
      "zg": "lazygit"
    }
  }
}

Each configured command opens in a floating zellij pane using a default 90% by 90% popup with 5% margins.

Examples:

/zh
/zg

For commands that should accept extra arguments, use the object form.

Helix and lazygit example:

{
  "pi-zellij": {
    "commands": {
      "zh": {
        "run": "hx",
        "acceptArgs": true,
        "description": "Open Helix in a floating pane"
      },
      "zg": {
        "run": "lazygit",
        "description": "Open lazygit in a floating pane"
      }
    }
  }
}

Then you can use:

/zh
/zh src/auth.ts
/zg

Configured command names cannot reuse built-in Pi commands such as /settings, /model, or /reload, and they also cannot replace pi-zellij's own slash commands such as /zv, /zj, /zt, /zz, or /zcv.

If the same command exists in both global and project settings, the project setting wins. After changing settings, run /reload in Pi.

Pane highlight on completion

You can optionally tint the current zellij pane when Pi finishes a turn and is waiting for input.

Supported locations:

• ~/.pi/agent/settings.json for global settings
• .pi/settings.json for project-local settings

During the rename from pi-zv to pi-zellij, legacy pi-zv.paneHighlight is still accepted for compatibility. If both keys exist, pi-zellij.paneHighlight wins.

Minimal form:

{
  "pi-zellij": {
    "paneHighlight": true
  }
}

That enables a default done-state background tint. The feature is zellij-only and does nothing outside an active zellij session.

Object form:

{
  "pi-zellij": {
    "paneHighlight": {
      "enabled": true,
      "doneBg": "#17352a",
      "doneFg": "#e7fff0",
      "workingBg": "#2f2415"
    }
  }
}

Supported keys:

• enabled
  • set to false to disable the feature
• doneBg, doneFg
  • pane colors to apply after agent_end when the pane is not currently focused
• workingBg, workingFg
  • optional pane colors to apply while Pi is working; if omitted, pi-zellij resets the pane to its default colors when the next input is submitted or when the pane is focused again after being elsewhere

When enabled, pi-zellij resets the pane color on session start, session switch, the next submitted input, pane refocus when zellij focus state is available, and session shutdown so completed-turn highlights do not linger across sessions. If the pane is already focused when a turn completes, the done-state tint is skipped so the Pi editor does not stay tinted while you type. Aborted runs do not apply the done-state tint. After changing these settings, run /reload in Pi.

Zoxide jump commands

• /zz <query>
  • resolves the query with zoxide query
  • opens a new pane to the right
  • starts a fresh pi session in the matched directory
• /zzh <query>
  • resolves the query with zoxide query
  • opens a new pane below
  • starts a fresh pi session in the matched directory

Example:

/zz mono

If the argument is already a valid directory path, /zz and /zzh use it directly instead of querying zoxide.

Continuation and worktree helpers

• /zcv
  • opens a new pane to the right
  • creates a related handoff session in the current checkout
• /zch
  • opens a new pane below
  • creates a related handoff session in the current checkout
• /zcv <note> / /zch <note>
  • same as above, but adds a focus note to the handoff context
• /zcv -c <branch> / /zch -c <branch>
  • creates a new branch worktree from the current HEAD, then opens a new pane there
• /zcv -c <branch> --from <ref> / /zch -c <branch> --from <ref>
  • creates a new branch worktree from an explicit base ref such as main or origin/main
• /zcv -c <branch> [--from <ref>] <note...> / /zch -c <branch> [--from <ref>] <note...>
  • same as above, but also adds a focus note to the worktree handoff

Examples:

/zcv
/zcv focus on tests
/zcv -c fix/notify-bug
/zcv -c fix/notify-bug --from main
/zcv -c fix/notify-bug --from main review the existing changes first
/zch -c feature/review-ui focus on edge cases

Review helpers

pi-zellij includes built-in review instructions; no skill installation is required and no review skill is registered globally. It also bundles prompt templates for in-place review:

• /review <target>
  • prompt template for reviewing a file, directory, or GitHub pull request URL in the current pane
• /review-diff [focus-or-pr-url]
  • prompt template for reviewing the current git diff in the current pane, or a GitHub pull request URL via gh

Split review commands:

• /zrv
  • with no arguments, reviews the current git diff in a new right pane
• /zrh
  • with no arguments, reviews the current git diff in a new lower pane
• /zrv [--bugs|--refactor|--tests] <target> or /zrv --diff [focus]
  • opens a new pane to the right
  • starts a fresh pi review session in the same cwd
• /zrh [--bugs|--refactor|--tests] <target> or /zrh --diff [focus]
  • opens a new pane below
  • starts a fresh pi review session in the same cwd

--diff is the default, so /zrv and /zrh usually do not need the flag.

There are no /review-v or /review-h aliases in pi-zellij, so it can coexist more cleanly with other Pi packages.

Examples:

/zrv
/zrh
/zrv src/auth.ts
/zrv --bugs src/auth.ts
/zrh --refactor src/auth/
/zrv --diff
/zrh --diff focus on token refresh and retries
/zrv https://github.com/owner/repo/pull/123

If the target is a GitHub pull request URL, the review workflow switches to PR review and instructs pi to inspect the pull request with gh pr view and gh pr diff.

Use your own review skill

By default, /zrv and /zrh inject the built-in review instructions into the new session's initial prompt only. To use an existing skill instead, set pi-zellij.review.skill in ~/.pi/agent/settings.json or the trusted project's .pi/settings.json:

{
  "pi-zellij": {
    "review": {
      "skill": "my-code-review"
    }
  }
}

Use the skill's name without the /skill: prefix. It must be loaded in the current Pi session. The commands expand its instructions before opening the pane, preserving its location for relative references and passing the review target and mode. The skill controls the workflow and output format; the request still tells Pi not to edit files unless asked.

• Omit the setting to use the built-in instructions.
• Project settings override global settings. Set "skill": null in the project to use the built-in instructions despite a global override.
• An unavailable or unreadable skill, or invalid review settings, produces an error without opening a pane. There is no silent fallback.
• Review settings are read on each invocation. After installing or enabling a skill, run /reload first.

This setting only affects /zrv and /zrh; /review and /review-diff remain self-contained prompt templates.