pi-link 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -6,6 +6,16 @@ This changelog is based on the git history from `2026-03-21` (initial commit) th
 
 ---
 
+## 0.1.9 — 2026-04-22
+
+### Added
+
+- **`--link-name <name>` flag.** Connect to link with a chosen terminal name on startup. Implies `--link` (no need for both). Persists the name and sets the Pi session name if currently unnamed. Name precedence: `--link-name` > saved `/link-name` > session name > random `t-xxxx`.
+
+- **`pi-link start` CLI.** New bin script (`bin/pi-link.mjs`) for session-by-name resume. `pi-link start worker-1` scans `~/.pi/agent/sessions/` for a matching session name — one match resumes it, no match creates a new session, multiple matches prints candidates and exits. Extra Pi flags pass through: `pi-link start worker-1 --model sonnet --thinking high`. Local-cwd sessions prioritized.
+
+---
+
 ## 0.1.8 — 2026-04-16
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 A WebSocket-based inter-terminal communication system that creates a local network between multiple Pi coding agent terminals. Enables terminals to discover each other, exchange messages, and orchestrate work across agents - all automatically on `localhost`.
 
-> Self-contained TypeScript in a single `index.ts` file. Start Pi with `--link` to enable.
+> Self-contained TypeScript in a single `index.ts` file. Start Pi with `--link` or `--link-name <name>` to enable.
 
 ---
 
@@ -57,16 +57,23 @@ pi uninstall npm:pi-link
 
 ### Usage
 
-Link is **off by default**. Start Pi with the `--link` flag to auto-connect on startup:
+Link is **off by default**. Start Pi with `--link-name` to connect with a meaningful name:
 
 ```
 Terminal 1                            Terminal 2
 ----------                            ----------
-$ pi --link                           $ pi --link
-✓ Link hub started on :9900 as "t-a1b2"  ✓ Joined link as "t-c3d4" (2 online)
+$ pi --link-name builder              $ pi --link-name reviewer
+✓ Link hub started on :9900 as "builder"  ✓ Joined link as "reviewer" (2 online)
 ```
 
-Already in a session without `--link`? You can connect mid-session with `/link-connect`.
+Or use `pi-link start` to resume an existing session by name (or create one):
+
+```bash
+pi-link start worker-1                # resume or create session "worker-1"
+pi-link start worker-1 --model sonnet # with extra Pi flags
+```
+
+`pi --link` also works (connects with an auto-generated name). Already in a session without either flag? Connect mid-session with `/link-connect`.
 
 Use `/link` in any terminal to check status, or let the LLM tools handle cross-terminal coordination.
 
@@ -124,18 +131,41 @@ Every other terminal sees:
 
 ## Configuration
 
-Link is **off by default**. Without `--link`, the extension is completely silent - no status bar, no connections, no warnings.
+Link is **off by default**. Without `--link` or `--link-name`, the extension is completely silent — no status bar, no connections, no warnings.
 
-| Method             | When                                | Auto-reconnect?                  |
-| ------------------ | ----------------------------------- | -------------------------------- |
-| `pi --link`        | Auto-connect on startup             | Yes                              |
-| `/link-connect`    | Opt-in mid-session (no flag needed) | Yes                              |
-| `/link-disconnect` | Opt-out mid-session                 | Suppressed until `/link-connect` |
+| Method                  | When                                | Auto-reconnect?                  |
+| ----------------------- | ----------------------------------- | -------------------------------- |
+| `pi --link-name <name>` | Connect on startup with a name      | Yes                              |
+| `pi --link`             | Connect on startup (random name)    | Yes                              |
+| `pi-link start <name>`  | Resume/create session, connect      | Yes                              |
+| `/link-connect`         | Opt-in mid-session (no flag needed) | Yes                              |
+| `/link-disconnect`      | Opt-out mid-session                 | Suppressed until `/link-connect` |
 
-`/link-connect` enables full participation in Pi Link regardless of whether `--link` was passed. Both `/link-connect` and `/link-disconnect` save their intent to the session - resume that session later and the connection state is restored without needing the flag. Explicit user intent takes precedence over `--link`.
+`--link-name` implies `--link` — no need for both. It also persists the name and sets the Pi session name if the session is currently unnamed.
+
+**Name precedence:** `--link-name` flag > saved `/link-name` > Pi session name > random `t-xxxx`.
+
+`/link-connect` and `/link-disconnect` save their intent to the session — resume later and the connection state is restored without needing the flag. Explicit user intent takes precedence over `--link`.
 
 Once connected, terminals discover each other on `127.0.0.1:9900`. See [Limitations](#limitations--design-decisions) for the hardcoded port.
 
+### `pi-link start`
+
+The `pi-link` CLI resolves sessions by display name:
+
+```bash
+pi-link start <name> [pi-flags...]
+```
+
+- Scans `~/.pi/agent/sessions/` for sessions with a matching name
+- **One match** → resumes that session with `--link-name <name>`
+- **No match** → starts a new session with `--link-name <name>`
+- **Multiple matches** → prints candidates (cwd, modified date, path) and exits
+- Extra Pi flags pass through: `pi-link start worker-1 --model sonnet --thinking high`
+- `--session` and `--link-name` cannot be passed as extra flags (managed by `pi-link start`)
+
+Sessions in the current working directory are prioritized when sorting candidates.
+
 ---
 
 ## LLM Tools
@@ -293,7 +323,7 @@ The network topology is **hub-spoke (star)**:
 
 ### Auto-Discovery Protocol
 
-The discovery sequence runs on startup (with `--link`) or when `/link-connect` is used. See [Configuration](#configuration) for details.
+The discovery sequence runs on startup (with `--link` or `--link-name`) or when `/link-connect` is used. See [Configuration](#configuration) for details.
 
 The sequence is a simple fallback:
 
@@ -377,6 +407,9 @@ When the hub goes down and a client promotes itself, terminal names and in-fligh
 ```json
 {
   "name": "pi-link",
+  "bin": {
+    "pi-link": "./bin/pi-link.mjs"
+  },
   "dependencies": {
     "ws": "^8.20.0"
   },
@@ -390,7 +423,7 @@ When the hub goes down and a client promotes itself, terminal names and in-fligh
 }
 ```
 
-The `pi.extensions` field tells Pi which files to load as extensions. `pi.skills` registers bundled skill directories - the `pi-link-coordination` skill is loaded automatically on install.
+`pi.extensions` tells Pi which files to load as extensions. `pi.skills` registers bundled skill directories. `bin` exposes the `pi-link` CLI (see [Configuration](#configuration)).
 
 ---
 
@@ -529,11 +562,11 @@ The flush pipeline:
 
 1. **Debounce** - `scheduleFlush(FLUSH_DELAY_MS)` coalesces burst arrivals (200ms window).
 2. **Idle gate** - `flushInbox()` checks `ctx.isIdle()`. If busy, retries every 500ms.
-3. **Batch** — up to 20 messages or ~16 000 chars per delivery (soft cap — the first item is always included even if oversized).
-4. **Deliver** — one `pi.sendMessage({ triggerTurn: true })` call with a `[Link: N message(s) received]` block.
-5. **Drain** — if the inbox still has items, reschedule.
+3. **Batch** - up to 20 messages or ~16 000 chars per delivery (soft cap - the first item is always included even if oversized).
+4. **Deliver** - one `pi.sendMessage({ triggerTurn: true })` call with a `[Link: N message(s) received]` block.
+5. **Drain** - if the inbox still has items, reschedule.
 
-On `agent_end`, the inbox flush is kicked via `scheduleFlush(0)` — deferred to the next macrotask, by which time `ctx.isIdle()` returns `true`.
+On `agent_end`, the inbox flush is kicked via `scheduleFlush(0)` - deferred to the next macrotask, by which time `ctx.isIdle()` returns `true`.
 
 | Constant          | Value  | Purpose                                  |
 | ----------------- | ------ | ---------------------------------------- |

package/bin/pi-link.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+// pi-link CLI — resolve session by name and launch Pi with --link-name
+//
+// Usage:
+//   pi-link start <name> [pi-flags...]
+//
+// If a session named <name> exists, resumes it.
+// If not, creates a new session.
+// Always connects to the link as <name>.
+
+import { readdir, stat } from "fs/promises";
+import { createReadStream } from "fs";
+import { createInterface } from "readline";
+import { join } from "path";
+import { homedir } from "os";
+import { spawn } from "child_process";
+
+const SESSIONS_DIR = join(homedir(), ".pi", "agent", "sessions");
+
+// ── Session scanning ───────────────────────────────────────────────────────
+
+async function getSessionName(filePath) {
+  let name;
+  let cwd;
+  const rl = createInterface({ input: createReadStream(filePath, "utf-8"), crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (!line) continue;
+    try {
+      const entry = JSON.parse(line);
+      if (entry.type === "session" && entry.cwd) cwd = entry.cwd;
+      if (entry.type === "session_info" && entry.name !== undefined) {
+        name = entry.name?.trim() || undefined;
+      }
+    } catch {
+      // skip malformed lines
+    }
+  }
+  return { name, cwd };
+}
+
+async function findSessionsByName(targetName) {
+  let cwdDirs;
+  try {
+    cwdDirs = await readdir(SESSIONS_DIR, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const matches = [];
+
+  for (const dir of cwdDirs) {
+    if (!dir.isDirectory()) continue;
+    const dirPath = join(SESSIONS_DIR, dir.name);
+
+    let files;
+    try {
+      files = await readdir(dirPath);
+    } catch {
+      continue;
+    }
+
+    for (const file of files) {
+      if (!file.endsWith(".jsonl")) continue;
+      const filePath = join(dirPath, file);
+      try {
+        const { name, cwd } = await getSessionName(filePath);
+        if (name === targetName) {
+          const stats = await stat(filePath);
+          matches.push({ path: filePath, cwd: cwd || "?", modified: stats.mtime });
+        }
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  // Local-first: current cwd matches before others, then by modified time
+  const localCwd = process.cwd();
+  matches.sort((a, b) => {
+    const aLocal = a.cwd === localCwd ? 1 : 0;
+    const bLocal = b.cwd === localCwd ? 1 : 0;
+    if (aLocal !== bLocal) return bLocal - aLocal;
+    return b.modified.getTime() - a.modified.getTime();
+  });
+  return matches;
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command !== "start" || args.length < 2) {
+  console.log(`Usage: pi-link start <name> [pi-flags...]
+
+Start Pi connected to the link as <name>.
+Resumes a session named <name> if one exists, otherwise creates a new session.
+
+Examples:
+  pi-link start worker-1
+  pi-link start worker-1 --model sonnet
+  pi-link start worker-1 --model sonnet --thinking high`);
+  process.exit(command === "start" ? 1 : 0);
+}
+
+const name = args[1].trim().replace(/\s+/g, " ");
+if (!name) {
+  console.error("Error: name cannot be empty.");
+  process.exit(1);
+}
+
+const extraFlags = args.slice(2);
+for (const flag of ["--session", "--link-name"]) {
+  if (extraFlags.includes(flag)) {
+    console.error(`Error: ${flag} is managed by pi-link start. Remove it.`);
+    process.exit(1);
+  }
+}
+
+console.log(`Searching for session "${name}"...`);
+const matches = await findSessionsByName(name);
+
+const piArgs = [];
+
+if (matches.length === 1) {
+  console.log(`Resuming session: ${matches[0].path}`);
+  piArgs.push("--session", matches[0].path);
+} else if (matches.length > 1) {
+  console.error(`\nMultiple sessions named "${name}":\n`);
+  for (const m of matches) {
+    console.error(`  ${m.modified.toISOString().slice(0, 19)}  cwd: ${m.cwd}`);
+    console.error(`  ${m.path}\n`);
+  }
+  console.error(`Use pi --session <path> --link-name ${name} to pick one.`);
+  process.exit(1);
+} else {
+  console.log("No existing session found. Starting new session.");
+}
+
+piArgs.push("--link-name", name, ...extraFlags);
+
+// On Windows, resolve 'pi' through the shell so .cmd/.ps1 shims work
+const isWin = process.platform === "win32";
+const cmd = isWin ? "cmd" : "pi";
+const cmdArgs = isWin ? ["/c", "pi", ...piArgs] : piArgs;
+
+const child = spawn(cmd, cmdArgs, { stdio: "inherit" });
+
+child.on("exit", (code) => process.exit(code ?? 0));
+child.on("error", (err) => {
+  console.error(`Failed to start pi: ${err.message}`);
+  process.exit(1);
+});

package/index.ts

@@ -2,7 +2,7 @@
  * Pi Link — WebSocket-based inter-terminal communication
  *
  * Connects multiple Pi terminals over a local WebSocket link.
- * Opt-in via --link flag or /link-connect command.
+ * Opt-in via --link / --link-name flag or /link-connect command.
  * First terminal to connect becomes the hub; others join as clients.
  * Hub loss triggers automatic promotion of a surviving client.
  *
@@ -115,6 +115,11 @@ export default function (pi: ExtensionAPI) {
     default: false,
   });
 
+  pi.registerFlag("link-name", {
+    description: "Connect to link with this terminal name",
+    type: "string",
+  });
+
   // ── State ────────────────────────────────────────────────────────────────
 
   let role: "hub" | "client" | "disconnected" = "disconnected";
@@ -853,25 +858,35 @@ export default function (pi: ExtensionAPI) {
     ctx = _ctx;
     currentCwd = _ctx.cwd;
 
-    // Restore preferred link name from session
-    const saved = _ctx.sessionManager
-      .getEntries()
-      .filter(
-        (e: { type: string; customType?: string }) =>
-          e.type === "custom" && e.customType === "link-name",
-      )
-      .pop() as { data?: { name?: string } } | undefined;
-    if (saved?.data?.name) {
-      preferredName = saved.data.name;
-      terminalName = preferredName;
+    // Resolve terminal name: --link-name flag > saved link-name > session name > random
+    const rawLinkName = pi.getFlag("link-name");
+    const flagName =
+      typeof rawLinkName === "string"
+        ? rawLinkName.trim().replace(/\s+/g, " ") || undefined
+        : undefined;
+    if (flagName) {
+      preferredName = flagName;
+      terminalName = flagName;
+      pi.appendEntry("link-name", { name: flagName });
+      if (!pi.getSessionName()) pi.setSessionName(flagName);
     } else {
-      // No explicit link-name: fall back to session name as a better default than t-xxxx
-      const sessionName = pi.getSessionName()?.trim().replace(/\s+/g, " ");
-      if (sessionName) terminalName = sessionName;
-      // NOT saved as preferredName — only /link-name persists
+      const saved = _ctx.sessionManager
+        .getEntries()
+        .filter(
+          (e: { type: string; customType?: string }) =>
+            e.type === "custom" && e.customType === "link-name",
+        )
+        .pop() as { data?: { name?: string } } | undefined;
+      if (saved?.data?.name) {
+        preferredName = saved.data.name;
+        terminalName = preferredName;
+      } else {
+        const sessionName = pi.getSessionName()?.trim().replace(/\s+/g, " ");
+        if (sessionName) terminalName = sessionName;
+      }
     }
 
-    if (shouldConnect(_ctx)) await initialize();
+    if (flagName || shouldConnect(_ctx)) await initialize();
   });
 
   pi.on("session_shutdown", async () => {

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "pi-link",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
   "author": "alvivar",
   "license": "MIT",
+  "bin": {
+    "pi-link": "./bin/pi-link.mjs"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/alvivar/pi-link"
+    "url": "git+https://github.com/alvivar/pi-link.git"
   },
   "keywords": [
     "pi-package",