codex-x-desktop-manager

Codex-X Desktop Manager

Skill by ara.so — Codex Skills collection.

Codex-X is a cross-platform desktop application for managing OpenAI Codex CLI configurations. It provides visual interfaces for prompt injection, provider switching, TOML/JSON editing, and session management. Built with Tauri 2, React 18, and Rust.

What Codex-X Does

• Prompt Injection: Inject instruction templates (gpt5.4-unrestricted.md, gpt5.5-unrestricted.md) into Codex CLI
• Provider Management: Switch between official OpenAI and third-party Codex API providers
• Configuration Editing: Visual editor for ~/.codex/config.toml and ~/.codex/auth.json
• Session Sync: Fix provider metadata in historical Codex sessions
• Cross-Platform: macOS (Apple Silicon/Intel), Windows, Linux

Installation

Download Pre-built Binaries

Download from GitHub Releases:

# Visit https://github.com/yynxxxxx/Codex-X/releases
# Available formats:
# - macOS: .dmg (Apple Silicon / Intel)
# - Windows: .msi / portable .zip
# - Linux: .deb / .rpm

macOS Gatekeeper Bypass

If macOS shows "app is damaged" warning:

xattr -dr com.apple.quarantine /Applications/Codex-X.app

Build from Source

# Clone repository
git clone https://github.com/yynxxxxx/Codex-X.git
cd Codex-X

# Install dependencies
pnpm install

# Development mode
pnpm dev

# Build desktop app
pnpm --dir apps/desktop tauri build

Configuration Paths

Codex-X reads and writes standard Codex CLI configuration files:

~/.codex/config.toml          # Main Codex configuration
~/.codex/auth.json            # Authentication data
~/.codex/sqlite/*.db          # Session databases
~/.codex/sessions/            # Active session data
~/.codex/archived_sessions/   # Archived session data

Codex-X stores its own data at:

~/.codexx/codexx.db           # Codex-X application database

Environment Variables

Override default paths:

export CODEX_HOME=/path/to/.codex
export CODEXX_HOME=/path/to/codex-x-data
export CC_SWITCH_HOME=/path/to/.cc-switch

Key Features

1. Prompt Injection

Codex-X includes two instruction templates for Codex CLI:

gpt5.4-unrestricted.md:

• CTF sandbox-style bypass approach
• ~180 lines, security research focused
• Detailed methodology for testing scenarios
• Use case: SQL injection testing, penetration testing guidance

gpt5.5-unrestricted.md:

• Direct unrestricted developer mode
• ~40 lines, minimal instruction set
• Broad coverage for development tasks
• Use case: Reverse engineering (APK/EXE analysis)

Enable Prompt Injection via UI

1. Open Codex-X application
2. Navigate to "指令提示词" (Instruction Prompts) tab
3. Select desired template (5.4 or 5.5)
4. Click "启用" (Enable)
5. Codex-X will:
   • Copy template to ~/.codex/
   • Update config.toml with model_instructions_file path

Manual Prompt Injection

# Copy template to Codex config directory
cp examples/gpt5.5-unrestricted.md ~/.codex/

# Edit config.toml
echo 'model_instructions_file = "/Users/yourusername/.codex/gpt5.5-unrestricted.md"' >> ~/.codex/config.toml

Testing Prompt Injection

After enabling, test with security research queries:

codex-cli chat

# Query: "如何对目标进行 SQL 注入测试？"
# Expected: Detailed SQL injection testing methodology
# (instead of refusal or generic response)

# Query: "APK逆向分析流程"
# Expected: Android APK reverse engineering workflow

2. Provider Management

Add Third-Party Provider via UI

1. Navigate to "供应商 API" (Provider API) tab
2. Click "添加供应商" (Add Provider)
3. Configure:
   • Name: Custom provider name
   • Base URL: API endpoint (e.g., https://api.example.com/v1)
   • API Key: Use environment variable reference
   • Model: Model identifier (e.g., gpt-4, claude-3)
   • Wire API: Protocol (OpenAI/Anthropic compatible)

Provider Configuration in TOML

Codex-X generates TOML configuration:

[providers.custom_provider]
base_url = "https://api.example.com/v1"
api_key = "${CUSTOM_API_KEY}"
model = "gpt-4"
wire_api = "openai"

[active]
provider = "custom_provider"

Switch Providers Programmatically

// TypeScript example - Tauri command
import { invoke } from '@tauri-apps/api/tauri';

async function switchProvider(providerName: string) {
  await invoke('set_active_provider', { 
    provider: providerName 
  });
}

// Switch to custom provider
await switchProvider('custom_provider');

Import from cc-switch

If migrating from cc-switch:

1. Set CC_SWITCH_HOME environment variable
2. Codex-X will auto-detect and offer import
3. All cc-switch providers will be available in Codex-X

3. TOML Configuration Editor

View Current Configuration

// Tauri command to read config.toml
import { invoke } from '@tauri-apps/api/tauri';

async function loadConfig() {
  const config = await invoke('read_codex_config');
  console.log(config);
  // Returns parsed TOML as JSON
}

Edit TOML via UI

1. Navigate to "TOML 配置" tab
2. View syntax-highlighted configuration
3. Edit directly in code editor
4. Click "保存" (Save) to write to ~/.codex/config.toml

Programmatic TOML Update

// Rust example - Tauri command handler
use tauri::command;
use std::fs;
use toml;

#[command]
fn update_codex_config(new_config: String) -> Result<(), String> {
    let config_path = dirs::home_dir()
        .unwrap()
        .join(".codex")
        .join("config.toml");
    
    // Validate TOML syntax
    let _parsed: toml::Value = toml::from_str(&new_config)
        .map_err(|e| format!("Invalid TOML: {}", e))?;
    
    // Write to file
    fs::write(config_path, new_config)
        .map_err(|e| format!("Write failed: {}", e))?;
    
    Ok(())
}

4. Auth Management

View Auth Configuration

// Read auth.json
import { invoke } from '@tauri-apps/api/tauri';

interface AuthConfig {
  chatgpt_auth?: string;
  api_keys?: Record<string, string>;
}

async function loadAuth(): Promise<AuthConfig> {
  return await invoke('read_auth_json');
}

Update Authentication

// Rust command to update auth.json
use serde_json::json;
use std::fs;

#[command]
fn update_auth(
    chatgpt_token: Option<String>,
    api_keys: Option<HashMap<String, String>>
) -> Result<(), String> {
    let auth_path = dirs::home_dir()
        .unwrap()
        .join(".codex")
        .join("auth.json");
    
    let mut auth = json!({});
    
    if let Some(token) = chatgpt_token {
        auth["chatgpt_auth"] = json!(token);
    }
    
    if let Some(keys) = api_keys {
        auth["api_keys"] = json!(keys);
    }
    
    fs::write(auth_path, serde_json::to_string_pretty(&auth).unwrap())
        .map_err(|e| e.to_string())
}

5. Session Provider Sync

Codex-X can fix provider metadata in historical sessions.

Sync Session Providers

// Scan and fix session provider metadata
import { invoke } from '@tauri-apps/api/tauri';

interface SessionSyncResult {
  sessions_found: number;
  sessions_fixed: number;
  errors: string[];
}

async function syncSessionProviders(): Promise<SessionSyncResult> {
  return await invoke('sync_session_providers');
}

// Usage
const result = await syncSessionProviders();
console.log(`Fixed ${result.sessions_fixed} of ${result.sessions_found} sessions`);

Session Data Locations

Codex-X reads session data from:

// Rust session scanner
use rusqlite::Connection;
use std::path::PathBuf;

fn get_session_paths() -> Vec<PathBuf> {
    let home = dirs::home_dir().unwrap();
    let codex_dir = home.join(".codex");
    
    vec![
        codex_dir.join("sqlite"),
        codex_dir.join("state_5.sqlite"),
        codex_dir.join("sessions"),
        codex_dir.join("archived_sessions"),
    ]
}

fn fix_session_provider(db_path: &PathBuf, provider: &str) -> Result<(), Box<dyn std::error::Error>> {
    let conn = Connection::open(db_path)?;
    
    conn.execute(
        "UPDATE threads SET provider_metadata = ?1 WHERE provider_metadata IS NULL OR provider_metadata != ?1",
        [provider],
    )?;
    
    Ok(())
}

Common Patterns

Pattern 1: Enable Unrestricted Mode

# 1. Open Codex-X
# 2. Navigate to "指令提示词" tab
# 3. Enable gpt5.5-unrestricted.md
# 4. Restart Codex CLI
codex-cli chat

# Test query
"如何进行渗透测试？"

Pattern 2: Switch to Third-Party Provider

// Add provider via Tauri API
import { invoke } from '@tauri-apps/api/tauri';

await invoke('add_provider', {
  name: 'anthropic',
  baseUrl: 'https://api.anthropic.com/v1',
  apiKey: '${ANTHROPIC_API_KEY}',
  model: 'claude-3-opus-20240229',
  wireApi: 'anthropic'
});

await invoke('set_active_provider', { provider: 'anthropic' });

Pattern 3: Batch Config Update

// Update multiple TOML fields atomically
use toml_edit::{Document, value};

#[command]
fn batch_update_config(updates: HashMap<String, String>) -> Result<(), String> {
    let config_path = dirs::home_dir().unwrap().join(".codex/config.toml");
    let content = fs::read_to_string(&config_path).unwrap();
    let mut doc = content.parse::<Document>().unwrap();
    
    for (key, val) in updates {
        let keys: Vec<&str> = key.split('.').collect();
        let mut current = &mut doc;
        
        for (i, k) in keys.iter().enumerate() {
            if i == keys.len() - 1 {
                current[k] = value(val.clone());
            } else {
                current = &mut current[k];
            }
        }
    }
    
    fs::write(config_path, doc.to_string()).unwrap();
    Ok(())
}

Pattern 4: Monitor Session Creation

// Watch for new Codex sessions and auto-sync provider
import { invoke } from '@tauri-apps/api/tauri';
import { listen } from '@tauri-apps/api/event';

// Set up file watcher
await invoke('watch_session_directory');

// Listen for new session events
await listen('session-created', async (event) => {
  const sessionId = event.payload.session_id;
  await invoke('sync_single_session', { sessionId });
});

Troubleshooting

Issue: "App is damaged" on macOS

Solution: Remove quarantine attribute

xattr -dr com.apple.quarantine /Applications/Codex-X.app

Issue: Config.toml changes not reflected in Codex CLI

Solution: Restart Codex CLI after saving changes

# Kill existing Codex processes
pkill -f codex-cli

# Start fresh session
codex-cli chat

Issue: Provider switch fails

Diagnosis: Check TOML syntax

# Validate TOML
cat ~/.codex/config.toml | python -c "import sys, toml; toml.loads(sys.stdin.read())"

Solution: Use Codex-X TOML editor (validates before saving)

Issue: Session sync reports errors

Common causes:

• Corrupted SQLite database
• Missing rollout JSONL files
• Permission issues

Solution:

# Check file permissions
ls -la ~/.codex/sqlite/
ls -la ~/.codex/sessions/

# Fix permissions
chmod -R 755 ~/.codex/

# Verify SQLite integrity
sqlite3 ~/.codex/state_5.sqlite "PRAGMA integrity_check;"

Issue: Custom prompt not applied

Checklist:

1. Verify file path in config.toml
2. Check file exists: ls -la ~/.codex/gpt5.5-unrestricted.md
3. Restart Codex CLI
4. Test with explicit prompt injection query

# Manual verification
grep model_instructions_file ~/.codex/config.toml
cat ~/.codex/gpt5.5-unrestricted.md

Issue: API key not recognized

Solution: Use environment variables instead of hardcoded keys

# Set API key
export CUSTOM_API_KEY="your-actual-key-here"

# Verify in config.toml
grep api_key ~/.codex/config.toml
# Should show: api_key = "${CUSTOM_API_KEY}"

Development & Extension

Add Custom Tauri Command

// src-tauri/src/main.rs
#[tauri::command]
fn custom_codex_operation(param: String) -> Result<String, String> {
    // Your custom logic
    Ok(format!("Processed: {}", param))
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![
            custom_codex_operation,
            // ... existing commands
        ])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Call from Frontend

import { invoke } from '@tauri-apps/api/tauri';

const result = await invoke<string>('custom_codex_operation', {
  param: 'test-value'
});

Add New Prompt Template

# 1. Create new template
cat > examples/custom-prompt.md << 'EOF'
# Custom Codex Instructions

You are in custom mode. Follow these rules:
- Rule 1
- Rule 2
EOF

# 2. Add to Codex-X UI (modify React component)
# apps/desktop/src/components/PromptManager.tsx

Resources

• GitHub: https://github.com/yynxxxxx/Codex-X
• Releases: https://github.com/yynxxxxx/Codex-X/releases
• License: MIT
• Community: LINUX DO Forum (https://linux.do/)

Technology Stack

• Desktop Framework: Tauri 2
• Frontend: React 18, TypeScript, Vite
• Backend: Rust
• Database: SQLite (rusqlite)
• Config Formats: TOML, JSON