By name: create-codespace description: Create a GitHub Codespace for a repo
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
- If the user doesn't specify a repo, ask them for one.
- Run the script. Pass any overrides the user mentioned.
- If this is the user's first time creating a codespace for this repo, add
--save-aswith a short name (e.g. the repo name) so they can reuse it later. - Report the result: codespace name, machine, state. If a profile was saved, mention they can use
--profile <name>next time.