Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/chatgpt-local-agent-mcp/llms.txt

Use this file to discover all available pages before exploring further.

The project is TypeScript compiled with tsc. The development workflow uses tsx for watch mode so you get hot-reloading without a separate compile step. The runtime target is Node.js running the compiled output from dist/index.js; the source lives in src/index.ts and the supporting modules under src/.

​
Prerequisites

  • Windows (the server uses Windows-specific APIs for process inspection, desktop automation, and PowerShell tooling)
  • Node.js and npm — required for both development and the installer’s build step
  • PowerShell or Windows PowerShell — required for the installer and control scripts
  • Git — recommended; the server exposes Git tools that expect a working Git installation
Use npm ci rather than npm install for reproducible builds. The installer’s Install Dependencies + Build step runs npm ci explicitly. Using npm install in a development or CI context can silently update package-lock.json and produce builds that differ from what was tested.

​
npm Scripts

All scripts are defined in package.json and run from the install folder (or the source root during local development).

​
npm run dev — Hot-reloading development server

Starts the server in watch mode using tsx. Any change to a TypeScript source file restarts the server automatically. 
npm run dev
Equivalent to running: 
tsx watch src/index.ts
Use this during active development when you want fast feedback without a separate compile step.

​
npm run build — Compile TypeScript to dist/

Compiles all TypeScript sources using the project’s tsconfig.json and writes output to dist/. 
npm run build
Equivalent to: 
tsc -p tsconfig.json
The compiled entry point is dist/index.js. This is what npm start and the control scripts run in production.

​
npm start — Run the built server

Starts the compiled server from dist/index.js using Node.js. 
npm start
Equivalent to: 
node dist/index.js
Use this to verify the production build behaves correctly before deploying or handing off to the installer.

​
npm run type-check — Type-check without emitting

Runs the TypeScript compiler in check-only mode. No output files are written. 
npm run type-check
Equivalent to: 
tsc --noEmit -p tsconfig.json
Run this in CI or before committing to catch type errors without producing a full build. It is faster than npm run build and leaves the dist/ folder untouched.

​
npm test — Run tests

Runs the test suite using tsx with Node’s built-in test runner. 
npm test
Equivalent to: 
tsx --test tests/*.test.ts
Tests are picked up from the tests/ directory. The tsx runner handles TypeScript without a separate compile step, so tests run against the source directly.

​
npm run audit:publish-safe — Check for files that should not be shared

Runs scripts/pack-safe.mjs to check the source folder for files and directories that should not appear in a shareable archive. 
npm run audit:publish-safe
See the Publish-safe check section below for the full list of what this checks.

​
Development Mode and AUTH_REQUIRED

AUTH_REQUIRED=false is allowed only when NODE_ENV is unset or set to development and the server is bound to 127.0.0.1 with no tunnel enabled. This combination is intended for the Path A local smoke test — confirming the server starts, the dashboard opens, and the health endpoint responds — before OAuth is configured. Safe local-only development values: 
PUBLIC_BASE_URL=http://127.0.0.1:8789
CLOUDFLARE_TUNNEL_ENABLED=false
AUTH_REQUIRED=false
NODE_ENV=development
Never use AUTH_REQUIRED=false with a public URL, public hostname, or Cloudflare Tunnel. The server guards against unsafe combinations, but .env is still your responsibility.
Once you move to Path B (the full remote ChatGPT connector), AUTH_REQUIRED must be true regardless of NODE_ENV.

​
What the Installer Does During “Install Dependencies + Build”

The installer’s Install Dependencies + Build step runs these two commands in sequence inside the runtime install folder: 
npm ci
npm run build
This step is designed to be re-runnable for repair and update flows. If node_modules/ already exists, npm ci will still verify the lockfile and reinstall cleanly. If dist/ exists, it will be overwritten.

​
Install Folder vs Source Folder

The extracted source folder (where you unzipped or cloned the project) is not the runtime folder. The installer copies the public app files into the runtime install folder and builds there.
LocationPurpose
Source folder (extracted zip or repo clone)Read-only source package. Run the installer from here.
%LOCALAPPDATA%\chatgpt-local-agent-mcpRuntime install folder. Contains .env, node_modules/, dist/, data/, logs, screenshots, backups, and the journal.
Your private .env, logs, data/, dependencies, build output, browser artifacts, journals, backups, and screenshots all belong in the install folder — never in the extracted source folder. If you need to override the runtime root, set CHATGPT_LOCAL_AGENT_MCP_RUNTIME_ROOT in your environment before launching the fallback dashboard or control scripts.

​
Publish-safe Check

Before sharing the source folder — as a zip, archive, pull request, or any other form — run the publish-safe audit: 
npm run audit:publish-safe
The script (scripts/pack-safe.mjs) checks that the source folder does not contain any of the following:
  • .env — private configuration and secrets
  • data/ — journals, backups, screenshots
  • node_modules/ — installed dependencies
  • dist/ — compiled build output
  • *.log — server logs
  • Runtime screenshots
  • Browser artifacts (Playwright browser cache, CDP profiles)
  • Journals (*.jsonl)
  • Backups
The included .gitignore excludes the main runtime directories and log files, but the publish-safe audit is the final check. The ignore file alone is not sufficient — run the audit before publishing.
The audit is especially important if you develop in the install folder directly. In that case the runtime artifacts (.env, data/, dist/, node_modules/) will be right next to the source files, and it is easy to accidentally include them in an archive.
If you encounter build errors, see Troubleshooting for common fixes including missing Playwright binaries, npm ci failures, and TypeScript version issues.

Build docs developers (and LLMs) love

Get started for freeTalk to us