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, 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
• /skill:code-review
  • loads the bundled structured review skill for files, directories, diffs, and PRs

Bundled extensions and resources

Extensions:

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

Other bundled resources:

• code-review skill
• /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.

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 also bundles a reusable code-review skill plus 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.