# GitHub Codespaces setup

GitHub Codespaces provides a cloud-based development environment that runs VS Code in your browser. This is the fastest way to start developing Comind.work apps without installing anything locally.

Alternative: Local development

You can [set up your local environment](/developer-guide/getting-started/local-environment.md) if you prefer, but you'll need to install Node.js, npm, and VS Code on your machine.

## Getting started with Codespaces[​](#getting-started-with-codespaces "Direct link to Getting started with Codespaces")

### Step 1: Get repository access[​](#step-1-get-repository-access "Direct link to Step 1: Get repository access")

Ask your admin for access to your organization's GitHub repository, typically located at:

```
https://github.com/comindwork/your-org
```

### Step 2: Create a Codespace[​](#step-2-create-a-codespace "Direct link to Step 2: Create a Codespace")

1. Navigate to your organization's GitHub repository
2. Click the green **"Code"** button in the repository
3. Select the **"Codespaces"** tab
4. Click **"Create codespace on main"**

![GitHub Codespaces creation interface](/assets/images/gh-code-spaces-950fdeca3e74049b9559d2d2a892c699.png)

### Step 3: Wait for environment setup[​](#step-3-wait-for-environment-setup "Direct link to Step 3: Wait for environment setup")

Your Codespace will automatically:

* Launch a web-based VS Code editor
* Install Node.js and dependencies (`npm install`)
  <!-- -->
  * if `npm install` fails - you might need to update node-version with `nvm install 22.13.0` and run again `npm install`
* Set up the development environment

Extension installation

When prompted with "Do you want to install recommended extensions?", click **Yes**. These extensions provide helpful tools for Comind.work app development.

![GitHub Codespaces VS Code interface](/assets/images/gh-codespaces-main-68b26b1ede6c409bb4d0dc665e245ee2.png)

## Set up Claude Code[​](#set-up-claude-code "Direct link to Set up Claude Code")

Claude Code in Codespaces requires a devcontainer configuration. Your repository should already include a `.devcontainer/` folder with the necessary setup. If it does not, follow the [Claude Code devcontainer guide](https://code.claude.com/docs/en/devcontainer) to add one.

When you create a Codespace from a repository that has a devcontainer configured for Claude Code:

1. Claude Code is automatically installed in the container
2. Open the Claude Code panel from the sidebar, or run `claude` in the terminal
3. When prompted to sign in, follow the authentication flow

### Install the Comind.work development skill[​](#install-the-comindwork-development-skill "Direct link to Install the Comind.work development skill")

The development skill teaches Claude how Comind.work apps are structured - fields, actions, layouts, deployment commands:

1. In the Claude panel, type `/plugins`
2. Add the comind-dev marketplace plugin from the link your admin provides
3. Type `/reload plugins` to activate
4. Verify by asking Claude to describe an app in your repository

The skill is a curated markdown file (\~30 KB) built from patterns across hundreds of real apps. It does not auto-update when new versions are published - re-run `/plugins` periodically to get the latest version.

## Verify your setup[​](#verify-your-setup "Direct link to Verify your setup")

Test that everything is working correctly by running these commands in the Terminal:

```
# Copy sample environment variables
cp .config/dev.env.sample .config/dev.env

# Run the test suite
npm test
```

If both commands succeed, you're ready to start developing!

## Next steps[​](#next-steps "Direct link to Next steps")

✅ **Setup complete!** You can now:

* [Configure environment variables](/developer-guide/getting-started/environment-variables.md) for your organization
* [Start developing apps](/developer-guide/getting-started/start-app-development.md)
* Learn about [commit signing](/developer-guide/getting-started/sign-commits.md) if you need admin privileges

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**Codespace won't start?**

* Check that you have access to the repository
* Try refreshing the page and creating a new Codespace

**Extensions not working?**

* Reload the window: `Ctrl+Shift+P` → "Developer: Reload Window"
* Manually install extensions from the Extensions panel

**Claude extension panel is blank or won't load?**

* Try reloading the window first
* If the panel still does not appear, use the terminal CLI instead: open the integrated terminal and run `claude`
* As a last resort, [set up Claude Code Desktop locally](/developer-guide/getting-started/local-environment.md#claude-code-desktop) and work from a local clone

**Terminal commands failing?**

* Ensure the setup process completed (check for any error messages)
* Try running `npm install` manually