@pandi-coding-agent/pandi-kitty 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# pandi-kitty
+
+Extensión de Pi para controlar el terminal [kitty](https://sw.kovidgoyal.net/kitty/)
+en ejecución vía su protocolo de control remoto (`kitty @ ...`).
+
+## Requisitos
+
+`allow_remote_control yes` en `kitty.conf` (o `kitty -o allow_remote_control=yes`), y
+correr Pi desde una sesión de kitty en ejecución.
+
+## Comando
+
+```
+/kitty tab                 nueva tab
+/kitty window               nueva ventana (según el layout activo)
+/kitty vsplit                nueva ventana en split vertical
+/kitty hsplit                nueva ventana en split horizontal
+/kitty os-window             nueva ventana de OS
+/kitty layout <nombre>        cambia el layout activo (ej. splits, tall, fat, grid)
+/kitty close [id]             cierra una ventana (la activa si se omite el id)
+/kitty focus <id>             enfoca una ventana por id
+```
+
+## Tool
+
+`kitty_remote` — acciones `launch`, `goto-layout`, `close-window`, `focus-window`.
+Ver `index.ts` para el esquema de parámetros completo.
+
+## Nota
+
+`--location vsplit/hsplit` solo tiene efecto visible bajo el layout `splits`. Bajo
+otros layouts (`tall`, `fat`, `grid`, ...) la ventana se abre igual, pero la
+dirección del split la decide ese layout.

package/command.ts

@@ -0,0 +1,6 @@
+/** Parseo puro de `/kitty <subcomando> [args...]` en acción + tokens. */
+export function parseKittyCommand(input: string): { action: string; rest: string[] } {
+	const tokens = (input ?? "").trim().split(/\s+/).filter(Boolean);
+	const action = (tokens.shift() ?? "tab").toLowerCase();
+	return { action, rest: tokens };
+}

package/index.ts

@@ -0,0 +1,185 @@
+/**
+ * pandi-kitty: controla el terminal kitty en ejecución desde Pi vía su protocolo
+ * de control remoto (`kitty @ ...`).
+ *
+ * Dos superficies (convención del proyecto; ver pandi-worktree):
+ *   - `/kitty`         comando slash para personas (tab | window | vsplit | hsplit | layout <nombre>)
+ *   - `kitty_remote`   tool invocable por el modelo (acciones explícitas)
+ *
+ * Ambas comparten los manejadores puros de `./kitty.ts`. `kitty` siempre se invoca con
+ * un array ARGV (nunca un string de shell).
+ *
+ * Requiere `allow_remote_control yes` en kitty.conf (o `-o allow_remote_control=yes` al
+ * arrancar kitty) y correr DESDE una sesión de kitty en ejecución.
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { parseKittyCommand } from "./command.js";
+import {
+	DEFAULT_KITTY_TIMEOUT_MS,
+	type HandlerResult,
+	parseTimeoutMs,
+	runCloseWindow,
+	runFocusWindow,
+	runGotoLayout,
+	runKitty,
+	runLaunch,
+	SPLIT_LOCATIONS,
+	WINDOW_TYPES,
+} from "./kitty.js";
+import { notify } from "./notify.js";
+
+export { parseKittyCommand } from "./command.js";
+export {
+	buildCloseWindowArgs,
+	buildFocusWindowArgs,
+	buildGotoLayoutArgs,
+	buildLaunchArgs,
+	describeError,
+	runCloseWindow,
+	runFocusWindow,
+	runGotoLayout,
+	runKitty,
+	runLaunch,
+	SPLIT_LOCATIONS,
+	WINDOW_TYPES,
+} from "./kitty.js";
+
+const HELP_TEXT = [
+	"Uso:",
+	"  /kitty tab                new tab",
+	"  /kitty window              nueva ventana (según el layout activo)",
+	"  /kitty vsplit               nueva ventana en split vertical",
+	"  /kitty hsplit               nueva ventana en split horizontal",
+	"  /kitty os-window            nueva ventana de OS",
+	"  /kitty layout <nombre>       cambia el layout activo (ej. splits, tall, fat, grid)",
+	"  /kitty close [id]            cierra una ventana (la activa si se omite el id)",
+	"  /kitty focus <id>            enfoca una ventana por id",
+	"",
+	"Requiere `allow_remote_control yes` en kitty.conf y correr desde una sesión de kitty.",
+].join("\n");
+
+function buildOpts(cwd: string, signal: AbortSignal | null | undefined) {
+	return {
+		cwd,
+		signal: signal ?? undefined,
+		timeoutMs: parseTimeoutMs(process.env.PI_KITTY_TIMEOUT_MS, DEFAULT_KITTY_TIMEOUT_MS),
+	};
+}
+
+// --------------------------------------------------------------------------
+// Handler del comando
+// --------------------------------------------------------------------------
+
+async function runCommand(ctx: ExtensionContext, input: string): Promise<void> {
+	const { action, rest } = parseKittyCommand(input);
+	const opts = buildOpts(ctx.cwd, ctx.signal);
+
+	if (action === "help" || action === "-h" || action === "--help") {
+		notify(ctx, HELP_TEXT, "info");
+		return;
+	}
+
+	let result: HandlerResult;
+	switch (action) {
+		case "tab":
+			result = await runLaunch(runKitty, { type: "tab" }, opts);
+			break;
+		case "window":
+			result = await runLaunch(runKitty, { type: "window" }, opts);
+			break;
+		case "vsplit":
+			result = await runLaunch(runKitty, { type: "window", location: "vsplit" }, opts);
+			break;
+		case "hsplit":
+			result = await runLaunch(runKitty, { type: "window", location: "hsplit" }, opts);
+			break;
+		case "os-window":
+			result = await runLaunch(runKitty, { type: "os-window" }, opts);
+			break;
+		case "layout":
+			result = await runGotoLayout(runKitty, { layout: rest[0] ?? "" }, opts);
+			break;
+		case "close":
+			result = await runCloseWindow(runKitty, { matchId: rest[0] }, opts);
+			break;
+		case "focus":
+			result = await runFocusWindow(runKitty, { matchId: rest[0] ?? "" }, opts);
+			break;
+		default:
+			notify(ctx, `Subcomando desconocido: ${action}\n\n${HELP_TEXT}`, "warning");
+			return;
+	}
+	notify(ctx, result.text, result.ok ? "info" : "error");
+}
+
+// --------------------------------------------------------------------------
+// Adaptador del resultado de la tool
+// --------------------------------------------------------------------------
+
+function toToolResult(result: HandlerResult) {
+	return { content: [{ type: "text" as const, text: result.text }], details: result.details };
+}
+
+// --------------------------------------------------------------------------
+// Entrada de la extensión
+// --------------------------------------------------------------------------
+
+export default function kittyExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("kitty", {
+		description:
+			"Controlá kitty vía remote control: tab | window | vsplit | hsplit | os-window | layout | close | focus",
+		handler: async (args, ctx) => {
+			await runCommand(ctx, args);
+		},
+	});
+
+	pi.registerTool({
+		name: "kitty_remote",
+		label: "Control remoto de kitty",
+		description:
+			"Controlá el terminal kitty en ejecución vía su protocolo de control remoto (`kitty @ ...`). Acciones: 'launch' (abre tab/window/os-window nueva, opcionalmente con split vsplit/hsplit), 'goto-layout' (cambia el layout activo), 'close-window' (cierra una ventana), 'focus-window' (enfoca una ventana por id). Requiere `allow_remote_control yes` en kitty.conf y correr desde una sesión de kitty en ejecución.",
+		promptSnippet: "Controlá kitty (tabs, ventanas, splits, layout) vía su protocolo de control remoto.",
+		promptGuidelines: [
+			"Usá kitty_remote para abrir tabs/ventanas/splits de kitty o cambiar su layout en lugar de instruir al usuario a hacerlo manualmente.",
+			"Para 'launch' con type:'window', pasá location:'vsplit' o 'hsplit' para un split; el split solo se ve como tal si el layout activo es 'splits' (usá goto-layout primero si hace falta).",
+			"Si kitty_remote falla con un error de socket, es porque no hay remote control habilitado (allow_remote_control yes en kitty.conf) o no se está corriendo desde dentro de una sesión de kitty — no reintentes a ciegas, avisale al usuario.",
+		],
+		parameters: Type.Object({
+			action: StringEnum(["launch", "goto-layout", "close-window", "focus-window"] as const),
+			type: Type.Optional(StringEnum(WINDOW_TYPES, { description: "Para launch: tab | os-window | window." })),
+			location: Type.Optional(
+				StringEnum(SPLIT_LOCATIONS, { description: "Para launch con type:'window': vsplit | hsplit." }),
+			),
+			layout: Type.Optional(
+				Type.String({ description: "Para goto-layout: nombre del layout (ej. splits, tall, fat, grid)." }),
+			),
+			matchId: Type.Optional(
+				Type.String({ description: "Para close-window/focus-window: id de la ventana objetivo." }),
+			),
+		}),
+		executionMode: "sequential",
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const opts = buildOpts(ctx.cwd, signal);
+			switch (params.action) {
+				case "launch":
+					return toToolResult(
+						await runLaunch(runKitty, { type: params.type ?? "tab", location: params.location }, opts),
+					);
+				case "goto-layout":
+					return toToolResult(await runGotoLayout(runKitty, { layout: params.layout ?? "" }, opts));
+				case "close-window":
+					return toToolResult(await runCloseWindow(runKitty, { matchId: params.matchId }, opts));
+				case "focus-window":
+					return toToolResult(await runFocusWindow(runKitty, { matchId: params.matchId ?? "" }, opts));
+				default:
+					return {
+						content: [{ type: "text" as const, text: `Acción desconocida: ${params.action}` }],
+						details: { isError: true },
+					};
+			}
+		},
+	});
+}

package/kitty.ts

@@ -0,0 +1,288 @@
+/**
+ * Utilidades puras + un único punto de ejecución para la extensión pandi-kitty.
+ *
+ * kitty expone su protocolo de control remoto vía `kitty @ <subcomando>`. Solo funciona
+ * desde una sesión de kitty en ejecución con `allow_remote_control` habilitado, y habla
+ * con esa instancia por un socket local.
+ *   - `runKitty` lanza `kitty` con un array ARGV (nunca un string de shell).
+ *   - `build*Args` son constructores puros de argv (testeados exactamente).
+ *   - los manejadores `run*` reciben una fn `run` inyectada para que el despacho sea
+ *     determinista en tests sin necesitar una sesión de kitty real.
+ */
+
+import { spawn } from "node:child_process";
+
+// --------------------------------------------------------------------------
+// Punto de spawn
+// --------------------------------------------------------------------------
+
+export interface KittyResult {
+	ok: boolean;
+	stdout: string;
+	stderr: string;
+	exitCode?: number;
+	timedOut?: boolean;
+	/** Se setea cuando nunca logramos hacer spawn de `kitty` (ej. no está instalado). */
+	spawnError?: string;
+}
+
+export interface RunKittyOptions {
+	cwd?: string;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+	/** Binario a ejecutar; redefinible para que los tests apunten a un nombre garantizadamente ausente. */
+	bin?: string;
+}
+
+export const DEFAULT_KITTY_TIMEOUT_MS = 15_000;
+export const MIN_KITTY_TIMEOUT_MS = 1_000;
+
+export function parseTimeoutMs(raw: string | undefined, fallback = DEFAULT_KITTY_TIMEOUT_MS): number {
+	const n = Number(raw);
+	if (!Number.isFinite(n) || n <= 0) return fallback;
+	return Math.max(MIN_KITTY_TIMEOUT_MS, Math.floor(n));
+}
+
+/** Firma compartida por runKitty y el runner simulado inyectado en tests. */
+export type RunKitty = (args: string[], options?: RunKittyOptions) => Promise<KittyResult>;
+
+/**
+ * Hace spawn de `kitty @ ...` con un array argv. Falla de spawn, exit no cero, timeout o
+ * abort vuelven como un KittyResult (nunca lanza).
+ */
+export function runKitty(args: string[], options: RunKittyOptions = {}): Promise<KittyResult> {
+	const { cwd, signal, timeoutMs = DEFAULT_KITTY_TIMEOUT_MS, bin = "kitty" } = options;
+	return new Promise((resolve) => {
+		let stdout = "";
+		let stderr = "";
+		let settled = false;
+		let timedOut = false;
+
+		const child = spawn(bin, ["@", ...args], { cwd, windowsHide: true });
+
+		const finish = (result: KittyResult) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			if (signal) signal.removeEventListener("abort", onAbort);
+			resolve(result);
+		};
+
+		const onAbort = () => {
+			timedOut = true;
+			child.kill("SIGTERM");
+		};
+		if (signal) {
+			if (signal.aborted) onAbort();
+			else signal.addEventListener("abort", onAbort, { once: true });
+		}
+
+		const timer = setTimeout(() => {
+			timedOut = true;
+			child.kill("SIGTERM");
+		}, timeoutMs);
+
+		child.stdout?.on("data", (chunk) => {
+			stdout += chunk.toString();
+		});
+		child.stderr?.on("data", (chunk) => {
+			stderr += chunk.toString();
+		});
+		child.on("error", (err: Error) => {
+			finish({ ok: false, stdout, stderr, spawnError: err.message });
+		});
+		child.on("close", (code) => {
+			finish({ ok: !timedOut && code === 0, stdout, stderr, exitCode: code ?? undefined, timedOut });
+		});
+	});
+}
+
+// --------------------------------------------------------------------------
+// Constructores de argv (puros)
+// --------------------------------------------------------------------------
+
+export const WINDOW_TYPES = ["tab", "os-window", "window"] as const;
+export type WindowType = (typeof WINDOW_TYPES)[number];
+
+export const SPLIT_LOCATIONS = ["vsplit", "hsplit"] as const;
+export type SplitLocation = (typeof SPLIT_LOCATIONS)[number];
+
+export interface LaunchOptions {
+	type: WindowType;
+	location?: SplitLocation;
+	cwd?: string;
+}
+
+export function buildLaunchArgs(opts: LaunchOptions): string[] {
+	const args = ["launch", "--type", opts.type];
+	if (opts.location) args.push("--location", opts.location);
+	if (opts.cwd) args.push("--cwd", opts.cwd);
+	return args;
+}
+
+export function buildGotoLayoutArgs(layout: string): string[] {
+	return ["goto-layout", layout];
+}
+
+export function buildCloseWindowArgs(opts: { matchId?: string } = {}): string[] {
+	const args = ["close-window"];
+	if (opts.matchId) args.push("--match", `id:${opts.matchId}`);
+	return args;
+}
+
+export function buildFocusWindowArgs(matchId: string): string[] {
+	return ["focus-window", "--match", `id:${matchId}`];
+}
+
+// --------------------------------------------------------------------------
+// Normalización de errores
+// --------------------------------------------------------------------------
+
+const NOT_RUNNING_HINT =
+	"No se pudo hablar con kitty por el socket de control remoto. Verificá que estés dentro de una sesión de kitty y que `allow_remote_control yes` esté en kitty.conf (o iniciá kitty con -o allow_remote_control=yes).";
+
+/** Convierte un KittyResult fallido en una sola línea acotada y accionable. */
+export function describeError(result: KittyResult, action: string): string {
+	if (result.spawnError) {
+		if (/ENOENT/i.test(result.spawnError)) return "No se encontró el binario `kitty` en el PATH.";
+		return `No se pudo ejecutar \`kitty @ ${action}\`: ${result.spawnError}`;
+	}
+	if (result.timedOut) return `\`kitty @ ${action}\` agotó el tiempo de espera.`;
+	const detail = (result.stderr || result.stdout || "").trim();
+	if (/no such remote control socket|could not connect|is kitty running/i.test(detail)) return NOT_RUNNING_HINT;
+	return detail
+		? `\`kitty @ ${action}\` falló: ${detail}`
+		: `\`kitty @ ${action}\` falló (salida ${result.exitCode ?? "?"}).`;
+}
+
+// --------------------------------------------------------------------------
+// Manejadores de alto nivel (reciben un runner inyectado; por lo demás, despacho puro)
+// --------------------------------------------------------------------------
+
+export interface HandlerResult {
+	ok: boolean;
+	text: string;
+	details: Record<string, unknown>;
+}
+
+export interface HandlerOpts {
+	cwd?: string;
+	signal?: AbortSignal;
+	timeoutMs?: number;
+}
+
+function isWindowType(type: string): type is WindowType {
+	return (WINDOW_TYPES as readonly string[]).includes(type);
+}
+
+function isSplitLocation(location: string): location is SplitLocation {
+	return (SPLIT_LOCATIONS as readonly string[]).includes(location);
+}
+
+export async function runLaunch(
+	run: RunKitty,
+	params: { type: string; location?: string; cwd?: string },
+	opts: HandlerOpts,
+): Promise<HandlerResult> {
+	if (!isWindowType(params.type)) {
+		return {
+			ok: false,
+			text: `Tipo de ventana desconocido "${params.type}". Tipos válidos: ${WINDOW_TYPES.join(", ")}.`,
+			details: { isError: true, action: "launch" },
+		};
+	}
+	if (params.location && !isSplitLocation(params.location)) {
+		return {
+			ok: false,
+			text: `Ubicación de split desconocida "${params.location}". Ubicaciones válidas: ${SPLIT_LOCATIONS.join(", ")}.`,
+			details: { isError: true, action: "launch" },
+		};
+	}
+	const result = await run(
+		buildLaunchArgs({ type: params.type, location: params.location as SplitLocation | undefined, cwd: params.cwd }),
+		opts,
+	);
+	if (!result.ok) {
+		return { ok: false, text: describeError(result, "launch"), details: { isError: true, action: "launch" } };
+	}
+	const id = result.stdout.trim();
+	return {
+		ok: true,
+		text: `Se abrió ${params.type} nueva (id ${id || "?"}).`,
+		details: { action: "launch", type: params.type, location: params.location, id },
+	};
+}
+
+export async function runGotoLayout(
+	run: RunKitty,
+	params: { layout: string },
+	opts: HandlerOpts,
+): Promise<HandlerResult> {
+	if (!params.layout) {
+		return {
+			ok: false,
+			text: "goto-layout requiere un nombre de layout.",
+			details: { isError: true, action: "goto-layout" },
+		};
+	}
+	const result = await run(buildGotoLayoutArgs(params.layout), opts);
+	if (!result.ok) {
+		return {
+			ok: false,
+			text: describeError(result, "goto-layout"),
+			details: { isError: true, action: "goto-layout" },
+		};
+	}
+	return {
+		ok: true,
+		text: `Layout activo: ${params.layout}.`,
+		details: { action: "goto-layout", layout: params.layout },
+	};
+}
+
+export async function runCloseWindow(
+	run: RunKitty,
+	params: { matchId?: string },
+	opts: HandlerOpts,
+): Promise<HandlerResult> {
+	const result = await run(buildCloseWindowArgs(params), opts);
+	if (!result.ok) {
+		return {
+			ok: false,
+			text: describeError(result, "close-window"),
+			details: { isError: true, action: "close-window" },
+		};
+	}
+	return {
+		ok: true,
+		text: params.matchId ? `Se cerró la ventana ${params.matchId}.` : "Se cerró la ventana activa.",
+		details: { action: "close-window", matchId: params.matchId },
+	};
+}
+
+export async function runFocusWindow(
+	run: RunKitty,
+	params: { matchId: string },
+	opts: HandlerOpts,
+): Promise<HandlerResult> {
+	if (!params.matchId) {
+		return {
+			ok: false,
+			text: "focus-window requiere un id de ventana.",
+			details: { isError: true, action: "focus-window" },
+		};
+	}
+	const result = await run(buildFocusWindowArgs(params.matchId), opts);
+	if (!result.ok) {
+		return {
+			ok: false,
+			text: describeError(result, "focus-window"),
+			details: { isError: true, action: "focus-window" },
+		};
+	}
+	return {
+		ok: true,
+		text: `Foco en la ventana ${params.matchId}.`,
+		details: { action: "focus-window", matchId: params.matchId },
+	};
+}

package/notify.ts

@@ -0,0 +1,13 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export function notify(ctx: ExtensionContext, message: string, type: "info" | "warning" | "error" = "info"): void {
+	if (ctx.mode === "print") {
+		(type === "info" ? console.log : console.error)(message);
+		return;
+	}
+	if (ctx.hasUI) {
+		ctx.ui.notify(message, type);
+		return;
+	}
+	if (type !== "info") console.error(message);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@pandi-coding-agent/pandi-kitty",
+	"version": "0.1.0",
+	"description": "Extensión de Pi para controlar el terminal kitty vía su protocolo de control remoto: un comando /kitty y una herramienta kitty_remote invocable por el modelo (tabs, ventanas, splits, layout).",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/andrestobelem/pandi-extensions.git",
+		"directory": "extensions/pandi-kitty"
+	},
+	"type": "module",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension",
+		"kitty",
+		"terminal",
+		"remote-control"
+	],
+	"files": [
+		"index.ts",
+		"command.ts",
+		"kitty.ts",
+		"notify.ts",
+		"skills",
+		"README.md"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		],
+		"skills": [
+			"./skills"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "^0.80.3",
+		"@earendil-works/pi-coding-agent": "^0.80.3",
+		"typebox": "^1.1.38"
+	}
+}

package/skills/kitty-remote-control/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: kitty-remote-control
+description: >-
+  Controla la terminal kitty desde el shell mediante su protocolo de
+  remote-control (`kitty @ ...`): abre tabs, ventanas y splits nuevos, y
+  consulta/administra la instancia de kitty en ejecución. Usar cuando el
+  usuario pida abrir una tab o ventana nueva de kitty, dividir paneles
+  (vertical/horizontal), o scriptear kitty desde una sesión en curso. Si la
+  extensión pandi-kitty está instalada, preferí su comando `/kitty` o la tool
+  `kitty_remote` antes que shell ad hoc.
+---
+
+# Control remoto de kitty
+
+kitty trae un protocolo de remote-control manejado por el subcomando
+`kitty @`. Habla con la instancia de kitty *actualmente en ejecución* a
+través de un socket de control, así que solo funciona desde dentro de una
+sesión kitty que tenga el remote control habilitado. 🐼
+
+## Prerequisito
+
+El remote control tiene que estar permitido. Revisá/habilitalo en `kitty.conf`:
+
+```
+allow_remote_control yes
+```
+
+O iniciá kitty con `-o allow_remote_control=yes`. Sin esto, todo comando
+`kitty @ ...` falla con un error de socket/permisos.
+
+## Comandos principales
+
+```bash
+# Tab nueva en la ventana actual
+kitty @ launch --type=tab
+
+# Ventana de OS nueva
+kitty @ launch --type=os-window
+
+# Ventana nueva en la tab actual (usa el layout activo)
+kitty @ launch --type=window
+
+# Split vertical (solo tiene efecto bajo el layout `splits`)
+kitty @ launch --type=window --location=vsplit
+
+# Split horizontal
+kitty @ launch --type=window --location=hsplit
+
+# Forzar el layout splits primero si el layout activo no es splits
+kitty @ goto-layout splits
+```
+
+Cada llamada a `launch` imprime el id de la tab/ventana nueva si tiene éxito
+(p. ej. `2`), que se puede usar con otros subcomandos de `kitty @`
+(`focus-window`, `close-window`, `send-text`, etc.) para apuntarle con
+precisión.
+
+## Trampas
+
+- `--location=vsplit`/`hsplit` solo tiene efecto visible bajo el layout
+  `splits`. Bajo `tall`, `fat`, `grid`, etc. la ventana nueva igual se abre,
+  pero la dirección del split la decide ese layout en su lugar.
+- Todos los comandos `kitty @` son no-ops desde fuera de kitty (por ejemplo,
+  desde un script desacoplado o una terminal distinta) — necesitan que el
+  socket de un proceso kitty vivo sea alcanzable, lo cual normalmente
+  significa correr desde un shell dentro de esa instancia kitty.
+- `--type=window` sin `--location` simplemente usa lo que el layout actual
+  haga con una ventana nueva (puede no verse como un "split" en absoluto).
+
+## Integración en Pi
+
+En este repo, `extensions/pandi-kitty/` envuelve estos comandos como paquete
+standalone:
+
+- comando `/kitty` para personas (`tab`, `window`, `vsplit`, `hsplit`,
+  `os-window`, `layout`, `close`, `focus`)
+- tool `kitty_remote` para el modelo, con acciones `launch`, `goto-layout`,
+  `close-window` y `focus-window`
+
+Usá la extensión cuando esté disponible; reservá `kitty @ ...` directo para
+casos de diagnóstico o cuando la extensión no esté instalada.