pathnote 0.2.0 → 0.2.1

package/README.md

@@ -31,7 +31,7 @@ Quit Claude Desktop first (⌘Q). It rewrites its config file while running, so
 }
 ```
 
-Open Claude Desktop again, open http://127.0.0.1:4747 in your browser, and ask Claude something like:
+Open Claude Desktop again and ask Claude something like the line below. The map opens in your browser as soon as Claude starts looking (http://127.0.0.1:4747).
 
 > Go through the meeting notes and customer interviews and write next quarter's priorities as a new note.
 
@@ -48,6 +48,7 @@ Use the same command: `npx -y pathnote <folder> [<folder> ...]`.
 ## The viewer
 
 - http://127.0.0.1:4747 (the next free port if 4747 is taken; the address is printed to the client's MCP log).
+- It opens in your browser by itself the first time the AI uses Pathnote, unless a viewer page is already open. Add `--no-open` (or set `PATHNOTE_NO_OPEN=1`) to turn that off.
 - Drag to move, scroll to zoom. File names appear as you zoom in.
 - Several AI sessions on the same folders all report to one viewer.
 - To keep the viewer open while clients come and go: `npx pathnote <folders> --viewer`.

package/bin/pathnote.js

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-// pathnote <folder> [<folder> ...] [--port 4747] [--viewer]
+// pathnote <folder> [<folder> ...] [--port 4747] [--viewer] [--no-open]
 // pathnote --sample <new folder>   copies the sample notes there, to try Pathnote safely
 //   Started by an MCP client: MCP over stdin/stdout, plus the viewer at http://127.0.0.1:4747
 //   --viewer: only the viewer, for keeping it open while MCP clients come and go
+//   --no-open (or PATHNOTE_NO_OPEN=1): don't open the viewer in the browser when the AI starts working
 // stdout belongs to MCP, so every message for people goes to stderr.
 import fs from 'node:fs';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { Workspace } from '../src/workspace.js';
 import { History } from '../src/history.js';
-import { Hub } from '../src/hub.js';
+import { Hub, openBrowser } from '../src/hub.js';
 import { createServer } from '../src/mcp.js';
 
 const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url)));
@@ -26,7 +27,7 @@ if (flag('--sample')) {
   process.exit(0);
 }
 if (!folder || flag('--help')) {
-  console.error(`Pathnote ${pkg.version}\n\nUsage: pathnote <folder> [<folder> ...] [--port 4747] [--viewer]\n       pathnote --sample <new folder>`);
+  console.error(`Pathnote ${pkg.version}\n\nUsage: pathnote <folder> [<folder> ...] [--port 4747] [--viewer] [--no-open]\n       pathnote --sample <new folder>`);
   process.exit(folder ? 0 : 1);
 }
 for (const f of folders) {
@@ -38,7 +39,8 @@ for (const f of folders) {
 
 const ws = new Workspace(folders);
 const history = new History(ws);
-const hub = new Hub(ws, history, Number(opt('--port')) || 4747);
+const noOpen = flag('--no-open') || process.env.PATHNOTE_NO_OPEN === '1';
+const hub = new Hub(ws, history, Number(opt('--port')) || 4747, { open: noOpen ? null : openBrowser });
 const url = await hub.start();
 console.error(`Pathnote ${pkg.version}: ${ws.roots.join(', ')}\nViewer: ${url}`);
 ws.warm().catch(() => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pathnote",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "See which files your AI searched, read and wrote, live on a map of your folders. MCP server + local viewer.",
   "keywords": [
     "mcp",

package/src/hub.js

@@ -2,6 +2,7 @@
 // Claude Desktop may start several Pathnote processes; the first one for a set of folders owns the
 // viewer port and the others forward their events to it.
 import http from 'node:http';
+import { spawn } from 'node:child_process';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -10,8 +11,11 @@ const PAGE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'view
 const KEEP = 500;
 
 export class Hub {
-  constructor(ws, history, port) {
+  // open: called with the viewer URL the first time the AI does something while no viewer page is
+  // connected, so the map shows up without the user looking for it. null turns this off.
+  constructor(ws, history, port, { open = null } = {}) {
     this.ws = ws;
+    this.open = open;
     this.history = history;
     this.port = port;
     this.events = [];
@@ -81,6 +85,12 @@ export class Hub {
     this.events.push(e);
     if (this.events.length > KEEP) this.events.shift();
     for (const res of this.clients) res.write(`data: ${JSON.stringify(e)}\n\n`);
+    // Once per process: a page left open from an earlier run reconnects by itself, so it counts
+    if (this.open && this.clients.size === 0) {
+      const open = this.open;
+      this.open = null;
+      open(`http://127.0.0.1:${this.port}`);
+    }
   }
 
   // Only pages served from this port may call the API, so other websites can't trigger undo.
@@ -102,6 +112,7 @@ export class Hub {
     if (req.method === 'GET' && url.pathname === '/api/graph') return send(res, 200, await this.ws.graph());
     if (req.method === 'GET' && url.pathname === '/api/events') {
       res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+      res.flushHeaders(); // the page counts as connected before the first event
       for (const e of this.events) res.write(`data: ${JSON.stringify(e)}\n\n`);
       this.clients.add(res);
       req.on('close', () => this.clients.delete(res));
@@ -125,6 +136,18 @@ export class Hub {
   }
 }
 
+// Opens a URL in the default browser. Errors are ignored: the URL is also in the client's MCP log.
+export function openBrowser(url) {
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => {});
+    child.unref();
+  } catch {}
+}
+
 function send(res, status, data) {
   res.writeHead(status, { 'Content-Type': 'application/json' });
   res.end(JSON.stringify(data));