sahajsoft · gsong · Jul 2, 2025
diff --git a/docs/codex-vs-gemini-comparison.md b/docs/codex-vs-gemini-comparison.md
@@ -0,0 +1,344 @@
+# Codex vs Gemini CLI: Customization and Extensibility Comparison
+
+A comprehensive analysis of two leading AI-powered CLI tools, focusing on their customization capabilities and extensibility features.
+
+## Executive Summary
+
+**Codex CLI** (OpenAI) and **Gemini CLI** (Google) represent two distinct approaches to AI-powered command-line development tools. While both prioritize customization and extensibility, they employ fundamentally different architectural philosophies:
+
+- **Codex** emphasizes a **minimalist, protocol-driven architecture** with strong security guarantees
+- **Gemini** focuses on a **feature-rich, user-friendly experience** with comprehensive built-in capabilities
+
+## Project Overview
+
+### Codex CLI (OpenAI)
+
+- **Language**: Rust
+- **Philosophy**: Lightweight coding agent with security-first design
+- **Target**: Terminal-focused developers who prioritize performance and security
+- **Architecture**: Protocol-driven client-server with multiple UI frontends
+
+### Gemini CLI (Google)
+
+- **Language**: TypeScript/Node.js
+- **Philosophy**: Comprehensive AI workflow tool with rich feature set
+- **Target**: Developers working with large codebases and complex workflows
+- **Architecture**: Package-based modular system with React-powered terminal UI
+
+## Customization Capabilities
+
+### Configuration Systems
+
+| Aspect                    | Codex                            | Gemini                                              |
+| ------------------------- | -------------------------------- | --------------------------------------------------- |
+| **Format**                | TOML with comments               | JSON with environment variable expansion            |
+| **Locations**             | `~/.codex/config.toml`           | `~/.gemini/settings.json` + `.gemini/settings.json` |
+| **Environment Variables** | Limited (`CODEX_HOME`, API keys) | Extensive (`$VAR` expansion, hierarchical `.env`)   |
+| **Profiles**              | ✅ Named profile system          | ❌ No profiles (workspace settings instead)         |
+| **Runtime Changes**       | ❌ Requires restart              | ✅ Dynamic updates supported                        |
+
+#### Codex Configuration Strengths
+
+- **Profile System**: Switch between complete configuration sets
+- **TOML Format**: Human-readable with comment support
+- **Strong Typing**: Rust-based validation prevents configuration errors
+- **Hierarchical Precedence**: CLI flags → profiles → base config → defaults
+
+#### Gemini Configuration Strengths
+
+- **Two-Tier Settings**: User and workspace-specific configurations
+- **Dynamic Updates**: Settings can be modified during runtime
+- **Environment Integration**: Extensive variable expansion and `.env` support
+- **Hierarchical Context**: Multi-level context file inheritance
+
+### Model and Provider Customization
+
+#### Codex
+
+```toml
+[model_providers.custom-llm]
+name = "Custom LLM Provider"
+base_url = "https://api.custom.com/v1"
+env_key = "CUSTOM_API_KEY"
+wire_api = "chat"
+query_params = { api-version = "2025-04-01" }
+
+[profiles.development]
+model = "gpt-4"
+approval_policy = "untrusted"
+sandbox = "workspace-write"
+```
+
+#### Gemini
+
+```json
+{
+  "theme": "atom-one",
+  "coreTools": ["file_system", "shell", "web"],
+  "mcpServers": {
+    "custom-server": {
+      "command": "python",
+      "args": ["server.py"],
+      "trust": true
+    }
+  }
+}
+```
+
+## Extensibility Features
+
+### Extension Architecture Comparison
+
+| Feature                 | Codex                         | Gemini                            |
+| ----------------------- | ----------------------------- | --------------------------------- |
+| **Plugin System**       | ❌ Configuration-based only   | ✅ Directory-based extensions     |
+| **MCP Support**         | ✅ Native Rust implementation | ✅ Official SDK integration       |
+| **Custom Tools**        | Via MCP servers only          | MCP + custom tool discovery       |
+| **Extension Discovery** | Configuration files           | `.gemini/extensions/` directories |
+| **API Access**          | Protocol-based communication  | Direct TypeScript interfaces      |
+
+### Model Context Protocol (MCP) Integration
+
+Both projects heavily leverage MCP for extensibility, but with different implementations:
+
+#### Codex MCP Features
+
+- **Native Rust Implementation**: Custom MCP client/server in Rust
+- **Connection Manager**: Sophisticated multi-server management
+- **Tool Namespacing**: Prevents conflicts with `server__OAI_CODEX_MCP__tool` format
+- **Security**: Sandboxed server execution with timeout management
+- **Performance**: Concurrent server spawning and tool aggregation
+
+#### Gemini MCP Features
+
+- **Official SDK**: Uses standard MCP TypeScript SDK
+- **Multiple Transports**: Stdio, SSE, and HTTP support
+- **Trust Model**: Trust-based confirmation bypass for known servers
+- **Extension Integration**: MCP servers can be defined per-extension
+- **Tool Registry**: Centralized tool discovery and registration
+
+### Custom Tool Development
+
+#### Codex Approach
+
+```rust
+// Tools must be implemented as MCP servers
+// Example: Custom file processor MCP server
+pub struct CustomTool {
+    name: String,
+    description: String,
+}
+
+impl McpTool for CustomTool {
+    async fn execute(&self, params: serde_json::Value) -> Result<ToolResult> {
+        // Custom tool implementation
+    }
+}
+```
+
+#### Gemini Approach
+
+```typescript
+// Built-in tool interface
+export class CustomFileTool implements Tool<CustomParams, CustomResult> {
+  name = "custom_file_tool";
+  displayName = "Custom File Tool";
+  description = "Processes files with custom logic";
+
+  async execute(params: CustomParams): Promise<CustomResult> {
+    // Direct tool implementation
+  }
+}
+
+// Or via tool discovery command
+{
+  "toolDiscoveryCommand": "python discover_tools.py",
+  "toolCallCommand": "python execute_tool.py"
+}
+```
+
+### Extension Examples
+
+#### Codex Extensions (via MCP)
+
+- **Custom Model Providers**: Add any OpenAI-compatible API
+- **External Tools**: Database clients, cloud providers, monitoring systems
+- **Notification Integrations**: Slack, Discord, email notifications
+- **Development Tools**: Linters, formatters, test runners
+
+#### Gemini Extensions
+
+```json
+{
+  "name": "development-tools",
+  "version": "1.0.0",
+  "mcpServers": {
+    "linter": { "command": "eslint-mcp-server" },
+    "formatter": { "command": "prettier-mcp-server" }
+  },
+  "excludeTools": ["web_search"],
+  "contextFileName": "DEV_CONTEXT.md"
+}
+```
+
+## Security and Sandboxing
+
+### Codex Security Model
+
+- **Multi-layered Approval**: Separate workflows for commands and file patches
+- **Native Sandboxing**: Landlock (Linux) and Seatbelt (macOS) integration
+- **Execution Policies**: Configurable safety checks and command restrictions
+- **MCP Isolation**: Server process isolation with resource limits
+
+### Gemini Security Model
+
+- **Confirmation-based**: User prompts for destructive operations
+- **Trust System**: Bypass confirmations for trusted MCP servers
+- **Docker Sandboxing**: Optional containerized execution environment
+- **Allowlisting**: Server and tool-level access controls
+
+## Performance and Architecture
+
+### System Architecture
+
+#### Codex: Protocol-Driven Design
+
+```
+┌─────────────┐    Protocol    ┌──────────────┐
+│ TUI/CLI/Exec│ ◄──────────── │ Core Library │
+└─────────────┘               └──────────────┘
+                                      │
+                               ┌──────▼──────┐
+                               │ MCP Manager │
+                               └─────────────┘
+```
+
+**Benefits:**
+
+- Transport-agnostic communication
+- Multiple UI implementations possible
+- Clear separation of concerns
+- Native performance with zero-cost abstractions
+
+#### Gemini: Package-Based Modularity
+
+```
+┌─────────────┐    Direct Calls    ┌──────────────┐
+│ CLI Package │ ◄────────────────► │ Core Package │
+└─────────────┘                   └──────────────┘
+                                          │
+                                   ┌──────▼──────┐
+                                   │ Tool Registry│
+                                   └─────────────┘
+```
+
+**Benefits:**
+
+- Flexible tool registration
+- Modern TypeScript ecosystem
+- React-based terminal UI
+- Comprehensive built-in toolset
+
+### Performance Characteristics
+
+| Metric                    | Codex                   | Gemini                      |
+| ------------------------- | ----------------------- | --------------------------- |
+| **Startup Time**          | Fast (native binary)    | Moderate (Node.js runtime)  |
+| **Memory Usage**          | Low (Rust efficiency)   | Higher (JavaScript runtime) |
+| **Tool Execution**        | Fast (native + MCP)     | Good (async/await patterns) |
+| **Concurrent Operations** | Excellent (Rust async)  | Good (Node.js event loop)   |
+| **File Operations**       | Moderate (MCP overhead) | Excellent (built-in tools)  |
+
+## Use Case Recommendations
+
+### Choose Codex If You Need:
+
+- **Maximum Security**: Native sandboxing and strict approval workflows
+- **Performance**: Native execution with minimal resource usage
+- **Flexibility**: Protocol-driven architecture supporting multiple frontends
+- **Extensibility via MCP**: Rich ecosystem of external MCP servers
+- **Terminal-First**: Optimized for terminal-based development workflows
+
+### Choose Gemini If You Need:
+
+- **Rich Built-in Tools**: Comprehensive file system and web capabilities
+- **User-Friendly UX**: Modern terminal UI with React components
+- **Large Codebase Support**: 1M+ token context windows
+- **Rapid Prototyping**: Extensive built-in functionality reduces setup time
+- **Google Ecosystem**: Integration with Google services and authentication
+
+## Customization Examples
+
+### Codex: Creating a Development Profile
+
+```toml
+# ~/.codex/config.toml
+[profiles.development]
+model = "gpt-4"
+approval_policy = "untrusted"
+sandbox = "workspace-write"
+notify = ["osascript", "-e", "display notification \"Task completed\""]
+
+[profiles.production]
+model = "o1"
+approval_policy = "on-failure"
+sandbox = "read-only"
+
+[mcp_servers.database]
+command = "python"
+args = ["-m", "database_mcp_server"]
+env = { DB_URL = "$DATABASE_URL" }
+```
+
+### Gemini: Project-Specific Extension
+
+```json
+# .gemini/settings.json
+{
+  "theme": "github",
+  "mcpServers": {
+    "project-tools": {
+      "command": "./scripts/mcp-server.js",
+      "trust": true
+    }
+  },
+  "excludeTools": ["web_search"],
+  "contextFileName": "PROJECT_CONTEXT.md"
+}
+```
+
+## Future Extensibility
+
+### Codex Roadmap Indicators
+
+- **Custom Trusted Commands**: User-defined safe commands
+- **Enhanced Protocol**: More sophisticated communication patterns
+- **Multi-model Support**: Improved model provider ecosystem
+- **Plugin API**: Potential for more formal plugin architecture
+
+### Gemini Current Trajectory
+
+- **Extension Registry**: Centralized extension discovery
+- **Advanced Telemetry**: Enhanced monitoring and analytics
+- **Tool Ecosystem**: Growing library of community tools
+- **API Improvements**: More powerful tool development APIs
+
+## Conclusion
+
+Both Codex and Gemini offer robust customization and extensibility, but serve different developer needs:
+
+**Codex excels for developers who prioritize**:
+
+- Security and sandboxing
+- Performance and resource efficiency
+- Protocol-driven architecture
+- MCP-based extensibility
+
+**Gemini excels for developers who prioritize**:
+
+- Rich built-in functionality
+- User experience and interface design
+- Rapid development workflows
+- Comprehensive tool ecosystem
+
+The choice between them depends on your specific requirements for security, performance, built-in capabilities, and architectural preferences. Both represent mature, well-designed approaches to AI-powered development tools with strong extensibility stories through MCP and their respective configuration systems.