Architecture

Three source files under src/, all consumed by src/index.ts's main(context) which calls withConfigSchematics and withToolsProvider per the LM Studio plugin contract:

• configSchematics.ts — declares the user-facing settings: process plumbing (binCommand, session, headed, timeoutMs, screenshotDir) and the human-emulation block (userAgent, viewport, acceptLanguage, colorScheme, extraBrowserArgs) which is on by default. Field types are validated against @lmstudio/sdk's basicKVValueTypesLibrary.
• agentBrowser.ts — runAgentBrowser(settings, args, opts) is the only thing that spawns a process. Owns PATH discovery, command resolution, argument ordering, abort signals, and stdout/stderr capture.
• toolsProvider.ts — registers 13 tools, each one a thin call into runAgentBrowser with a curated subset of agent-browser's 100+ subcommand surface. Tool descriptions are part of the user-visible contract — they steer LLM tool selection, edit them deliberately.

Two invariants in agentBrowser.ts that must not be broken

These are load-bearing. The repo's history (see CONTEXT.md) is two debug sessions of these going wrong:

• PATH discovery, not PATH inheritance. LM Studio's plugin runtime launches Node with a stripped PATH (~/usr/bin:/bin), so spawn("npx") fails with ENOENT. resolveAbsolute(cmd) scans known toolchain dirs (Homebrew, Volta, fnm, nvm, asdf, bun, npm-global, system bins) and falls back to /bin/sh -lc 'command -v <cmd>'. Spawned children also receive an enrichedPath() so descendants (e.g. npx finding node) work. The integration test deliberately strips process.env.PATH to exercise this.

• Argument order: subcommand args first, global flags last. agent-browser open https://... --session lmstudio --timeout 30000 is correct; putting --timeout before open makes the CLI parse it as the subcommand and exit. Inside runAgentBrowser, the order is [...prefix, ...args, ...globalFlags] — preserve this. The human-emulation flags (--user-agent, --headers, --color-scheme, --args) live in the globalFlags tail alongside --session/--timeout.

Constraint to respect

Do not add agent-browser as an npm dependency of this plugin. The plugin must work via the host's npx / agent-browser. The binCommand setting exists so users can override discovery with an absolute path when the scan misses.

TypeScript / build

• CommonJS, ES2021, strict, rootDir=src, outDir=dist. The integration test require()s the compiled output from dist/, so changes to src/ need a build before re-running test:verify (the npm script chains tsc for you).
• .lmstudio/ is generated by lms dev; do not edit by hand.