Skip to content

refactor: make DevSpace a native MCP runtime #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ssfxx0923 merged 1 commit into from
Aug 7, 2026
Merged

refactor: make DevSpace a native MCP runtime #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 15 additions & 18 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# DevSpace

DevSpace is a local development execution layer for MCP hosts such as ChatGPT and Claude. It gives a remote host workspace-scoped tools for reading, editing, searching, running commands, managing Git worktrees, reviewing changes, and coordinating bounded subagents on the user's machine.
DevSpace is a local development execution layer for MCP hosts such as ChatGPT and Claude. It gives a remote host workspace-scoped tools for reading, editing, searching, running commands, managing Git worktrees, and reviewing changes on the user's machine.

Pi's SDK currently provides mature local coding primitives. DevSpace wraps those primitives in a Streamable HTTP MCP server and adds the product-specific boundaries around them: approved roots, workspace state, instructions, process sessions, worktrees, artifacts, review checkpoints, widgets, and subagent execution.
Pi's SDK currently provides mature local coding primitives. DevSpace wraps those primitives in a Streamable HTTP MCP server and adds the product-specific boundaries around them: approved roots, workspace state, instructions, process sessions, worktrees, artifacts, review checkpoints, and widgets. The MCP host is the coding agent; DevSpace must not invoke models or coding-agent providers.

DevSpace owns tooling mechanics. The model receives only meaningful and actionable choices. The user sees outcomes. Tool defination should not leak internal implementation or it shoudn't be giving unwanted options to model to choose from if tooling can handle this.

Expand All @@ -13,9 +13,9 @@ These ideas should stay true as the project evolves:
1. **The host is the orchestrator.** DevSpace exposes clear capabilities and execution state. It should not hide the workflow inside an opaque, uninspectable agent loop.
2. **Everything happens in a workspace.** A workspace represents one local project directory or worktree plus the instructions and state accumulated while operating in it.
3. **Local authority stays explicit.** DevSpace runs with access to the user's machine. Roots, paths, commands, processes, credentials, and destructive operations must be treated as product boundaries.
4. **Subagents are bounded workers.** A subagent should have an explicit task, profile, working context, lifecycle, and result that the host can inspect and coordinate.
5. **Adapters stay at the edges.** Pi, MCP hosts, and model providers each have their own terminology and capabilities. Provider-specific behavior should not become the core domain model.
6. **Prefer composable primitives.** Build a small set of reliable operations that can be combined into larger workflows instead of baking every workflow into the server.
4. **The host is the agent.** DevSpace exposes runtime tools and never delegates coding or reasoning to another model or coding-agent provider.
5. **Adapters stay at the edges.** Pi and MCP hosts have their own terminology and capabilities. Adapter-specific behavior should not become the core domain model.
6. **Prefer composable primitives.** Build a small set of reliable operations that can be combined into larger workflows instead of baking workflows into the server.

## Glossary

Expand All @@ -26,11 +26,9 @@ These ideas should stay true as the project evolves:
- **Allowed root** — a configured filesystem boundary within which a workspace may be opened. It is not itself necessarily a workspace.
- **Checkout mode** — operating on an existing checkout supplied by the user.
- **Worktree mode** — operating in an isolated Git worktree.
- **Tool surface** — the tools exposed by a configured mode, such as minimal, full, or Codex-compatible.
- **Tool surface** — the tools exposed by a configured mode, such as native, minimal, or full.
- **Process session** — a long-running command tracked for later input, output, or termination.
- **Instruction file** — an `AGENTS.md` or `CLAUDE.md` discovered while navigating a workspace.
- **Subagent** — a bounded model invocation delegated and coordinated by the host.
- **Agent profile** — the model, provider, tools, and instructions used for a subagent.
- **Artifact** — an output surfaced for the host or user to inspect.
- **Review checkpoint** — stored state representing a coherent set of changes.
- **Widget** — host-rendered UI/Cards attached to an MCP response.
Expand All @@ -47,9 +45,9 @@ Keep tunnel ownership and credentials with the user. DevSpace may operate throug

## Diagnose the correct layer

A failure may belong to the host, MCP transport, DevSpace, a Pi adapter, a provider, a model, a tool implementation, or the target project. Preserve the original error and identify the failing boundary before changing code.
A failure may belong to the host, MCP transport, DevSpace, a Pi primitive, a tool implementation, or the target project. Preserve the original error and identify the failing boundary before changing code.

An adapter exception is not evidence that a model failed. A successful command is not evidence that a GUI opened, a host refreshed, or a user-visible workflow succeeded.
A successful command is not evidence that a GUI opened, a host refreshed, or a user-visible workflow succeeded.

Do not expand DevSpace's responsibility while fixing a local symptom. Host UI, provider model naming, tunnel management, and duplicated review experiences require an explicit product decision.

Expand All @@ -62,7 +60,7 @@ Determine how the user will consume the change and verify that path. Behavior ma
- a fresh process and a server or host that needs restarting;
- checkout mode and worktree mode;
- Linux, macOS, and Windows Bash environments;
- minimal, full, and Codex-compatible tool surfaces;
- native, minimal, and full tool surfaces;
- widgets enabled, disabled, or limited to change review.

State clearly when only a narrower proxy was verified. For model-facing schemas, inspect what the host receives. For UI and artifacts, inspect the rendered result rather than inferring success from the producing command.
Expand All @@ -75,7 +73,7 @@ When changing a cross-cutting concept, check every surface it actually reaches:
- workspace lifecycle and instruction loading;
- allowed-root and path-containment behavior;
- checkout and worktree modes;
- process and subagent lifecycle;
- process lifecycle;
- tool-surface filtering;
- widgets, artifacts, and review checkpoints;
- persistence and migrations;
Expand All @@ -94,25 +92,24 @@ For UI changes, include before/after images and a short interaction video when b
## Where code lives

- `src/server.ts` — MCP server setup, tool registration, and response wiring.
- `src/workspaces.ts` — workspace lifecycle, instructions, skills, and profiles.
- `src/workspaces.ts` — workspace lifecycle, instructions, and skills.
- `src/roots.ts` — allowed roots and path containment.
- `src/process-sessions.ts` — long-running process lifecycle.
- `src/git.ts` and `src/git-worktrees.ts` — Git and worktree operations.
- `src/local-agent-*.ts` — subagent configuration, providers, and execution.
- `src/artifact-*.ts` and `src/incoming-artifacts.ts` — artifact handling.
- `src/review-checkpoints.ts` — persisted change-review checkpoints.
- `src/ui/` — MCP widgets.
- `src/db/` — persisted local state and migrations.
- `test/` — behavior and regression tests.

Start at the boundary named by the problem and follow the data. Keep policy in DevSpace, provider translation in adapters, and important behavior in schemas, types, checks, or explicit tool results rather than hidden prompt conventions.
Start at the boundary named by the problem and follow the data. Keep policy in DevSpace and important behavior in schemas, types, checks, or explicit tool results rather than hidden prompt conventions.

## Project taste

- Prefer explicit lifecycle and state over hidden autonomy.
- Make tasks, inputs, outputs, failures, and ownership inspectable.
- Keep subagent execution composable and independently testable.
- Preserve host and provider data unless DevSpace has a concrete reason to normalize it.
- Keep runtime operations composable and independently testable.
- Preserve host data unless DevSpace has a concrete reason to normalize it.
- Add compatibility behavior only for an identified consumer with a real upgrade path.
- Reuse glossary terms in schemas, types, documentation, and errors.
- Keep the execution layer small, reliable, and unsurprising.
- Keep the execution layer small, reliable, and unsurprising.
29 changes: 10 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<h1 align="center">DevSpace</h1>

<p align="center">Bring a Codex-style coding workflow to ChatGPT.</p>
<p align="center">A local coding MCP runtime for ChatGPT.</p>

<p align="center">
<a href="https://www.npmjs.com/package/@waishnav/devspace"><img alt="npm" src="https://img.shields.io/npm/v/%40waishnav%2Fdevspace?style=flat-square" /></a>
Expand All @@ -16,9 +16,9 @@

[![DevSpace connected to ChatGPT](https://raw.githubusercontent.com/Waishnav/devspace/main/docs/assets/devspace-screenshot.png)](https://raw.githubusercontent.com/Waishnav/devspace/main/docs/assets/devspace-screenshot.png)

**Give ChatGPT a secure connection to your own machine and Turn ChatGPT into Codex**
**ChatGPT is the coding agent. DevSpace is the local runtime and tool layer.**

DevSpace is a self-hosted MCP server that lets ChatGPT read, edit, search, and run code in your real local projects — your files, your tools, your terminal — without uploading anything to a third party. You run it on your machine, expose it through a tunnel you control, and approve the connection with a password only you have.
DevSpace is a self-hosted MCP server that lets ChatGPT and other MCP hosts directly work with local projects through workspace-scoped filesystem tools, native shell execution, persistent process sessions, Git worktrees, artifacts, and change review. DevSpace does not invoke another coding model or coding-agent provider behind the scenes.

## Sponsors and Special Thanks

Expand Down Expand Up @@ -133,21 +133,20 @@ and show you what changed.

DevSpace gives ChatGPT tools to:

- read, write, and edit files inside the opened workspace
- search code and inspect directories
- run shell commands for tests, builds, git, and package scripts
- read and search files inside the opened workspace
- apply structured patches for precise source changes
- run normal local development commands, including file operations, Git, package managers, generators, tests, builds, and project scripts
- keep long-running and interactive processes available through persistent process sessions
- use isolated Git worktrees for parallel coding sessions
- follow project instructions from `AGENTS.md` and `CLAUDE.md`
- discover local agent skills from your skill folders
- show tool cards and optional change summaries in ChatGPT Apps-compatible hosts

## Mental Model

DevSpace is remote access to selected local folders.
The MCP host is the coding agent. DevSpace is remote access to selected local folders and the local development runtime.

You decide which roots are allowed. The MCP client still has powerful local
capabilities inside an opened workspace, including shell execution. Treat a
connected client like a trusted coding partner with access to your machine.
You decide which roots are allowed for structured filesystem tools. Shell commands run with the authority of the local user running DevSpace and are not an OS sandbox. Treat a connected client like a trusted coding partner with access to your machine.

For a normal ChatGPT coding session:

Expand Down Expand Up @@ -189,15 +188,7 @@ devspace doctor
Every piece of software is becoming conversational. Natural language is
redefining how we interact with tools, workflows, and systems.

My bet is that ChatGPT becomes the operating system for everything. Once we
reach AGI, we will simply talk to ChatGPT, and it will prompt, coordinate, and
orchestrate sub-agents that set up the right loops for us.

We are not there yet.

DevSpace is one attempt to fast-forward that future: a way for MCP-capable
hosts like ChatGPT and Claude to work directly with local project files through
explicit, inspectable tools.
DevSpace keeps that relationship direct: MCP-capable hosts such as ChatGPT and Claude perform the reasoning and coding work themselves, while DevSpace provides explicit, inspectable access to the local development environment.

## Built by Waishnav

Expand Down
165 changes: 0 additions & 165 deletions docs/agent-profile-schema.md
View file
Open in desktop

This file was deleted.

Loading
Loading