feat(init): onboard subagents for ChatGPT and Coding Agents

README.md

@@ -66,26 +66,28 @@ Install the DevSpace CLI:
 npm install -g @waishnav/devspace
 ```
 
-Then initialize and start the server:
+Then initialize DevSpace:
 
 ```bash
 devspace init
-devspace serve
 ```
 
 Or run it without a global install:
 
 ```bash
 npx @waishnav/devspace init
-npx @waishnav/devspace serve
 ```
 
 During setup, DevSpace asks for:
 
-- the local project folders ChatGPT is allowed to open through DevSpace
-- the local port, usually `7676`
-- your public HTTPS base URL from Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel, or
-  another reverse proxy
+- where you will use it: ChatGPT, Coding Agents, or both
+- which Coding Agents DevSpace may use
+
+If you select ChatGPT, setup also asks which local project folders it may open
+and for your public HTTPS base URL from Cloudflare Tunnel, ngrok, Pinggy,
+Tailscale Funnel, or another reverse proxy. A Coding Agents-only setup asks
+neither question: local commands use the current Git project, or the current
+directory outside a repository.
 
 Use the public origin without `/mcp` during setup:
 
@@ -94,6 +96,8 @@ https://your-tunnel-host.example.com
 ```
 
 You will configure your MCP client with the public `/mcp` URL after setup.
+Run `devspace serve` when using ChatGPT. For Coding Agents, setup prints a
+`skills` command and lets the Skills CLI handle installation.
 
 When the client connects, DevSpace opens an Owner password approval page. Enter
 the Owner password printed by `devspace init`. It is also stored in:

docs/chatgpt-coding-workflow.md

@@ -116,7 +116,7 @@ DevSpace discovers standard Agent Skills from:
 
 It also keeps compatibility with:
 
-- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
+- the bundled `subagents` skill when Subagents are enabled, unless `~/.devspace/skills/subagents/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
@@ -140,13 +140,13 @@ Skill paths may be outside the workspace. DevSpace only permits reading:
 - advertised `SKILL.md` files
 - files under a skill directory after that skill's `SKILL.md` has been read
 
-Set `DEVSPACE_SKILLS=0` to hide skills from workspace output. Set
-`DEVSPACE_SUBAGENTS=1` to expose the experimental subagent catalog and
-`subagent-delegation` skill. That skill teaches the minimal
-`devspace agents ls`, `devspace agents run`, `devspace agents continue`, and
-`devspace agents show`
-workflow. The catalog comes from `open_workspace`; `devspace agents ls` lists
-existing subagent sessions for that workspace.
+Set `DEVSPACE_SKILLS=0` to hide skills from workspace output. Enable Subagents
+and choose providers through `devspace init` or the persisted provider
+configuration. The bundled `subagents` skill teaches the minimal
+`devspace agents targets`, `devspace agents ls`, `devspace agents run`,
+`devspace agents continue`, and `devspace agents show` workflow. The catalog
+comes from `open_workspace`; `devspace agents ls` lists existing subagent
+sessions for that workspace.
 
 ## Tool Names
 

docs/configuration.md

@@ -136,7 +136,7 @@ DevSpace discovers standard Agent Skills from:
 
 It also keeps compatibility with:
 
-- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
+- the bundled `subagents` skill when Subagents are enabled, unless `~/.devspace/skills/subagents/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
@@ -185,10 +185,18 @@ descriptions, providers, and optional models/effort levels so the host model can
 agent without reading provider-specific launch details. Disabled or unavailable
 providers and their profiles are omitted from this model-facing catalog. `devspace agents ls`
 lists existing subagent sessions for the current workspace, scoped by the
-workspace environment injected into shell commands. The `subagent-delegation`
+workspace environment injected into shell commands. The `subagents`
 skill teaches the model to use only the minimal `devspace agents ls`,
-`devspace agents run`, `devspace agents continue`, and `devspace agents show`
-workflow.
+`devspace agents targets`, `devspace agents run`, `devspace agents continue`,
+and `devspace agents show` workflow.
+
+For Codex, Claude Code, OpenCode, Pi, or another supported Coding Agent, use
+the Skills CLI to install the same skill. DevSpace setup prints this command but
+does not run it or write into agent skill directories:
+
+```bash
+npx skills add Waishnav/devspace --skill subagents --global
+```
 
 Starter profile templates are available under `examples/agents/`. Copy or adapt
 them into one of the active profile directories before use.

docs/gotchas.md

@@ -154,9 +154,11 @@ DevSpace does not currently prune workspace sessions, conversation bindings,
 or review refs. A future product retention policy will define safe cleanup for
 these records; no automatic deletion is performed today.
 
-## Workspace Path Rejected
+## MCP Workspace Path Rejected
 
-The path must be inside one of the allowed roots configured during setup.
+The path passed to `open_workspace` must be inside one of the allowed roots
+configured during ChatGPT setup. Direct `devspace agents` commands instead use
+the current local project and are not gated by MCP allowed roots.
 
 Run:
 
@@ -216,21 +218,31 @@ DevSpace looks in standard Agent Skills locations:
 
 It also checks compatibility and custom paths:
 
-- the bundled `subagent-delegation` skill when `DEVSPACE_SUBAGENTS=1`, unless `~/.devspace/skills/subagent-delegation/SKILL.md` exists
+- the bundled `subagents` skill when Subagents are enabled, unless `~/.devspace/skills/subagents/SKILL.md` exists
 - `DEVSPACE_AGENT_DIR/skills`, defaulting to `~/.codex/skills`
 - additional paths from `DEVSPACE_SKILL_PATHS`
 
-When `DEVSPACE_SUBAGENTS=1`, DevSpace loads agent profiles from
+When Subagents are enabled, DevSpace loads agent profiles from
 `~/.devspace/agents/*.md` and project `.devspace/agents/*.md`, then exposes a
 compact profile catalog through `open_workspace`. The bundled
-`subagent-delegation` skill keeps the model-facing workflow to
-`devspace agents ls`, `devspace agents run`, `devspace agents continue`, and
-`devspace agents show`.
+`subagents` skill keeps the model-facing workflow to
+`devspace agents targets`, `devspace agents ls`, `devspace agents run`,
+`devspace agents continue`, and `devspace agents show`.
 Those commands automatically manage the internal local agent daemon; `devspace
 serve` is not a prerequisite.
 `devspace agents ls` lists existing subagent sessions, not profile
 definitions.
 
+For a Coding Agent, run the installation command printed by
+`devspace init`:
+
+```bash
+npx skills add Waishnav/devspace --skill subagents --global
+```
+
+The Skills CLI handles agent discovery and installation. DevSpace setup does
+not copy files into agent skill directories.
+
 Packaged agent profile examples under `examples/agents/` are starter templates.
 Copy or adapt them into one of the active profile directories before use.
 

docs/setup.md

@@ -1,18 +1,19 @@
 # Setup Guide
 
-This guide is for users who want ChatGPT or another MCP host to work in local
-projects through DevSpace.
+This guide covers ChatGPT and Coding Agents using DevSpace with local projects.
 
 ## Requirements
 
 - Node `>=22.19 <27`
 - npm
 - Git
 - Bash, including Git Bash or WSL on Windows
-- a public HTTPS URL that forwards to the local DevSpace server
+- a public HTTPS URL that forwards to the local DevSpace server, only when
+  ChatGPT will connect
 
-DevSpace does not create the public tunnel for you. Use Cloudflare Tunnel,
-ngrok, Pinggy, Tailscale Funnel, or your own HTTPS reverse proxy.
+DevSpace does not create the public tunnel for you. ChatGPT users can use
+Cloudflare Tunnel, ngrok, Pinggy, Tailscale Funnel, or their own HTTPS reverse
+proxy.
 
 ## Install And Configure
 
@@ -24,10 +25,13 @@ npx @waishnav/devspace init
 
 The setup flow asks one question at a time.
 
-### Project Roots
+First choose where you will use DevSpace: ChatGPT, Coding Agents, or both.
+DevSpace uses that answer to skip setup that does not apply to you.
 
-Choose the folders ChatGPT is allowed to open through DevSpace. Keep this
-narrow.
+### Project roots
+
+If you selected ChatGPT, choose the project folders it may open through
+DevSpace. Keep this narrow.
 
 Examples:
 
@@ -43,20 +47,31 @@ Examples:
 C:\Users\alice\dev,C:\Users\alice\work
 ```
 
-### Local Port
+A Coding Agents-only setup skips this question. Direct `devspace agents`
+commands use the current Git project, or the current directory outside a
+repository, with the authority of your local shell. MCP workspace operations
+remain limited to the roots configured for ChatGPT.
 
-The default is `7676`.
+### Coding Agents
 
-The local MCP URL is:
+Setup detects supported Coding Agents and asks which ones DevSpace may use.
+These choices are stored as provider objects under `subagents` in
+`~/.devspace/config.json`.
 
-```text
-http://127.0.0.1:7676/mcp
+If you selected Coding Agents, setup prints:
+
+```bash
+npx skills add Waishnav/devspace --skill subagents --global
 ```
 
-### Public Base URL
+The Skills CLI asks which installed Coding Agents should receive the skill.
+The skill uses `devspace agents targets`, `run`, `continue`, `show`, and `ls`.
+These commands do not require `devspace serve`.
+
+### Connect ChatGPT
 
-Start your tunnel or reverse proxy before entering this value. Point the tunnel
-at:
+Setup only asks for a public URL if you selected ChatGPT. Start your tunnel or
+reverse proxy first and point it at:
 
 ```text
 http://127.0.0.1:7676
@@ -74,6 +89,8 @@ Configure the MCP client with the full MCP endpoint:
 https://your-tunnel-host.example.com/mcp
 ```
 
+A Coding Agents-only setup skips this section.
+
 ## Start The Server
 
 Run:

package.json

@@ -29,7 +29,7 @@
     "dev": "node scripts/dev-server.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/cli-workspace.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-config.test.ts && tsx src/local-agent-catalog.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-daemon-lifecycle.test.ts && tsx src/local-agent-daemon-protocol.test.ts && tsx src/local-agent-daemon.test.ts && tsx src/local-agent-codex.test.ts && tsx src/local-agent-opencode.test.ts && tsx src/local-agent-acp.test.ts && tsx src/local-agent-pi-sandbox.test.ts && tsx src/local-agent-pi.test.ts && tsx src/local-agent-claude.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/local-agent-manager.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/onboarding.test.ts && tsx src/cli-workspace.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-config.test.ts && tsx src/local-agent-catalog.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-daemon-lifecycle.test.ts && tsx src/local-agent-daemon-protocol.test.ts && tsx src/local-agent-daemon.test.ts && tsx src/local-agent-codex.test.ts && tsx src/local-agent-opencode.test.ts && tsx src/local-agent-acp.test.ts && tsx src/local-agent-pi-sandbox.test.ts && tsx src/local-agent-pi.test.ts && tsx src/local-agent-claude.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/local-agent-manager.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "keywords": [],