create-codespace

Create Codespace

Do not run gh codespace create directly — it fails without --machine in non-interactive terminals.

Use the script at scripts/create-codespace.mjs relative to this skill's plugin directory:

node "$(dirname "$(dirname "$(cd "$(dirname "$0")" && pwd)")")/scripts/create-codespace.mjs" --repo <owner/repo> [options]

Options

Only --repo is required (unless --profile provides it). Everything else has smart defaults:

Flag	Default	Description
--repo	(required)	GitHub repo in owner/repo format
--branch	main	Branch to create from
--machine	auto-picked	Prefers prebuild-ready, then largest. Validated against the repo's available machines.
--devcontainer-path	auto-detected	Used if the repo has exactly one devcontainer config
--location	GitHub default	EastUs, WestUs2, WestEurope, SouthEastAsia
--display-name	none	Display name for the codespace
--profile	none	Load a saved profile as defaults. Explicit flags override profile values.
--save-as	none	Save the resolved config as a named profile for reuse.

Output

JSON with ok: true/false. On success: codespaceName, state, machine, machineDisplay, branch, devcontainerPath, timedOut.

On error: error message plus context (e.g. availableMachines if machine name was invalid).

Instructions

1. If the user doesn't specify a repo, ask them for one.
2. Run the script. Pass any overrides the user mentioned.
3. If this is the user's first time creating a codespace for this repo, add --save-as with a short name (e.g. the repo name) so they can reuse it later.
4. Report the result: codespace name, machine, state. If a profile was saved, mention they can use --profile <name> next time.