From 9b103871b9a903093c9bf79ad36547b313d631d5 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Fri, 13 Mar 2026 09:49:46 -0700
Subject: [PATCH] feat: add help command to browse server

Agents that don't have SKILL.md loaded (or misread flags) had no way to
self-discover the CLI. The help command returns a formatted reference of
all commands and snapshot flags.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 browse/src/server.ts | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/browse/src/server.ts b/browse/src/server.ts
index 0825b176..85dc413b 100644
--- a/browse/src/server.ts
+++ b/browse/src/server.ts
@@ -124,7 +124,7 @@ export const META_COMMANDS = new Set([
   'tabs', 'tab', 'newtab', 'closetab',
   'status', 'stop', 'restart',
   'screenshot', 'pdf', 'responsive',
-  'chain', 'diff',
+  'chain', 'diff', 'help',
   'url', 'snapshot',
 ]);
 
@@ -201,6 +201,34 @@ async function handleCommand(body: any): Promise<Response> {
       result = await handleWriteCommand(command, args, browserManager);
     } else if (META_COMMANDS.has(command)) {
       result = await handleMetaCommand(command, args, browserManager, shutdown);
+    } else if (command === 'help') {
+      const helpText = [
+        'gstack browse — headless browser for AI agents',
+        '',
+        'Commands:',
+        '  Navigation:    goto <url>, back, forward, reload',
+        '  Interaction:   click <sel>, fill <sel> <text>, select <sel> <val>, hover, type, press, scroll, wait',
+        '  Read:          text [sel], html [sel], links, forms, accessibility, cookies, storage, console, network, perf',
+        '  Evaluate:      js <expr>, eval <expr>, css <sel> <prop>, attrs <sel>, is <sel> <state>',
+        '  Snapshot:      snapshot [-i] [-c] [-d N] [-s sel] [-D] [-a] [-o path] [-C]',
+        '  Screenshot:    screenshot [path], pdf [path], responsive <widths>',
+        '  Tabs:          tabs, tab <id>, newtab [url], closetab [id]',
+        '  State:         cookie <set|get|clear>, cookie-import <json>, cookie-import-browser [browser]',
+        '  Headers:       header <set|clear> [name] [value], useragent [string]',
+        '  Upload:        upload <sel> <file1> [file2...]',
+        '  Dialogs:       dialog, dialog-accept [text], dialog-dismiss',
+        '  Meta:          status, stop, restart, diff, chain, help',
+        '',
+        'Snapshot flags:',
+        '  -i  interactive only    -c  compact (remove empty nodes)',
+        '  -d N  limit depth       -s sel  scope to CSS selector',
+        '  -D  diff vs previous    -a  annotated screenshot with ref labels',
+        '  -o path  output file    -C  cursor-interactive elements',
+      ].join('\n');
+      return new Response(helpText, {
+        status: 200,
+        headers: { 'Content-Type': 'text/plain' },
+      });
     } else {
       return new Response(JSON.stringify({
         error: `Unknown command: ${command}`,