OpenCode vs Codex CLI: Harness Architecture Deep Dive (2025)

// OpenCode uses Vercel AI SDK for model abstraction
// Client/Server architecture with Hono HTTP API

// Key architectural components:
├── packages/
│   ├── core/           // Agent orchestration
│   ├── tui/            // Bubble Tea terminal UI
│   ├── web/            // Desktop app (Tauri)
│   └── opencode-ai/    // Model abstraction layer
├── Model Layer: Vercel AI SDK (provider-agnostic)
├── HTTP API: Hono (enables mobile/remote control)
├── TUI: Bubble Tea framework
└── State: Client/server with persistent sessions

// Agent modes:
// - "build": Full tool access (default)
// - "plan": Read-only, asks permission
// - "general": Subagent for complex tasks
// - "explore": Read-only codebase navigation

// Codex CLI: Monolithic Rust implementation
// Direct OpenAI API integration, no abstraction layer

// Key architectural components:
├── codex-rs/
│   ├── core/           // Agent logic + prompts
│   ├── cli/            // Terminal interface
│   ├── mcp-server/     // MCP tool server
│   └── exec/           // Command execution
├── Model Layer: Direct OpenAI API (GPT-5-Codex optimized)
├── Cloud: Sandboxed task execution (per-task isolation)
├── TUI: Custom Rust terminal framework
└── State: Session-based with cloud persistence

// Execution modes:
// - Local: Runs on user machine
// - Cloud: Isolated sandbox per task
// - CI/CD: GitHub Actions integration

You are a coding agent running in the Codex CLI, a terminal-based
coding assistant. Codex CLI is an open source project led by OpenAI.
You are expected to be precise, safe, and helpful.

## Capabilities
- Receive user prompts and context provided by the harness
- Communicate by streaming thinking & responses
- Make and update plans for multi-step tasks
- Emit function calls to run terminal commands
- Apply patches to modify files

## Personality
The default personality is concise, direct, and friendly.
It communicates efficiently, keeping the user informed about
ongoing actions without unnecessary detail.

## GPT-5 Specific Instructions (from gpt_5_codex_prompt.md)
You are Codex, based on GPT-5. When searching for text or files,
prefer using rg or rg --files respectively because rg is much
faster than alternatives like grep.

# Example: .opencode/agents/build.md
---
name: build
description: Default agent for development work
mode: primary
model: anthropic/claude-sonnet-4
temperature: 0.7
tools:
  write: true
  edit: true
  bash: true
  webfetch: true
permission:
  edit: allow
  bash: ask
  webfetch: allow
maxSteps: 50
---

You are a coding assistant helping with software development.
Focus on writing clean, maintainable code that follows the
project's existing patterns and conventions.

When making changes:
1. Read relevant files first to understand context
2. Make minimal, focused changes
3. Run tests after modifications
4. Explain your reasoning

// OpenCode edit tool (simplified schema)
{
  "name": "edit",
  "description": "Apply targeted edits to an existing file",
  "parameters": {
    "path": { "type": "string", "description": "File path" },
    "old_string": { "type": "string", "description": "Text to find" },
    "new_string": { "type": "string", "description": "Replacement text" },
    "replace_all": { "type": "boolean", "default": false }
  }
}

// Codex CLI apply_patch tool (simplified schema)
{
  "name": "apply_patch",
  "description": "Apply unified diff patch to modify files",
  "parameters": {
    "patch": { "type": "string", "description": "Unified diff content" }
  }
}

// Key difference: OpenCode uses search-replace semantics
// Codex uses unified diff patches (more git-native)

// Primary Agents (switch with Tab)
├── Build Agent
│   ├── All tools enabled
│   ├── Full file system access
│   └── Default for development work
│
└── Plan Agent
    ├── Read-only by default
    ├── Denies file edits
    └── Asks permission for bash

// Subagents (invoked via Task tool or @ mention)
├── General Subagent (@general)
│   ├── Full tool access (except todo)
│   ├── For complex multi-step tasks
│   └── Runs in parallel child sessions
│
└── Explore Subagent (@explore)
    ├── Read-only access
    ├── Fast codebase navigation
    └── Pattern matching and search

// Local Execution (default)
User Prompt → Agent Loop → Tool Calls → Local FS
    ↓
   Model: GPT-5-Codex
   Context: 192K tokens
   Tools: Local shell, file ops, MCP

// Cloud Execution (for complex tasks)
User Prompt → Cloud Sandbox → Isolated Container
    ↓
   - Pre-loaded with repo + environment
   - Full development toolchain
   - Results reviewed before merge
   - Multiple tasks can run in parallel

// CI/CD Execution (GitHub Actions)
PR Comment → @codex → GitHub Runner → Results
    ↓
   - Runs within Actions workflow
   - Access to CI secrets/environment
   - Automated task execution

// opencode.json permission structure
{
  "permission": {
    "edit": "allow",      // allow | ask | deny
    "bash": {
      "*": "ask",         // Default: ask for all
      "git *": "allow",   // Allow git commands
      "npm test": "allow",
      "rm -rf *": "deny"  // Block dangerous patterns
    },
    "webfetch": "allow",
    "task": {
      "general": "allow",
      "explore": "allow",
      "custom-*": "ask"
    },
    "skill": {
      "pr-review": "allow",
      "dangerous-*": "deny"
    }
  }
}

// Codex sandbox modes via CLI flags
$ codex --full-auto          # All permissions granted
$ codex --suggest            # Suggest-only, no auto-execute
$ codex                      # Default: ask for destructive ops

// Cloud sandbox (per-task isolation)
- Each cloud task runs in isolated container
- Pre-loaded with repo snapshot
- No access to local filesystem
- Results require explicit approval to merge

// AGENTS.md permission hints
# In your repo's AGENTS.md:
## Permissions
- Allow: git commands, npm/yarn, pytest
- Ask: file deletions, config changes
- Deny: system-level operations

// opencode.json provider configuration
{
  "provider": {
    "default": "anthropic/claude-sonnet-4",
    "fallback": "openai/gpt-4o",
    "local": "ollama/codellama:34b"
  },
  "agent": {
    "build": {
      "model": "anthropic/claude-sonnet-4"
    },
    "plan": {
      "model": "openai/gpt-4o"  // Different model for planning
    }
  }
}

// Supported providers (partial list):
// - anthropic/* (Claude models)
// - openai/* (GPT models)
// - google/* (Gemini models)
// - mistral/* (Mistral models)
// - ollama/* (Local models)
// - groq/* (Fast inference)
// - together/* (Open models)
// ... 75+ total providers

// Codex CLI model options (via ChatGPT subscription)
$ codex --model gpt-5-codex-high   # Highest quality
$ codex --model gpt-5-codex-medium # Balanced
$ codex --model gpt-5-codex-low    # Fastest

// Or via config (~/.codex/config.toml)
[model]
default = "gpt-5-codex-high"
thinking_effort = "high"  # low | medium | high

// API key authentication
$ export OPENAI_API_KEY="sk-..."
# Or use ChatGPT session (automatic with subscription)