DevMate

English | 简体中文

imageCI imageVS Code Marketplace imageRelease imageLicense: MIT

DevMate lets the model in your chat window work directly on your own computer: read, search and edit project files, run commands and tests, use Git, see the errors your editor already reports, and hand whole tasks to the coding agents installed on your machine. It is a local runtime that offers these capabilities through the Model Context Protocol (MCP).

The main use is connecting the chat window you already use (ChatGPT on the web, Claude) to your machine and developing from there. It is not tied to one of them: every MCP client connects to the same runtime. What your plan allows says which ChatGPT and Claude plans can change files and run commands through a connector, and which can only read.

• Your machine, your route. Nothing is relayed through a service of ours. Cloud clients reach you through a tunnel you own (Cloudflare, OpenAI's official tunnel, your reverse proxy, or SSH), and DevMate proves the route end to end.
• You decide what is shared, at your computer. Which folders, read only or read and write, credential files protected. A connected client can narrow these and never widen them.
• One runtime for every entry. Any number of VS Code windows, Obsidian and the command line share one runtime per machine, guaranteed by the operating system.
• It knows what your editor knows. Compiler, type and lint errors come straight from VS Code, without running a build.

 ChatGPT web · Claude.ai                    Claude Code · Codex · any local MCP client
          │  HTTPS through your own tunnel                 │  http://127.0.0.1:8788/mcp
          ▼                                                ▼          or `devmate mcp` (stdio)
   ingress port 8789 ───────────────┐      ┌─────────────── control port 8788
   MCP and OAuth only               ▼      ▼                owner only: CLI, editors, workbench
                              ┌──────────────────┐
                              │  DevMate runtime │  one per instance directory
                              │  every call is   │  files · search · Git · shell
                              │  authorised here │  editor diagnostics · agents
                              └──────────────────┘
                                 ▲      ▲      ▲
                         VS Code windows · Obsidian · `devmate` command line

imageThe DevMate workbench showing the uncommitted changes of a project

Install

Requirements: Node.js 24 or newer, and Git 2.41 or newer (the Git that ships with the macOS developer tools is older: brew install git). The command line and Obsidian also need rg (ripgrep); the VS Code extension brings its own.

devmate doctor (or DevMate: Doctor in an editor) checks everything this installation needs and prints the exact command to fix each item for your system.

The first five minutes

With VS Code:

1. Open a project folder and run DevMate: Start DevMate Runtime from the Command Palette. The folder is shared, read and write, and the window tells you so once.
2. Run DevMate: Copy MCP URL. For a client on the same computer that is all: claude mcp add --transport http devmate http://127.0.0.1:8788/mcp.
3. For ChatGPT on the web or Claude.ai, run DevMate: Configure Connection once (see Connecting a client), then add the copied address as a custom MCP connector.
4. Ask the model for "an overview of my project". It calls project_overview and you are working.

With the command line only:

devmate start                          # start the background runtime, or join the one that runs
devmate project add C:\Projects\Example
devmate doctor
devmate mcp-url                        # the address to give a client
devmate ui --open                      # the workbench in your browser

Four entries, one runtime

One instance directory (default ~/.devmate/runtime) has exactly one runtime process at a time.

• Several VS Code windows, Obsidian and the command line can run together. Pressing Start in all of them starts one runtime; the others join it.
• Each editor window works on its own folders. Closing a window affects neither the runtime nor the other windows.
• The runtime keeps running after you close the editor, with its public connection if you configured one, until you stop it: devmate stop, or Stop DevMate Runtime in an editor. Stopping affects every entry, so the editors ask first.
• After a crash the next start simply works. VS Code with devMate.autoStart brings a crashed runtime back; one you stopped stays stopped.

Command line

Every command accepts --instance <directory> to use another instance. The command line can do everything the workbench and the extensions can.

Commands run in PowerShell on Windows: PowerShell 7 when it is installed, otherwise the built-in 5.1. Version 5.1 has no && and ||, which models use by habit, so installing PowerShell 7 is recommended (winget install Microsoft.PowerShell). On macOS and Linux commands run in bash, or sh when there is no bash.

VS Code extension

Commands (all under DevMate: in the Command Palette):

Settings (user settings only: a repository's .vscode/settings.json cannot change them):

• An opened folder is shared read and write by default, and the window says so once with a Change… button. A folder you take out stays out until you share it again.
• No separate ripgrep is needed: when PATH has no rg, the runtime uses the copy VS Code ships and remembers it for use without the editor.
• Editors with built-in MCP support discover the local endpoint on their own.
• The extension needs VS Code 1.101 or newer and is tested in a real editor on 1.101 and 1.133.
• Remote windows (SSH, WSL, Dev Containers): the extension runs on the remote side, so DevMate, Node.js and the shared folders are those of the remote computer, and "local" addresses are local to it. This setup is not tested yet.

Obsidian plugin

• DevMate: Start runtime starts the runtime; the status bar shows its state and opens the sidebar.
• DevMate: Attach this vault shares the vault and offers the note tools (search, properties, graph, move, trash). The first time it asks: read and write, read only, or not now. The whole vault folder is shared, so connected clients also reach it with the file tools.
• DevMate: Change how this vault is shared changes that at any time. Detach only stops the note tools; sharing is unchanged.
• DevMate: Stop shared runtime and Restart shared runtime ask first, because they affect every entry.
• When an agent waits for your approval or an answer, Obsidian tells you; DevMate: Open workbench is where you answer.

Disclosures. The plugin is desktop only and needs Node.js 24 installed separately (set its path in the plugin settings when it is not found; ripgrep must be installed too). It starts the DevMate runtime as a background process that keeps running after Obsidian closes, until you run Stop shared runtime. The runtime listens on 127.0.0.1 only (ports 8788 and 8789, and one more loopback port for vault operations). Its state, credentials and its own program files are kept in ~/.devmate/runtime, outside the vault. The plugin carries those program files inside main.js as plain, readable text (nothing is encoded), writes them there and checks each against its hash on every start. It makes no network connection unless you configure a public connection (Cloudflare Tunnel, OpenAI Secure MCP Tunnel, SSH or your own HTTPS proxy). No telemetry, no account, no payment.

The plugin has been loaded and driven in a real Obsidian 1.12.7 on Windows: loading, starting the runtime, sharing the vault read only and read and write, the note tools, stopping and disabling. Obsidian on macOS and Linux has not been tried. Please report what you find.

Chrome and Edge extension

DevMate can drive a browser of its own (the browser control engine), but that browser is not yours: it has none of your bookmarks, tabs, history or sign-ins. The extension gives your client the browser you actually use.

devmate chrome install        # tell Chrome and Edge which program the extension may talk to (your account only), and put the extension where the browser loads it from

Then load the extension: open chrome://extensions (edge://extensions in Edge), switch on Developer mode, choose Load unpacked and pick the folder devmate chrome names: chrome/extension in DevMate's instance directory (~/.devmate/runtime/chrome/extension unless you chose another). devmate chrome says whether the browser is registered and connected, and so does devmate doctor.

Leave Developer mode on, and that is all there is to do, updates included. The folder stays where it is and DevMate keeps it current: every start of the runtime makes it the extension of the DevMate that runs (a newer one that is already there is left alone), whichever entry was updated, and makes the program the browser starts that same DevMate. The extension notices within about two minutes that its files changed and loads itself again, with nothing to click. With Developer mode off, Chrome switches an unpacked extension off at that moment.

• An entry like the editors. The extension's panel says in one sentence how things stand and the one thing to do about it, with the browser's own words when it cannot reach DevMate. It starts DevMate, opens the workbench, copies the address a client in the cloud needs (the public one where you have a route, otherwise this computer's) and counts what waits for your answer.

• Two switches, both yours. Let DevMate use this browser: switched off, every request is refused and your client is told that you paused it. Start DevMate with the browser: off until you turn it on; like an editor it starts the runtime and never stops it.

• What DevMate did in this browser is listed in the panel: the last calls with their time and outcome, never their content. The panel is in English and Chinese.

• What your client can do with the browser (through capability_list {engine:"chrome"}, capability_query for what only reads and capability_call for changes; no project is needed):

  	Read	Change
  Bookmarks	the tree, search	create, rename, move, remove
  Tabs and windows	list tabs, windows and tab groups	open, go to an address, bring to front, reload, close, move, group, ungroup; open and close windows
  History	search by words and time	delete an address or a time range
  Downloads	list	start a download
  Recently closed	list	bring back
  Reading list, most visited	list	add, remove
  A tab's page	title, address and text; a picture of what it shows or of the whole page	go back, go forward
  Debugging a page	the console and uncaught errors, the network requests and one of them in full, the page as its elements, one element in detail (attributes, box, styles), what the page stores, wait for an element or a text	click, type, press a key, choose from a list, hover, scroll, run a script, answer a dialog, reload, emulate a screen, a color scheme or being offline

• Debugging works like DevTools, on the tab you name or the one in front. The first call puts Chrome's debugger on that tab; Chrome shows its own bar on the tab while it is there, and it comes off after five minutes without a call or with chrome.page.debugStop. The console and the network are recorded from that moment: chrome.page.reload shows a page loading from the start. chrome.page.snapshot gives every element a number, and click, type, hover, scroll and inspect take that number, a CSS selector, or the text the element shows.

• The values a page stores (its cookies among them) are credentials. chrome.page.storage gives names only; the values come only with includeValues through capability_call, which your client asks you about.

• Text read from a web page (its text, its console, its requests, its elements, what a script returns) is marked as untrusted: it is data for the model, never instructions.

• The browser talks to DevMate through a native messaging host, a small program the browser itself starts for this one extension. Nothing listens for it and it works with no public connection. devmate chrome uninstall takes the registration away.

• On Windows the registration is written through the system's own management service, so that it lands where browsers read it whichever terminal the command is run from. A terminal inside a packaged app has a registry of its own that no browser sees; devmate chrome says so when it finds a registration only there.

The runtime's side has been run end to end with the browser's own message framing against a real runtime. STATUS says what has been tried in a real browser.

Connecting a client

On the same computer

No tunnel and no sign-in:

http://127.0.0.1:8788/mcp

Any other client: add an HTTP (Streamable HTTP) MCP server with this address. A browser-based client on another origin is refused until you add its origin to allowedOrigins in the DevMate configuration; add only clients you run yourself.

ChatGPT on the web and Claude.ai

They reach your MCP server from the cloud, so they need a route from outside to your machine. DevMate offers six. Two of them have nothing of a third party in between: a relay on a server of your own, and for ChatGPT OpenAI's own tunnel.

A relay of your own: an address that stays

With a public Linux server you control (a small rented one is enough) and key login to it over SSH:

devmate relay setup root@203.0.113.7 --domain devmate.example.com
devmate restart
devmate mcp-url

relay setup installs Caddy on the server from the system's own packages, lets it get the certificate for that name, and forwards one path nobody can guess to a loopback port there. This computer holds that port open from the inside with OpenSSH, so nothing has to be opened on your router. Answers stream as they do locally, and there is no request count, size limit or changing address: the only limits are the server's own.

• By default the relay answers only to the addresses ChatGPT and Claude connect from (their published ranges, fetched again every six hours) and to this computer. --any-address leaves the protection to the key in the path.
• A relay asks for no sign-in and cannot: it forwards that one path and nothing else, so the pages of a sign-in would not be reachable. What keeps strangers out is the key and the list of addresses; --auth oauth together with a relay is refused when you set it.
• Without --domain the relay is reached by the server's IP address and asks for a certificate for that address, which needs Caddy 2.10 or newer on the server. Where the system's own package is older or missing (Debian, Ubuntu, Fedora, RHEL), relay setup takes Caddy from Caddy's own package repository. A Caddy that was on the server before is never replaced: the setup stops and prints the commands that would do it.
• It needs root on the server, or a login that may use sudo without a password. No password is ever asked for or stored: authentication is your SSH key.
• Running it again changes nothing and keeps the address. devmate relay remove root@203.0.113.7 takes the relay off the server, and Caddy and its package repository too if this had installed them.

The server script and the forwarding are tested; a relay on a real public server has not been tried yet. STATUS says exactly what is unverified.

Quick tunnel: connected in a minute

With cloudflared installed (Windows: winget install Cloudflare.cloudflared; macOS: brew install cloudflared), three commands give you an address for ChatGPT or Claude:

devmate connect quick
devmate restart
devmate mcp-url

Nothing is registered anywhere: Cloudflare hands out a random trycloudflare.com host name while the tunnel runs, and DevMate checks that it reaches this runtime. There is no sign-in. The address ends in a key that DevMate makes anew at every start (https://<name>.trycloudflare.com/mcp/<key>), and only the whole address opens anything: the host name alone, which anyone watching DNS can see, answers "not found". Whoever has the whole address can do what you can, so give it to your own client only and do not paste it anywhere else; devmate doctor prints it without the key. It changes whenever DevMate or the tunnel starts again; the client then gets the new one from devmate mcp-url.

A quick tunnel is what Cloudflare offers for testing and development: no uptime guarantee, at most 200 requests at once, and no event streams. DevMate therefore answers through it in plain JSON, without progress messages while a call runs. For daily use take an address that stays, with one of the routes below.

Cloudflare tunnel

1. In Cloudflare Zero Trust create a tunnel with a public hostname such as devmate.example.com, and set its service to http://127.0.0.1:8789.
2. Configure it and store the token:

devmate connect cloudflare --url https://devmate.example.com/mcp --executable "C:\Program Files (x86)\cloudflared\cloudflared.exe"
devmate secret set CLOUDFLARE_TUNNEL_TOKEN      # paste the token and press Enter, or pipe it in
devmate restart
devmate doctor

3. Give the address printed by devmate mcp-url to ChatGPT or Claude as a custom MCP connector.

OpenAI tunnel

Create a tunnel in the organisation settings of the OpenAI Platform (Settings → Tunnels). It gives you a tunnel id and a runtime key:

devmate connect openai-tunnel --tunnel-id tunnel_xxxxxxxx
devmate secret set CONTROL_PLANE_API_KEY      # paste the runtime key and press Enter
devmate restart

devmate mcp-url prints the tunnel ID; choose the Tunnel connection type in ChatGPT and enter it. It stays the same across restarts.

This computer only reaches out, to api.openai.com, and asks for work: nothing listens for the outside, no router setting and no server are needed, and the only party that can limit the route is OpenAI. DevMate speaks the tunnel's published protocol itself, so there is no second program to download and keep current, and it serves up to 32 calls at once (maxConcurrentRequests in the connection settings, 1 to 256). To use OpenAI's own tunnel-client program instead, add --executable <its path>. devmate doctor says which of the two is in use, and counts the calls that have arrived: a call that came through is the proof that the route works.

When OpenAI refuses the key or the tunnel, devmate doctor repeats OpenAI's answer and says what to do about it. For a key OpenAI wants the tunnel's organisation named with, that is --organization <org-…> on the connect command.

If ChatGPT does not offer the tunnel although the doctor shows it connected, the cause is in the OpenAI account and not in DevMate: the tunnel has to include the ChatGPT workspace you use, not only a Platform organisation, and your account needs the Tunnels permissions Read and Use ("Troubleshooting" in OpenAI's guide). Whether your ChatGPT plan offers the Tunnel connection type is decided by OpenAI; this has not been tried with a real account yet.

Is it really connected?

A running tunnel process is not a working route. DevMate connects back through the public address as a real MCP client, lists the tools and calls one, and the answer must come from this very runtime; it repeats the check periodically and says so when the route breaks. The route works when connection.public is ok in devmate doctor. The OpenAI tunnel has no public address to connect back through: there the doctor shows that OpenAI accepts the runtime key, and how many calls have arrived.

A connector that cannot start does not take local work down and is never hidden: doctor and connection.status give the reason. After storing a new credential, restart only the connector: devmate connection.restart.

What your plan allows

Whether a chat product lets a connector you add yourself change things is decided by that product and your plan, not by DevMate. As their own documentation states it:

Sources: Developer mode and MCP apps in ChatGPT, Build an MCP server for Claude. Both change; check them for your plan. DevMate's own tools stay inside the tighter of these limits: a command or a delegated task is waited for at most 50 seconds per call (it keeps running and is asked about again), and a text result stays under 140,000 characters. A capability that runs longer by nature (a browser navigation, a game-engine run) is better started as a job with job.start and read later.

Who may do what

• Two ports, two levels of trust. The control port (default 127.0.0.1:8788) is yours alone: workbench, command line, editors, MCP clients on this computer. The ingress port (default 8789) serves only MCP and OAuth and is the only thing a tunnel or proxy points at; the control port refuses anything that arrived through a proxy.
• What is shared is decided at your computer. Folders are shared from an editor, with devmate project add, or in the local workbench. A connected client cannot share a folder, widen read-only access, lift the protection of credential files or bring back a folder you took out; it can only narrow.
• Write access is full access. In a writable project a client can run commands, and commands run as your operating-system account. With at least one writable project the limits on other folders keep a well-behaved model in place; they are not a wall against a hostile one. For a client you do not fully trust, share read only: then there are no commands and the limits hold. DevMate is not a sandbox.
• auth.mode is none by default. Whoever reaches the MCP address is you. Treat a public address like a password, or require sign-in.
• Optional sign-in (OAuth). devmate connect … --auth oauth makes clients of the public address sign in: on first connection they are sent to DevMate's authorisation page, where you enter a one-time code from devmate login-code. Signing in proves the client is you: DevMate has one owner and no other accounts. A client that publishes no description of itself (a client metadata document) is registered by you under auth.clients in the configuration, with its name and redirect addresses. Clients on your own computer never need to sign in.
• Approvals and questions are answered by you, at your computer. When an agent asks for permission, you answer in the editor or the local workbench. No connected client can answer, including the model that started the agent.
• Full access, when you want none of that in your way. The default profile is guarded: everything above. If you drive your work from a chat client and do not want to walk to the computer, switch on full access there: devmate access full, DevMate: Change Permission Profile in VS Code, or Permissions… in Obsidian. A client connected as you can then share folders, widen access, read credential files, set up capability engines, answer what an agent asks and run the doctor, and what an agent you delegated to asks permission for is granted automatically (each grant stays on record). It takes effect at once and only you, at your computer, can switch it on; devmate access guarded takes it back. With full access, whoever reaches your MCP address acts as you without asking: keep the address private or require sign-in.
• Credential files are protected by default. .env, key files, .npmrc and the like are not read or listed by the file tools; Git status names them, marked "do not commit". You can switch that off for one project, at your computer.
• Secrets in command lines are not shown. Process lists and activity records replace inline tokens and passwords with [redacted]; the command that runs is unchanged. This recognises common forms and is no guarantee.
• The workbench session stays in its browser tab. It is entered through a single-use link, and its session is never a cookie that other local services would receive.
• File contents, command output and web pages the model reads are data, never instructions to it.

SECURITY.md has the full policy and the known limits.

Tools the model gets

A model is shown its tools under the names it was trained on. Which list a client gets is decided by what it says it is; a client that is not recognised gets DevMate's own names.

• Every tool of every list can be called by every client: the list only decides what a model is told about up front. To choose a list yourself, add ?tools=gpt, ?tools=claude or ?tools=generic to the MCP address you give the client. devmate doctor says what the last client called itself, which list it was shown and why.
• projectId is a project id, a project's root directory or a unique project name, and can be left out when only one project is shared. With several, read-only tools follow the editor window you are working in; a change must name its project.
• There is no tool for sharing a folder. That is yours to do; the model is told to ask you.
• A tool list has 34 to 37 entries and takes 32 to 35 KB. Nothing that only reads is kept off it: a tool a model cannot see is a tool it does not use, and what only reads is what a client does not ask you about.
• Tools carry accurate hints (read only, write, destructive, open world), so clients ask for confirmation only where it matters.
• A cancelled or timed-out call only stops waiting: the command or agent task it started continues and stays reachable.
• The server speaks MCP 2026-07-28 and the 2025 revisions.
• The reverse-engineering engine includes tools that read, and can write, the memory of another process on Windows. Both are off until you switch them on at your computer (allowProcessAccess, allowMemoryWrite); a connected client cannot. See docs/CAPABILITIES.md for all engines.

Delegating to coding agents on this machine

One call hands a task to Codex, Claude Code, Gemini CLI or Grok CLI installed here:

{ "projectId": "Example", "provider": "claude", "prompt": "Fix the failing case in tests/login.test.ts and say why it failed" }

• A task that finishes within the wait returns its result and the list of changed files; otherwise it returns an agentId to follow with agents_result.
• Passing the same agentId again continues that session with its context.
• With "isolate": true the agent works in a copy of the project instead (a Git worktree of the last commit, kept in DevMate's own directory). The project does not change until you have read what it proposes (agents.proposal) and brought it in (agents.apply: all of it as uncommitted changes, or none of it when the project changed in the same places meanwhile) or dropped it (agents.discard). The copy holds what is committed: uncommitted changes and ignored files such as installed dependencies are not in it.
• The agent works in the project folder with its own account, quota and tools. What it asks you (approvals, questions) appears in the workbench and as a notification in VS Code and Obsidian, and you answer it at your computer.
• Collaboration inside one vendor (Claude Code sessions messaging each other, Codex sub-agents) is done natively by them. DevMate covers the part between clients, for example handing a task from ChatGPT on the web to Claude Code on your machine.

For several agents exchanging messages and tasks in one workflow, use the finer workflow.*, agents.*, message.* and task.* operations, or the workbench.

Workbench

devmate ui --open opens the workbench in your browser: projects, files, changes, commands, editor problems, agents and their activity, messages, tasks, approvals, artifacts and references. open_devmate_workbench opens the same interface inside clients that support MCP Apps (ChatGPT, Claude and others); there it shows everything, while sharing a folder and answering an agent stay at your computer.

Troubleshooting

Run devmate doctor first. It names the item that is wrong and how to fix it.

Uninstalling

Removing the extension or the plugin does not stop the runtime, because other entries may be using it. Stop it first (Stop DevMate Runtime, or devmate stop), then uninstall. Everything DevMate keeps is in the instance directory (~/.devmate/runtime by default): delete it to remove the state, the credentials and the restorable file versions. Your project files are never touched by this.

Data and retention

State lives in one SQLite database in the instance directory. The event journal, operation receipts, finished jobs and approvals, and restorable file versions are pruned after retentionDays (default 30). Projects, workflows, messages and tasks are not pruned.

Compatibility

These are treated as public: the names and parameters of the tools above, operation names, configuration keys, command-line commands and the workbench resource ui://devmate/workbench/v1. A change to any of them is listed in the changelog. A test pins the tool names and parameters, so none changes by accident. The stored state carries a format number: a release never touches state written by a newer one and says which versions are involved.

Development

npm ci
npm run lint               # mistakes only: undefined names, unreachable code and the like
npm run check              # manifest, versions, pinned workflow actions, syntax
npm run test:unit          # the whole test suite
npm run test:vscode-host   # the extension in a real VS Code: two editors and a third window on one runtime
npm run candidate          # build once, smoke-test that build as packaged, write what a release publishes to dist/release/

Pushing a tag X.Y.Z that matches the package version (no v) verifies that commit and publishes the GitHub release and the VS Code Marketplace version. CONTRIBUTING.md describes the release steps.

Every operation is defined once in runtime/operations/ and authorised by the registry in runtime/service.mjs. MCP, the command line and the workbench all get it from there.

Documentation

• Capabilities: browser, Godot, reverse engineering, Obsidian
• Security policy and its known limits
• Changelog
• Contributing and releasing · Support · Code of conduct
• Status (in Chinese): what is not done yet, what could not be verified, and measured performance

License

MIT