DevMate

Local-first agent capability and automation runtime for ChatGPT, powered by MCP.

DevMate gives ChatGPT Codex-like local execution capabilities without embedding another model. It can inspect and edit project files, use Git, run commands and tests, automate a managed browser, consume live VS Code or Obsidian context, and hand long-running work to durable jobs or remote Runners — while project and runtime state stay on machines you control.

ChatGPT remains the agent/model surface. In the normal ChatGPT and Companion workflow, DevMate adds the local capability layer without requiring a DevMate-managed OpenAI API key or separate model-inference bill. That can reduce dependence on separate Codex runs for routine local work; ChatGPT plan limits and any tunnel, cloud, or Runner infrastructure costs still apply.

It works as a VS Code extension, an Obsidian desktop host, a standalone CLI, or a service-backed Gateway.

Get, report, and contribute

• Get DevMate: install the VS Code extension from its Marketplace listing; install the Obsidian host from Community Plugins after its one-time Community directory submission is approved; GitHub Releases continue to provide the VSIX, Obsidian ZIP, standard Obsidian release assets, and portable CLI archives.
• Report a bug: use the bug report form.
• Request a feature: use the feature request form.
• Contribute: follow CONTRIBUTING.md for the branch, testing, and pull-request requirements.
• Report a security vulnerability privately: follow SECURITY.md; do not disclose live security details in a public issue.

VS Code experience

DevMate keeps the active project, verified MCP ingress, Gateway lifecycle controls, diagnostics, permissions, and workspace state visible in one place. Project boundaries and connection state stay explicit instead of being hidden behind background processes.

Obsidian experience

DevMate brings the same shared Gateway and project-aware workflow into Obsidian, exposing vault context, note workflows, runtime controls, and index state without separating the knowledge workspace from the connected ChatGPT workflow.

What stands out

• Real project access — files, commands, Git, previews, diagnostics, testing, and project-aware context through MCP.
• Agent automation — structured local tools, Browser Control, repeatable .devmate/automation.json workflows, durable jobs, and remote Runners let an agent carry work from inspection through validation instead of stopping at code suggestions.
• Project isolation — each ChatGPT conversation stays bound to its selected project across reconnects; explicit local paths remain authoritative.
• Local-first runtime — the Gateway, project state, credentials, backups, and execution stay on your machine or your own Runner hosts.
• ChatGPT browser Companion — use the official ChatGPT browser side chat as the agent UI, combine the current page with DevMate local capabilities, and keep model access on the user's ChatGPT plan instead of storing a DevMate model API key.
• One desktop runtime — VS Code and Obsidian share one machine-wide Gateway and public connection instead of competing for separate processes.
• Durable work — reviewed jobs survive MCP request boundaries and Gateway restarts.
• Remote execution when needed — scoped external Runners can handle platform-specific or long-running work without owning central policy state.
• Current MCP only — protocol 2026-07-28, server/discover negotiation, stateless HTTP transport, and legacy transport rejection.
• Built-in safety boundaries — workspace containment, protected-path filtering, bounded command output, optional approvals/leases, audit metadata, and ownership-aware process cleanup.

Single-owner MCP defaults to no authentication for both local and public ingress; OAuth is for team/member identity.

Quick start

VS Code

1. Open a project.
2. Run DevMate: Start — or keep the default auto-start enabled.
3. DevMate starts or attaches to the shared Gateway and configured public connection.
4. Before reporting Ready, DevMate verifies MCP with server/discover against protocol 2026-07-28, then runs tools/list and a real read-only gateway_status call.
5. Add the verified HTTPS /mcp URL to ChatGPT.

Fresh desktop instances use ngrok by default. Cloudflare Quick, Cloudflare managed tunnels, and existing external HTTPS ingress are also supported.

The default single-owner auth.mode: "none" works for both loopback and configured public MCP. Enable OAuth when the endpoint is shared with team/member identities.

Standalone CLI

# Personal instance: single-owner no-auth + embedded execution
npx devmate bootstrap --preset personal --workspace /srv/project

# Start the Gateway owned by the CLI
npx devmate start

# Inspect current state without exposing credentials
npx devmate status

For explicit service layouts, custom config paths, Team/Control-plane presets, and portable Windows/Linux packages, see docs/STANDALONE.md and docs/BOOTSTRAP.md.

Obsidian

DevMate also ships a desktop-only Obsidian host. It publishes vault context and note workflows through the same shared Gateway/public connection model used by VS Code.

The release is Community Plugins-compatible: each version publishes the standard main.js, manifest.json, and styles.css assets under an exact semantic-version GitHub tag. After DevMate's one-time Community directory submission is approved, install it from Settings → Community plugins → Browse → DevMate.

For local development only:

npm run build:obsidian

Copy obsidian-plugin/dist into <Vault>/.obsidian/plugins/devmate/, then enable the plugin.

Obsidian Community directory disclosures

• Network use: DevMate can expose its local MCP Gateway through ngrok, Cloudflare Tunnel, or an HTTPS origin you manage so a connected MCP client such as ChatGPT can reach it. Provider selection is explicit. DevMate does not send vault data to a DevMate-hosted analytics or telemetry service.
• Files outside the vault: the desktop host writes machine-wide runtime, configuration, diagnostics, and rollback metadata to the DevMate shared state directory (by default under ~/.devmate/desktop) and materializes its bundled runtime there. It may also access explicitly registered DevMate workspaces outside the current vault when you authorize those workspaces.
• External executables: the desktop host can launch a configured Node.js 24+ runtime and, when selected, ngrok or cloudflared. The Obsidian plugin does not install or update these external dependencies; install them separately using their official distribution methods.
• Accounts and telemetry: no DevMate account is required. ChatGPT and tunnel-provider accounts are required only when you choose those services. The Obsidian plugin contains no client-side telemetry.

See obsidian-plugin/README.md, docs/RELEASING.md, and docs/OBSIDIAN_DATA_WORKFLOWS.md.

Product surfaces

Authentication presets

Presets are setup defaults, not runtime modes. Connection provider, authentication, request policy, workspace coordination, and Runner topology remain independent capabilities.

Architecture

VS Code / Obsidian / CLI
          │
          │ local host control + project context
          ▼
    DevMate Gateway
    ├─ MCP 2026 transport
    ├─ workspace + tool policy
    ├─ files / commands / Git / previews
    ├─ leases / approvals / audit
    ├─ durable job queue
    └─ optional platform plugins
          │
          │ HTTPS /mcp
          ▼
       ChatGPT

    DevMate Gateway
          │ /runner/v1 + scoped dmr_ credential
          ▼
    External Runner hosts
          └─ local toolchains and workspaces

The central Gateway remains authoritative for workspace scope, identity, approvals, leases, job ownership, retries, and cancellation. External Runners distribute execution only.

VS Code and Obsidian coordinate one machine-wide desktop state directory and one provider-native public connection. Ready evidence is generation-bound: a Gateway restart, provider restart, ownership transfer, or endpoint-generation change invalidates stale verification even if the public hostname stays the same.

See docs/ARCHITECTURE.md for the full runtime model.

Project and workspace model

DevMate treats project selection as a real boundary, not UI state:

• explicit absolute local paths take precedence over editor/vault defaults;
• new ChatGPT conversations can adopt the current VS Code/Obsidian project when no path is supplied;
• reconnects do not silently drift a conversation to another project;
• sessions, leases, previews, and jobs remain project-scoped;
• same-project conversations can still continue shared work records where policy allows it;
• writable and readonly/reference workspaces remain distinct.

This keeps normal project switching lightweight without mixing work between unrelated repositories.

Durable jobs and Runners

Long-running work can continue beyond one MCP request:

job_target_catalog
job_submit
job_list
job_status
job_artifacts
job_cancel
job_retry
runner_status

The queue accepts reviewed targets such as smart checks, configured scripts, Browser QA, Godot audits/tests, performance checks, capture, exports, release reports, snapshots, and non-pushing git_save. Arbitrary queued shell commands, direct push, force operations, and credential-bearing arguments are rejected.

External Runners use dedicated dmr_ credentials accepted only by /runner/v1. Runner-reported capabilities and workspace IDs are intersected with credential scope; they cannot widen their own authorization.

See docs/JOBS.md and docs/EXTERNAL_RUNNERS.md.

Optional capabilities

Optional plugins stay disabled until enabled.

• Browser QA — local previews, Playwright scenarios, screenshots, reports, and structured app-state assertions.
• Godot — project/runtime audit, dependency graphs, native and Web acceptance, performance budgets/regressions, deterministic Movie Maker capture, GUT/GdUnit4 workflows, quality reports, release gates, and multi-platform exports.
• Codex Collaboration — proposal-snapshot collaboration with network-off supervised execution and explicit reviewed apply boundaries.

Repeatable project automation can be committed in .devmate/automation.json.

See docs/PLUGINS.md, docs/AUTOMATION_MANIFEST.md, and the Godot documentation linked below.

Security model

auth.mode: "none" is the intentional single-owner trust model. It grants owner access to requests that can reach the configured MCP ingress, so use it only when that endpoint is private to the owner. OAuth is opt-in for team/member identity and shared access.

Other important boundaries:

• the Gateway binds to loopback by default;
• credentials are never accepted in MCP URLs;
• real .env files, keys, databases, logs, and credential-shaped paths are blocked from normal file tools;
• workspace operations enforce lexical and realpath containment;
• commands run as the DevMate OS identity and are not a hostile-code sandbox;
• Runner credentials, OAuth identities, provider credentials, preview shares, and MCP access are separate trust domains;
• configuration and durable coordination state use cross-process locking and crash-safe atomic replacement;
• unsupported future config/state versions fail closed rather than being silently downgraded.

For shared or organizational deployments, use OAuth, scoped members, optional workspace leases, approvals, bounded request policy, and separate OS/VM/container trust domains where appropriate.

See SECURITY.md and docs/AUTHENTICATION.md.

Verification and engineering quality

The repository runs more than source-level tests. CI covers the actual packaged/runtime boundaries used by the product:

• Windows + Node 24 + real VS Code Extension Host E2E;
• Node Current compatibility;
• Linux runtime, Docker network smoke, and real Godot validation;
• packaged VSIX runtime and shared-tunnel smoke tests;
• Obsidian bundle/runtime smoke tests;
• portable Windows and Linux CLI packages;
• dependency audits, architecture contracts, unit/policy tests, and Gateway smoke tests.

Each tagged release publishes the VSIX, the complete Obsidian plugin ZIP, portable Windows and Linux CLI archives, and SHA256SUMS. The portable CLI assets are named devmate-<version>-windows-x64.zip and devmate-<version>-linux-x64.tar.gz.

Local verification:

npm ci
npm run check
npm run test:unit
npm run smoke:gateway
npm run package:vsix
npm run package:obsidian

Godot support

The optional Godot capability is deliberately broader than a command wrapper. It can verify the editor/toolchain, audit project structure, build dependency graphs, install the QA bridge, run native/Web acceptance, sample performance monitors, compare reviewed baselines, capture deterministic AVI evidence, run GUT/GdUnit4 tests, produce quality reports, and route exports to matching Runners.

The repository's Linux CI uses a real Godot 4.7.1 editor under Xvfb for native QA, performance sampling, and deterministic Movie Maker capture.

See:

• docs/GODOT_AUTOMATION.md
• docs/GODOT_RUNTIME_QUALITY.md
• docs/GODOT_TEST_PERFORMANCE.md
• docs/GODOT_RELEASE_MATURITY.md

Operations

Prometheus-compatible metrics are loopback-only:

http://127.0.0.1:8787/control/metrics

Deployment examples are included for systemd, Docker, external Runner hosts, and Caddy reverse proxying under deploy/.

Documentation

• docs/ARCHITECTURE.md — runtime topology and current architecture
• docs/AUTHENTICATION.md — single-owner and OAuth identity model
• docs/BOOTSTRAP.md — setup presets
• docs/STANDALONE.md — CLI, service, and portable usage
• docs/HOST_INTEGRATION.md — VS Code/Obsidian lifecycle
• docs/JOBS.md — durable jobs
• docs/EXTERNAL_RUNNERS.md — Runner protocol and deployment
• docs/TEAM_DEPLOYMENT.md — shared access and hardened deployments
• docs/TUNNELS.md — public connection providers
• docs/PLUGINS.md — optional capability plugins
• docs/MCP_TOOLS.md — tool catalog
• SECURITY.md — trust boundaries and security policy

License

MIT