GPT Commander: An LLM-Facing Software Engineering Substrate

GPT Commander is a security-first MCP server that gives LLMs a safe, structured way to operate on a developer environment. It provides filesystem, process, and search tools; opinionated build/test/lint primitives; optional IDE-native context via VS Code; and integrations for CLI runners and memory stores.

This repo is intentionally "LLM-native": the tool surface is constrained, named, and predictable so models can operate reliably without improvising shell commands.

Why this exists

• LLMs are best when the action space is small, stable, and explicit.
• Most existing "terminal helpers" are too permissive or too brittle.
• The difference between "helper" and "pair programmer" is IDE context and safe primitives.

Feature highlights (all the bells + whistles)

• Security guardrails: path allowlist, command blocklist, read/write limits, binary file sniffing.
• Process management: start, interact, read output, kill; TTL auto-prunes long-running sessions.
• Search + edits: ripgrep-backed search + targeted block replacement.
• Opinionated primitives: run_tests, lint, build, typecheck, dev_server_start, etc.
• IDE bridge (VS Code): diagnostics, symbols, references, workspace edits, and unsaved buffers.
• CLI wrappers: safe runners for Codex, Claude, and Gemini CLIs.
• Memory MCP: a memory_note tool that stores ad hoc notes externally.
• Telemetry: optional tool/command metrics + JSONL event log.
• Onboarding gate: mandatory obstacle course to ensure the model is actually calling tools correctly.
• HTTP/SSE or stdio: run as a local stdio MCP or as a URL-based SSE MCP.

Requirements

• Node.js >= 18
• ripgrep (rg) on PATH (recommended for start_search)

Install

npm install
npm run build

Run: Stdio MCP (local clients)

Add to your MCP config (e.g. GPT Desktop, Claude Desktop, Codex, etc.):

{
  "mcpServers": {
    "gpt-commander": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "GPT_DC_CONFIG": "/optional/custom/config.json"
      }
    }
  }
}

Run: HTTP/SSE MCP (URL clients)

npm run build
node dist/sse.js

Then point your MCP client at:

http://127.0.0.1:3333/mcp

If you are using a reverse proxy or tailnet URL, set an absolute endpoint:

GPT_DC_HOST=127.0.0.1 GPT_DC_PORT=3333 \
GPT_DC_ABSOLUTE_ENDPOINT="https://your-host.example/desktop" \
node dist/sse.js

Ollama MCP (optional)

This repo includes a standalone MCP server that exposes local Ollama via tools.

npm run build
OLLAMA_HOST="http://127.0.0.1:11434" node dist/ollama-mcp.js

Tools:

• ollama_list_models
• ollama_show_model
• ollama_generate
• ollama_chat

Optional env:

• OLLAMA_HOST (default http://127.0.0.1:11434)
• OLLAMA_TIMEOUT_MS (default 120000)

OpenWebUI tool (sparse + CLI)

OpenWebUI Function plugin that bridges to Commander MCP with a minimal tool list plus CLI wrappers.

• File: openwebui/commander_mcp_bridge.py
• Setup: openwebui/README.md

Configuration

Default config is created at ~/.gpt-desktop-commander/config.json.

{
  "allowedDirectories": ["$HOME"],
  "blockedCommands": ["rm", "shutdown", "reboot", "mkfs", "mount", "umount"],
  "fileReadLimitBytes": 10485760,
  "fileWriteLineLimit": 10000,
  "defaultShell": "$SHELL",
  "enableShell": true,
  "telemetryEnabled": false,
  "telemetryLogFile": "$HOME/.gpt-desktop-commander/telemetry.jsonl",
  "telemetryMaxEvents": 200,
  "processTtlMinutes": 480,
  "onboarding": {
    "enabled": true
  },
  "memoryMcp": {
    "enabled": false,
    "url": "",
    "defaultType": "note",
    "defaultScope": "",
    "defaultTags": [],
    "defaultTtlDays": 0
  },
  "ideBridge": {
    "enabled": false,
    "host": "127.0.0.1",
    "port": 7311,
    "token": "<generated>",
    "requestTimeoutMs": 15000,
    "originAllowlist": []
  }
}

Set GPT_DC_CONFIG to point at a specific config file. The config is loaded at server start, so restart the server to apply changes.

Onboarding gate (mandatory)

When onboarding.enabled is true, all tool calls are gated until onboarding completes. The tool list is still visible so the model can discover commander_onboard.

Onboarding steps: 1) commander_onboard 2) tools/list 3) list_directory 4) start_search 5) commander_finish

This ensures the model has proven it can execute tools correctly before getting full capabilities.

IDE Bridge (VS Code)

The IDE bridge exposes LSP-grade context: diagnostics, symbols, references, workspace edits, and unsaved buffers.

1) Enable in config:

{
  "ideBridge": {
    "enabled": true,
    "host": "127.0.0.1",
    "port": 7311,
    "token": "YOUR_TOKEN"
  }
}

2) Install the VS Code extension from the vscode-extension/ folder. 3) Set VS Code settings:

gptDesktopCommander.bridgeUrl = "ws://127.0.0.1:7311"
gptDesktopCommander.bridgeToken = "YOUR_TOKEN"

4) Use ide_list_workspaces() to get the workspaceId, then call:

• ide_get_diagnostics
• ide_symbol_search
• ide_find_references
• ide_read_buffer
• ide_apply_workspace_edit

Opinionated primitives (Node + Python)

The project_info tool detects project language and tooling. Primitives use the best available commands:

Node/TypeScript

Detection:

• package.json, lockfiles for npm/yarn/pnpm
• tsconfig*.json for typecheck

Commands:

• run_tests: npm run test or local vitest/jest/mocha/ava
• lint: npm run lint or local eslint/biome
• format: npm run format or local prettier/biome
• typecheck: local tsc/vue-tsc --noEmit
• dev_server_start: npm run dev or npm run start

Python

Detection:

• pyproject.toml, requirements.txt, setup.py
• uv, poetry, or pip

Commands:

• run_tests: pytest
• lint: ruff check .

‑ format: ruff format . or black . ‑ typecheck: mypy .

CLI wrappers (Codex, Claude, Gemini)

Set the paths and the CLI wrappers become tools:

CODEX_PATH=/opt/homebrew/bin/codex
CLAUDE_PATH=$HOME/.local/bin/claude
GEMINI_PATH=/opt/homebrew/bin/gemini
GEMINI_WORKDIR=$HOME/gemini-work

Tools:

• codex_run(args?, cwd?, env?, timeoutMs?, maxBufferBytes?, input?)
• claude_run(args?, cwd?, env?, timeoutMs?, maxBufferBytes?, input?)
• gemini_run(args?, cwd?, env?, timeoutMs?, maxBufferBytes?, input?)

Memory MCP integration

memory_note writes to a separate Memory MCP (e.g. memory.write).

Config:

{
  "memoryMcp": {
    "enabled": true,
    "url": "https://memory.example/mcp",
    "defaultType": "note"
  }
}

Tool:

memory_note { "content": "...", "type": "note", "tags": ["ops"] }

Telemetry

When enabled, get_metrics returns totals and recent events for:

• tool calls
• command exits
• durations
• error counts

Optional JSONL logging is written to telemetryLogFile.

Tool surface

Core tools:

• commander_onboard
• commander_finish
• get_metrics
• memory_note
• list_directory, read_file, write_file, get_file_info
• start_process, interact_with_process, read_process_output, list_sessions, kill_process
• start_search (ripgrep)
• edit_block

IDE tools:

• ide_list_workspaces, ide_get_diagnostics, ide_symbol_search, ide_find_references
• ide_read_buffer, ide_apply_workspace_edit

Primitives:

• project_info
• run_tests, run_unit_tests, run_integration_tests
• lint, format, typecheck, build
• dev_server_start, dev_server_stop

Dev helpers:

• git_status, git_diff, git_commit_prepare
• search_code, find_symbol, open_file_at_line

Environment variables

Server:

• GPT_DC_CONFIG (config path override)
• GPT_DC_HOST, GPT_DC_PORT (SSE bind)
• GPT_DC_TAILNET_HOST (allowed host list)
• GPT_DC_ABSOLUTE_ENDPOINT (absolute base for SSE rewrite)
• GPT_DC_TLS_KEY, GPT_DC_TLS_CERT (optional HTTPS)

CLI wrappers:

• CODEX_PATH, CLAUDE_PATH, GEMINI_PATH, GEMINI_WORKDIR

Security model

• Path allowlist: every FS op is resolved inside allowedDirectories using realpath.
• Command blocklist: hard-fails dangerous commands before spawn.
• Read/write limits: prevents giant file operations.
• Binary detection: rejects non-text reads by default.
• Process TTL: prevents zombie processes from lingering.

Troubleshooting

• Tool not found: ensure you are calling tools by name via tools/call, not /Commander/link_*.
• Tool list stale: start a new chat to refresh the tool registry.
• CLI tool missing: verify the *_PATH env var is set before server start.
• IDE bridge offline: confirm VS Code extension is running and token matches.
• SSE origin mismatch: set GPT_DC_ABSOLUTE_ENDPOINT for proxy/tailnet URLs.

Roadmap ideas

• Append-only audit log
• Rich search (glob + ignore support)
• Safer structured edits (range-based)
• Per-tool rate limits

License

PolyForm Noncommercial 1.0.0. See LICENSE.md.