pi-zellij 0.4.0 → 0.4.8

package/CHANGELOG.md

@@ -13,6 +13,20 @@
 - 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.
+- Added an agent-facing `zellij_open_terminal` tool so Pi can open explicitly requested interactive terminal commands in right or lower splits, tabs, and floating panes.
+- Added an agent-facing `zellij_start_pi` tool for fresh Pi sessions in right or lower splits and tabs, with optional initial prompts, model settings, pane titles, and explicit history inheritance through a separate cloned session.
+
+### Changed
+
+- Explicit history inheritance now rejects branches with no conversation messages before creating a cloned session or opening a pane.
+- Expanded `zellij_open_terminal` prompt guidance so agents recognize requests to start another Pi session and prefer the dedicated `zellij_start_pi` interface when available.
+- Pi launch command construction now supports quoted provider, model, and thinking options and stops option parsing before initial prompts.
+- 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
 

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.
 
-It includes split and tab commands, generic tool launchers, settings-driven floating app shortcuts, zoxide jumps, review workflows, and split-based task handoff.
+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
 
@@ -34,6 +38,13 @@ If pi is already running, use:
 - 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
@@ -49,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
 
@@ -66,6 +79,7 @@ If pi is already running, use:
 Extensions:
 - `zv-split`
 - `zv-open`
+- `zv-highlight`
 - `zv-zoxide`
 - `zv-review`
 - `zv-continue`
@@ -118,6 +132,29 @@ Examples:
 
 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:
+
+```text
+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`.
@@ -184,6 +221,53 @@ Configured command names cannot reuse built-in Pi commands such as `/settings`,
 
 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>`

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,9 +1,10 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+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) {
 	zvSplitExtension(pi);
@@ -11,4 +12,5 @@ export default function piZellijExtensionBundle(pi: ExtensionAPI) {
 	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,19 @@
-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 PiThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export type PaneOpenResult = { ok: true; paneId?: string } | { ok: false; error: string };
+export type TabOpenResult = { ok: true; tabId?: string } | { ok: false; error: string };
+
+export interface PiCommandOptions {
+	sessionFile?: string;
+	prompt?: string;
+	provider?: string;
+	model?: string;
+	thinking?: PiThinkingLevel;
+}
 
 interface ZellijExecResult {
 	ok: boolean;
@@ -11,22 +22,70 @@ 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, `'\\''`)}'`;
 }
 
-export function buildPiCommand(cwd: string, options?: { sessionFile?: string; prompt?: string }): string {
+export function buildPiCommand(cwd: string, options?: PiCommandOptions): string {
 	const commandParts = ["cd", shellEscape(cwd), "&&", "exec", "pi"];
 	if (options?.sessionFile) {
 		commandParts.push("--session", shellEscape(options.sessionFile));
 	}
+	if (options?.provider) {
+		commandParts.push("--provider", shellEscape(options.provider));
+	}
+	if (options?.model) {
+		commandParts.push("--model", shellEscape(options.model));
+	}
+	if (options?.thinking) {
+		commandParts.push("--thinking", shellEscape(options.thinking));
+	}
 	const prompt = options?.prompt?.trim();
 	if (prompt) {
-		commandParts.push(shellEscape(prompt));
+		commandParts.push("--", shellEscape(prompt));
 	}
 	return commandParts.join(" ");
 }
@@ -60,28 +119,110 @@ 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 }> {
+	options?: { name?: string },
+): Promise<PaneOpenResult> {
 	if (!isInsideZellijSession()) {
 		return { ok: false, error: "This command must be run from inside an active zellij session" };
 	}
 
-	const result = await execZellij(pi, ["run", "--direction", direction, "--", "sh", "-lc", command]);
+	const args = ["run", "--direction", direction];
+	if (options?.name) args.push("--name", options.name);
+	args.push("--", "sh", "-lc", command);
+
+	const result = await execZellij(pi, args);
 	if (!result.ok) {
 		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 +240,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 +248,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 submitCommandResult = await execZellij(pi, ["action", "write", "10"]);
-	if (!submitCommandResult.ok) {
-		return { ok: false, error: submitCommandResult.error || "Failed to start command in new zellij tab" };
+	const newTabResult = await execZellij(pi, [...buildNewTabArgs(cwd, options), "--", "sh", "-lc", command]);
+	if (newTabResult.ok) {
+		return { ok: true, tabId: getCreatedTabId(newTabResult.stdout) };
 	}
 
-	return { ok: true };
+	return openCommandInNewTabLegacy(pi, cwd, command, options);
 }