CodeGuard

Appearance

Troubleshooting ​

codeguard command not found ​

For the source checkout, build and invoke the CLI directly:

sh
npm ci
npm run build
node dist/cli/index.js --help

For the beta, install the published package with npm install -g codeguard-local@beta. npm link can make a development checkout's executable available globally instead. Check npm prefix -g and the shell PATH if codeguard is still not found.

Unsupported Node.js version ​

Check node --version; CodeGuard requires Node.js 24 or later. Use nvm use or install Node.js 24 through the OS installer. VS Code/Codex may use a different PATH than the interactive terminal.

Invalid configuration ​

Run codeguard check <project>. The error identifies the configuration file and validation issue. Check JSON syntax, setting types, keys, and rule IDs in Configuration.

Missing project files ​

Check the selected --root, configured ignore patterns, and the scanner's supported extensions (.ts, .tsx, .js, .jsx, and .json). Oversized files and directories beyond the depth, entry-count, or supported-file limits are not analyzed; narrow ignore patterns to reduce scan scope.

MCP server connection closed or tools unavailable ​

  1. Rebuild with npm run build.
  2. Confirm the configured command points to the built dist/cli/index.js or installed executable.
  3. Supply mcp --root <path> with an existing directory.
  4. Ensure the host uses stdio and does not add output to stdout.
  5. Check stderr and host logs for startup or permission failures.
  6. Restart the host after changing its MCP configuration.

For VS Code PATH issues, configure the absolute Node executable path if necessary. Use npx @modelcontextprotocol/inspector node dist/cli/index.js mcp --root <path> to test the handshake and tool list.

Unlink and re-link from the repository only for development:

sh
npm unlink --global codeguard-local
npm link
codeguard --version

For release validation, prefer npm run package:smoke, which packs and installs a temporary tarball and does not use npm link.

Watch mode does not re-analyze ​

  1. Confirm the changed file is a .ts, .tsx, .js, or .jsx file (or a CodeGuard/TypeScript config file) and is not ignored by default rules or your ignore patterns. Files named like secrets, credentials, or tokens are never watched.
  2. Symlinked directories are not followed; watch the real directory instead.
  3. Look for warnings about watcher limits or errors. On Linux, raise fs.inotify.max_user_watches if the OS limit is reached, or narrow the watched path.
  4. Network drives and some container mounts do not deliver file events; use codeguard check.
  5. Increase --debounce if analysis starts before a tool finishes writing files.

MCP prompts fail with invalid arguments ​

explain_diagnostics requires a code made of letters, digits, ., _, and -, and filePath must be project-relative without ... review_project accepts only the documented focus values.