GPT Commander: An LLM-Facing Software Engineering Substrate

![CI](https://github.com/PushPullCommitPush/GPT-Commander---An-LLM-facing-software-engineering-substrate/actions/workflows/ci.yml) ![License](LICENSE.md)

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.): ``json { "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: ``bash 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: ``json { "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: ``json { "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.

GPT Commander