---
mode: subagent
---

<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->
# t1665.6: Add Codex, Cursor, Droid Runtime Entries + Fix Codex Docker MCP

## Origin

- **Created:** 2026-03-26
- **Session:** claude-code:interactive
- **Created by:** marcusquinn (human + ai-interactive)
- **Parent task:** t1665
- **Conversation context:** User tried Codex CLI and hit MCP_DOCKER failure. Also wants Codex, Cursor, and Droid as first-class supported runtimes in aidevops setup/update.

## What

1. **Immediate fix**: Remove or conditionally disable the broken `MCP_DOCKER` entry in `~/.codex/config.toml` (Docker 28.5.2 via OrbStack doesn't support `docker mcp`)
2. **CLI installation**: Add `setup_codex_cli()` to `tool-install.sh` (install `@openai/codex` via npm/bun)
3. **Runtime entries**: Add Codex, Cursor, and Droid to the runtime registry with correct properties
4. **MCP deployment**: Deploy aidevops MCP servers to Codex config.toml, Cursor mcp.json, and Droid (when installed)
5. **System prompt deployment**: Deploy instructions/AGENTS.md to each runtime's native mechanism
6. **Setup integration**: Wire into `setup.sh` interactive and non-interactive flows

## Why

- Codex CLI ships with a broken `MCP_DOCKER` config that fails on non-Docker-Desktop setups (OrbStack, Colima, Rancher Desktop)
- Codex, Cursor, and Droid are popular AI coding tools that aidevops users want to use alongside Claude Code and OpenCode
- The framework's value proposition is "one setup, all runtimes" — these are the most-requested additions
- This is the concrete deliverable that validates the runtime abstraction layer (t1665.1-t1665.3)

## How (Approach)

### P0: Fix Codex Docker MCP (immediate, no dependencies)

The current `~/.codex/config.toml` contains:

```toml
[mcp_servers.MCP_DOCKER]
command = 'docker'
args = ['mcp', 'gateway', 'run']
```

But `docker mcp` requires Docker Desktop 4.40+ with the MCP Toolkit extension. OrbStack's Docker (28.5.2) doesn't support it.

**Fix approach**: During Codex config generation, validate each MCP server's command before writing:

```bash
# In mcp-config-adapter.sh (t1665.2) or standalone fix
validate_codex_mcp_entries() {
    local config="$HOME/.codex/config.toml"
    [[ -f "$config" ]] || return 0

    # Check each [mcp_servers.X] entry
    local mcp_names
    mcp_names=$(grep '^\[mcp_servers\.' "$config" | sed 's/\[mcp_servers\.\(.*\)\]/\1/')

    while IFS= read -r name; do
        [[ -z "$name" ]] && continue
        local cmd
        cmd=$(sed -n "/^\[mcp_servers\.$name\]/,/^\[/{ /^command/s/.*= *'\\(.*\\)'/\\1/p; }" "$config")
        if [[ -n "$cmd" ]] && ! command -v "$cmd" &>/dev/null; then
            print_warning "Codex MCP '$name': command '$cmd' not found — commenting out"
            # Comment out the section
            sed -i.bak "/^\[mcp_servers\.$name\]/,/^\[/{s/^/# /;}" "$config"
        fi
    done <<< "$mcp_names"
}
```

**Standalone quick fix** (can be applied before the full registry exists):

```bash
# Remove MCP_DOCKER if docker mcp is not available
if [[ -f "$HOME/.codex/config.toml" ]] && ! docker mcp --help &>/dev/null 2>&1; then
    # Comment out the MCP_DOCKER section
    sed -i.bak '/^\[mcp_servers\.MCP_DOCKER\]/,/^$/s/^/# /' "$HOME/.codex/config.toml"
    print_info "Disabled MCP_DOCKER in Codex config (docker mcp not available)"
fi
```

### CLI installation functions

**Codex** — add to `setup-modules/tool-install.sh`:

```bash
setup_codex_cli() {
    print_info "Setting up OpenAI Codex CLI..."

    if command -v codex >/dev/null 2>&1; then
        local version
        version=$(codex --version 2>/dev/null | head -1 || echo "unknown")
        print_success "Codex already installed: $version"
        return 0
    fi

    local installer=""
    if command -v bun >/dev/null 2>&1; then
        installer="bun"
    elif command -v npm >/dev/null 2>&1; then
        installer="npm"
    else
        print_warning "Neither bun nor npm found - cannot install Codex"
        return 0
    fi

    print_info "Codex is OpenAI's AI coding CLI"
    local install_it="Y"
    if [[ "$NON_INTERACTIVE" != "true" ]]; then
        read -r -p "Install Codex via $installer? [Y/n]: " install_it || install_it="Y"
    fi
    if [[ "$install_it" =~ ^[Yy]?$ ]]; then
        if run_with_spinner "Installing Codex" npm_global_install "@openai/codex@latest"; then
            print_success "Codex installed"
            echo ""
            print_info "Codex needs OpenAI authentication."
            print_info "Run 'codex' and follow the auth prompts."
        else
            print_warning "Codex installation failed"
            print_info "Try manually: npm install -g @openai/codex@latest"
        fi
    else
        print_info "Skipped Codex installation"
    fi
    return 0
}
```

**Cursor** — already exists at `setup-modules/tool-install.sh:949-1005` (`setup_cursor_cli()`). Verify it's wired into the setup flow.

**Droid** — add to `setup-modules/tool-install.sh`:

```bash
setup_droid_cli() {
    print_info "Setting up Factory.AI Droid CLI..."

    if command -v droid >/dev/null 2>&1; then
        local version
        version=$(droid --version 2>/dev/null | head -1 || echo "unknown")
        print_success "Droid already installed: $version"
        return 0
    fi

    # Droid install method TBD — check factory.ai docs
    print_info "Droid (Factory.AI) not installed"
    print_info "Install from: https://factory.ai/docs/cli"
    return 0
}
```

### MCP deployment to new runtimes

Using `mcp-config-adapter.sh` (t1665.2), deploy the standard aidevops MCP servers:

```bash
# Standard MCP servers to deploy to all runtimes
deploy_standard_mcps_to_runtime() {
    local runtime_id="$1"

    # Core MCPs (always deployed if command exists)
    register_mcp_for_runtime "$runtime_id" "playwright" \
        '{"command":"playwright-mcp","args":[]}'
    register_mcp_for_runtime "$runtime_id" "chrome-devtools" \
        '{"command":"chrome-devtools-mcp","args":[]}'
    register_mcp_for_runtime "$runtime_id" "context7" \
        '{"command":"npx","args":["-y","@upstash/context7-mcp@latest"]}'
    register_mcp_for_runtime "$runtime_id" "openapi-search" \
        '{"command":"","url":"https://openapi-mcp.openapisearch.com/mcp","transport":"http"}'
    # ... etc from the MCP list in generate-opencode-agents.sh
}
```

### System prompt deployment

Using `prompt-injection-adapter.sh` (t1665.3):

- **Codex**: Create `~/.codex/instructions.md` with pointer to `~/.aidevops/agents/AGENTS.md`
- **Cursor**: Deploy AGENTS.md to `~/.cursor/rules/AGENTS.md` (or verify symlink from verify-mirrors.sh)
- **Droid**: Deploy AGENTS.md to `~/.factory/skills/AGENTS.md` (or verify symlink)

### Setup.sh integration

Add to the interactive and non-interactive flows in `setup.sh`:

```bash
# In the tools installation section (around line 853)
confirm_step "Setup Codex CLI (OpenAI AI coding tool)" && setup_codex_cli
confirm_step "Setup Droid CLI (Factory.AI coding tool)" && setup_droid_cli

# In the config update section (around line 769)
# This is handled by the unified generator (t1665.4) or individual runtime config updates
```

### Key files to modify

- `setup-modules/tool-install.sh` — add `setup_codex_cli()`, `setup_droid_cli()`
- `setup.sh` — wire new CLI setup functions into interactive/non-interactive flows
- `~/.codex/config.toml` — fix MCP_DOCKER (user's machine, not repo file)
- `.agents/scripts/runtime-registry.sh` — verify Codex/Cursor/Droid entries are correct
- `.agents/scripts/tool-version-check.sh` — add Codex and Droid version checks

### Key files to reference

- `setup-modules/tool-install.sh:1484-1536` — existing `setup_opencode_cli()` (pattern to follow)
- `setup-modules/tool-install.sh:949-1005` — existing `setup_cursor_cli()`
- `.agents/scripts/ai-cli-config.sh:251-263` — existing `_configure_openapi_droid()`
- `configs/mcp-templates/augment-context-engine.json` — multi-runtime MCP template

## Acceptance Criteria

- [ ] Codex Docker MCP error is fixed: `codex` starts without `MCP_DOCKER` failure
  ```yaml
  verify:
    method: bash
    run: "! grep -q '^\\[mcp_servers\\.MCP_DOCKER\\]' ~/.codex/config.toml 2>/dev/null || docker mcp --help &>/dev/null"
  ```
- [ ] `setup_codex_cli()` exists and installs `@openai/codex` via npm/bun
- [ ] `setup_droid_cli()` exists with install guidance
- [ ] Codex config.toml has aidevops MCP servers registered (playwright, chrome-devtools, context7, etc.)
- [ ] `~/.codex/instructions.md` exists with pointer to aidevops AGENTS.md
- [ ] Cursor `~/.cursor/mcp.json` has aidevops MCP servers registered
- [ ] `setup.sh` interactive flow includes Codex and Droid CLI setup steps
- [ ] `tool-version-check.sh` reports Codex and Droid versions
- [ ] MCP command validation prevents broken entries (like MCP_DOCKER) from being written
- [ ] All new code passes shellcheck and is Bash 3.2 compatible
