pi-zellij 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- Initial `pi-zellij` release with zellij-powered pane workflows for Pi.
+
+### Changed
+
+- Clarified README notification wording to match the current `zv-notify` behavior: `Waiting`, `Task Complete`, and `Error`.
+- Added `zv-notify` for desktop notifications using `osascript` on macOS or `notify-send` on Linux.
+- Added `/zv`, `/zj`, and `/zt` to open a new zellij pane or tab and start a fresh Pi session in the same working directory.
+- Added `/zo` and `/zoh` to open a new pane and run any shell command there.
+- Added configurable floating app commands via `pi-zellij.commands` in Pi `settings.json`, including shorthand entries such as `"zh": "hx"` and `"zg": "lazygit"`, plus object entries with `acceptArgs` support.
+- Added compatibility fallback for legacy `pi-zv.commands` settings during the rename to `pi-zellij`.
+- Reserved Pi built-in slash commands such as `/settings`, `/model`, and `/reload` so configured floating commands cannot shadow them.
+- Added `/zz` and `/zzh` to open a new pane from a zoxide match or direct directory path and start Pi there.
+- Added `zv-review` with `/zrv` and `/zrh`, plus bundled `code-review` skill and `/review` / `/review-diff` prompt templates for focused review workflows, including GitHub pull request review via `gh` when given a PR URL.
+- Added `zv-continue` with `/zcv` and `/zch` for split-based task handoff in the current checkout or by creating a git worktree branch with `-c <branch>`.

package/README.md

@@ -0,0 +1,296 @@
+# pi-zellij
+
+Pi package with zellij-powered terminal integrations for [Pi](https://pi.dev).
+
+## Why
+
+[Pi](https://pi.dev) works well in the terminal, but pane orchestration is better handled by a terminal multiplexer. `pi-zellij` adds zellij-native split workflows for Pi, plus optional desktop notifications.
+
+It includes split and tab commands, generic tool launchers, settings-driven floating app shortcuts, zoxide jumps, review workflows, split-based task handoff, and automatic run notifications.
+
+## Usage
+
+Install with pi:
+
+```bash
+pi install npm:pi-zellij
+```
+
+Or with the installer:
+
+```bash
+npx pi-zellij
+```
+
+If pi is already running, use:
+
+```text
+/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
+- notifications use:
+  - `osascript` on macOS
+  - `notify-send` on Linux
+
+## 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`
+
+### 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
+
+### Notifications
+
+- automatic via `zv-notify`
+  - sends desktop notifications for Pi run states such as `Waiting`, `Task Complete`, and `Error`
+
+## Bundled extensions and resources
+
+Extensions:
+- `zv-notify`
+- `zv-split`
+- `zv-open`
+- `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:
+
+```text
+/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:
+
+```text
+/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:
+
+```json
+{
+  "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:
+
+```text
+/zh
+/zg
+```
+
+For commands that should accept extra arguments, use the object form:
+
+```json
+{
+  "pi-zellij": {
+    "commands": {
+      "zh": {
+        "run": "hx",
+        "acceptArgs": true,
+        "description": "Open Helix in a floating pane"
+      }
+    }
+  }
+}
+```
+
+Then you can pass arguments through to the configured command:
+
+```text
+/zh src/auth.ts
+```
+
+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.
+
+### 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:
+
+```text
+/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:
+
+```text
+/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:
+
+```text
+/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`.
+
+## Notifications
+
+The bundled `zv-notify` extension summarizes each run and sends a desktop notification when supported by the host system.
+
+Current notification types:
+- `Waiting`
+- `Task Complete`
+- `Error`
+
+You can control notification noise with one setting:
+- `PI_ZV_NOTIFY_LEVEL=all` - `Waiting`, `Task Complete`, and `Error`
+- `PI_ZV_NOTIFY_LEVEL=medium` - `Task Complete` and `Error`
+- `PI_ZV_NOTIFY_LEVEL=low` - `Error` only
+- `PI_ZV_NOTIFY_LEVEL=disabled` - disable notifications
+
+## Environment variables
+
+- `PI_ZV_NOTIFY_LEVEL` - notification level: `all`, `medium`, `low`, or `disabled` (default: `all`)
+- `PI_ZV_NOTIFY_THRESHOLD_MS` - duration threshold before a run is labeled `Task Complete` instead of `Waiting` (default: `15000`)
+- `PI_ZV_NOTIFY_DEBOUNCE_MS` - minimum delay between duplicate notifications (default: `3000`)
+- `PI_ZV_NOTIFY_TITLE` - notification title override (default: `Pi`)

package/extensions/git-core.ts

@@ -0,0 +1,184 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { basename, dirname, join } from "node:path";
+import { existsSync, mkdirSync } from "node:fs";
+
+const GIT_TIMEOUT_MS = 10000;
+const DEFAULT_MAX_STATUS_LINES = 20;
+
+export interface GitExecResult {
+	ok: boolean;
+	stdout: string;
+	stderr: string;
+	error?: string;
+}
+
+export interface GitRepoInfo {
+	repoRoot: string;
+	branch?: string;
+	statusLines: string[];
+}
+
+interface GitWorktreeInfo {
+	path: string;
+	branch?: string;
+}
+
+export async function execGit(pi: ExtensionAPI, cwd: string, args: string[]): Promise<GitExecResult> {
+	const result = await pi.exec("git", args, { timeout: GIT_TIMEOUT_MS, cwd });
+	if (result.killed) {
+		return {
+			ok: false,
+			stdout: result.stdout,
+			stderr: result.stderr,
+			error: "git command timed out",
+		};
+	}
+	if (result.code !== 0) {
+		return {
+			ok: false,
+			stdout: result.stdout,
+			stderr: result.stderr,
+			error: result.stderr.trim() || result.stdout.trim() || `git exited with code ${result.code}`,
+		};
+	}
+	return {
+		ok: true,
+		stdout: result.stdout,
+		stderr: result.stderr,
+	};
+}
+
+export async function getGitRepoInfo(pi: ExtensionAPI, cwd: string, maxStatusLines: number = DEFAULT_MAX_STATUS_LINES): Promise<GitRepoInfo | undefined> {
+	const rootResult = await execGit(pi, cwd, ["rev-parse", "--show-toplevel"]);
+	if (!rootResult.ok) return undefined;
+	const repoRoot = rootResult.stdout.trim();
+	if (!repoRoot) return undefined;
+
+	const branchResult = await execGit(pi, cwd, ["branch", "--show-current"]);
+	const statusResult = await execGit(pi, cwd, ["status", "--short", "--untracked-files=all"]);
+
+	return {
+		repoRoot,
+		branch: branchResult.ok ? branchResult.stdout.trim() || undefined : undefined,
+		statusLines: statusResult.ok
+			? statusResult.stdout
+				.split("\n")
+				.map((line) => line.trimEnd())
+				.filter((line) => line.trim().length > 0)
+				.slice(0, maxStatusLines)
+			: [],
+	};
+}
+
+function parseWorktreeList(text: string): GitWorktreeInfo[] {
+	const worktrees: GitWorktreeInfo[] = [];
+	let current: GitWorktreeInfo | undefined;
+
+	for (const rawLine of text.split("\n")) {
+		const line = rawLine.trimEnd();
+		if (line.startsWith("worktree ")) {
+			if (current) worktrees.push(current);
+			current = { path: line.slice("worktree ".length).trim() };
+			continue;
+		}
+		if (!current) continue;
+		if (line.startsWith("branch ")) {
+			current.branch = line.slice("branch ".length).trim().replace(/^refs\/heads\//, "") || undefined;
+			continue;
+		}
+		if (line.length === 0) {
+			worktrees.push(current);
+			current = undefined;
+		}
+	}
+
+	if (current) worktrees.push(current);
+	return worktrees;
+}
+
+function slugifyBranchName(branch: string): string {
+	return branch
+		.trim()
+		.replace(/[^A-Za-z0-9._-]+/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/^-|-$/g, "") || "worktree";
+}
+
+export async function branchExists(pi: ExtensionAPI, repoRoot: string, branch: string): Promise<boolean> {
+	const result = await pi.exec("git", ["show-ref", "--verify", "--", `refs/heads/${branch}`], { timeout: GIT_TIMEOUT_MS, cwd: repoRoot });
+	return !result.killed && result.code === 0;
+}
+
+async function resolveWorktreePath(
+	pi: ExtensionAPI,
+	repoRoot: string,
+	branch: string,
+): Promise<{ ok: true; path: string; reused: boolean } | { ok: false; error: string }> {
+	const listResult = await execGit(pi, repoRoot, ["worktree", "list", "--porcelain"]);
+	if (!listResult.ok) {
+		return { ok: false, error: listResult.error || "Failed to list git worktrees" };
+	}
+
+	const existing = parseWorktreeList(listResult.stdout).find((worktree) => worktree.branch === branch);
+	if (existing) {
+		return { ok: true, path: existing.path, reused: true };
+	}
+
+	const worktreeRoot = join(dirname(repoRoot), `${basename(repoRoot)}-worktrees`);
+	const targetPath = join(worktreeRoot, slugifyBranchName(branch));
+	if (existsSync(targetPath)) {
+		return { ok: false, error: `Worktree path already exists and cannot be reused: ${targetPath}` };
+	}
+
+	mkdirSync(worktreeRoot, { recursive: true });
+	return { ok: true, path: targetPath, reused: false };
+}
+
+export async function ensureExistingBranchWorktree(
+	pi: ExtensionAPI,
+	repoRoot: string,
+	branch: string,
+): Promise<{ ok: true; path: string; reused: boolean } | { ok: false; error: string }> {
+	if (!(await branchExists(pi, repoRoot, branch))) {
+		return { ok: false, error: `Local branch does not exist: ${branch}` };
+	}
+
+	const pathResult = await resolveWorktreePath(pi, repoRoot, branch);
+	if (!pathResult.ok) return pathResult;
+	if (pathResult.reused) return pathResult;
+
+	const addResult = await execGit(pi, repoRoot, ["worktree", "add", pathResult.path, branch]);
+	if (!addResult.ok) {
+		return { ok: false, error: addResult.error || `Failed to create worktree for branch ${branch}` };
+	}
+
+	return pathResult;
+}
+
+export async function ensureCreatedBranchWorktree(
+	pi: ExtensionAPI,
+	repoRoot: string,
+	branch: string,
+	fromRef?: string,
+): Promise<{ ok: true; path: string } | { ok: false; error: string }> {
+	if (await branchExists(pi, repoRoot, branch)) {
+		return { ok: false, error: `Branch already exists: ${branch}` };
+	}
+
+	const pathResult = await resolveWorktreePath(pi, repoRoot, branch);
+	if (!pathResult.ok) return pathResult;
+	if (pathResult.reused) {
+		return { ok: true, path: pathResult.path };
+	}
+
+	const args = ["worktree", "add", "-b", branch, pathResult.path];
+	if (fromRef?.trim()) {
+		args.push(fromRef.trim());
+	}
+	const addResult = await execGit(pi, repoRoot, args);
+	if (!addResult.ok) {
+		return { ok: false, error: addResult.error || `Failed to create branch worktree ${branch}` };
+	}
+
+	return { ok: true, path: pathResult.path };
+}

package/extensions/index.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import zvNotifyExtension from "./zv-notify.ts";
+import zvSplitExtension from "./zv-split.ts";
+import zvZoxideExtension from "./zv-zoxide.ts";
+import zvReviewExtension from "./zv-review.ts";
+import zvContinueExtension from "./zv-continue.ts";
+import zvOpenExtension from "./zv-open.ts";
+
+export default function piZellijExtensionBundle(pi: ExtensionAPI) {
+	zvNotifyExtension(pi);
+	zvSplitExtension(pi);
+	zvZoxideExtension(pi);
+	zvReviewExtension(pi);
+	zvContinueExtension(pi);
+	zvOpenExtension(pi);
+}

package/extensions/templates/handoff-same-checkout.md

@@ -0,0 +1 @@
+Continue the current task from this new pane.{{FOCUS_NOTE_SENTENCE}} Use the inherited session history and the handoff summary already present in this session. Start with the highest-priority next step.

package/extensions/templates/handoff-worktree.md

@@ -0,0 +1 @@
+Continue the current task in this git worktree for branch {{TARGET_BRANCH}}.{{FOCUS_NOTE_SENTENCE}} Use the handoff summary already present in this session. First confirm the branch and repository state in this worktree, then proceed with the highest-priority next step.