CodeLocator Agent

CodeLocator Agent is a local browser workbench for Android apps that have integrated the CodeLocator SDK. It captures the current device layout through ADB, renders the screenshot and View tree, and can send selected View context to Codex for analysis or small code changes.

Requirements

• Node.js 20 or newer.
• ADB available in PATH, or pass it with --adb.
• One connected Android device, or pass a device serial with --serial.
• The target app must integrate CodeLocator and expose the layout capture broadcast.

Installation

临时运行可以直接使用 npx：

npx codelocator-agent --project-root /path/to/android/project

需要固定安装到本机命令行时，使用全局安装：

npm install -g codelocator-agent
codelocator-agent --project-root /path/to/android/project

卸载全局命令：

npm uninstall -g codelocator-agent

Usage

Run with npx:

npx codelocator-agent --project-root /path/to/android/project

Or run after global installation:

codelocator-agent --project-root /path/to/android/project

Useful options:

npx codelocator-agent --project-root . --port 5123
npx codelocator-agent --project-root . --host 0.0.0.0
npx codelocator-agent --project-root . --serial R5CN0000000
npx codelocator-agent --project-root . --adb /path/to/adb

Workbench settings are saved on the local server under .codelocator-agent/settings-db.json. Settings changed in the browser persist across refreshes and server restarts. Explicit CLI values for --project-root, --serial, and --adb take precedence over the saved runtime settings and are written back for later runs.

After the server starts, open the printed URL in a browser. By default it listens on:

http://127.0.0.1:5123

CLI

codelocator-agent --project-root <path> [--host <host>] [--port <port>] [--serial <deviceSerial>] [--adb <adbPath>]

Development

npm install
npm run dev
npm run build
npm test

Local global-install verification before publishing:

npm install . -g
codelocator-agent --help
npm uninstall -g codelocator-agent

Publishing

当前包名是 codelocator-agent，package.json 已配置：

• bin.codelocator-agent = dist/server/cli.js，支持 npm install -g 后直接运行 codelocator-agent。
• files 只发布 dist、README.md、LICENSE.txt 和 package.json。
• prepack 会在 npm pack / npm publish 前自动执行 npm run build。
• publishConfig.registry 固定到 https://registry.npmjs.org/，避免误发到镜像源。

发布前检查：

npm whoami --registry=https://registry.npmjs.org/
npm run typecheck
npm test
npm run build
npm publish --dry-run

正式发布：

npm publish --access public

发布后验证：

npm view codelocator-agent version --registry=https://registry.npmjs.org/
npm install -g codelocator-agent
codelocator-agent --help