How to Set Up Windsurf (Codeium): A Practical Guide

TL;DR

• Install in 2 minutes: VS Code (ext install Codeium.codeium) or JetBrains (search "Codeium" in plugins).
• Cascade mode: Agentic workflows for multi-step coding (e.g., /refactor + /test).
• Free tier: Unlimited autocomplete, 50 chat requests/day. Pro ($12/user/month) unlocks unlimited chat.
• Privacy: No telemetry, self-hostable (Enterprise). Aligns with AI Security Posture Framework™ for PROTECT and COMPLY phases.

1. Installation and Setup

VS Code (Recommended)

# Install via CLI (VS Code must be open)
code --install-extension Codeium.codeium

Expected Output:

Installing extensions...
Extension 'Codeium.codeium' v3.12.0 was successfully installed.

Post-Install:

1. Reload VS Code.
2. Sign in via GitHub/GitLab/Google (or use anonymously for autocomplete only).
3. Accept permissions (read/write to workspace files for context).

Gotcha:

• If autocomplete doesn’t appear, check the status bar (bottom-right) for errors. Run Codeium: Restart Extension from the command palette (Ctrl+Shift+P).

JetBrains (IntelliJ, PyCharm, etc.)

1. Open Settings > Plugins.
2. Search for Codeium and install.
3. Restart the IDE.
4. Sign in via the popup.

Gotcha:

• JetBrains plugins update slower than VS Code. For latest features, use Codeium’s JetBrains nightly builds.

CLI (Terminal)

# Install Python package (requires Python 3.8+)
pip install codeium --upgrade

Verify Installation:

codeium --version
# Output: codeium, version 3.12.0

Authenticate:

codeium auth
# Opens browser to sign in. Token saved to ~/.codeium/credentials.json.

2. Cascade Mode (Agentic Coding)

Cascade mode lets you chain AI actions (e.g., refactor → test → document) in a single prompt. Key for ASSESS and PROTECT phases of the AI Security Posture Framework™ (e.g., automated security fixes).

Enable Cascade

1. Open the Codeium chat panel (Ctrl+Shift+I in VS Code).
2. Type /cascade to start a multi-step workflow.

Example: Secure Refactor

Prompt:

/cascade
1. Refactor this Python function to use type hints and remove hardcoded secrets.
2. Add input validation for the `user_id` parameter.
3. Generate a unit test using pytest.

Expected Output:

# Refactored function (step 1)
def get_user_data(user_id: str, api_key: str = os.getenv("API_KEY")) -> dict:
    if not isinstance(user_id, str) or len(user_id) != 36:
        raise ValueError("user_id must be a 36-character UUID string")
    # ... rest of the function

# Generated test (step 3)
def test_get_user_data():
    with patch("os.getenv", return_value="test_key"):
        assert get_user_data("123e4567-e89b-12d3-a456-426614174000") == {...}

Pro Tip:

• Use /cascade + /explain to audit changes for compliance (COMPLY phase of the AI Security Posture Framework™).
• Save common workflows as custom commands (see Section 5).

3. Autocomplete Configuration

Enable/Disable Autocomplete

VS Code:

1. Open Settings (Ctrl+,).
2. Search for Codeium: Enable Autocomplete.
3. Toggle the checkbox.

JetBrains:

1. Go to Settings > Tools > Codeium.
2. Check/uncheck Enable Autocomplete.

Customize Trigger Keys

Add to settings.json (VS Code):

{
  "codeium.enableAutoSuggestions": true,
  "codeium.suggestionTriggerKeys": ["Tab", "Enter"] // Default: ["Tab"]
}

Gotcha:

• If Tab conflicts with snippets, use Enter instead.

Language-Specific Settings

{
  "codeium.languageSettings": {
    "python": {
      "maxSuggestions": 5, // Default: 3
      "suggestionDelay": 200 // ms (default: 300)
    },
    "javascript": {
      "disableAutocomplete": true // For specific languages
    }
  }
}

4. Command Palette and Shortcuts

Essential Shortcuts

Custom Commands

Define slash commands in ~/.codeium/commands.json:

{
  "commands": [
    {
      "name": "secure-refactor",
      "description": "Refactor code with security checks",
      "prompt": "/cascade\n1. Add input validation\n2. Remove hardcoded secrets\n3. Add logging for sensitive operations"
    }
  ]
}

Usage: Type /secure-refactor in the chat panel.

5. Model Selection

Cloud Models (Default)

Codeium uses proprietary models optimized for code. No configuration needed for free/Pro tiers.

Local Models (Experimental)

Requirements:

• 16GB+ RAM, NVIDIA GPU (recommended).
• Install Ollama or LM Studio.

Configure Local Model:

1. Open settings.json (VS Code/JetBrains).
2. Add:

{
  "codeium.useLocalModel": true,
  "codeium.localModelPath": "/path/to/model.gguf" // e.g., CodeLlama-7B
}

Gotcha:

• Local models are slower and lack multi-file context. Use for offline work only.

6. Working with Monorepos

Enable Multi-File Context

1. Open the root directory of your monorepo in your IDE.
2. Codeium automatically indexes files in the workspace.

Limitations:

• Max 32k tokens for context (long files may truncate).
• For large repos (>10k files), exclude directories in settings.json:

{
  "codeium.excludedDirectories": [
    "**/node_modules",
    "**/dist",
    "**/.git"
  ]
}

Example: Cross-File Refactor

Prompt:

/cascade
1. Update the `UserService` class in `backend/services/user.py` to use the new `AuthClient` from `backend/clients/auth.py`.
2. Generate a migration script for the database schema changes.

Expected Output:

• Codeium will:
  1. Import AuthClient in user.py.
  2. Replace deprecated auth methods.
  3. Generate a migrations/002_add_auth_client.sql file.

7. Free Tier vs. Pro Features

Upgrade to Pro:

1. Open the Codeium panel in your IDE.
2. Click Upgrade and select a plan.

Common Errors and Fixes

Alternatives at a Glance

What's Next?

1. Set up Cascade mode for your most repetitive tasks (e.g., /cascade /refactor /test).
2. Configure custom commands for security checks (e.g., /secure-audit to scan for secrets).
3. Explore self-hosting if you’re in a regulated industry (contact Codeium Enterprise).

For teams adopting AI tools, Hyperion Consulting offers AI Security Posture Framework™ workshops to align Codeium with your security and compliance goals. Learn more at hyperion-consulting.io.