pi-zellij 0.3.1 → 0.4.6

package/CHANGELOG.md

@@ -5,11 +5,6 @@
 ### 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.
@@ -18,3 +13,16 @@
 - 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>`.
+- Added opt-in `paneHighlight` settings so Pi can tint the current zellij pane when an agent turn completes, with optional working-state colors.
+
+### Changed
+
+- When zellij reports created pane or tab IDs, `pi-zellij` now shows them in success notifications for split, floating, zoxide, review, continuation, and tab commands.
+- `/zt` now uses `zellij action new-tab -- <command>` when available instead of always simulating typed input, while keeping the previous typed-input path as a compatibility fallback.
+- Pane highlights now clear on the next submitted input or when the pane is focused again after being elsewhere, instead of waiting for the next agent start event. Aborted runs no longer apply the done-state tint.
+- Pane focus polling no longer writes transient zellij query timeout warnings into the Pi editor; refocus-based clearing is skipped if focus state cannot be queried reliably.
+- Done-state pane tint is now only applied while the Pi pane is unfocused, so the editor is reset immediately instead of staying green while typing in the active pane.
+
+### Removed
+
+- Removed the bundled `zv-notify` extension so `pi-zellij` does not conflict with separate notification packages or user-specific notification setups.

package/README.md

@@ -1,12 +1,16 @@
 # pi-zellij
 
-Pi package with zellij-powered terminal integrations for [Pi](https://pi.dev).
+Pi package with [zellij](https://zellij.dev)-powered terminal integrations for [Pi](https://pi.dev). Make your workflow agent driven.
+
+## Workflow
+
+![pi-zellij workflow](assets/workflow.gif)
 
 ## 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.
+[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.
 
-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.
+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
 
@@ -33,9 +37,13 @@ If pi is already running, use:
 - `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
+
+### 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
 
@@ -52,6 +60,8 @@ If pi is already running, use:
 
 - `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
 
@@ -64,17 +74,12 @@ If pi is already running, use:
 - `/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-highlight`
 - `zv-zoxide`
 - `zv-review`
 - `zv-continue`
@@ -159,7 +164,9 @@ Examples:
 /zg
 ```
 
-For commands that should accept extra arguments, use the object form:
+For commands that should accept extra arguments, use the object form.
+
+Helix and lazygit example:
 
 ```json
 {
@@ -169,22 +176,75 @@ For commands that should accept extra arguments, use the object form:
         "run": "hx",
         "acceptArgs": true,
         "description": "Open Helix in a floating pane"
+      },
+      "zg": {
+        "run": "lazygit",
+        "description": "Open lazygit in a floating pane"
       }
     }
   }
 }
 ```
 
-Then you can pass arguments through to the configured command:
+Then you can use:
 
 ```text
+/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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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>`
@@ -273,24 +333,3 @@ Examples:
 
 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

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { basename, dirname, join } from "node:path";
 import { existsSync, mkdirSync } from "node:fs";
 

package/extensions/index.ts

@@ -1,16 +1,16 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import zvNotifyExtension from "./zv-notify.ts";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 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";
+import zvHighlightExtension from "./zv-highlight.ts";
 
 export default function piZellijExtensionBundle(pi: ExtensionAPI) {
-	zvNotifyExtension(pi);
 	zvSplitExtension(pi);
 	zvZoxideExtension(pi);
 	zvReviewExtension(pi);
 	zvContinueExtension(pi);
 	zvOpenExtension(pi);
+	zvHighlightExtension(pi);
 }

package/extensions/zv-continue.ts

@@ -1,10 +1,12 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { SessionManager, type ExtensionAPI, type ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { SessionManager, type ExtensionAPI, type ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import {
 	buildPiCommand,
+	formatPaneSuccessMessage,
 	openCommandInNewSplit,
+	type PaneOpenResult,
 	type SplitDirection,
 } from "./zv-core.ts";
 import {
@@ -388,7 +390,7 @@ async function openContinueSplit(
 	ctx: ExtensionCommandContext,
 	direction: SplitDirection,
 	request: ContinueRequest,
-): Promise<{ ok: true } | { ok: false; error: string }> {
+): Promise<PaneOpenResult> {
 	const handoffTarget = await resolveHandoffTarget(pi, ctx, request);
 	if (!handoffTarget.ok) {
 		return handoffTarget;
@@ -422,7 +424,7 @@ function registerContinueCommand(
 
 			const result = await openContinueSplit(pi, ctx, direction, parsed.request);
 			if (result.ok) {
-				ctx.ui.notify(successMessage, "info");
+				ctx.ui.notify(formatPaneSuccessMessage(successMessage, result.paneId), "info");
 			} else {
 				ctx.ui.notify(`continuation split failed: ${result.error}`, "error");
 			}

package/extensions/zv-core.ts

@@ -1,8 +1,10 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const ZELLIJ_TIMEOUT_MS = 5000;
 
 export type SplitDirection = "right" | "down";
+export type PaneOpenResult = { ok: true; paneId?: string } | { ok: false; error: string };
+export type TabOpenResult = { ok: true; tabId?: string } | { ok: false; error: string };
 
 interface ZellijExecResult {
 	ok: boolean;
@@ -11,10 +13,49 @@ interface ZellijExecResult {
 	error?: string;
 }
 
-function isInsideZellijSession(): boolean {
+export function isInsideZellijSession(): boolean {
 	return Boolean(process.env.ZELLIJ || process.env.ZELLIJ_SESSION_NAME || process.env.ZELLIJ_PANE_ID);
 }
 
+function getLastNonEmptyLine(value: string): string | undefined {
+	const lines = value
+		.split(/\r?\n/)
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0);
+	return lines.length > 0 ? lines[lines.length - 1] : undefined;
+}
+
+function normalizePaneId(value: string): string | undefined {
+	const trimmed = value.trim();
+	if (!trimmed) {
+		return undefined;
+	}
+	if (/^(?:terminal|plugin)_\d+$/.test(trimmed)) {
+		return trimmed;
+	}
+	if (/^\d+$/.test(trimmed)) {
+		return `terminal_${trimmed}`;
+	}
+	return undefined;
+}
+
+function getCreatedPaneId(stdout: string): string | undefined {
+	return normalizePaneId(getLastNonEmptyLine(stdout) ?? "");
+}
+
+function getCreatedTabId(stdout: string): string | undefined {
+	const candidate = getLastNonEmptyLine(stdout);
+	return candidate && /^\d+$/.test(candidate) ? candidate : undefined;
+}
+
+export function formatPaneSuccessMessage(message: string, paneId?: string): string {
+	return paneId ? `${message} (${paneId})` : message;
+}
+
+export function formatTabSuccessMessage(message: string, tabId?: string): string {
+	return tabId ? `${message} (tab ${tabId})` : message;
+}
+
 export function shellEscape(value: string): string {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -60,11 +101,88 @@ async function execZellij(pi: ExtensionAPI, args: string[]): Promise<ZellijExecR
 	};
 }
 
+function getCurrentPaneTargetArgs(): string[] {
+	return process.env.ZELLIJ_PANE_ID ? ["-p", process.env.ZELLIJ_PANE_ID] : [];
+}
+
+export async function resetCurrentPaneColor(pi: ExtensionAPI): Promise<{ ok: true } | { ok: false; error: string }> {
+	if (!isInsideZellijSession()) {
+		return { ok: false, error: "This command must be run from inside an active zellij session" };
+	}
+
+	const result = await execZellij(pi, ["action", "set-pane-color", ...getCurrentPaneTargetArgs(), "--reset"]);
+	if (!result.ok) {
+		return { ok: false, error: result.error || "Failed to reset zellij pane color" };
+	}
+
+	return { ok: true };
+}
+
+export async function setCurrentPaneColor(
+	pi: ExtensionAPI,
+	options: { bg?: string; fg?: string },
+): Promise<{ ok: true } | { ok: false; error: string }> {
+	if (!isInsideZellijSession()) {
+		return { ok: false, error: "This command must be run from inside an active zellij session" };
+	}
+
+	const paneTargetArgs = getCurrentPaneTargetArgs();
+	const args = ["action", "set-pane-color", ...paneTargetArgs];
+	if (options.bg) {
+		args.push("--bg", options.bg);
+	}
+	if (options.fg) {
+		args.push("--fg", options.fg);
+	}
+	if (args.length === 2 + paneTargetArgs.length) {
+		return resetCurrentPaneColor(pi);
+	}
+
+	const result = await execZellij(pi, args);
+	if (!result.ok) {
+		return { ok: false, error: result.error || "Failed to set zellij pane color" };
+	}
+
+	return { ok: true };
+}
+
+function buildNewTabArgs(cwd: string, options?: { name?: string }): string[] {
+	const args = ["action", "new-tab", "--cwd", cwd];
+	if (options?.name) {
+		args.push("--name", options.name);
+	}
+	return args;
+}
+
+async function openCommandInNewTabLegacy(
+	pi: ExtensionAPI,
+	cwd: string,
+	command: string,
+	options?: { name?: string },
+): Promise<TabOpenResult> {
+	const newTabResult = await execZellij(pi, buildNewTabArgs(cwd, options));
+	if (!newTabResult.ok) {
+		return { ok: false, error: newTabResult.error || "Failed to open a new zellij tab" };
+	}
+
+	const writeCommandResult = await execZellij(pi, ["action", "write-chars", command]);
+	if (!writeCommandResult.ok) {
+		return { ok: false, error: writeCommandResult.error || "Failed to write command to new zellij tab" };
+	}
+
+	const submitCommandResult = await execZellij(pi, ["action", "write", "10"]);
+	if (!submitCommandResult.ok) {
+		return { ok: false, error: submitCommandResult.error || "Failed to start command in new zellij tab" };
+	}
+
+	return { ok: true, tabId: getCreatedTabId(newTabResult.stdout) };
+}
+
 export async function openCommandInNewSplit(
 	pi: ExtensionAPI,
 	direction: SplitDirection,
 	command: string,
-): Promise<{ ok: true } | { ok: false; error: string }> {
+): Promise<PaneOpenResult> {
 	if (!isInsideZellijSession()) {
 		return { ok: false, error: "This command must be run from inside an active zellij session" };
 	}
@@ -74,14 +192,14 @@ export async function openCommandInNewSplit(
 		return { ok: false, error: result.error || "Failed to open a new zellij pane" };
 	}
 
-	return { ok: true };
+	return { ok: true, paneId: getCreatedPaneId(result.stdout) };
 }
 
 export async function openCommandInFloatingPane(
 	pi: ExtensionAPI,
 	command: string,
 	options?: { name?: string; width?: string; height?: string; x?: string; y?: string },
-): Promise<{ ok: true } | { ok: false; error: string }> {
+): Promise<PaneOpenResult> {
 	if (!isInsideZellijSession()) {
 		return { ok: false, error: "This command must be run from inside an active zellij session" };
 	}
@@ -99,7 +217,7 @@ export async function openCommandInFloatingPane(
 		return { ok: false, error: result.error || "Failed to open a new floating zellij pane" };
 	}
 
-	return { ok: true };
+	return { ok: true, paneId: getCreatedPaneId(result.stdout) };
 }
 
 export async function openCommandInNewTab(
@@ -107,30 +225,15 @@ export async function openCommandInNewTab(
 	cwd: string,
 	command: string,
 	options?: { name?: string },
-): Promise<{ ok: true } | { ok: false; error: string }> {
+): Promise<TabOpenResult> {
 	if (!isInsideZellijSession()) {
 		return { ok: false, error: "This command must be run from inside an active zellij session" };
 	}
 
-	const newTabArgs = ["action", "new-tab", "--cwd", cwd];
-	if (options?.name) {
-		newTabArgs.push("--name", options.name);
-	}
-
-	const newTabResult = await execZellij(pi, newTabArgs);
-	if (!newTabResult.ok) {
-		return { ok: false, error: newTabResult.error || "Failed to open a new zellij tab" };
-	}
-
-	const writeCommandResult = await execZellij(pi, ["action", "write-chars", command]);
-	if (!writeCommandResult.ok) {
-		return { ok: false, error: writeCommandResult.error || "Failed to write command to new zellij tab" };
+	const newTabResult = await execZellij(pi, [...buildNewTabArgs(cwd, options), "--", "sh", "-lc", command]);
+	if (newTabResult.ok) {
+		return { ok: true, tabId: getCreatedTabId(newTabResult.stdout) };
 	}
 
-	const submitCommandResult = await execZellij(pi, ["action", "write", "10"]);
-	if (!submitCommandResult.ok) {
-		return { ok: false, error: submitCommandResult.error || "Failed to start command in new zellij tab" };
-	}
-
-	return { ok: true };
+	return openCommandInNewTabLegacy(pi, cwd, command, options);
 }