# Claude Code setup

Claude Code is an AI coding assistant that can read, write, and deploy Comind.work apps directly from your terminal. With the **comind-dev** plugin installed, it understands the app engine - fields, actions, layouts, deployment commands, and testing patterns - so you can describe changes in plain language and have them applied to your codebase.

info

Claude Code is optional - you can develop Comind.work apps with any editor. This guide covers the AI-assisted workflow.

## Prerequisites[​](#prerequisites "Direct link to Prerequisites")

Before setting up Claude Code, make sure you have:

* A working development environment - either [local](/developer-guide/getting-started/local-environment.md) or [GitHub Codespaces](/developer-guide/getting-started/github-codespaces.md)
* Your organization's repository cloned and `npm install` completed
* A `.config/dev.env` file configured with your credentials (see [environment variables](/developer-guide/getting-started/environment-variables.md))

## Installing Claude Code[​](#installing-claude-code "Direct link to Installing Claude Code")

### Desktop app (recommended)[​](#desktop-app-recommended "Direct link to Desktop app (recommended)")

The standalone desktop app works on macOS, Windows, and Linux. It runs Claude Code in a built-in terminal with preview panels for web content.

1. Download the installer from <https://claude.ai/download>
2. Run the installer and sign in with your Anthropic account
3. Open your project folder from **File > Open Folder**

The desktop app provides the best experience for app development because it can render live previews of deployed apps inline.

### VS Code extension[​](#vs-code-extension "Direct link to VS Code extension")

If you prefer to stay in VS Code (or a VS Code-based editor like Cursor):

1. Open VS Code
2. Go to **Extensions** (`Ctrl+Shift+X`)
3. Search for **"Claude Code"** and install the Anthropic extension
4. Open the Claude Code panel from the sidebar or run `Claude Code: Open` from the command palette (`Ctrl+Shift+P`)

tip

The extension works in VS Code Desktop and in browser-based VS Code (GitHub Codespaces). If the extension panel appears blank in Codespaces, see [Known issues](#claude-extension-blank-in-github-codespaces) below.

## Adding the Comind.work developer plugin[​](#adding-the-comindwork-developer-plugin "Direct link to Adding the Comind.work developer plugin")

The **comind-dev** plugin adds skills that teach Claude Code how to work with the Comind.work app engine. The plugin source is available at [github.com/comindwork/claude-code-plugins](https://github.com/comindwork/claude-code-plugins). Install it from the Comind.work plugin marketplace.

### Step 1: Register the marketplace[​](#step-1-register-the-marketplace "Direct link to Step 1: Register the marketplace")

Run this command in the Claude Code terminal (or any terminal where `claude` is on your PATH):

```
claude plugin marketplace add comindwork/claude-code-plugins
```

### Step 2: Install the plugin[​](#step-2-install-the-plugin "Direct link to Step 2: Install the plugin")

```
claude plugin install comind-dev@comind-claude-code-plugins
```

This installs at **user scope** (available in all projects). To install per-project instead:

```
claude plugin install comind-dev@comind-claude-code-plugins --scope project
```

### Step 3: Verify the installation[​](#step-3-verify-the-installation "Direct link to Step 3: Verify the installation")

Start a new Claude Code session in your project folder and type:

```
/plugins
```

You should see `comind-dev` listed with its skills: `apps-dev`, `apps-test`, and `plugins-dev`.

## Working with skills[​](#working-with-skills "Direct link to Working with skills")

### Loading and invoking skills[​](#loading-and-invoking-skills "Direct link to Loading and invoking skills")

Skills are loaded automatically when the plugin is installed. To invoke a skill, use its slash command:

```
/comind-dev:apps-dev app-org-task
```

This tells Claude Code to load the `apps-dev` skill with `app-org-task` as the target app folder. After loading, Claude understands your app's fields, actions, layouts, and settings - and can make changes when you describe what you need.

You can also invoke skills without the plugin prefix if there's no ambiguity:

```
/apps-dev app-org-task
```

If you've just installed or updated a plugin and the slash command isn't recognized, reload plugins:

```
/reload plugins
```

Feeding the skill manually

If the slash command fails for any reason (parsing error, plugin not recognized), you can feed the skill file directly using the `@file` syntax:

```
@SKILL.md app-org-task
```

Point the `@file` reference to the `SKILL.md` file in the plugin's skill directory. Claude Code will read the file and apply it as context for the conversation.

### Updating skills[​](#updating-skills "Direct link to Updating skills")

**Marketplace installs** update automatically when the plugin author publishes a new version. To force a manual update:

```
claude plugin marketplace update comind-claude-code-plugins
claude plugin update comind-dev@comind-claude-code-plugins
```

If you installed with `--scope project`, add `--scope project` to the update command as well.

**Manual copies** (skill files copied directly into your project) do not auto-update. You must re-download the latest version from the marketplace whenever the skill changes.

### Token budget awareness[​](#token-budget-awareness "Direct link to Token budget awareness")

Each skill file consumes tokens from your context window when loaded. The `apps-dev` skill is approximately 30 KB of text, which translates to roughly 8,000 tokens.

Keep this in mind when working on complex tasks:

* Load only the skills you need for the current task
* If you're running low on context in a long session, start a new conversation rather than stacking multiple skills
* The skill stays loaded for the entire conversation - you don't need to reload it after each message

## Choosing an interface[​](#choosing-an-interface "Direct link to Choosing an interface")

Claude Code runs in three interfaces. Each has the same skill and plugin support - the difference is in workflow and visibility.

| Interface                             | Best for                                                                                      | Trade-offs                                                                                                                                         |
| ------------------------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Terminal CLI** (`claude` command)   | Experienced developers who want full control, transparent output, and multi-session workflows | No visual preview panel; all output is text-based                                                                                                  |
| **VS Code extension - panel mode**    | Developers who want a chat-style UI alongside their editor, file tree, and Git panel          | Panel can be blank in Codespaces (see [known issues](#claude-extension-blank-in-github-codespaces)); hides some tool output behind UI abstractions |
| **VS Code extension - terminal mode** | Developers who want the full CLI experience without leaving VS Code                           | Same transparency as the standalone terminal, but integrated into the VS Code terminal pane                                                        |
| **Desktop app**                       | New users or those who want inline preview panels for deployed apps                           | Separate window from your main editor; requires a local clone                                                                                      |

The VS Code extension supports both modes. Toggle between them using the switcher in the extension's sidebar panel. Terminal mode gives you the same text-based output as the standalone CLI, while panel mode provides a chat-style interface with rendered markdown and inline diffs.

Start with terminal mode

If you are unsure which interface to use, start with terminal mode - either standalone or inside VS Code. It is the most reliable across all environments (local, Codespaces, SSH) and shows exactly what Claude is doing. You can switch to panel mode or the Desktop app later without losing your plugin or skill configuration.

## Known issues and workarounds[​](#known-issues-and-workarounds "Direct link to Known issues and workarounds")

### Claude extension blank in GitHub Codespaces[​](#claude-extension-blank-in-github-codespaces "Direct link to Claude extension blank in GitHub Codespaces")

The Claude Code VS Code extension sometimes renders as a blank white panel in browser-based Codespaces. This appears to be a webview initialization issue in the remote environment.

**Workaround:** Use the Claude Code CLI directly in the Codespaces terminal instead of the extension panel:

```
claude
```

This starts an interactive Claude Code session in the terminal with full functionality. All slash commands and skills work the same way.

### Localhost redirect during authentication[​](#localhost-redirect-during-authentication "Direct link to Localhost redirect during authentication")

When authenticating Claude Code inside a Codespace, the OAuth flow may redirect to `localhost` instead of the Codespace's forwarded URL. The browser opens a local address that doesn't resolve, and authentication fails silently.

**Workaround:** Complete the authentication flow on your local machine first, then let the credentials sync to your Codespace. Alternatively, copy the authentication token manually from your local Claude Code configuration.

### Skill file parsing errors[​](#skill-file-parsing-errors "Direct link to Skill file parsing errors")

If you see an error like "malformed skill file" or "unexpected frontmatter", the skill file may contain extra frontmatter delimiters (`---`) or duplicate YAML blocks.

**Fix:** Open the skill's `SKILL.md` file and check the top of the file. A valid skill file has exactly one frontmatter block:

```
---
name: apps-dev
description: Skill for developing Comind.work apps.
---

# Skill content starts here
```

Delete any duplicate `---` lines or repeated YAML keys. This can happen when a file is copied or merged incorrectly.

### Claude refuses to edit environment files[​](#claude-refuses-to-edit-environment-files "Direct link to Claude refuses to edit environment files")

Claude Code has a built-in safety check that prevents it from editing `.env` files to avoid accidentally exposing secrets. When you ask it to update `.config/dev.env` or similar files, it will refuse or ask for confirmation.

**Workaround:** When Claude Code prompts you to approve the edit, review the proposed changes and approve manually. This is expected behavior - the safety check is there to prevent accidental secret exposure.

warning

Never paste API tokens, passwords, or other secrets directly into the Claude Code chat. Edit environment files yourself or approve Claude's proposed edits after reviewing them. Secrets pasted into chat are sent to the API and may appear in conversation logs.

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

Your Claude Code setup is complete. You can now:

* [Start developing apps](/developer-guide/getting-started/start-app-development.md) with AI-assisted or manual workflows
* [Configure environment variables](/developer-guide/getting-started/environment-variables.md) for your organization
* [Set up commit signing](/developer-guide/getting-started/sign-commits.md) if you deploy to production