OpenAI Codex CLI SDK

<dependencies>
    <!-- Core AgentClient API -->
    <dependency>
        <groupId>org.springaicommunity.agents</groupId>
        <artifactId>spring-ai-agent-client</artifactId>
        <version>0.1.0-SNAPSHOT</version>
    </dependency>

    <!-- Codex integration -->
    <dependency>
        <groupId>org.springaicommunity.agents</groupId>
        <artifactId>spring-ai-codex-agent</artifactId>
        <version>0.1.0-SNAPSHOT</version>
    </dependency>
</dependencies>

<dependency>
    <groupId>org.springaicommunity.agents</groupId>
    <artifactId>spring-ai-starter-agent-codex</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

import org.springaicommunity.agents.client.AgentClient;
import org.springaicommunity.agents.client.AgentClientResponse;
import org.springaicommunity.agents.codex.CodexAgentModel;
import org.springaicommunity.agents.codex.CodexAgentOptions;
import org.springaicommunity.agents.codexsdk.CodexClient;

import java.nio.file.Paths;

public class CodexExample {
    public static void main(String[] args) {
        // 1. Create the Codex client
        CodexClient codexClient = CodexClient.create(
            Paths.get(System.getProperty("user.dir"))
        );

        // 2. Configure agent options
        CodexAgentOptions options = CodexAgentOptions.builder()
            .model("gpt-5-codex")
            .fullAuto(true)
            .build();

        // 3. Create the agent model
        CodexAgentModel agentModel = new CodexAgentModel(codexClient, options, null);

        // 4. Create AgentClient
        AgentClient agentClient = AgentClient.create(agentModel);

        // 5. Execute a goal
        AgentClientResponse response = agentClient.run(
            "Create a simple Calculator class with add, subtract, multiply, and divide methods"
        );

        System.out.println("Result: " + response.getResult());
        System.out.println("Success: " + response.isSuccessful());
    }
}

// Create with default working directory
CodexClient client = CodexClient.create();

// Create with specific working directory
Path projectPath = Paths.get("/path/to/project");
CodexClient client = CodexClient.create(projectPath);

// Create with custom Codex CLI path
CodexClient client = CodexClient.create(
    projectPath,
    "/custom/path/to/codex"
);

CodexAgentOptions options = CodexAgentOptions.builder()
    // Model selection
    .model("gpt-5-codex")

    // Execution settings
    .fullAuto(true)                       // Enable full autonomous mode
    .timeout(Duration.ofMinutes(10))      // Execution timeout
    .skipGitCheck(false)                  // Require git repository

    // Advanced: Manual sandbox/approval configuration
    .sandboxMode(SandboxMode.WORKSPACE_WRITE)
    .approvalPolicy(ApprovalPolicy.NEVER)

    // CLI path (for non-standard installations)
    .executablePath("/custom/path/to/codex")

    .build();

// Full-auto mode (recommended for most use cases)
CodexAgentOptions options = CodexAgentOptions.builder()
    .fullAuto(true)  // Sets sandbox=workspace-write, approval=never
    .build();

// Equivalent to:
CodexAgentOptions options = CodexAgentOptions.builder()
    .sandboxMode(SandboxMode.WORKSPACE_WRITE)
    .approvalPolicy(ApprovalPolicy.NEVER)
    .build();

// Read-only mode for analysis
CodexAgentOptions analysisOptions = CodexAgentOptions.builder()
    .sandboxMode(SandboxMode.READ_ONLY)
    .build();

// Workspace write for development (recommended)
CodexAgentOptions devOptions = CodexAgentOptions.builder()
    .sandboxMode(SandboxMode.WORKSPACE_WRITE)
    .build();

// Full access (use with caution)
CodexAgentOptions fullOptions = CodexAgentOptions.builder()
    .sandboxMode(SandboxMode.DANGER_FULL_ACCESS)
    .build();

// Autonomous execution (recommended with workspace-write)
CodexAgentOptions autoOptions = CodexAgentOptions.builder()
    .approvalPolicy(ApprovalPolicy.NEVER)
    .build();

// Smart prompting for safety
CodexAgentOptions smartOptions = CodexAgentOptions.builder()
    .approvalPolicy(ApprovalPolicy.SMART)
    .build();

// Full control (requires manual approval)
CodexAgentOptions manualOptions = CodexAgentOptions.builder()
    .approvalPolicy(ApprovalPolicy.ALWAYS)
    .build();

// Execute a task
ExecuteResult result1 = codexClient.execute("Start implementing the user service");

// Resume with the session ID
String sessionId = result1.getSessionId();
ExecuteResult result2 = codexClient.resume(sessionId, "Add validation to the createUser method");

// Require git repository (default, recommended)
CodexAgentOptions gitOptions = CodexAgentOptions.builder()
    .skipGitCheck(false)
    .build();

// Skip git check (use only for temporary/throwaway directories)
CodexAgentOptions noGitOptions = CodexAgentOptions.builder()
    .skipGitCheck(true)
    .build();

// Configure working directory via client
CodexClient client = CodexClient.create(
    Paths.get("/path/to/microservice")
);

// Or via AgentClient fluent API
AgentClientResponse response = agentClient
    .goal("Add validation to the UserController")
    .workingDirectory("/path/to/microservice")
    .run();

ExecuteOptions options = ExecuteOptions.builder()
    .model("gpt-5-codex")
    .fullAuto(true)
    .json(true)  // Enable JSONL event streaming
    .build();

ExecuteResult result = codexClient.execute("Implement feature", options);

// Access rich metadata
String activityLog = result.getActivityLog();
int exitCode = result.getExitCode();
Duration duration = result.getDuration();
String sessionId = result.getSessionId();

// Quick tasks
CodexAgentOptions quickOptions = CodexAgentOptions.builder()
    .timeout(Duration.ofMinutes(2))
    .build();

// Complex refactoring
CodexAgentOptions complexOptions = CodexAgentOptions.builder()
    .timeout(Duration.ofMinutes(30))
    .build();

import org.springaicommunity.agents.codexsdk.exceptions.CodexSDKException;

try {
    AgentClientResponse response = agentClient.run("Complex refactoring goal");

    if (!response.isSuccessful()) {
        System.err.println("Goal failed: " + response.getResult());
    }

} catch (CodexSDKException e) {
    // Codex CLI process failed
    System.err.println("Codex execution error: " + e.getMessage());

} catch (RuntimeException e) {
    // Other runtime errors (timeout, etc.)
    System.err.println("Unexpected error: " + e.getMessage());
}

@Service
public class CodexService {

    private final AgentClient agentClient;

    public CodexService(AgentClient agentClient) {
        this.agentClient = agentClient;
    }

    public String refactorCode(String className, String requirements) {
        // Validate inputs
        if (className == null || className.trim().isEmpty()) {
            throw new IllegalArgumentException("Class name is required");
        }

        try {
            // First, analyze the code
            AgentClientResponse analysis = agentClient
                .goal("Analyze " + className + " and suggest improvements")
                .options(CodexAgentOptions.builder()
                    .sandboxMode(SandboxMode.READ_ONLY)
                    .build())
                .run();

            if (!analysis.isSuccessful()) {
                throw new ServiceException("Analysis failed: " + analysis.getResult());
            }

            // Then perform refactoring
            AgentClientResponse refactoring = agentClient
                .goal("Refactor " + className + " based on: " + requirements)
                .options(CodexAgentOptions.builder()
                    .fullAuto(true)
                    .build())
                .run();

            return refactoring.getResult();

        } catch (Exception e) {
            // Log error and return meaningful message
            log.error("Refactoring failed for class: {}", className, e);
            throw new ServiceException("Unable to refactor " + className + ": " + e.getMessage());
        }
    }
}

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

    // CodexClient, CodexAgentModel, and AgentClient are auto-configured

    @Bean
    public CommandLineRunner demo(AgentClient agentClient) {
        return args -> {
            AgentClientResponse response = agentClient.run(
                "Create a REST controller for managing users"
            );
            System.out.println(response.getResult());
        };
    }
}

spring:
  ai:
    agents:
      codex:
        model: gpt-5-codex
        timeout: PT10M
        full-auto: true
        skip-git-check: false
        executable-path: /custom/path/to/codex  # Optional

spring.ai.agents.codex.model=gpt-5-codex
spring.ai.agents.codex.timeout=PT10M
spring.ai.agents.codex.full-auto=true
spring.ai.agents.codex.skip-git-check=false
spring.ai.agents.codex.executable-path=/custom/path/to/codex

@Configuration
public class CodexConfiguration {

    @Bean
    public CodexAgentOptions customCodexOptions() {
        return CodexAgentOptions.builder()
            .model("gpt-5-codex")
            .fullAuto(true)
            .timeout(Duration.ofMinutes(15))
            .build();
    }

    @Bean
    public CodexClient customCodexClient() {
        return CodexClient.create(
            Paths.get("/path/to/project"),
            "/custom/path/to/codex"
        );
    }
}

// Good: Specific and contextual
agentClient.run("Add input validation to UserController.createUser() method using Bean Validation annotations");

// Good: Clear scope and requirements
agentClient.run("Refactor PaymentService to use the Strategy pattern for different payment processors");

// Avoid: Vague requests
agentClient.run("Fix the code");

// Avoid: Overly broad scope
agentClient.run("Rewrite the entire application");

@Profile("development")
@Configuration
public class DevelopmentCodexConfig {

    @Bean
    public CodexAgentOptions devCodexOptions() {
        return CodexAgentOptions.builder()
            .fullAuto(true) // OK for development
            .build();
    }
}

@Profile("production")
@Configuration
public class ProductionCodexConfig {

    @Bean
    public CodexAgentOptions prodCodexOptions() {
        return CodexAgentOptions.builder()
            .sandboxMode(SandboxMode.READ_ONLY) // Safe for production
            .build();
    }
}

@Component
public class CodexMonitor {

    private final MeterRegistry meterRegistry;
    private final AgentClient agentClient;

    public CodexMonitor(MeterRegistry meterRegistry, AgentClient agentClient) {
        this.meterRegistry = meterRegistry;
        this.agentClient = agentClient;
    }

    public String executeWithMetrics(String goal) {
        return Timer.Sample.start(meterRegistry)
            .stop(Timer.builder("codex.goal.duration")
                .tag("goal", goal.substring(0, Math.min(goal.length(), 50)))
                .register(meterRegistry))
            .recordCallable(() -> {
                Counter.builder("codex.goal.count").register(meterRegistry).increment();

                AgentClientResponse response = agentClient.run(goal);

                Counter.builder("codex.goal.result")
                    .tag("success", String.valueOf(response.isSuccessful()))
                    .register(meterRegistry)
                    .increment();

                return response.getResult();
            });
    }
}

# Verify installation
codex --version

# Check PATH
which codex  # macOS/Linux
where codex  # Windows

# Set CODEX_CLI_PATH for custom installation
export CODEX_CLI_PATH=/path/to/codex

# Check environment variable
echo $CODEX_API_KEY

# Test with Codex CLI directly
codex --help

# Or use session authentication
codex auth login

# Initialize git in your working directory
cd /path/to/project
git init

# Or skip the check (not recommended)
# Set skipGitCheck(true) in CodexAgentOptions

# Check directory permissions
ls -la /path/to/project

# Fix if needed
chmod -R u+rw /path/to/project

CodexAgentOptions options = CodexAgentOptions.builder()
    .timeout(Duration.ofMinutes(30)) // Longer timeout
    .build();

logging:
  level:
    org.springaicommunity.agents.codex: DEBUG
    org.springaicommunity.agents.codexsdk: DEBUG
    org.springaicommunity.agents.client: DEBUG