Multi-CLI Configuration Discovery Patterns

Research Date: 2025-10-19 Purpose: Inform architectural decision for .claude → .coditect migration with universal CLI compatibility Status: Comprehensive web research complete

Executive Summary

We researched configuration discovery patterns across 9 major llm CLI tools to determine optimal naming and compatibility strategy for CODITECT's skill/agent system.

Key Findings:

✅ Claude Code: Most flexible - supports CLAUDE_CONFIG_DIR environment variable
❌ Gemini CLI: Hardcoded ~/.gemini - no environment variable support
✅ Aider: Sophisticated 3-level fallback system (home → git repo → current dir)
⚠️ Cursor: SQLite storage + VS Code compatibility, no custom directory support
⚠️ Windsurf: OS-specific paths, no documented environment variables
❌ Amazon Q: Hardcoded ~/.aws/amazonq - XDG support requested since 2017
⚠️ JetBrains: Product-specific paths with *_PROPERTIES env vars
⚠️ GitHub Copilot: Follows VS Code patterns, undocumented VSCODE_EXTENSIONS
✅ Eclipse theia: Excellent - THEIA_CONFIG_DIR + full XDG support

Strategic Recommendation: Use dual-path compatibility (.claude/ + .coditect/) via symlinks + environment variables.

Detailed CLI Analysis

1. Claude Code

Vendor: Anthropic Source: GitHub Issues, Configuration Docs

Configuration Discovery Order (highest to lowest priority):

CLAUDE_CONFIG_DIR environment variable     # Highest priority
XDG_CONFIG_HOME/claude (Linux/Unix only)  # XDG compliance
~/.claude                                  # Default fallback

Environment Variables:

# Custom config directory (RECOMMENDED)
export CLAUDE_CONFIG_DIR=$HOME/.config/claude

# XDG-compliant (Linux/Unix)
export XDG_CONFIG_HOME=$HOME/.config
# Claude Code will look in ~/.config/claude

# Default (no env vars)
# Claude Code uses ~/.claude

Settings Hierarchy:

Enterprise Config (highest priority)
  ↓
User Config (~/.claude/settings.json or $CLAUDE_CONFIG_DIR/settings.json)
  ↓
Project Config (.claude/settings.json)
  ↓
Local Project Config (.claude/settings.local.json - NOT version controlled)

Known Issues:

❌ Symlink bugs: Relative paths in CLAUDE.md fail when directory is symlinked (Issue #764)
❌ Config not found: .claude-config/config.json not found with CLAUDE_CONFIG_DIR (Issue #519)
⚠️ Partial XDG: Uses XDG_CONFIG_HOME/claude but violates spec by mixing config, cache, runtime files

Compatibility Strategy:

# Option 1: Use CLAUDE_CONFIG_DIR to point to .coditect
export CLAUDE_CONFIG_DIR=/workspace/.coditect

# Option 2: Symlink (RISKY - known bugs)
ln -s /workspace/.coditect ~/.claude

# Option 3: Dual directories (SAFEST)
# Keep .claude/ as symlink to .coditect/
# Set CLAUDE_CONFIG_DIR=/workspace/.coditect

XDG Compliance: ⚠️ Partial - Uses XDG path but violates separation of concerns

2. Gemini CLI (Google)

Vendor: Google Source: Gemini CLI GitHub, Tutorial

Configuration Directory Discovery:

# Hardcoded - NO environment variable support currently
~/.gemini/settings.json  # Created automatically on first launch

Project-Level Override:

<project-root>/.gemini/settings.json  # Overrides global settings

Environment Variables (for settings, NOT directory location):

GEMINI_API_KEY         # Your Gemini API key
GOOGLE_CLOUD_PROJECT   # GCP project ID (for Vertex AI)
GOOGLE_CLOUD_LOCATION  # GCP location (for Code Assist)
GEMINI_SANDBOX         # Enable sandbox mode

Settings Hierarchy (highest to lowest priority):

Command-line flags
  ↓
Environment variables (GEMINI_*)
  ↓
Project settings (.gemini/settings.json)
  ↓
Global settings (~/.gemini/settings.json)

Alternative Configuration:

~/.env  # Gemini CLI also checks for environment variables here

Known Limitations:

❌ No directory environment variable: Cannot customize ~/.gemini location
❌ No XDG support: Does not follow XDG Base Directory Specification
❌ Cannot rename directory: .gemini name is hardcoded
📝 Feature request: Issue #2815 - requesting GEMINI_CONFIG_DIR

Compatibility Strategy:

# CANNOT use Gemini CLI with .coditect directory
# Must create .gemini/ directory separately
# OR wait for GEMINI_CONFIG_DIR feature (no timeline)

# Workaround: Symlink (untested)
ln -s /workspace/.coditect ~/.gemini  # May or may not work

XDG Compliance: ❌ None

3. Aider

Vendor: Aider (Open Source) Source: Aider Config Docs, YAML Config

Multi-Path Fallback Pattern (loaded in order, later overrides earlier):

~/.aider.conf.yml              # Home directory (loaded first)
<git-repo-root>/.aider.conf.yml # Git repo root (loaded second)
<current-dir>/.aider.conf.yml  # Current directory (highest priority)

Alternative: Single Config File:

aider --config <filename>  # Only load this one config file

Environment Variables (automatic AIDER_ prefix):

# ALL command-line arguments automatically get AIDER_ env var support
AIDER_MODEL=gpt-4o
AIDER_OPENAI_API_KEY=sk-...
AIDER_EDIT_FORMAT=whole
AIDER_AUTO_COMMITS=true
AIDER_DARK_MODE=true

# Pattern: --option-name → AIDER_OPTION_NAME

.env File Discovery (loaded in same order as YAML):

~/.env                     # Home directory
<git-repo-root>/.env      # Git repo root
<current-dir>/.env        # Current directory
aider --env-file <path>   # Explicit path (highest priority)

Configuration Precedence (highest to lowest):

Command-line arguments
  ↓
Environment variables (AIDER_*)
  ↓
.env file (current dir)
  ↓
.aider.conf.yml (current dir)
  ↓
.env file (git repo root)
  ↓
.aider.conf.yml (git repo root)
  ↓
.env file (home)
  ↓
.aider.conf.yml (home)

Example Multi-Level Config:

# Project structure
~/projects/my-app/
  .git/
  .aider.conf.yml      # Project-specific config
  src/
    feature/
      .aider.conf.yml  # Feature-specific overrides

~/.aider.conf.yml      # Global defaults

# Running from ~/projects/my-app/src/feature/
# Loads ALL three files in order (home → repo → current)

Compatibility Strategy:

# Aider uses .aider.conf.yml naming pattern
# NOT compatible with .coditect directory

# Workaround: Symlink config file
ln -s /workspace/.coditect/aider.conf.yml ~/.aider.conf.yml

XDG Compliance: ❌ None - Uses traditional dotfile pattern

4. Cursor IDE

Vendor: Cursor (VS Code fork) Source: Cursor Settings, VS Code Migration

Settings Storage Location (by platform):

macOS:

# SQLite database (Cursor-specific, not plain JSON)
~/Library/Application Support/Cursor/User/globalStorage/state.vscdb

# User settings (VS Code compatible)
~/Library/Application Support/Cursor/User/settings.json

# Keybindings
~/Library/Application Support/Cursor/User/keybindings.json

Windows:

%USERPROFILE%\AppData\Roaming\Cursor\User\settings.json
%USERPROFILE%\AppData\Roaming\Cursor\User\globalStorage\state.vscdb

Linux:

~/.config/Cursor/User/settings.json
~/.config/Cursor/User/globalStorage/state.vscdb

Extensions Discovery:

# macOS
~/Library/Application Support/Cursor/extensions/

# Windows
%USERPROFILE%\.cursor\extensions\

# Linux
~/.cursor/extensions/

Project Configuration:

<project-root>/.cursor/rules/     # Cursor rules (v0.45+)
<project-root>/.cursorrules       # Legacy cursor rules
<project-root>/.cursor/mcp.json   # MCP configuration
<project-root>/.cursor/docs/      # Documentation

MCP Configuration Locations:

~/.cursor/mcp.json              # Global MCP servers
<project-root>/.cursor/mcp.json # Project-specific MCP servers

VS Code Compatibility:

✅ Can import VS Code settings with one click
✅ Extensions directory follows VS Code pattern
✅ workspace settings use .vscode/settings.json (compatible)

Known Limitations:

⚠️ Hybrid storage: Uses both JSON files AND SQLite database
❌ No environment variables: No CURSOR_CONFIG_DIR equivalent
❌ Cannot customize directory: Config location is hardcoded
⚠️ Partial XDG: Linux uses ~/.config/Cursor (XDG path only)

Compatibility Strategy:

# CANNOT use Cursor with .coditect directory
# Must use project-level .cursor/ directory

# Project config (SUPPORTED)
/workspace/.cursor/mcp.json
/workspace/.cursor/rules/

XDG Compliance: ⚠️ Partial - Linux uses XDG path, but macOS/Windows don't

5. Windsurf IDE

Vendor: Codeium Source: Windsurf Docs, Installation Guide

Configuration Directories (by platform):

Windows:

%APPDATA%\Windsurf
# Full path: C: Users <username> AppData Roaming Windsurf

macOS:

~/Library/Application Support/Windsurf

Linux:

~/.config/windsurf

MCP Configuration:

# Windows
%USERPROFILE%\.codeium\windsurf\mcp_config.json
# OR
%APPDATA%\Codeium\Windsurf\mcp_config.json

# macOS/Linux
~/.codeium/windsurf/mcp_config.json

Project Configuration:

<project-root>/.windsurfrules  # workspace-specific rules

Settings Access:

UI: Ctrl+, (Windows/Linux) or Cmd+, (macOS) → "View Settings"
File: settings.json in user data directory

VS Code Compatibility:

✅ Built on VS Code codebase
✅ Can import VS Code settings and extensions with one click
✅ Uses similar directory structure

Known Limitations:

❌ No documented environment variables: Cannot customize config path
❌ No XDG support: Uses OS-specific standard paths only
⚠️ MCP config location differs: Uses .codeium/windsurf/ not .windsurf/

Compatibility Strategy:

# CANNOT use Windsurf with .coditect directory
# Must use separate .codeium/windsurf/ for MCP

# Workaround: Symlink (untested)
ln -s /workspace/.coditect ~/.codeium/windsurf

XDG Compliance: ⚠️ Partial - Linux uses ~/.config/windsurf (XDG path only)

6. Amazon Q Developer

Vendor: AWS Source: AWS Docs, MCP Guide

Configuration Directories:

~/.aws/amazonq/                   # Global config directory
~/.aws/amazonq/mcp.json           # MCP configuration (global)
~/.aws/amazonq/default.json       # IDE configuration (global)
~/.aws/amazonq/agents/            # Custom agents

<project-root>/.amazonq/mcp.json  # MCP configuration (project-specific)
<project-root>/.amazonq/default.json # IDE configuration (project-specific)

Environment Variables:

# Logging
Q_LOG_LEVEL=debug|info|warn|error

# Proxy
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=https://proxy.example.com:8443

# AWS credentials (standard)
AWS_CONFIG_FILE=/custom/path/config
AWS_SHARED_CREDENTIALS_FILE=/custom/path/credentials

MCP Configuration Structure:

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Known Limitations:

❌ No XDG support: Does NOT support XDG_CONFIG_HOME
❌ Hardcoded path: ~/.aws/amazonq location cannot be changed
📝 Long-standing issue: XDG support requested since 2017 (no timeline)
⚠️ MCP env optional: If env field not defined, no environment variables set

Compatibility Strategy:

# CANNOT use Amazon Q with .coditect directory
# Must use ~/.aws/amazonq/ directory

# Workaround: Symlink (untested)
ln -s /workspace/.coditect ~/.aws/amazonq

XDG Compliance: ❌ None - Hardcoded ~/.aws/ path

7. JetBrains AI Assistant

Vendor: JetBrains Source: JetBrains Docs, IDE Directories

Configuration Directories (2020.1+, by platform):

Windows:

# Configuration
%APPDATA%\JetBrains\<ProductName><Version>
# Example: %APPDATA% JetBrains IntelliJIdea2022.2

# System/Caches
%LOCALAPPDATA%\JetBrains\<ProductName><Version>

macOS:

# Configuration
~/Library/Application Support/JetBrains/<ProductName><Version>

# System/Caches
~/Library/Caches/JetBrains/<ProductName><Version>

# Logs
~/Library/Logs/JetBrains/<ProductName><Version>

Linux:

# Configuration
~/.config/JetBrains/<ProductName><Version>

# Plugins
~/.local/share/JetBrains/<ProductName><Version>

# System/Caches
~/.cache/JetBrains/<ProductName><Version>

Environment Variables (product-specific):

# Each JetBrains product has its own environment variable
CL_PROPERTIES=/path/to/clion.properties
PYCHARM_PROPERTIES=/path/to/pycharm.properties
DATAGRIP_PROPERTIES=/path/to/datagrip.properties
IDEA_PROPERTIES=/path/to/idea.properties

# Within idea.properties file:
idea.config.path=/custom/config/path
idea.system.path=/custom/system/path
idea.plugins.path=/custom/plugins/path

AI Assistant Settings:

UI: Settings | Tools | AI Assistant | Models
Rules: Settings | Tools | AI Assistant | Rules
Follows standard JetBrains plugin architecture
No dedicated environment variable for AI Assistant

MCP Configuration (JetBrains Junie IDE):

~/.junie/mcp.json              # Global
<project-root>/.junie/mcp/mcp.json # Project

Legacy Paths (pre-2020.1):

~/.IntelliJIdea2019.3  # Linux/macOS
C:\Users\<user>\.IntelliJIdea2019.3  # Windows

Compatibility Strategy:

# Use product-specific properties file
export IDEA_PROPERTIES=/workspace/.coditect/idea.properties

# In idea.properties:
idea.config.path=/workspace/.coditect/config
idea.plugins.path=/workspace/.coditect/plugins

XDG Compliance: ✅ Full (Linux only, 2020.1+) - Uses ~/.config, ~/.local/share, ~/.cache

8. GitHub Copilot

Vendor: GitHub/Microsoft Source: VS Code Copilot Docs, GitHub Docs

Configuration Files (by platform):

User Settings:

# Windows
%APPDATA%\Code\User\settings.json

# macOS
~/Library/Application Support/Code/User/settings.json

# Linux
~/.config/Code/User/settings.json

Extensions Directory:

# Windows
%USERPROFILE%\.vscode\extensions

# macOS/Linux
~/.vscode/extensions

VS Code OSS (Open Source):

# Linux Settings
~/.config/Code - OSS/User/settings.json

# Linux Extensions
~/.vscode-oss

Environment Variables (undocumented but works):

# Custom extensions directory
export VSCODE_EXTENSIONS=/path/to/extensions

# Windows (temporary)
set VSCODE_EXTENSIONS=C:\path\to\extensions

# Windows (permanent)
setx VSCODE_EXTENSIONS=C:\path\to\extensions

Command-Line Flags:

# Change extensions directory
code --extensions-dir=/path/to/extensions

# Install extension
code --install-extension /path/to/extension.vsix

Extension Discovery:

Manifest: package.json in extension directory
Configuration: contributes > configuration property in package.json

GitHub Copilot CLI (if applicable):

# Config (customizable via XDG_CONFIG_HOME)
~/.config/config.json
~/.config/mcp-config.json

# Environment
export XDG_CONFIG_HOME=~/.config  # Defaults to ~/.config

Compatibility Strategy:

# Use VSCODE_EXTENSIONS for custom extensions path
export VSCODE_EXTENSIONS=/workspace/.coditect/extensions

# OR use command-line flag
code --extensions-dir=/workspace/.coditect/extensions

XDG Compliance: ⚠️ Partial - Linux uses ~/.config/Code (XDG path only)

9. Eclipse theia (T2 Project Foundation)

Vendor: Eclipse Foundation Source: Eclipse theia GitHub, theia Docs

Configuration Discovery Order (highest to lowest priority):

THEIA_CONFIG_DIR environment variable  # Highest priority
XDG_CONFIG_HOME/theia (Linux)         # XDG compliance
~/Library/Application Support/theia (macOS)
%APPDATA%/theia (Windows)
~/.theia                               # Legacy fallback

Environment Variables:

# Primary configuration directory
export THEIA_CONFIG_DIR=/workspace/.coditect

# Extension registry
export VSX_REGISTRY_URL=https://custom-registry.example.com

# XDG support (Linux)
export XDG_CONFIG_HOME=/custom/xdg/config
# theia will use $XDG_CONFIG_HOME/theia

Settings Files:

# workspace
${workspace}/.theia/settings.json

# User
${home}/.theia/settings.json

Extensions:

.theia-blueprint/extensions  # Extension directory

Recommended Directory Structure:

Project Root:
├── .theia/
│   ├── settings.json          # workspace settings
│   ├── mcp.json               # Project-specific MCP servers
│   └── extensions/            # workspace extensions

User Home (Linux with XDG):
├── .config/theia/             # XDG-compliant
│   ├── settings.json          # User settings
│   ├── mcp.json               # Global MCP servers
│   └── extensions/            # User extensions

Compatibility Strategy:

# EXCELLENT SUPPORT - Use THEIA_CONFIG_DIR
export THEIA_CONFIG_DIR=/workspace/.coditect

# theia will use /workspace/.coditect/ for all config
# Full XDG support on Linux

XDG Compliance: ✅ Full (Linux) - Complete XDG Base Directory Specification support

MCP (Model Context Protocol) Configuration Patterns

Emerging Standard: Most modern AI IDEs support MCP configuration

Common Configuration File Locations:

Tool	Global Config	Project Config
Cursor	`~/.cursor/mcp.json`	`.cursor/mcp.json`
Amazon Q	`~/.aws/amazonq/mcp.json`	`.amazonq/mcp.json`
JetBrains Junie	`~/.junie/mcp.json`	`.junie/mcp/mcp.json`
Continue	N/A	`.continue/mcpServers/mcp.json`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	N/A
VS Code	User settings	`.vscode/mcp.json`
theia	`${THEIA_CONFIG_DIR}/mcp.json`	`.theia/mcp.json`

Standard MCP Config Structure:

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      },
      "disabled": false,
      "autoApprove": ["tool1", "tool2"]
    }
  }
}

Compatibility Strategy for CODITECT:

# Support multiple MCP config locations
/workspace/.coditect/mcp.json           # Primary
/workspace/.theia/mcp.json              # theia compatibility
/workspace/.cursor/mcp.json             # Cursor compatibility
/workspace/.amazonq/mcp.json            # Amazon Q compatibility
~/.codeium/windsurf/mcp_config.json     # Windsurf compatibility

XDG Base Directory Specification Compliance

XDG Standard (Linux):

$XDG_CONFIG_HOME    # User config files (default: ~/.config)
$XDG_DATA_HOME      # User data files (default: ~/.local/share)
$XDG_STATE_HOME     # User state files (default: ~/.local/state)
$XDG_CACHE_HOME     # User cache files (default: ~/.cache)
$XDG_RUNTIME_DIR    # User runtime files

CLI Compliance Summary:

Tool	XDG Support	Rating	Notes
Eclipse theia	Full	✅	Complete XDG support on Linux
JetBrains	Full	✅	XDG paths on Linux (2020.1+)
Claude Code	Partial	⚠️	Uses `$XDG_CONFIG_HOME/claude` but mixes file types
Cursor	Partial	⚠️	Linux uses `~/.config/Cursor` (path only)
Windsurf	Partial	⚠️	Linux uses `~/.config/windsurf` (path only)
GitHub Copilot	Partial	⚠️	Linux uses `~/.config/Code` (path only)
Gemini CLI	None	❌	Hardcoded `~/.gemini`
Amazon Q	None	❌	Hardcoded `~/.aws/amazonq`
Aider	None	❌	Traditional dotfile pattern

Best Practice Implementation:

# Configuration files
$XDG_CONFIG_HOME/coditect/config.yml      # ~/.config/coditect/config.yml

# Data files (models, databases)
$XDG_DATA_HOME/coditect/models/           # ~/.local/share/coditect/models/

# State files (logs, history)
$XDG_STATE_HOME/coditect/history.log      # ~/.local/state/coditect/history.log

# Cache files (temporary data)
$XDG_CACHE_HOME/coditect/cache/           # ~/.cache/coditect/cache/

# Runtime files (sockets, PIDs)
$XDG_RUNTIME_DIR/coditect/daemon.pid

Strategic Recommendations for CODITECT

Universal Compatibility Strategy

Phase 1: Dual-Path Support (Immediate - Sprint 3)

# Primary configuration
/workspace/.coditect/           # Brand-aligned directory

# Compatibility symlinks
/workspace/.claude/    → .coditect/    # Claude Code compatibility
/workspace/.theia/     → .coditect/    # theia compatibility (optional - theia can use THEIA_CONFIG_DIR)

# Environment variables (set in container)
export THEIA_CONFIG_DIR=/workspace/.coditect
export CLAUDE_CONFIG_DIR=/workspace/.coditect
export XDG_CONFIG_HOME=/workspace/.config  # Standard Linux

Phase 2: Multi-CLI MCP Support (Sprint 4)

# Support MCP config in multiple locations
.coditect/mcp.json              # Primary
.cursor/mcp.json                # Cursor users
.amazonq/mcp.json               # Amazon Q users
.codeium/windsurf/mcp_config.json # Windsurf users

# All symlinked or copied to .coditect/mcp.json

Phase 3: Container Versioning (Sprint 5)

# Bake into container image
/workspace/.coditect/           # Pre-configured skills/agents
  ├── skills/
  │   ├── REGISTRY.json
  │   ├── build-deploy-workflow/
  │   ├── gcp-resource-cleanup/
  │   ├── git-workflow-automation/
  │   ├── cross-file-documentation-update/
  │   └── token-cost-tracking/
  ├── agents/
  │   ├── orchestrator.md
  │   ├── codebase-analyzer.md
  │   └── ...
  └── mcp.json

# Versioning
coditect/combined:v1.0.0-skills-2025.10.19

Configuration Discovery Implementation

Recommended Discovery Order (for CODITECT):

CODITECT_CONFIG_DIR          # Highest priority (custom env var)
THEIA_CONFIG_DIR             # theia native support
CLAUDE_CONFIG_DIR            # Claude Code compatibility
XDG_CONFIG_HOME/coditect     # XDG compliance (Linux)
~/.config/coditect           # XDG default (Linux)
~/Library/Application Support/coditect # macOS standard
%APPDATA%/coditect           # Windows standard
~/.coditect                  # Legacy fallback

Implementation (in CODITECT startup):

// src/config/discovery.ts
function getConfigDir(): string {
  // 1. Check custom environment variable
  if (process.env.CODITECT_CONFIG_DIR) {
    return process.env.CODITECT_CONFIG_DIR;
  }

  // 2. Check theia environment variable
  if (process.env.THEIA_CONFIG_DIR) {
    return process.env.THEIA_CONFIG_DIR;
  }

  // 3. Check Claude Code environment variable
  if (process.env.CLAUDE_CONFIG_DIR) {
    return process.env.CLAUDE_CONFIG_DIR;
  }

  // 4. XDG compliance (Linux)
  if (process.platform === 'linux') {
    const xdgConfigHome = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
    return path.join(xdgConfigHome, 'coditect');
  }

  // 5. macOS standard
  if (process.platform === 'darwin') {
    return path.join(os.homedir(), 'Library', 'Application Support', 'coditect');
  }

  // 6. Windows standard
  if (process.platform === 'win32') {
    return path.join(process.env.APPDATA || '', 'coditect');
  }

  // 7. Legacy fallback
  return path.join(os.homedir(), '.coditect');
}

Known Compatibility Issues

Claude Code Symlink Bugs

Issue: Relative paths in CLAUDE.md fail when directory is symlinked
GitHub: Issue #764
Workaround: Use CLAUDE_CONFIG_DIR instead of symlinks

Gemini CLI Hardcoded Path

Issue: Cannot customize ~/.gemini directory location
Feature Request: Issue #2815
Workaround: None - must use ~/.gemini for Gemini CLI

Amazon Q XDG Support

Issue: Does NOT support XDG_CONFIG_HOME
Timeline: Requested since 2017, no implementation timeline
Workaround: None - must use ~/.aws/amazonq

Cursor SQLite Storage

Issue: Settings stored in SQLite database, not plain JSON
Impact: Cannot easily edit settings via text files
Workaround: Use UI settings editor

Conclusion

Best Universal Compatibility Approach:

Use .coditect/ as primary directory (brand alignment)
Set environment variables for CLI compatibility:
- THEIA_CONFIG_DIR=/workspace/.coditect
- CLAUDE_CONFIG_DIR=/workspace/.coditect
Support multiple MCP config locations (symlinks or copies)
Follow XDG Base Directory Specification on Linux
Provide CLI-specific compatibility layers as needed

Trade-offs:

✅ Brand consistency: .coditect/ directory aligns with product name
✅ theia compatibility: Full support via THEIA_CONFIG_DIR
✅ Claude Code compatibility: Full support via CLAUDE_CONFIG_DIR
⚠️ Gemini CLI: May require separate .gemini/ directory
⚠️ Amazon Q: May require separate .aws/amazonq/ directory
✅ Cursor/Windsurf: Project-level configs (.cursor/, .windsurfrules) work fine

Final Recommendation: Proceed with .coditect/ naming + environment variable compatibility layer. This provides maximum flexibility while maintaining brand identity.

Research Complete: 2025-10-19 Next Step: Create ADR documenting final architectural decision Implementation: Sprint 3 (Phase 1: Dual-path support)

Executive Summary​

Detailed CLI Analysis​

1. Claude Code​

2. Gemini CLI (Google)​

3. Aider​

4. Cursor IDE​

5. Windsurf IDE​

6. Amazon Q Developer​

7. JetBrains AI Assistant​

8. GitHub Copilot​

9. Eclipse theia (T2 Project Foundation)​

MCP (Model Context Protocol) Configuration Patterns​

XDG Base Directory Specification Compliance​

Strategic Recommendations for CODITECT​

Universal Compatibility Strategy​

Configuration Discovery Implementation​

Known Compatibility Issues​

Claude Code Symlink Bugs​

Gemini CLI Hardcoded Path​

Amazon Q XDG Support​

Cursor SQLite Storage​

Conclusion​

Executive Summary

Detailed CLI Analysis

1. Claude Code

2. Gemini CLI (Google)

3. Aider

4. Cursor IDE

5. Windsurf IDE

6. Amazon Q Developer

7. JetBrains AI Assistant

8. GitHub Copilot

9. Eclipse theia (T2 Project Foundation)

MCP (Model Context Protocol) Configuration Patterns

XDG Base Directory Specification Compliance

Strategic Recommendations for CODITECT

Universal Compatibility Strategy

Configuration Discovery Implementation

Known Compatibility Issues

Claude Code Symlink Bugs

Gemini CLI Hardcoded Path

Amazon Q XDG Support

Cursor SQLite Storage

Conclusion