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.