Configure Amazon Q for AWS-integrated code generation and analysis.

Install Amazon Q CLI and set basic settings:

brew install --cask amazon-q

q login

q settings chat.defaultModel "claude-3-sonnet"

q settings chat.enableKnowledge true

Amazon Q uses different configuration locations for different purposes:

Settings Configuration

Manage settings via: q settings [key] [value] - This is the recommended way. See official settings guide.

MCP Configuration

MCP servers are configured separately:

Note: Modern MCP configuration is in default.json. Legacy mcp.json support is controlled by useLegacyMcpJson field in ~/.aws/amazonq/default.json.

See official MCP configuration guide.

Amazon Q uses AWS Builder ID (free) or AWS Identity Center (pro) for authentication.

Builder ID (Free Tier)

1. Run login command:

   q login --license free

2. Opens browser for authentication
3. Free tier with basic features

AWS Identity Center (Pro Tier)

1. Run login with your organization’s details:

   q login --license pro \
     --identity-provider https://your-org.awsapps.com/start \
     --region us-east-1

2. Follow browser authentication flow
3. Full access to all features

Check status: q whoami

Example settings:

q settings chat.defaultModel "claude-3-opus"
q settings chat.enableThinking true
q settings telemetry.enabled false

Control which tools Amazon Q can use with granular permissions. Agent configuration uses JSON format:

{
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws"
  ],
  "allowedTools": [
    "fs_read",
    "fs_*",
    "@git/git_status"
  ],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["src/**", "tests/**"]
    },
    "execute_bash": {
      "allowedCommands": ["git status", "cargo check", "npm test"]
    },
    "use_aws": {
      "allowedServices": ["s3", "lambda", "dynamodb"]
    }
  }
}

For per-user settings managed via q settings commands, use the CLI (e.g., q settings chat.defaultModel "claude-3-sonnet").

Register external Model Context Protocol (MCP) servers to extend Amazon Q’s capabilities.

Global MCP Configuration

Edit ~/.aws/amazonq/default.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "timeout": 60000
    },
    "git": {
      "command": "git-mcp",
      "args": [],
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      },
      "timeout": 120000
    }
  },
  "tools": [
    "@github",
    "@git/git_status",
    "@git/git_log"
  ],
  "allowedTools": [
    "@github/search_*",
    "@git"
  ]
}

Project-Level MCP Configuration

Create .amazonq/default.json in project root:

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["./mcp-server-postgres.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  },
  "tools": ["use_postgres"],
  "allowedTools": ["@postgres/*"]
}

Environment variable resolution uses ${VAR_NAME} syntax from shell environment.

Enable semantic search over your project:

q settings chat.enableKnowledge true
q settings knowledge.indexType "Best"  # or "Fast"
q settings knowledge.maxFiles 1000
q settings knowledge.defaultIncludePatterns '["**/*.rs", "**/*.md", "**/*.toml"]'
q settings knowledge.defaultExcludePatterns '["**/target/**", "**/node_modules/**"]'

Create specialized AI assistants in .q/agents/my-agent.json:

{
  "name": "rust-developer",
  "description": "Specialized for Rust and AWS development",
  "prompt": "You are an expert Rust developer with AWS knowledge",
  "model": "claude-3-sonnet",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws",
    "@git"
  ],
  "allowedTools": [
    "fs_*",
    "execute_bash",
    "use_aws",
    "@git/*"
  ],
  "resources": [
    "file://README.md",
    "file://docs/**/*.md"
  ],
  "hooks": {
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "rustfmt $(jq -r '.tool_input.path')"
      }
    ]
  }
}

Run with: q chat --agent rust-developer

Amazon Q enforces separation between team-shared configuration (git-tracked) and personal settings (local only):

Shared Team Configuration (Git-Tracked)

Store team guidelines and custom agents in version control:

Project Rules (.amazonq/rules/**/*.md):

• All changes require at least 2 approvals
• Include tests for new functionality
• Update documentation for API changes

• Use conventional commit format
• Include ticket numbers in commit messages

**Shared Agents** (`.amazonq/cli-agents/team-agent.json`):
```json
{
  "name": "team-agent",
  "description": "Team development standards agent",
  "resources": [
    "file://.amazonq/rules/**/*.md",
    "file://README.md",
    "file://docs/**/*.md"
  ],
  "tools": [
    "fs_read",
    "execute_bash"
  ]
}

Personal Overrides (Local Only)

Individual developers set personal preferences via q settings commands (not committed):

q settings chat.defaultModel "claude-3-opus"

q settings telemetry.enabled false

q settings chat.defaultAgent team-agent

Settings are stored in ~/.aws/amazonq/ (never commit to git).

MCP Servers for Teams

Shared MCP servers go in project-level .amazonq/default.json:

{
  "mcpServers": {
    "shared-github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  },
  "allowedTools": [
    "@github/search_*",
    "fs_read"
  ]
}

Amazon Q supports custom agents and prompt templates rather than fixed commands. Create agents for common workflows:

name: "deploy"
description: "Handles deployment workflows"
prompt: "You are a deployment specialist"
tools:
  - execute_bash
  - use_aws
toolsSettings:
  execute_bash:
    allowedCommands:
      - "git push"
      - "npm run build"
      - "aws s3 sync"

✅ Do:

• Use q settings commands to manage configuration
• Store sensitive values in environment variables or .env files
• Create project-specific agents in .q/agents/
• Use tool permissions to limit access in shared environments
• Enable knowledge base for better project context
• Commit team settings to version control, keep personal overrides local

❌ Don’t:

• Edit YAML files directly (use q settings commands)
• Commit personal authentication tokens
• Disable all tool permissions (breaks functionality)
• Use wildcard permissions in production without review
• Ignore the q diagnostic command when troubleshooting

Validate configuration:

q diagnostic
q settings list

Common issues:

Debug mode:

q settings log.level "debug"
q chat --verbose

Check logs: q diagnostic --format json

• Official Amazon Q CLI Documentation
• Command Reference
• Settings Guide
• MCP Integration
• AWS Builder ID

Last updated: 2025-11-12

Configure Claude Code for terminal-based AI-assisted development.

Install and start Claude Code:

brew install --cask claude-code

curl -fsSL https://claude.ai/install.sh | bash

cd your-project
claude

First run will prompt for login via browser (Claude.ai or Claude Console account required).

Claude Code uses Claude.ai or Claude Console accounts for authentication.

Interactive Login (Recommended)

1. Run Claude Code:

   claude

2. Follow browser authentication prompt
3. Choose account type:
   • Claude.ai: Pro or Max subscription (personal use)
   • Claude Console: API usage billing (workspace/team use)

Force Login Method

Configure which login method to use:

{
  "forceLoginMethod": "claudeai"
}

Options: "claudeai" or "console"

API Key for Automation

For non-interactive use (CI/CD, scripts):

export ANTHROPIC_API_KEY="sk-ant-..."

Or use dynamic key generation:

{
  "apiKeyHelper": "~/bin/get-api-key.sh"
}

Example:

{
  "model": "opus",
  "cleanupPeriodDays": 60,
  "env": {
    "CUSTOM_VAR": "value"
  }
}

Available model shortcuts: "sonnet", "opus", "haiku" (maps to latest versions)

Claude Code uses a granular permission system with allow/ask/deny rules:

{
  "permissions": {
    "allow": [
      "Bash(git diff:*)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "ask": [
      "Bash(git push:*)",
      "WebFetch"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(~/.aws/**)"
    ],
    "additionalDirectories": ["../docs/"],
    "defaultMode": "acceptEdits"
  }
}

Permission modes:

• "plan" - Read-only analysis, no changes
• "acceptEdits" - Allow file edits with confirmation
• "bypassPermissions" - Skip all permission checks (dangerous)

Tool-specific patterns:

• Bash(command:*) - Shell command prefix matching
• Read(path) - File/directory read access
• Edit(path) - File write access
• WebFetch or WebFetch(domain:example.com) - Network access
• mcp__servername - All tools from MCP server
• mcp__servername__toolname - Specific MCP tool

Register external tools via MCP. Add servers using CLI or configuration files:

Adding MCP Servers via CLI

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

claude mcp add --transport stdio clickup \
  --env CLICKUP_API_KEY=YOUR_KEY \
  --env CLICKUP_TEAM_ID=YOUR_TEAM_ID \
  -- npx -y @hauptsache.net/clickup-mcp

claude mcp list

MCP Configuration in .mcp.json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "API_URL": "${COMPANY_API_URL}"
      }
    }
  }
}

Environment variable expansion: Use ${VAR_NAME} or ${VAR_NAME:-default} syntax.

MCP Permissions

{
  "enableAllProjectMcpServers": false,
  "enabledMcpjsonServers": ["github", "sentry"],
  "disabledMcpjsonServers": ["filesystem"],
  "permissions": {
    "allow": [
      "mcp__github",
      "mcp__sentry__get_issue"
    ],
    "deny": [
      "mcp__filesystem"
    ]
  }
}

Note: MCP permissions do NOT support wildcards. Use mcp__servername for all tools or list each tool individually.

Auto-load project documentation for better context:

Documentation files (loaded automatically at startup):

• CLAUDE.md or AGENTS.md in project root
• .claude/CLAUDE.md (project-specific)
• ~/.claude/CLAUDE.md (personal, all projects)

What to document:

• Common bash commands with descriptions
• Core files and utility functions
• Code style guidelines
• Testing instructions
• Repository etiquette (branch naming, merge strategy)
• Developer environment setup
• Project-specific warnings

Enable advanced sandboxing for bash command isolation (macOS/Linux):

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["docker", "git"],
    "allowUnsandboxedCommands": true,
    "network": {
      "allowUnixSockets": ["/var/run/docker.sock"],
      "allowLocalBinding": true
    }
  }
}

Filesystem and network access are controlled via Read, Edit, and WebFetch permission rules, not sandbox settings.

Managed Policy Settings (Enterprise)

IT/DevOps can deploy organization-wide policies that cannot be overridden:

macOS: /Library/Application Support/ClaudeCode/managed-settings.json
Linux/WSL: /etc/claude-code/managed-settings.json
Windows: C:\ProgramData\ClaudeCode\managed-settings.json

{
  "env": {
    "COMPANY_VAR": "value"
  },
  "permissions": {
    "deny": ["Read(~/.aws/**)", "Bash(curl:*)"],
    "disableBypassPermissionsMode": "disable"
  },
  "allowedMcpServers": [
    {"serverName": "github"},
    {"serverName": "company-internal"}
  ],
  "deniedMcpServers": [
    {"serverName": "filesystem"}
  ]
}

Managed MCP Configuration (Enterprise)

Deploy centrally-managed MCP servers:

macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
Linux/WSL: /etc/claude-code/managed-mcp.json
Windows: C:\ProgramData\ClaudeCode\managed-mcp.json

{
  "mcpServers": {
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

Settings Precedence

Settings are applied in order (highest to lowest):

1. Enterprise managed policies (managed-settings.json) - Cannot be overridden
2. Command line arguments - Temporary session overrides
3. Local project settings (.claude/settings.local.json) - Personal, git-ignored
4. Shared project settings (.claude/settings.json) - Team shared, version controlled
5. User settings (~/.claude/settings.json) - Personal global settings

✅ Do:

• Use CLAUDE.md or AGENTS.md to document project context and common commands
• Store API keys in environment variables, never in settings files
• Create .claude/settings.local.json for personal settings (auto git-ignored)
• Use permission deny rules to exclude sensitive files (.env, secrets/)
• Configure MCP servers at project level (.mcp.json) for team sharing
• Use permissions.defaultMode: "plan" for read-only analysis in production repos
• Test configuration changes in isolated branches first

❌ Don’t:

• Commit API keys or tokens to version control
• Use bypassPermissions mode without strong justification
• Mix authentication methods in the same config
• Ignore enterprise managed policies (they override everything)
• Use wildcards in MCP permission patterns (not supported)
• Disable all tool permissions (breaks core functionality)

Interactive configuration:

claude        # Start Claude Code
/config       # Open settings UI
/permissions  # Configure allowed tools
/mcp          # Manage MCP servers

Common issues:

Environment variables for debugging:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export DISABLE_PROMPT_CACHING=1

export MAX_MCP_OUTPUT_TOKENS=50000

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Check configuration:

cat ~/.claude/settings.json

cat .claude/settings.json

claude mcp list

• Official Claude Code Documentation
• Settings Reference
• MCP Integration Guide
• MCP Connectors Directory
• Model Context Protocol Specification
• Hooks Documentation
• Security & Sandboxing
• Troubleshooting Guide

Last updated: 2025-11-12

Configure Cursor AI code editor for intelligent completion, targeted edits, and agentic development. For comprehensive feature details, see the official Cursor documentation.

Access settings via:

Ctrl/⌘ + Shift + J  (Cursor Settings)
OR
Ctrl/⌘ + Shift + P → "Cursor Settings"

Basic settings in Cursor Settings UI:

• Models: Select AI models (GPT-4o, Claude, cursor-small, custom)
• Features: Enable/disable Tab, Chat, long context
• Beta: Experimental features like Long Context Chat

Windows/Linux path: %APPDATA%/Cursor/User/settings.json

Cursor uses account-based authentication for AI features and settings sync.

OAuth Login (Recommended)

Sign in via Cursor’s web-based OAuth:

1. Click “Sign in” in Cursor (top-left corner)
2. Browser opens for authentication at cursor.com
3. Credentials stored securely in system keychain
4. Settings sync enabled automatically

Plans Available:

• Free: Limited fast requests
• Pro: $20/month, unlimited fast requests
• Teams: Collaborative features
• Enterprise: SSO, admin controls

Enterprise SSO

For Teams and Enterprise customers:

• SAML/OIDC integration
• Centralized management via Cursor dashboard
• Admin-enforced rules and commands

Sign Out

Access via Command Palette:

Ctrl/⌘ + Shift + P → "Sign Out"

Configure AI models through Cursor Settings → Models:

Model Selection:

• Access via Ctrl/⌘ + K or dropdown below AI input box
• Add custom models: Cursor Settings → Models → Model Names

Context Window Limitations:

• Standard chat: ~20,000 tokens (or model max if less)
• Cmd+K: ~10,000 tokens (optimized for speed)
• Long context chat: Full model context window (enable in Beta settings)

Official model documentation

Configure custom API keys through Cursor Settings → Models:

OpenAI API Key

Cursor Settings → Models → OpenAI API Key
Enter your key → Click "Verify"

Note: API key is sent to Cursor server with each request for prompt building.

Anthropic API Key

Cursor Settings → Models → Anthropic API Key
Enter your key to enable Claude models

Enables Claude-based models at your cost. Key transmitted to Cursor server.

Azure API Key

Cursor Settings → Models → Azure API Key
Configure to use Azure OpenAI models

Google API Key

Cursor Settings → Models → Google API Key
Example model: gemini-1.5-flash-500k

Official API key documentation

Configure Chat behavior through Cursor Settings → Features → Chat:

Official chat customization docs

Enable advanced Tab features through Cursor Settings → Features → Cursor Tab:

Partial Accepts

Accept parts of suggestions (e.g., next word):

Keybinding: Ctrl/⌘ + Right Arrow
Navigate to: Cursor Settings → Features → Cursor Tab
Set: editor.action.inlineSuggest.acceptNextWord

Cursor Prediction

Cursor predicts next edit location after accepting changes. Press Tab to move through sequential edits.

Tab in Peek Views

Use Tab functionality in “Go to Definition” or “Go to Type Definition” peek views. Especially useful with Vim’s gd command to fix all usages efficiently.

Official Tab documentation

Create a .cursorrules file in your project root to define custom AI instructions:

Use TypeScript for all new files.
Write tests for all functions.
Follow Material-UI design patterns.
Prefer functional components over class components.

Usage:

• Instructions apply to Cursor Chat and Ctrl/⌘ K
• Project-specific, committed to version control
• Plain text format, one instruction per line

Official rules documentation

Exclude files/directories from Cursor’s AI context using .cursorignore:

dist/

*.log

config.json

node_modules/

Syntax: Same as .gitignore (supports wildcards and directory patterns)

Official ignore files documentation

Enable larger context windows for complex tasks:

Cursor Settings → Beta → Long Context Chat

Toggle modes: Ctrl/⌘ + .

Context Limits:

• Standard chat: ~20,000 tokens
• Long context: Full model window (up to 500k for gemini-1.5-flash-500k)

Long Context Models:

• gpt-4o-128k
• gemini-1.5-flash-500k
• claude-3-haiku-200k
• claude-3-sonnet-200k
• claude-3.5-sonnet-200k

Reference specific context in Chat or Cmd+K:

Cmd K Chunking Strategies:

• auto: Automatically selects strategy based on file size
• full file: Uses entire file as context
• outline: Parses file outline
• chunks: Selects most relevant chunk

Official context documentation

Cursor automatically imports VS Code settings:

• Extensions: Installed extensions migrate automatically
• Themes: Color and icon themes
• Keybindings: Custom shortcuts
• Workspace settings: Project-specific configurations

Manual Import:

Cursor Settings → Import from VS Code

Change Activity Bar Orientation:

Open VS Code settings (Ctrl/⌘ + ,)
Set "workbench.activityBar.orientation" to "vertical"
Restart Cursor

Official migration guide

✅ Do:

• Use .cursorrules to document project coding standards
• Enable Long Context Chat for complex tasks requiring large context
• Store API keys securely (use Cursor Settings UI, not plain text files)
• Commit .cursorrules and .cursorignore to version control
• Use @Files and @Code symbols to provide precise context
• Review AI changes in diff view before accepting (Ctrl/⌘ + Enter)
• Use Tab for quick completions, Cmd+K for targeted changes, Chat for complex tasks
• Enable partial accepts for granular control over suggestions

❌ Don’t:

• Commit API keys to version control
• Use web search for every query (enable only when needed)
• Accept all AI suggestions without review
• Ignore .cursorignore for sensitive files
• Mix VS Code and Cursor settings files (use appropriate UI)
• Disable Long Context Chat if working with large codebases

Access Developer Tools:

Ctrl/⌘ + Shift + P → "Developer: Open DevTools"

Check Logs:

• macOS/Linux: ~/.cursor/logs/
• Windows: C:\Users\<user-name>\AppData\Roaming\Cursor\logs

Common Issues:

Disable HTTP/2 (for corporate proxy issues):

{
  "cursor.general.disableHttp2": true
}

Add to VS Code settings file.

Sign Out of GitHub:

Ctrl/⌘ + Shift + P → Sign out of GitHub

Useful for resolving authentication issues.

• Cursor Official Documentation – Complete feature guides and API references
• Cursor Homepage – Product overview and downloads
• Cursor Pricing – Free, Pro, Teams, Enterprise plans
• Cursor Changelog – Latest features and updates (2.0 features)
• Cursor Forum – Community discussions and support
• Model Context Protocol Documentation – MCP specification (if integrating custom tools)
• VS Code Documentation – Base editor features and extensions

Last updated: 2025-11-12

Configure Google’s Gemini CLI for AI-assisted development workflows. For comprehensive feature documentation, see official Gemini CLI documentation.

Create ~/.gemini/settings.json:

{
  "model": {
    "name": "gemini-2.5-flash"
  },
  "tools": {
    "sandbox": true,
    "autoAccept": false
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

Configuration precedence (higher numbers override lower):

1. Default values (hardcoded)
2. System defaults file
3. User settings file
4. Project settings file
5. System settings file
6. Environment variables
7. Command-line arguments

Gemini CLI supports multiple authentication methods for accessing Gemini and Vertex AI APIs.

Method 1: Gemini API Key (Simplest)

Set environment variable:

export GEMINI_API_KEY="your-api-key-here"

Or add to .env file in project root:

GEMINI_API_KEY=your-api-key-here

Method 2: Google Cloud Application Default Credentials

For Vertex AI access:

gcloud auth application-default login

Set required environment variables:

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

Method 3: Service Account (CI/CD)

For automation environments:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

See official authentication documentation for all available methods.

Configure which Gemini model to use and inference parameters.

Example:

{
  "model": {
    "name": "gemini-2.5-pro",
    "maxSessionTurns": 20,
    "compressionThreshold": 0.3
  }
}

Command-line override:

gemini --model gemini-2.5-flash
gemini -m gemini-2.5-flash

Environment variable:

export GEMINI_MODEL="gemini-2.5-flash"

See official model documentation for available models.

Controls built-in tools like file operations, shell commands, and web access.

Example:

{
  "tools": {
    "sandbox": "docker",
    "autoAccept": false,
    "allowed": [
      "run_shell_command(git)",
      "run_shell_command(npm test)"
    ],
    "exclude": ["web_search"]
  }
}

Command-line flags:

gemini --sandbox
gemini -s

gemini --approval-mode auto_edit  # auto-approve edits only
gemini --approval-mode yolo       # auto-approve everything
gemini --approval-mode default    # prompt for all

gemini --allowed-tools "run_shell_command(git status),read_file"

See official tools documentation for all built-in tools.

Register external Model Context Protocol servers to extend tool capabilities.

Configure in mcpServers section of settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DB_URL}"
      },
      "trust": true,
      "includeTools": ["query", "schema"]
    },
    "custom-api": {
      "httpUrl": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      },
      "timeout": 30000
    }
  }
}

MCP server configuration options:

Global MCP control:

{
  "mcp": {
    "allowed": ["github", "postgres"],
    "excluded": ["untrusted-server"]
  }
}

Command-line:

gemini --allowed-mcp-server-names github,postgres

See official MCP documentation for details.

Provide project-specific instructions via hierarchical Markdown context files.

Default filename: GEMINI.md (configurable via context.fileName)

Loading hierarchy (more specific overrides more general):

1. ~/.gemini/GEMINI.md - Global user context
2. Parent directories up to project root - Broad project context
3. Current directory and subdirectories - Specific component context

Example GEMINI.md:

• Use 2 spaces for indentation
• Prefer functional programming
• All functions require JSDoc comments

• Interface names prefixed with I (e.g., IUserService)
• Private class members prefixed with _
• Test files: *.spec.ts

• Use fetchWithRetry for all GET requests
• Include error logging for API failures

**Configuration options**:

| Option | Type | Default | Purpose |
|--------|------|---------|---------|
| `context.fileName` | string/array | undefined | Context file name(s) to load |
| `context.discoveryMaxDirs` | number | 200 | Max directories to search |
| `context.includeDirectories` | array | [] | Additional directories for context |
| `context.fileFiltering.respectGitIgnore` | boolean | true | Honor .gitignore when scanning |
| `context.fileFiltering.respectGeminiIgnore` | boolean | true | Honor .geminiignore when scanning |

**Commands**:
```bash
/memory show

/memory refresh

See official context documentation for details.

Customize terminal appearance and behavior.

Example:

{
  "ui": {
    "theme": "GitHub",
    "hideBanner": true,
    "hideTips": true,
    "useFullWidth": false
  },
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  }
}

Command-line:

gemini --screen-reader

See official themes documentation for available themes.

Control usage data collection.

Example:

{
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

Environment variables:

export GEMINI_TELEMETRY_ENABLED=false

See official telemetry documentation for details on what’s collected.

Execute tools in isolated environments for security.

Configuration:

{
  "tools": {
    "sandbox": true  // or "docker", "podman", or path to profile
  }
}

Custom sandbox with Dockerfile:

Create .gemini/sandbox.Dockerfile in project root:

FROM gemini-cli-sandbox

RUN apt-get update && apt-get install -y python3-pip
RUN pip3 install pytest pandas

COPY ./requirements.txt /app/
RUN pip3 install -r /app/requirements.txt

Build and run:

BUILD_SANDBOX=1 gemini -s

Environment variable:

export GEMINI_SANDBOX=true
export GEMINI_SANDBOX=docker

See official sandbox documentation for advanced configurations.

Key environment variables for configuration.

.env file loading order:

1. .env in current directory
2. Search upward to project root (identified by .git)
3. ~/.env in home directory

Example .env:

GEMINI_API_KEY=your-api-key
GOOGLE_CLOUD_PROJECT=my-project-id
GOOGLE_CLOUD_LOCATION=us-central1

See official environment variables documentation for complete list.

✅ Do:

• Store API keys in environment variables or .env files (git-ignored)
• Use project settings (.gemini/settings.json) for team-shared configuration
• Use user settings (~/.gemini/settings.json) for personal preferences
• Document configuration decisions in project README
• Use GEMINI.md files for project-specific instructions
• Enable sandbox mode for untrusted operations
• Version control .gemini/settings.json for team consistency

❌ Don’t:

• Commit API keys or credentials to version control
• Use global settings for project-specific needs
• Ignore .gemini directory in .gitignore (only ignore .gemini/.local.json)
• Mix authentication methods without clear documentation
• Disable sandbox mode with --yolo in production environments

Validate settings:

The CLI validates settings automatically on startup. Check for schema errors in the output.

View current configuration:

/settings show

/memory show

Debug mode:

gemini --debug
export DEBUG=true
gemini

Common issues:

Schema validation:

Use JSON schema for autocomplete and validation in your editor:

{
  "$schema": "https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json",
  "model": {
    "name": "gemini-2.5-flash"
  }
}

See official troubleshooting documentation for detailed debugging.

• Official Gemini CLI Documentation – Complete feature guide
• Configuration Reference – Exhaustive settings options
• Authentication Guide – All auth methods
• MCP Server Integration – External tool setup
• Built-in Tools – Available CLI tools
• Enterprise Configuration – Team/admin setup
• GitHub Repository – Source code and examples
• Settings Schema – JSON validation schema

Last updated: 2025-11-12

Configure GitHub Copilot across IDE extensions and enterprise deployments.

VS Code settings (~/.config/Code/User/settings.json or settings.json in workspace):

{
  "github.copilot.enable": {
    "*": true,
    "plaintext": false
  },
  "github.copilot.chat.enabled": true,
  "github.copilot.advanced": {
    "authorizationFallback": true
  }
}

GitHub Copilot uses GitHub account login with OAuth.

VS Code / JetBrains IDEs

1. Install GitHub Copilot extension
2. Click “Sign in to GitHub” in extension
3. Browser opens for OAuth flow
4. Authorize extension access
5. Token stored securely in IDE credential store (auto-refreshed)

GitHub CLI

gh auth login
gh auth setup-git

Copilot can access GitHub CLI authentication automatically.

Enterprise SSO

For organization-managed users:

1. Go to GitHub → Settings → Developer settings → Authorizations
2. Enterprise may enforce specific OAuth app
3. Token syncs from GitHub SAML/SSO provider

VS Code

Example workspace config:

{
  "github.copilot.enable": {
    "*": true,
    "plaintext": false,
    "markdown": false,
    "yaml": false
  },
  "github.copilot.chat.enabled": true,
  "github.copilot.voice.enabled": false
}

JetBrains IDEs

Via IDE Settings pane:

• GitHub Copilot → Toggle “Show Copilot in editor”
• GitHub Copilot Chat → Configure chat panel location
• Advanced → Set API timeout and max retries

Vim/Neovim

Configure via Vim plugin settings. See GitHub Copilot.vim documentation for configuration options.

Example configuration in .vimrc or init.vim:

" Enable Copilot for specific filetypes
let g:copilot_filetypes = {
\ '*': v:true,
\ 'markdown': v:false,
\ }

" Customize keybindings
imap <silent><script><expr> <C-J> copilot#Accept("\<CR>")

GitHub Organization admins can enforce policies via Admin portal:

Workspace enforcement (via .vscode/settings.json):

{
  "github.copilot.enable": {
    "*": true
  },
  "[python]": {
    "github.copilot.enable": true
  }
}

Configure MCP servers for GitHub Copilot to access external tools and services.

VS Code - Personal MCP Configuration

Add to settings.json for user-level MCP servers:

{
  "github.copilot.mcp.servers": [
    {
      "serverID": "github-mcp",
      "serverUrl": "https://api.githubcopilot.com/mcp/"
    }
  ]
}

Or enable automatic discovery of existing MCP configurations:

{
  "chat.mcp.discovery.enabled": true
}

VS Code - Project MCP Configuration

Create .vscode/mcp.json in repository root to share MCP servers with team:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "github_token",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
      }
    }
  }
}

JetBrains IDEs - MCP Configuration

Local MCP Server (using NPM):

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

Remote MCP Server (OAuth):

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Remote MCP Server (PAT authentication):

{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "requestInit": {
        "headers": {
          "Authorization": "Bearer YOUR_PAT_HERE"
        }
      }
    }
  }
}

MCP Server Configuration for Coding Agent

For GitHub Copilot Coding Agent, configure MCP servers with specific tools and environment variables:

{
  "mcpServers": {
    "sentry": {
      "type": "local",
      "command": "npx",
      "args": ["@sentry/mcp-server@latest", "--host=$SENTRY_HOST"],
      "tools": ["get_issue_details", "get_issue_summary"],
      "env": {
        "SENTRY_HOST": "https://contoso.sentry.io",
        "SENTRY_ACCESS_TOKEN": "COPILOT_MCP_SENTRY_ACCESS_TOKEN"
      }
    }
  }
}

MCP Configuration Guide: See official MCP documentation for complete setup instructions.

Use slash commands in Copilot Chat for specific tasks:

These commands provide targeted assistance within the Copilot Chat interface.

✅ Do:

• Keep GitHub token current; re-authenticate periodically
• Use workspace-level .vscode/settings.json for team consistency
• Enable audit logging in enterprise deployments
• Scope Copilot suggestions with “Brush” filters for quality code
• Review Copilot suggestions before accepting (especially in security-sensitive code)
• Document approved Copilot settings in team onboarding

❌ Don’t:

• Share GitHub tokens or auth credentials
• Accept all Copilot suggestions blindly
• Disable enterprise security policies
• Mix personal and work GitHub accounts
• Rely on Copilot for security-critical code without review

Verify authentication:

gh auth status

Common issues:

Debug mode:

VS Code:

1. Open output panel: Cmd+Shift+U
2. Select “GitHub Copilot” from dropdown
3. Check for auth, connection, and suggestion errors

JetBrains:

1. Help → Diagnostics → Show Log in Finder
2. Search logs for “Copilot” entries

• GitHub Copilot Documentation
• GitHub Copilot Enterprise
• Supported Languages & IDEs
• MCP Protocol Documentation

Last updated: 2025-11-12

Configure Qwen Code for AI-powered command-line development workflows. Qwen Code is adapted from Gemini CLI and optimized for Qwen3-Coder models.

Create ~/.qwen/settings.json:

{
  "model": {
    "name": "qwen3-coder-plus"
  },
  "tools": {
    "approvalMode": "plan",
    "sandbox": "docker"
  }
}

Qwen Code supports multiple authentication methods. Qwen OAuth is recommended for free tier access.

Method 1: Qwen OAuth (🚀 Recommended - Free)

Free tier: 2,000 requests/day, 60 requests/minute

1. Run: qwen
2. Browser opens automatically for authentication
3. Login with your qwen.ai account
4. Credentials cached automatically in ~/.qwen/

Switch to Qwen OAuth (if already using OpenAI-compatible mode):

/auth

Method 2: OpenAI-Compatible API

User-wide configuration (~/.qwen/.env):

mkdir -p ~/.qwen
cat >> ~/.qwen/.env <<'EOF'
OPENAI_API_KEY="your-api-key"
OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
OPENAI_MODEL="qwen3-coder-plus"
EOF

Project-specific configuration (.qwen/.env):

mkdir -p .qwen
cat >> .qwen/.env <<'EOF'
OPENAI_API_KEY="your-api-key"
OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1"
OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct"
EOF

Environment variables:

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="your_api_endpoint"  # Optional
export OPENAI_MODEL="your_model_choice"     # Optional

API Provider Options

Mainland China (Free Options):

• ModelScope (2,000 free calls/day):

  OPENAI_BASE_URL="https://api-inference.modelscope.cn/v1"
  OPENAI_MODEL="Qwen/Qwen3-Coder-480B-A35B-Instruct"

• Alibaba Cloud Bailian:

  OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
  OPENAI_MODEL="qwen3-coder-plus"

International Users:

• OpenRouter (free tier available):

  OPENAI_BASE_URL="https://openrouter.ai/api/v1"
  OPENAI_MODEL="qwen/qwen3-coder:free"

• Alibaba Cloud ModelStudio:

  OPENAI_BASE_URL="https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
  OPENAI_MODEL="qwen3-coder-plus"

Configure model and general settings in ~/.qwen/settings.json:

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": false,
    "hideTips": false
  },
  "model": {
    "name": "qwen3-coder-plus",
    "maxSessionTurns": 10
  }
}

Model Settings

Session Token Management

Configure session limits:

{
  "sessionTokenLimit": 32000
}

Session commands:

• /compress - Compress conversation history to save tokens
• /clear - Clear all conversation history
• /stats - Check current token usage and limits

Configure tool behavior and approval modes:

{
  "tools": {
    "approvalMode": "plan",
    "sandbox": "docker",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["dangerous_tool"]
  }
}

Approval Modes

Sandbox Configuration

Enable sandboxing in settings.json:

{
  "tools": {
    "sandbox": "docker"
  }
}

Or via environment variable:

export GEMINI_SANDBOX=true
qwen -p "run the test suite"

Custom sandbox flags (Podman):

export SANDBOX_FLAGS="--security-opt label=disable"

Tool Filtering

Exclude specific tools:

{
  "tools": {
    "exclude": ["write_file", "delete_file"]
  }
}

Configure MCP servers in ~/.qwen/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
      },
      "trust": true
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "timeout": 30000,
      "trust": false
    }
  }
}

MCP Server Types

Stdio Transport (local servers):

{
  "mcpServers": {
    "pythonServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "API_KEY": "$EXTERNAL_API_KEY"
      },
      "timeout": 15000
    }
  }
}

Docker Transport:

{
  "mcpServers": {
    "dockerizedServer": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "API_KEY",
        "-v", "${PWD}:/workspace",
        "my-mcp-server:latest"
      ],
      "env": {
        "API_KEY": "$EXTERNAL_SERVICE_TOKEN"
      }
    }
  }
}

SSE Transport (remote servers):

{
  "mcpServers": {
    "remoteServer": {
      "url": "https://api.example.com/sse",
      "headers": {
        "Authorization": "Bearer $API_TOKEN"
      },
      "timeout": 60000
    }
  }
}

MCP Server Access Control

{
  "mcp": {
    "allowed": ["github", "filesystem"],
    "excluded": ["experimental-server"]
  }
}

Or use allowMCPServers and excludeMCPServers:

{
  "allowMCPServers": ["github", "filesystem"],
  "excludeMCPServers": ["dangerous-server"]
}

MCP Authentication (Remote Servers)

Google Credentials:

{
  "mcpServers": {
    "googleCloudServer": {
      "httpUrl": "https://my-gcp-service.run.app/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": ["https://www.googleapis.com/auth/userinfo.email"]
      }
    }
  }
}

Service Account Impersonation:

{
  "mcpServers": {
    "serviceAccountServer": {
      "httpUrl": "https://your-iap-protected-service.run.app/mcp",
      "authProviderType": "service_account_impersonation",
      "targetAudience": "YOUR_OAUTH_CLIENT_ID",
      "targetServiceAccount": "your-service-account@your-project.iam.gserviceaccount.com"
    }
  }
}

OAuth Discovery (automatic):

{
  "mcpServers": {
    "discoveredServer": {
      "url": "https://api.example.com/sse"
    }
  }
}

Managing MCP Servers via CLI

Add stdio server:

qwen mcp add my-server python server.py --port 8080
qwen mcp add github-server -e API_KEY=123 /path/to/server arg1 arg2

List servers:

qwen mcp list

Authenticate with OAuth servers:

/mcp auth

/mcp auth serverName

Subagents are stored in ~/.qwen/agents/ directory as separate configuration files.

Create subagent:

/agents create

Manage existing subagents:

/agents manage

Subagent configuration example (~/.qwen/agents/backend.json):

{
  "name": "backend",
  "description": "Backend API development specialist",
  "model": "qwen3-coder-plus",
  "mcpServers": ["github", "postgres"],
  "tools": ["bash", "git", "docker"],
  "approvalMode": "plan"
}

Custom commands are defined in ~/.qwen/commands/*.toml files:

.qwen/commands/deploy.toml:

[command.deploy]
description = "Deploy to staging environment"
steps = [
  "npm run build",
  "npm run test",
  "npm run deploy:staging"
]
approval = true

Run command:

/deploy

Qwen Code uses QWEN.md file for project context with hierarchical loading:

QWEN.md (in project root):

This project uses microservices architecture…

Run npm install to set up dependencies…

**Configure context loading** in settings.json:
```json
{
  "context": {
    "fileName": ["CONTEXT.md", "QWEN.md"],
    "includeDirectories": ["~/projects/shared-docs"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  }
}

Context files are automatically loaded when starting Qwen Code in a project directory.

Qwen Code supports automatic vision model switching for image analysis.

Configure vision switching in settings.json:

{
  "experimental": {
    "vlmSwitchMode": "once",
    "visionModelPreview": true
  }
}

Vision switch modes:

• "once" - Switch to vision model for one query only
• "session" - Switch for entire session
• "persist" - Never switch automatically
• Not set - Show interactive dialog (default)

Command line override:

qwen --vlm-switch-mode once
qwen --vlm-switch-mode session

Disable vision models:

{
  "experimental": {
    "visionModelPreview": false
  }
}

Configure telemetry and usage statistics:

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "privacy": {
    "usageStatisticsEnabled": true
  }
}

Disable telemetry:

{
  "telemetry": {
    "enabled": false
  },
  "privacy": {
    "usageStatisticsEnabled": false
  }
}

Complete settings.json Example

{
  "general": {
    "vimMode": true,
    "preferredEditor": "code"
  },
  "ui": {
    "theme": "GitHub",
    "hideBanner": false,
    "hideTips": false,
    "customWittyPhrases": [
      "Connecting to AGI"
    ]
  },
  "tools": {
    "approvalMode": "plan",
    "sandbox": "docker",
    "discoveryCommand": "bin/get_tools",
    "callCommand": "bin/call_tool",
    "exclude": ["dangerous_tool"]
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN"
      }
    }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "logPrompts": true
  },
  "privacy": {
    "usageStatisticsEnabled": true
  },
  "model": {
    "name": "qwen3-coder-plus",
    "maxSessionTurns": 10,
    "summarizeToolOutput": {
      "run_shell_command": {
        "tokenBudget": 100
      }
    }
  },
  "context": {
    "fileName": ["CONTEXT.md", "QWEN.md"],
    "includeDirectories": ["~/projects/shared"],
    "loadFromIncludeDirectories": true,
    "fileFiltering": {
      "respectGitIgnore": false
    }
  },
  "advanced": {
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE", "NODE_ENV"]
  }
}

✅ Do:

• Use Qwen OAuth for free tier (2,000 requests/day)
• Store API keys in .qwen/.env or ~/.qwen/.env (git-ignored)
• Use approvalMode = "plan" for production work
• Configure sandboxing (sandbox: "docker") for safety
• Define custom commands in .qwen/commands/ for team workflows
• Use QWEN.md for project context documentation
• Create subagents for specialized tasks in ~/.qwen/agents/
• Configure MCP servers in settings.json with proper authentication

❌ Don’t:

• Commit API keys or secrets to git
• Use approvalMode = "yolo" without understanding risks
• Disable sandboxing in untrusted environments
• Mix authentication methods (choose one approach)
• Store sensitive credentials in settings.json directly (use environment variables)

Common issues:

Debug mode:

export DEBUG=qwen:*
qwen --verbose

Check logs: Logs are stored in ~/.qwen/logs/ (if logging enabled)

Session commands:

• /help - Display available commands
• /stats - Show session information and token usage
• /compress - Compress conversation history
• /clear - Clear conversation history

• Qwen Code GitHub Repository - Official repository with documentation
• Qwen Models Documentation - Qwen3-Coder model details
• Gemini CLI Documentation - Original project (Qwen Code is adapted from this)
• Model Context Protocol (MCP) - MCP specification
• Alibaba Cloud DashScope - DashScope API documentation (Mainland China)
• ModelScope API - Free tier API (2,000 calls/day)
• OpenRouter - International free tier option

Last updated: 2025-11-12

Configure Windsurf AI IDE with Cascade agent for collaborative code development.

Windsurf uses standard VS Code-style settings with Windsurf-specific extensions for Cascade features.

Access settings via:

• Profile icon (top right) → Windsurf Settings
• Command Palette (Cmd/Ctrl+Shift+P) → “Open Windsurf Settings”

Windows path: %APPDATA%\Codeium\windsurf\ Linux path: ~/.codeium/windsurf/

Windsurf uses Windsurf account authentication (free signup) for IDE and Cascade features.

Windsurf Account (Required)

Sign up during onboarding (completely free):

1. Launch Windsurf application
2. Onboarding flow prompts for authentication
3. Select “Sign up” or “Log in”
4. Browser opens for OAuth authentication
5. Authenticate with your account
6. Token stored securely in system
7. Click “Open Windsurf” to start

Free Tier: Includes Cascade access with limited credits/month

Pro/Teams/Enterprise: Paid plans with higher usage limits and team features

Manual Authentication Code (Fallback)

If OAuth flow fails:

1. During onboarding, select “Having Trouble?”
2. Click “Copy link” to get authentication URL
3. Open link in browser and authenticate
4. Copy authentication code
5. Enter code manually in Windsurf

Account Management

Access account settings:

Profile icon (top right) → Windsurf Settings → Account

Cascade settings are accessible via:

Profile icon (top right) → Windsurf Settings → Cascade
OR
Command Palette → Open Windsurf Settings → Cascade section

Key Cascade Settings

Cascade Modes

Cascade Code (Cmd/Ctrl+L):

• Create/edit files, generate projects, refactor code
• File changes with Accept/Reject flow
• Per tool call + context size credit cost

Cascade Chat (Cmd/Ctrl+L):

• Questions, design discussions, explanations
• Conversation + optional code proposals
• Per message credit cost

Plans & Todo Lists

• Planning Agent - Continuously refines strategy while executing actions
• Todo Lists - Cascade maintains task list within conversation
• Manual/Auto Updates - Plans evolve based on errors, discoveries, Memory entries

Named Checkpoints

• Create - Save named snapshot of project state at conversation step
• Revert - Hover over prompt → click revert arrow (irreversible!)
• Use Case - Explore multiple approaches, snapshot, revert if needed

Reusable markdown-based task automation stored in .windsurf/workflows/:

Invocation: /[workflow-name] in Cascade

Pre-configured workflows:

• /address-pr-comments - Process GitHub PR feedback
• /git-workflows - Commit, branch, and PR management
• /dependency-management - Update/install dependencies
• /code-formatting - Run Prettier, Black, ESLint, Flake8
• /run-tests-and-fix - Execute tests and auto-fix failures
• /deployment - Automate deployment workflows
• /security-scan - Run vulnerability scans

Create custom workflow:

1. Click Customizations icon (top right Cascade panel) → Workflows
2. Click + Workflow
3. Write markdown steps (Cascade follows sequentially)
4. Workflows support nested calls: /workflow-1 can invoke /workflow-2

Example: PR Review Workflow (.windsurf/workflows/review-pr.md):

1. Fetch latest changes
   $ git fetch origin

2. Check out PR branch
   $ git checkout PR-123

3. Run tests
   $ npm test

4. Check linting
   $ npx eslint . --fix

5. Summarize findings

Configure MCP servers in ~/.codeium/windsurf/mcp_config.json:

Adding MCP Plugins

Via Plugin Store (recommended):

1. Click Plugins icon (Cascade panel top right)
2. Search Plugin Store (official plugins show blue checkmark)
3. Click plugin → Install
4. Refresh Cascade

Manual Configuration: Edit ~/.codeium/windsurf/mcp_config.json directly

MCP Server Configuration

Stdio Transport (GitHub example):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_PAT>"
      }
    }
  }
}

HTTP Transport (SSE example):

{
  "mcpServers": {
    "figma": {
      "serverUrl": "<your-server-url>/mcp"
    }
  }
}

MCP Tool Limits

• Total Tool Limit: 100 tools maximum across all plugins
• Per-Plugin Configuration: Navigate to plugin → Tools tab → toggle tools on/off
• Settings Access: Windsurf Settings → Cascade → Manage plugins

Supported Transport Types

• stdio - Command-based execution (Node.js, Python, Go servers)
• http - URL-based endpoint (URL format: https://<server-url>/mcp)

MCP Resources

• Official MCP Documentation
• MCP Server Reference Repository
• OpenTools Plugin Directory

Team admins can whitelist approved MCP servers:

Access: Team Settings → MCP Settings

Whitelist Behavior:

• Whitelist even one server → all non-whitelisted servers blocked for team
• Uses regex pattern matching for flexible configuration
• Command field, arguments, and array length must match exactly

Regex Matching Rules:

• Full string matching (auto-anchored with ^(?:pattern)$)
• Case-sensitive
• Special characters (., $, [, ]) need escaping for literal matches

Common Patterns:

Configure Cascade’s interaction with terminal commands:

Access: Windsurf Settings → Terminal

Auto-Execute Settings

Allow List - Commands that auto-execute without confirmation:

Example: Add "git" to allow list
→ "git add -A" runs automatically

Deny List - Commands that always require user permission:

Example: Add "rm" to deny list
→ "rm index.py" always prompts for confirmation

Turbo Mode - Additional terminal execution optimizations (configurable in settings)

Terminal Actions

• Send Selection to Cascade - Highlight error/stack trace → Cmd/Ctrl+L
• Cascade Terminal Commands - Cascade can execute terminal commands with tool calls
• Monitor Terminal Output - Cascade monitors terminal output for real-time awareness

Windsurf supports remote development workflows:

SSH Support

• Connect to Linux-based remote hosts
• Execute Cascade tasks on remote machines
• Built-in OpenSSH integration
• Access via “Open a Remote Window” (bottom left)

Dev Containers

• Local: Docker required
• Remote over SSH: Docker on remote host
• Commands: Reopen in Container, Attach to Running Container, Show Logs
• Uses devcontainer.json configuration

WSL (Beta)

• Windows Subsystem for Linux support
• Access via “Open a Remote Window” (bottom left)

Customize Cascade behavior with persistent context via Memories feature:

Access: /memory command in Cascade or Windsurf Settings → Cascade → Memories

Memories

Store project-specific knowledge that persists across conversations:

• Coding standards and patterns
• Project architecture notes
• Common workflows and conventions
• Team-specific guidelines

Format: Define rules using markdown or structured text within Cascade

Example (coding guidelines):

- Project language: Python
- Use early returns when possible
- Always add documentation for new functions and classes

Organized format (with XML tags):

<coding_guidelines>
- Project language: Python  
- Use early returns when possible
- Always add documentation for new functions and classes
</coding_guidelines>

Rules

Guide Cascade’s decision-making and behavior:

• Define preferred coding styles
• Specify testing requirements
• Set documentation standards
• Establish naming conventions

Persistence: Memories and rules remain active across conversations in the same project

Management:

• View current memories: /memory command
• Edit via Cascade Settings → Memories
• Project-level persistence (not stored as JSON files)

WINDSURF.md

Optional project instructions file with hierarchical loading:

• Global: ~/.windsurf/WINDSURF.md
• Git Root: <repo-root>/WINDSURF.md
• Subdirectory: <subfolder>/WINDSURF.md

Cascade automatically loads context from these files when starting in a project directory.

Exclude files from Cascade context using .codeiumignore:

Project-level (.codeiumignore at workspace root):

node_modules/
dist/
.git/
*.log
build/
coverage/
secrets/
*.env

Global (Teams/Enterprise: ~/.codeium/.codeiumignore):

Enforced across all repositories for team members

Format: Follows gitignore syntax

Gitignore Access Setting

Configure whether Cascade can read .gitignore-matched files:

Access: Windsurf Settings → Cascade → Cascade Gitignore Access

Enable voice-to-text for hands-free Cascade interaction:

Note: Transcription only; Cascade still requires written prompts for full reasoning

Enable: Windsurf Settings → Cascade → Voice Mode (beta feature for paying users)

Common commands to invoke during Cascade conversation:

Queued Messages

• Queue multiple requests while Cascade works
• Type message → Press Enter to queue
• Send immediately: Press Enter again (if text box empty)
• Delete: Remove queued message before execution

Real-Time Awareness

• Cascade monitors your live edits, terminal output, and active context
• Simply tell Cascade “Continue” after making edits
• No manual context re-injection needed

Conversation Sharing (Teams & Enterprise)

Share Cascade conversations with team members:

Cascade panel → ... (more options) → Share Conversation

Custom App Icons (Beta - Mac only)

For paying users:

Profile/settings icon (top right) → Customize App Icon

✅ Do:

• Create checkpoints before major changes - Use named snapshots to explore safely
• Start with Chat mode for planning - Discuss approach before Code mode edits
• Review before accepting changes - Always review Cascade’s edits before clicking Accept
• Build custom workflows - Workflows are faster than repeated prompts for common tasks
• Use Memories for project context - Store coding standards, patterns, architecture notes
• Configure terminal allow/deny lists - Prevent dangerous commands from auto-executing
• Set up MCP plugins strategically - Stay under 100-tool limit by enabling only needed tools
• Use .codeiumignore - Exclude sensitive files from Cascade context
• Enable proper team MCP controls - Whitelist approved servers for team security

❌ Don’t:

• Revert without caution - Checkpoints reverts are irreversible
• Disable all approval gates - Keep some review points for safety
• Exceed 100 MCP tool limit - Disable unused tools to stay under limit
• Commit sensitive data to workflows - Keep credentials in environment variables
• Ignore terminal deny list - Add dangerous commands (like rm -rf) to deny list
• Mix authentication accounts - Use consistent account across devices
• Rely solely on Cascade - Always review AI-generated code before shipping

Common issues:

Debug MCP connection:

which npx

npx @modelcontextprotocol/server-github --version

cat ~/.codeium/windsurf/mcp_config.json

Debug mode:

1. Open Developer Console: Cmd/Ctrl+Shift+P → “Developer: Toggle Developer Tools”
2. Check Windsurf logs: ~/.codeium/windsurf/logs/
3. Look for MCP and auth errors in console

Restart Windsurf: Many config changes require restart to take effect

Auto-update:

• Click “Restart to Update” button (top right menu bar when available)

Manual check:

1. Profile icon dropdown → Check for Updates
2. Command Palette (Cmd/Ctrl+Shift+P) → “Check for Updates”

Windsurf Next (Prerelease):

• Opt-in for early access to newest features
• Download: https://windsurf.com/editor/download-next

Steps:

1. Close Windsurf application
2. Delete application (drag to Trash on macOS)
3. Remove configuration directory:

macOS/Linux:

rm -rf ~/.codeium/windsurf

Windows:

C:\Users\[YourUsername]\.codeium\windsurf

(Manually delete this folder)

• Windsurf Getting Started - Installation, onboarding, setup
• Cascade Overview - Full Cascade capabilities
• Cascade Workflows - Creating and running workflows
• MCP Integration - Extending Cascade with custom tools
• Memories & Rules - Persistent context customization
• Advanced Configuration - SSH, Dev Containers, WSL
• Terminal Integration - Terminal commands and auto-execute policies
• Model Context Protocol - MCP specification
• MCP Server Repository - Official MCP servers
• Windsurf Changelog - Release notes and updates
• Discord Community - Support and discussions

Last updated: 2025-11-12