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

Before setting up Claude Code, make sure you have:

• A working development environment - either local or GitHub Codespaces
• Your organization's repository cloned and npm install completed
• A .config/dev.env file configured with your credentials (see environment variables)

Installing Claude Code

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

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 below.

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. Install it from the Comind.work plugin marketplace.

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

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

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

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

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

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

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); 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

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

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

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 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

Your Claude Code setup is complete. You can now:

• Start developing apps with AI-assisted or manual workflows
• Configure environment variables for your organization
• Set up commit signing if you deploy to production