Skills › Compound Engineering › ce-polish › launch-json-schema.md
launch-json-schema.md
177 lines · skills/ce-polish/references/launch-json-schema.md at 3449230
Most marks come from matching words in the file, so treat them as pointers.
1# `.claude/launch.json` schema
3Polish reads `.claude/launch.json` at the repo root to resolve the dev-server start command. The schema is a subset of VS Code's `launch.json` format — chosen because Claude Code, Cursor, and VS Code all understand it and because users often already have one for editor integration.
.claude/launch.json schema
Polish reads .claude/launch.json at the repo root to resolve the dev-server start command. The schema is a subset of VS Code's launch.json format — chosen because Claude Code, Cursor, and VS Code all understand it and because users often already have one for editor integration.
5## Top-level shape
7```json
8{
9 "version": "0.2.0",
10 "configurations": [
11 {
12 "name": "<human label>",
13 "runtimeExecutable": "<binary>",
14 "runtimeArgs": ["<arg>", "<arg>"],
15 "port": <number>,
16 "cwd": "<optional, repo-relative>",
17 "env": { "<key>": "<value>" }
18 }
19 ]
20}
21```
Top-level shape
{
"version": "0.2.0",
"configurations": [
{
"name": "<human label>",
"runtimeExecutable": "<binary>",
"runtimeArgs": ["<arg>", "<arg>"],
"port": <number>,
"cwd": "<optional, repo-relative>",
"env": { "<key>": "<value>" }
}
]
}23## Fields polish consumes
25| Field | Required | Purpose |
26|-------|----------|---------|
27| `name` | yes (when multiple configurations) | Used to disambiguate when the array has more than one entry. Polish asks the user to pick by `name`. |
28| `runtimeExecutable` | yes | The binary polish spawns (e.g., `bin/dev`, `npm`, `overmind`, `bun`). |
29| `runtimeArgs` | no | Array of arguments passed to `runtimeExecutable`. Default: empty array. |
30| `port` | no | The dev-server port. A numeric value completes the tuple's port fact; when the command, working directory, and environment are also usable, no project detection or resolver runs. When omitted, polish resolves only the missing port from the selected project type. The port seeds `http://localhost:<port>` as the default endpoint candidate; server evidence or a user correction may replace that candidate, so the schema does not lock the URL scheme. |
31| `cwd` | no | Repo-relative working directory for the dev server. Default: repo root. Useful for monorepos (`apps/web`, `packages/frontend`). |
32| `env` | no | Additional environment variables for the dev-server process. Default: inherit polish's environment. |
Fields polish consumes
| Field | Required | Purpose |
|---|---|---|
name | yes (when multiple configurations) | Used to disambiguate when the array has more than one entry. Polish asks the user to pick by name. |
runtimeExecutable | yes | The binary polish spawns (e.g., bin/dev, npm, overmind, bun). |
runtimeArgs | no | Array of arguments passed to runtimeExecutable. Default: empty array. |
port | no | The dev-server port. A numeric value completes the tuple's port fact; when the command, working directory, and environment are also usable, no project detection or resolver runs. When omitted, polish resolves only the missing port from the selected project type. The port seeds http://localhost:<port> as the default endpoint candidate; server evidence or a user correction may replace that candidate, so the schema does not lock the URL scheme. |
cwd | no | Repo-relative working directory for the dev server. Default: repo root. Useful for monorepos (apps/web, packages/frontend). |
env | no | Additional environment variables for the dev-server process. Default: inherit polish's environment. |
Starts an agent spawns :28
Runs code bin/dev :28
34## Stub template (written on first run when user accepts)
36When auto-detection completes a missing tuple fact and the user confirms "Save this as `.claude/launch.json`?", polish writes the completed tuple. Preserve facts from a selected configuration and add only what was resolved; use the recipe templates below when auto-detection supplied the command. These templates intentionally hard-code common defaults — users can edit them later.
Stub template (written on first run when user accepts)
When auto-detection completes a missing tuple fact and the user confirms "Save this as .claude/launch.json?", polish writes the completed tuple. Preserve facts from a selected configuration and add only what was resolved; use the recipe templates below when auto-detection supplied the command. These templates intentionally hard-code common defaults — users can edit them later.
38### Rails stub
40```json
41{
42 "version": "0.2.0",
43 "configurations": [
44 {
45 "name": "Rails dev",
46 "runtimeExecutable": "bin/dev",
47 "runtimeArgs": [],
48 "port": 3000
49 }
50 ]
51}
52```
Rails stub
{
"version": "0.2.0",
"configurations": [
{
"name": "Rails dev",
"runtimeExecutable": "bin/dev",
"runtimeArgs": [],
"port": 3000
}
]
}Runs code bin/dev :46
54### Next.js stub
56```json
57{
58 "version": "0.2.0",
59 "configurations": [
60 {
61 "name": "Next dev",
62 "runtimeExecutable": "npm",
63 "runtimeArgs": ["run", "dev"],
64 "port": 3000
65 }
66 ]
67}
68```
Next.js stub
{
"version": "0.2.0",
"configurations": [
{
"name": "Next dev",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 3000
}
]
}70### Vite stub
72```json
73{
74 "version": "0.2.0",
75 "configurations": [
76 {
77 "name": "Vite dev",
78 "runtimeExecutable": "npm",
79 "runtimeArgs": ["run", "dev"],
80 "port": 5173
81 }
82 ]
83}
84```
Vite stub
{
"version": "0.2.0",
"configurations": [
{
"name": "Vite dev",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 5173
}
]
}86### Procfile / Overmind stub
88```json
89{
90 "version": "0.2.0",
91 "configurations": [
92 {
93 "name": "Overmind dev",
94 "runtimeExecutable": "overmind",
95 "runtimeArgs": ["start", "-f", "Procfile.dev"],
96 "port": 3000
97 }
98 ]
99}
100```
Procfile / Overmind stub
{
"version": "0.2.0",
"configurations": [
{
"name": "Overmind dev",
"runtimeExecutable": "overmind",
"runtimeArgs": ["start", "-f", "Procfile.dev"],
"port": 3000
}
]
}102### Nuxt stub
104```json
105{
106 "version": "0.2.0",
107 "configurations": [
108 {
109 "name": "Nuxt dev",
110 "runtimeExecutable": "npm",
111 "runtimeArgs": ["run", "dev"],
112 "port": 3000
113 }
114 ]
115}
116```
Nuxt stub
{
"version": "0.2.0",
"configurations": [
{
"name": "Nuxt dev",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 3000
}
]
}118### Astro stub
120```json
121{
122 "version": "0.2.0",
123 "configurations": [
124 {
125 "name": "Astro dev",
126 "runtimeExecutable": "npm",
127 "runtimeArgs": ["run", "dev"],
128 "port": 4321
129 }
130 ]
131}
132```
Astro stub
{
"version": "0.2.0",
"configurations": [
{
"name": "Astro dev",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 4321
}
]
}134### Remix stub
136```json
137{
138 "version": "0.2.0",
139 "configurations": [
140 {
141 "name": "Remix dev",
142 "runtimeExecutable": "npm",
143 "runtimeArgs": ["run", "dev"],
144 "port": 3000
145 }
146 ]
147}
148```
Remix stub
{
"version": "0.2.0",
"configurations": [
{
"name": "Remix dev",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 3000
}
]
}150### SvelteKit stub
152```json
153{
154 "version": "0.2.0",
155 "configurations": [
156 {
157 "name": "SvelteKit dev",
158 "runtimeExecutable": "npm",
159 "runtimeArgs": ["run", "dev"],
160 "port": 5173
161 }
162 ]
163}
164```
SvelteKit stub
{
"version": "0.2.0",
"configurations": [
{
"name": "SvelteKit dev",
"runtimeExecutable": "npm",
"runtimeArgs": ["run", "dev"],
"port": 5173
}
]
}166## Why a subset of VS Code's schema
168Polish does not use `type`, `request`, `console`, `stopOnEntry`, or any of the other VS Code fields. Including them is harmless — polish ignores them — but the stub writer never adds them. The fields polish cares about are the ones that describe *how to start a long-running dev server on a known port*, which is a smaller surface than what VS Code uses for debug-stepping.
Why a subset of VS Code's schema
Polish does not use type, request, console, stopOnEntry, or any of the other VS Code fields. Including them is harmless — polish ignores them — but the stub writer never adds them. The fields polish cares about are the ones that describe how to start a long-running dev server on a known port, which is a smaller surface than what VS Code uses for debug-stepping.
170## Cross-IDE notes
172`.claude/launch.json` is not yet a fully unified standard across Claude Code, Cursor, VS Code, and Codex. Polish leads with `.claude/launch.json` because:
173- Claude Code, Cursor, and VS Code can all read it as a launch config
174- It sits at a clean repo-root trust boundary (user-authored, not auto-detected)
175- Users who prefer `.vscode/launch.json` can symlink or mirror the two files manually
177If a cross-IDE standard emerges (e.g., `.workspace/launch.json`), the stub writer and reader can swap paths without touching the rest of the skill.
Cross-IDE notes
.claude/launch.json is not yet a fully unified standard across Claude Code, Cursor, VS Code, and Codex. Polish leads with .claude/launch.json because:
- Claude Code, Cursor, and VS Code can all read it as a launch config
- It sits at a clean repo-root trust boundary (user-authored, not auto-detected)
- Users who prefer
.vscode/launch.jsoncan symlink or mirror the two files manually
If a cross-IDE standard emerges (e.g., .workspace/launch.json), the stub writer and reader can swap paths without touching the rest of the skill.