@balanza/pi-codetour 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Emanuele
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @balanza/pi-codetour
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [pi](https://github.com/earendil-works/pi) extension that turns the agent into
+a **guided code tour**: when you ask how something works, pi can open an editor
+in a terminal split and point it at the exact file/line it is talking about,
+while you browse an interactive list of the relevant spots.
+
+## How it works
+
+```
+you ask a question
+      │
+      ▼
+pi calls the `code_tour` tool with a list of "stops"
+      │
+      ▼
+extension splits the terminal (wezterm → tmux) and launches an editor (nvim)
+      │
+      ▼
+you get an interactive list of stops; moving the cursor drives the editor
+```
+
+- **Split**: the bigger dimension of the pi pane is split, so a wide terminal
+  splits side-by-side and a tall terminal splits top/bottom.
+- **Multiplexer**: WezTerm if available, otherwise tmux.
+- **Editor**: Neovim (LazyVim), driven over a `--listen` socket and opened
+  **read-only** (`-R` + `:view`) since this is a navigation pane. The editor
+  layer is abstracted so more editors can be added later.
+- **Lifecycle**: the editor pane is created on the first tour and **closed when
+  you quit the tour**; the next tour reopens a fresh one.
+
+## Install
+
+```bash
+pi install npm:@balanza/pi-codetour
+```
+
+## Usage
+
+Or load it directly during development:
+
+```bash
+pi --extension ~/pi-codetour/index.ts
+```
+
+Then just ask the agent to explain part of the codebase. When it wants to show
+you code it will open the tour. Navigate with `↑`/`↓` (the editor follows),
+`enter` to focus the editor pane, `esc`/`q` to return to the chat (which also
+closes the editor pane).
+
+Re-open the most recent tour any time with `/codetour`.
+
+## Development
+
+```bash
+npm run lint        # Biome lint + format check
+npm run format      # apply Biome fixes
+npm test            # node:test suite over the pi-free engine
+npm run typecheck   # tsc --noEmit (needs the pi host packages present)
+```
+
+CI (`.github/workflows/ci.yml`) runs lint, tests, and typecheck on every push
+and pull request. The pure engine (`src/terminal.ts`, `src/editor.ts`) has no
+pi imports and is unit-tested directly; `index.ts` and `src/tour-ui.ts` are the
+pi adapter layer and are covered by the typecheck step.
+
+## Releasing
+
+Publishing to npm is automated by `.github/workflows/release.yml`, which runs on
+any pushed `v*.*.*` tag. One-time setup:
+
+Authentication uses [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers/)
+(OIDC), so **no npm token is stored anywhere**. One-time setup:
+
+1. Publish the first version manually, because a trusted publisher can only be
+   configured on a package that already exists:
+   ```bash
+   npm login && npm publish
+   ```
+2. On npmjs.com: **Packages → @balanza/pi-codetour → Settings → Trusted
+   Publisher → GitHub Actions**, with organization `balanza`, repository
+   `pi-codetour`, workflow filename `release.yml`, and the **npm publish**
+   action allowed. Fields are case-sensitive and are *not* validated on save.
+   The configuration expires if no publish succeeds within 2 days.
+3. Keep `repository.url` in `package.json` matching this repo exactly — npm
+   rejects OIDC publishes otherwise.
+4. Once a CI publish has succeeded, harden it: **Settings → Publishing access →
+   "Require two-factor authentication and disallow tokens"**.
+
+Provenance is generated automatically for OIDC publishes, so no `--provenance`
+flag is needed. The workflow pins Node 24 because trusted publishing requires
+npm ≥ 11.5.1, which Node 22 does not ship.
+
+Then cut a release. The version is derived from the conventional commits made
+since the last `v*` tag:
+
+- any **breaking change** (`type!:` or a `BREAKING CHANGE:` footer) → major
+- otherwise any **`feat`** → minor
+- otherwise → patch
+
+```bash
+npm run version:next     # print the next version without changing anything
+npm run version:next -- --json   # same, as JSON
+npm run release          # bump package.json + create the vX.Y.Z commit & tag
+git push --follow-tags   # the Release workflow publishes the matching version
+```
+
+The `--json` form prints the full decision as one compact line, so it pipes
+directly into `jq`:
+
+```bash
+$ npm run version:next -- --json | jq -r .nextVersion
+0.2.0
+```
+
+```json
+{"lastVersion":"0.1.0","nextVersion":"0.2.0","numCommits":13,"bump":"minor","source":"package.json","lastTag":null}
+```
+
+(The project `.npmrc` sets `loglevel=silent` so npm's `> pkg@version script`
+banner stays off stdout; CI overrides it with `NPM_CONFIG_LOGLEVEL=notice`.)
+
+`bump` is `null` when there are no commits since the last tag (then
+`nextVersion` equals `lastVersion`).
+
+The workflow re-runs lint/test/typecheck, verifies the tag matches
+`package.json` version, publishes with `--access public`, and creates a GitHub
+release for the tag with auto-generated notes and the npm tarball attached.

package/index.ts

@@ -0,0 +1,133 @@
+/**
+ * codetour — a pi extension that guides you through a codebase.
+ *
+ * The agent calls the `code_tour` tool with a list of stops (file + line +
+ * explanation). The extension splits the terminal, opens an editor (nvim) in
+ * the new pane, and shows you an interactive list; moving the cursor drives the
+ * editor to the matching spot. `/codetour` re-opens the most recent tour.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { EditorPane } from "./src/session.js";
+import { runTourUI } from "./src/tour-ui.js";
+import type { Tour } from "./src/types.js";
+
+const StopSchema = Type.Object({
+  file: Type.String({ description: "File path, absolute or relative to the codebase root." }),
+  line: Type.Number({ description: "1-based line the editor should land on." }),
+  endLine: Type.Optional(
+    Type.Number({ description: "Last line of a range to highlight, when relevant." }),
+  ),
+  label: Type.String({
+    description: "Very short label for the list, e.g. 'entry point' or 'the reducer'.",
+  }),
+  detail: Type.String({
+    description:
+      "One short paragraph explaining what to look at here and why it matters to the question.",
+  }),
+});
+
+const TourParams = Type.Object({
+  title: Type.String({ description: "What question this tour answers, as a short title." }),
+  overview: Type.Optional(
+    Type.String({ description: "Optional one-paragraph overview shown above the list." }),
+  ),
+  stops: Type.Array(StopSchema, {
+    minItems: 1,
+    description: "Ordered stops that walk the user through the relevant code.",
+  }),
+});
+
+function tourToText(tour: Tour): string {
+  const lines = [`Code tour: ${tour.title}`];
+  if (tour.overview) lines.push("", tour.overview);
+  lines.push("");
+  tour.stops.forEach((s, i) => {
+    lines.push(`${i + 1}. ${s.label} — ${s.file}:${s.line}`);
+    lines.push(`   ${s.detail}`);
+  });
+  return lines.join("\n");
+}
+
+export default function codetour(pi: ExtensionAPI) {
+  // Session-scoped editor pane and the last tour shown, for /codetour.
+  let pane: EditorPane | null = null;
+  let lastTour: Tour | null = null;
+
+  pi.on("session_shutdown", () => {
+    pane?.dispose();
+    pane = null;
+  });
+
+  const getPane = (ctx: ExtensionContext): EditorPane => {
+    if (!pane) pane = new EditorPane({ dir: ctx.cwd });
+    return pane;
+  };
+
+  async function present(ctx: ExtensionContext, tour: Tour): Promise<string> {
+    lastTour = tour;
+
+    if (ctx.mode !== "tui" || !ctx.hasUI) {
+      return `Guided tour is only interactive in the terminal UI. Stops:\n\n${tourToText(tour)}`;
+    }
+    if (!EditorPane.supported()) {
+      ctx.ui.notify("codetour: no wezterm/tmux detected — showing stops inline.", "warning");
+      return `No terminal multiplexer (wezterm/tmux) available to split, so no editor pane was opened. Present these stops to the user yourself:\n\n${tourToText(tour)}`;
+    }
+
+    const ready = await getPane(ctx).ensure();
+    if (!ready) {
+      ctx.ui.notify("codetour: could not open the editor pane.", "error");
+      return `Failed to open the editor pane. Present these stops to the user yourself:\n\n${tourToText(tour)}`;
+    }
+
+    const result = await runTourUI(ctx, getPane(ctx), tour);
+
+    // Quitting the tour tears the editor pane down too; the next tour reopens it.
+    pane?.dispose();
+    pane = null;
+
+    const ended = result.lastIndex >= 0 ? tour.stops[result.lastIndex] : undefined;
+    return [
+      `The user browsed the "${tour.title}" tour (${tour.stops.length} stops) in the editor pane.`,
+      ended
+        ? `They ended on stop ${result.lastIndex + 1}: ${ended.label} (${ended.file}:${ended.line}).`
+        : "",
+      "Continue the conversation; ask if they want more detail on any stop.",
+    ]
+      .filter(Boolean)
+      .join(" ");
+  }
+
+  pi.registerTool({
+    name: "code_tour",
+    label: "Code tour",
+    description:
+      "Guide the user through the codebase. Opens an editor beside the chat and shows an " +
+      "interactive, selectable list of 'stops' (file + line + explanation); as the user moves " +
+      "through the list the editor jumps to each spot. Use this instead of pasting long code " +
+      "excerpts when explaining how something works. Provide a focused, ordered set of stops; " +
+      "each `detail` should be one short paragraph tying that location to the user's question.",
+    parameters: TourParams,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+      const tour = params as Tour;
+      const text = await present(ctx, tour);
+      return {
+        content: [{ type: "text", text }],
+        details: { title: tour.title, stops: tour.stops.length },
+      };
+    },
+  });
+
+  pi.registerCommand("codetour", {
+    description: "Re-open the most recent code tour",
+    handler: async (_args, ctx) => {
+      if (!lastTour) {
+        ctx.ui.notify("codetour: no tour yet — ask the agent to explain some code first.", "info");
+        return;
+      }
+      await present(ctx, lastTour);
+    },
+  });
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@balanza/pi-codetour",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "type": "module",
+  "license": "MIT",
+  "description": "A pi extension that guides you through a codebase by driving an editor in a terminal split.",
+  "main": "index.ts",
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/balanza/pi-codetour.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "node --import tsx --test test/*.test.ts",
+    "version:next": "node scripts/next-version.mjs",
+    "release": "node scripts/next-version.mjs --apply"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^26.6.4",
+    "tsx": "^4.23.15",
+    "typescript": "^5.6.3"
+  }
+}

package/src/editor.ts

@@ -0,0 +1,130 @@
+/**
+ * Editor abstraction.
+ *
+ * An EditorDriver knows how to (1) produce the shell command that launches the
+ * editor inside the split pane in a remotely-controllable way, (2) wait until
+ * that editor is ready, and (3) jump to a file/line on demand. Only Neovim is
+ * implemented today, but the interface keeps room for more editors.
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export interface EditorDriver {
+  /** Human-readable editor name. */
+  readonly name: string;
+  /** Shell command to launch the editor inside the split pane. */
+  launchCommand(opts: { dir: string }): string;
+  /** Resolve true once the editor accepts remote commands, or false on timeout. */
+  waitReady(timeoutMs: number): Promise<boolean>;
+  /** Jump to `file` at `line` (1-based); select through `endLine` when given. */
+  goto(file: string, line: number, endLine?: number): void;
+  /** Release any resources (sockets, temp files). Never throws. */
+  dispose(): void;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Drives Neovim over a `--listen` socket. Works with any distro (LazyVim
+ * included) because it talks to the running server rather than sending keys
+ * through the multiplexer, so it is independent of the editor's current mode.
+ */
+export interface EditorDriverOptions {
+  /** Open files read-only (this is a navigation pane, not an editing one). */
+  readonly?: boolean;
+}
+
+export class NvimDriver implements EditorDriver {
+  readonly name = "nvim";
+  private readonly sock: string;
+  private readonly readonly: boolean;
+
+  constructor(opts: EditorDriverOptions = {}) {
+    this.readonly = opts.readonly ?? true;
+    this.sock = path.join(os.tmpdir(), `codetour-nvim-${process.pid}-${Date.now()}.sock`);
+  }
+
+  launchCommand(_opts: { dir: string }): string {
+    // `-R` starts nvim in read-only mode; the socket is how goto reaches it.
+    return `nvim ${this.readonly ? "-R " : ""}--listen ${this.sock}`;
+  }
+
+  async waitReady(timeoutMs: number): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (fs.existsSync(this.sock)) {
+        // Socket file exists; give nvim a beat to start serving on it.
+        try {
+          this.expr("1");
+          return true;
+        } catch {
+          /* not accepting yet */
+        }
+      }
+      await sleep(100);
+    }
+    return false;
+  }
+
+  goto(file: string, line: number, endLine?: number): void {
+    this.remoteSend(nvimGotoKeys(path.resolve(file), line, endLine, this.readonly));
+  }
+
+  dispose(): void {
+    try {
+      fs.rmSync(this.sock, { force: true });
+    } catch {
+      /* best-effort */
+    }
+  }
+
+  private remoteSend(keys: string): void {
+    execFileSync("nvim", ["--server", this.sock, "--remote-send", keys], { stdio: "ignore" });
+  }
+
+  private expr(expr: string): string {
+    return execFileSync("nvim", ["--server", this.sock, "--remote-expr", expr], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  }
+}
+
+/**
+ * Build the `--remote-send` key sequence that drives nvim to a file/line.
+ * Pure (no I/O) so it can be unit-tested without spawning an editor.
+ *
+ * `<C-\><C-n>` forces normal mode first so the Ex command always lands. `:view`
+ * opens read-only, `:edit` otherwise. With an `endLine`, the range is visually
+ * selected and the view recentred on its start.
+ */
+export function nvimGotoKeys(
+  absPath: string,
+  line: number,
+  endLine: number | undefined,
+  readonly: boolean,
+): string {
+  const safe = absPath.replace(/ /g, "\\ ");
+  const open = readonly ? "view" : "edit";
+  const start = Math.max(1, Math.floor(line));
+  let keys = `<C-\\><C-n>:${open} +${start} ${safe}<CR>zz`;
+  if (endLine && endLine > start) {
+    const span = Math.floor(endLine) - start;
+    keys += `V${span}j${start}G<C-\\><C-n>zz`;
+  }
+  return keys;
+}
+
+/** Resolve an editor driver by name. Defaults to nvim. */
+export function createEditorDriver(name = "nvim", opts: EditorDriverOptions = {}): EditorDriver {
+  switch (name) {
+    case "nvim":
+      return new NvimDriver(opts);
+    default:
+      throw new Error(`Unsupported editor: ${name}`);
+  }
+}

package/src/session.ts

@@ -0,0 +1,126 @@
+import { type EditorDriver, createEditorDriver } from "./editor.js";
+/**
+ * Ties the multiplexer and editor together into a single reusable "editor pane"
+ * for the lifetime of a pi session. The pane is created lazily on the first
+ * tour and reused afterwards; it is torn down on session shutdown.
+ */
+import {
+  type Mux,
+  closePane,
+  detectMux,
+  focusPane,
+  isLandscape,
+  openSplit,
+  paneAlive,
+  paneSize,
+} from "./terminal.js";
+
+export interface EditorPaneOptions {
+  /** Codebase root; the editor opens here. */
+  dir: string;
+  /** Editor name (currently only "nvim"). */
+  editor?: string;
+  /** Share of space the editor pane takes when first created (0..1). */
+  fraction?: number;
+  /** Open files read-only when the editor supports it. Default true. */
+  readonly?: boolean;
+}
+
+export class EditorPane {
+  private mux: Mux | null = null;
+  private selfPaneId: string | null = null;
+  private editorPaneId: string | null = null;
+  private driver: EditorDriver | null = null;
+  private readonly dir: string;
+  private readonly editorName: string;
+  private readonly fraction: number;
+  private readonly readonly: boolean;
+
+  constructor(opts: EditorPaneOptions) {
+    this.dir = opts.dir;
+    this.editorName = opts.editor ?? "nvim";
+    this.fraction = opts.fraction ?? 0.5;
+    this.readonly = opts.readonly ?? true;
+  }
+
+  /** True if the host terminal supports splitting at all. */
+  static supported(): boolean {
+    return detectMux() !== null;
+  }
+
+  get muxName(): Mux | null {
+    return this.mux;
+  }
+
+  /**
+   * Ensure a live editor pane exists, creating it if needed. Returns true if an
+   * editor pane is ready to receive goto commands.
+   */
+  async ensure(): Promise<boolean> {
+    if (this.editorPaneId && this.mux && paneAlive(this.mux, this.editorPaneId) && this.driver) {
+      return true;
+    }
+    // Stale pane (user closed it) — reset before recreating.
+    this.resetPane();
+
+    const host = detectMux();
+    if (!host) return false;
+    this.mux = host.mux;
+    this.selfPaneId = host.paneId;
+
+    // Orient the split along the bigger physical dimension of the pi pane.
+    const size = paneSize(host.mux, host.paneId);
+    const sideBySide = size ? isLandscape(size) : true;
+
+    this.driver = createEditorDriver(this.editorName, { readonly: this.readonly });
+    const split = openSplit({
+      mux: host.mux,
+      fromPaneId: host.paneId,
+      dir: this.dir,
+      command: this.driver.launchCommand({ dir: this.dir }),
+      sideBySide,
+      fraction: this.fraction,
+    });
+    this.editorPaneId = split.paneId;
+
+    const ready = await this.driver.waitReady(10_000);
+    if (!ready) {
+      this.dispose();
+      return false;
+    }
+    // Keep keyboard focus on the pi pane so the user stays in the list.
+    if (this.selfPaneId) focusPane(host.mux, this.selfPaneId);
+    return true;
+  }
+
+  /** Point the editor at a file/line. No-op if the pane is not ready. */
+  goto(file: string, line: number, endLine?: number): void {
+    this.driver?.goto(file, line, endLine);
+  }
+
+  /** Move keyboard focus into the editor pane. */
+  focusEditor(): void {
+    if (this.mux && this.editorPaneId) focusPane(this.mux, this.editorPaneId);
+  }
+
+  /** Move keyboard focus back to the pi pane. */
+  focusSelf(): void {
+    if (this.mux && this.selfPaneId) focusPane(this.mux, this.selfPaneId);
+  }
+
+  private resetPane(): void {
+    if (this.mux && this.editorPaneId && paneAlive(this.mux, this.editorPaneId)) {
+      closePane(this.mux, this.editorPaneId);
+    }
+    this.driver?.dispose();
+    this.driver = null;
+    this.editorPaneId = null;
+  }
+
+  /** Close the pane and release resources. Idempotent. */
+  dispose(): void {
+    this.resetPane();
+    this.mux = null;
+    this.selfPaneId = null;
+  }
+}

package/src/terminal.ts

@@ -0,0 +1,192 @@
+/**
+ * Terminal multiplexer layer.
+ *
+ * Creates a split pane in the active multiplexer and runs a command there, and
+ * reports pane geometry so a caller can orient the split along the bigger
+ * dimension. WezTerm is preferred; tmux is the fallback.
+ *
+ * Adapted from ~/pr-reviewer/src/terminal.ts.
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+
+export type Mux = "wezterm" | "tmux";
+
+export interface SplitResult {
+  /** Which multiplexer created the pane. */
+  mux: Mux;
+  /** Pane id, used to address the pane later (resize, close, drive editor). */
+  paneId: string;
+}
+
+export interface PaneSize {
+  cols: number;
+  rows: number;
+  /** True pixel dimensions, when the multiplexer reports them. */
+  pixelWidth?: number;
+  pixelHeight?: number;
+}
+
+function weztermBin(): string {
+  const app = "/Applications/WezTerm.app/Contents/MacOS/wezterm";
+  return fs.existsSync(app) ? app : "wezterm";
+}
+
+/** The multiplexer the pi TUI is currently running inside, or null. */
+export function detectMux(): { mux: Mux; paneId: string } | null {
+  // Prefer WezTerm (richer split API) when we are inside it.
+  if (process.env.WEZTERM_PANE) {
+    return { mux: "wezterm", paneId: process.env.WEZTERM_PANE };
+  }
+  if (process.env.TMUX) {
+    try {
+      const id = execFileSync("tmux", ["display-message", "-p", "#{pane_id}"], {
+        encoding: "utf8",
+      }).trim();
+      if (id) return { mux: "tmux", paneId: id };
+    } catch {
+      /* fall through */
+    }
+  }
+  return null;
+}
+
+/**
+ * Open a split pane next to `fromPaneId` and run `command` there.
+ *
+ * `sideBySide` true splits the width (panes left/right); false stacks them
+ * (panes top/bottom). `fraction` is the share of space the NEW pane takes.
+ */
+export function openSplit(opts: {
+  mux: Mux;
+  fromPaneId: string;
+  dir: string;
+  command: string;
+  sideBySide: boolean;
+  fraction?: number;
+}): SplitResult {
+  const { mux, fromPaneId, dir, command, sideBySide } = opts;
+  const percent = Math.round((opts.fraction ?? 0.5) * 100);
+
+  if (mux === "wezterm") {
+    const out = execFileSync(
+      weztermBin(),
+      [
+        "cli",
+        "split-pane",
+        sideBySide ? "--right" : "--bottom",
+        "--pane-id",
+        fromPaneId,
+        "--percent",
+        String(percent),
+        "--cwd",
+        dir,
+        "--",
+        "/bin/sh",
+        "-c",
+        command,
+      ],
+      { encoding: "utf8" },
+    );
+    return { mux, paneId: out.trim() };
+  }
+
+  // tmux: -h = side-by-side, -v = stacked.
+  const out = execFileSync(
+    "tmux",
+    [
+      "split-window",
+      sideBySide ? "-h" : "-v",
+      "-t",
+      fromPaneId,
+      "-p",
+      String(percent),
+      "-P",
+      "-F",
+      "#{pane_id}",
+      "-c",
+      dir,
+      command,
+    ],
+    { encoding: "utf8" },
+  );
+  return { mux, paneId: out.trim() };
+}
+
+/** Pane size in character cells (plus pixels for WezTerm), or null. */
+export function paneSize(mux: Mux, paneId: string): PaneSize | null {
+  try {
+    if (mux === "tmux") {
+      const out = execFileSync(
+        "tmux",
+        ["display-message", "-p", "-t", paneId, "#{pane_width} #{pane_height}"],
+        { encoding: "utf8" },
+      );
+      const [c, r] = out.trim().split(/\s+/).map(Number);
+      if (Number.isFinite(c) && Number.isFinite(r)) return { cols: c, rows: r };
+      return null;
+    }
+    const out = execFileSync(weztermBin(), ["cli", "list", "--format", "json"], {
+      encoding: "utf8",
+    });
+    const panes = JSON.parse(out) as Array<{
+      pane_id: number;
+      size?: { cols: number; rows: number; pixel_width?: number; pixel_height?: number };
+    }>;
+    const p = panes.find((x) => x.pane_id === Number(paneId));
+    if (p?.size && Number.isFinite(p.size.cols) && Number.isFinite(p.size.rows)) {
+      return {
+        cols: p.size.cols,
+        rows: p.size.rows,
+        pixelWidth: Number.isFinite(p.size.pixel_width) ? p.size.pixel_width : undefined,
+        pixelHeight: Number.isFinite(p.size.pixel_height) ? p.size.pixel_height : undefined,
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** True if the pane's physical width is larger than its physical height. */
+export function isLandscape(size: PaneSize): boolean {
+  if (size.pixelWidth && size.pixelHeight) {
+    return size.pixelWidth >= size.pixelHeight;
+  }
+  // A text cell is roughly twice as tall as it is wide, so approximate the
+  // physical aspect ratio from cells.
+  return size.cols >= size.rows * 2;
+}
+
+/** Give a pane keyboard focus (best-effort). */
+export function focusPane(mux: Mux, paneId: string): void {
+  try {
+    if (mux === "wezterm") {
+      execFileSync(weztermBin(), ["cli", "activate-pane", "--pane-id", paneId], {
+        stdio: "ignore",
+      });
+    } else {
+      execFileSync("tmux", ["select-pane", "-t", paneId], { stdio: "ignore" });
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** True if the pane still exists. */
+export function paneAlive(mux: Mux, paneId: string): boolean {
+  return paneSize(mux, paneId) !== null;
+}
+
+/** Close a pane by id (best-effort, never throws). */
+export function closePane(mux: Mux, paneId: string): void {
+  try {
+    if (mux === "wezterm") {
+      execFileSync(weztermBin(), ["cli", "kill-pane", "--pane-id", paneId], { stdio: "ignore" });
+    } else {
+      execFileSync("tmux", ["kill-pane", "-t", paneId], { stdio: "ignore" });
+    }
+  } catch {
+    /* already gone */
+  }
+}

package/src/tour-ui.ts

@@ -0,0 +1,145 @@
+/**
+ * The interactive tour list shown inside pi. It renders the stops as a
+ * selectable list; moving the cursor drives the editor pane to the matching
+ * file/line. Enter focuses the editor pane, esc/q returns to the chat.
+ */
+import { DynamicBorder, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  type SelectItem,
+  SelectList,
+  Text,
+  matchesKey,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import type { EditorPane } from "./session.js";
+import type { Tour, TourStop } from "./types.js";
+
+/** Result of running the tour UI. */
+export interface TourUIResult {
+  /** Index the user last looked at, or -1 if none. */
+  lastIndex: number;
+  /** How the user left the tour. */
+  reason: "closed" | "no-editor";
+}
+
+function stopItem(stop: TourStop, index: number): SelectItem {
+  const loc = `${stop.file}:${stop.line}`;
+  return {
+    value: String(index),
+    label: `${index + 1}. ${stop.label}`,
+    description: loc,
+  };
+}
+
+/**
+ * Show the tour list and block until the user leaves it. Each cursor move
+ * sends the corresponding stop to `pane`.
+ */
+export async function runTourUI(
+  ctx: ExtensionContext,
+  pane: EditorPane,
+  tour: Tour,
+): Promise<TourUIResult> {
+  const items = tour.stops.map(stopItem);
+  let lastIndex = -1;
+
+  const drive = (index: number) => {
+    const stop = tour.stops[index];
+    if (!stop) return;
+    lastIndex = index;
+    pane.goto(stop.file, stop.line, stop.endLine);
+  };
+
+  const result = await ctx.ui.custom<TourUIResult>((tui, theme, _kb, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(` Code tour — ${tour.title}`))));
+
+    // Overview paragraph (wrapped), when provided.
+    const overview = new Text("");
+    container.addChild(overview);
+
+    const list = new SelectList(items, Math.min(items.length, 12), {
+      selectedPrefix: (t) => theme.fg("accent", t),
+      selectedText: (t) => theme.fg("accent", t),
+      description: (t) => theme.fg("muted", t),
+      scrollInfo: (t) => theme.fg("dim", t),
+      noMatch: (t) => theme.fg("warning", t),
+    });
+
+    // Per-stop detail shown below the list, kept in sync with the cursor.
+    const detail = new Text("");
+    const renderDetail = (index: number, width: number) => {
+      const stop = tour.stops[index];
+      if (!stop) {
+        detail.setText("");
+        return;
+      }
+      const head = theme.fg("accent", `${stop.file}:${stop.line}`);
+      const body = wrapTextWithAnsi(stop.detail, Math.max(10, width - 2))
+        .map((l) => theme.fg("text", l))
+        .join("\n");
+      detail.setText(`${head}\n${body}`);
+    };
+
+    list.onSelectionChange = (item) => {
+      const index = Number(item.value);
+      drive(index);
+      renderDetail(index, lastWidth);
+      container.invalidate();
+      tui.requestRender();
+    };
+    // Enter: jump there and hand keyboard focus to the editor.
+    list.onSelect = (item) => {
+      drive(Number(item.value));
+      pane.focusEditor();
+      tui.requestRender();
+    };
+    list.onCancel = () => done({ lastIndex, reason: "closed" });
+
+    container.addChild(list);
+    container.addChild(detail);
+    container.addChild(
+      new Text(theme.fg("dim", " ↑↓ browse · enter focus editor · esc/q back to chat")),
+    );
+    container.addChild(new DynamicBorder((s) => theme.fg("accent", s)));
+
+    // Drive the first stop immediately.
+    drive(0);
+
+    let lastWidth = 80;
+    renderDetail(0, lastWidth);
+
+    return {
+      render(width: number) {
+        lastWidth = width;
+        if (tour.overview) {
+          overview.setText(
+            wrapTextWithAnsi(tour.overview, Math.max(10, width - 2))
+              .map((l) => theme.fg("muted", l))
+              .join("\n"),
+          );
+        } else {
+          overview.setText("");
+        }
+        return container.render(width);
+      },
+      invalidate() {
+        container.invalidate();
+      },
+      handleInput(data: string) {
+        if (matchesKey(data, "q")) {
+          done({ lastIndex, reason: "closed" });
+          return;
+        }
+        list.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+
+  // Keep the cursor back in the chat after the tour closes.
+  pane.focusSelf();
+  return result;
+}

package/src/types.ts

@@ -0,0 +1,22 @@
+/** A single stop on a guided code tour. */
+export interface TourStop {
+  /** File path, absolute or relative to the codebase root. */
+  file: string;
+  /** 1-based line the editor should land on. */
+  line: number;
+  /** Optional last line of a range to highlight. */
+  endLine?: number;
+  /** Short label shown in the list (e.g. "entry point", "the reducer"). */
+  label: string;
+  /** Longer explanation of what to look at here and why it matters. */
+  detail: string;
+}
+
+/** A guided tour: an ordered set of stops with an overall framing. */
+export interface Tour {
+  /** Title of the whole tour (what question it answers). */
+  title: string;
+  /** Optional one-paragraph overview shown above the list. */
+  overview?: string;
+  stops: TourStop[];
+}