Skip to content

README.md

Latest commit

 

History

History
310 lines (228 loc) · 7.92 KB

README.md

File metadata and controls

310 lines (228 loc) · 7.92 KB
Raw

Codex CLI Basic Usage Example

This example demonstrates how to use the Codex CLI provider for basic AI agent orchestration tasks with your OpenAI API key.

What You'll Learn

  • OpenAI Integration: Use your OpenAI API key with CAO
  • Basic Agent Creation: Create Codex agents for different development tasks
  • Status Detection: Understand how CAO detects Codex CLI states
  • Message Extraction: Extract responses from Codex agents
  • Multi-Agent Coordination: Simple supervisor-worker patterns

Prerequisites

  1. OpenAI API Key or ChatGPT Subscription: Authentication for Codex CLI

  2. Codex CLI: Install and authenticate:

    npm install -g @openai/codex
export OPENAI_API_KEY=your-key-here  # Or use: codex login
codex --version  # Verify installation

  3. CLI Agent Orchestrator: Installed and running

    cao-server  # Run in one terminal

Quick Start Example

1. Create a Simple Codex Agent

# Start cao-server in one terminal
cao-server

# In another terminal, create a Codex session
cao launch --agents codex_developer --provider codex

2. Send Your First Task

# In the tmux window, paste your prompt at the Codex prompt.

# Optional: print the CAO terminal id (useful for API automation / MCP)
echo "$CAO_TERMINAL_ID"

Optional automation from another terminal (send input + get extracted last message):

python3 - <<'PY'
import time

import requests

terminal_id = "<terminal-id>"

requests.post(
    f"http://localhost:9889/terminals/{terminal_id}/input",
    params={"message": "Write a Python function to validate email addresses using regex"},
).raise_for_status()

# Poll status until completion
while True:
    status = requests.get(f"http://localhost:9889/terminals/{terminal_id}").json()["status"]
    if status in {"completed", "error", "waiting_user_answer"}:
        break
    time.sleep(1)

resp = requests.get(
    f"http://localhost:9889/terminals/{terminal_id}/output",
    params={"mode": "last"},
)
resp.raise_for_status()
print(resp.json()["output"])
PY

Agent Profiles

The example includes pre-configured agent profiles for different Codex-based tasks:

1. Codex Developer (codex_developer.md)

  • General programming and development tasks
  • Code writing, debugging, refactoring
  • Language: Python, JavaScript, TypeScript

2. Codex Reviewer (codex_reviewer.md)

  • Code review and security analysis
  • Best practices and optimization
  • Testing and quality assurance

3. Codex Documenter (codex_documenter.md)

  • Technical writing and documentation
  • README files, API docs, tutorials
  • Clear, structured communication

Setup

When using the codex provider with --agents, CAO loads the specified agent profile and injects its system prompt into Codex as developer_instructions. This means Codex will adopt the role defined in the agent profile (e.g., supervisor, developer, reviewer).

Agent profiles are loaded from:

  1. Local store: ~/.aws/cli-agent-orchestrator/agent_store/<name>.md
  2. Built-in store: src/cli_agent_orchestrator/agent_store/<name>.md

Usage Examples

Example 1: Single Agent Code Generation

# Launch a Codex developer
cao launch --agents codex_developer --provider codex

# In the agent terminal:
"Write a Python function that:
1. Takes a list of URLs
2. Downloads each URL content
3. Extracts all email addresses
4. Returns a unique list of emails

Include proper error handling and docstring."

Expected Output:

  • Agent will think and process (PROCESSING state)
  • Write the Python function with proper structure
  • Return completed code (COMPLETED state)

Example 2: Code Review Workflow

# Launch a Codex reviewer
cao launch --agents codex_reviewer --provider codex

Paste this prompt into the Codex CLI:

Please review this Python code for security issues:

    import subprocess

    def execute_command(user_input):
        command = f"ls {user_input}"
        return subprocess.run(command, shell=True, capture_output=True)

Focus on:
1. Security vulnerabilities
2. Input validation
3. Safe coding practices
4. Potential improvements

Example 3: Documentation Generation

# Launch a Codex documenter
cao launch --agents codex_documenter --provider codex

# Request documentation:
"Create comprehensive README documentation for a Python package that:
- Has functions for data processing
- Includes installation instructions
- Provides usage examples
- Documents API reference
- Includes contribution guidelines

Make it professional and developer-friendly."

Understanding Codex Provider Behavior

Status Detection

The Codex provider automatically detects these states:

  1. PROCESSING: Codex is thinking or working

    [Agent is thinking...]

  2. WAITING_USER_ANSWER: Waiting for confirmation

    Approve this action? (y/n)

  3. COMPLETED: Task finished with response

    ❯  # Ready for next command

  4. ERROR: Error occurred

    Error: Invalid input provided

Message Extraction

CAO automatically extracts the last assistant response:

# CAO extracts this part
def validate_email(email):
    """Validate email address using regex."""
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return re.match(pattern, email) is not None

# This is the response returned by GET /terminals/{terminal_id}/output?mode=last

Advanced Examples

Example 4: Sequential Code Development

# Launch developer
cao launch --agents codex_developer --provider codex

# Multi-step task:
"1. First, write a Python class for User with fields: id, name, email, created_at
2. Then, add methods for validation and serialization
3. Finally, write unit tests for the User class

Proceed step by step and show me each part."

Example 5: Code Refactoring

# Launch reviewer then developer
cao launch --agents codex_reviewer --provider codex

Paste this prompt into the Codex CLI:

Review this legacy code and suggest refactoring improvements:

    def process_data(data):
        result = []
        for i in range(len(data)):
            if data[i] > 0:
                result.append(data[i] * 2)
            else:
                result.append(0)
        return result

Identify:
1. Code smells and anti-patterns
2. Performance improvements
3. Pythonic alternatives
4. Better naming and structure

Then provide a refactored version with explanations.

Troubleshooting

Common Issues

  1. Authentication Failed:

    codex logout
codex login
# Or set API key directly
export OPENAI_API_KEY=your-key-here

  2. Agent Not Responding:

    • Check tmux list-sessions for session status
    • Verify your OpenAI API key is valid (codex --version)
    • Check network connectivity

  3. Status Detection Issues:

    • Agent might be in unexpected state
    • Check terminal output manually: tmux attach -t <session-name>
    • Verify Codex CLI version compatibility

Performance Tips

  1. Clear Tasks: Be specific about what you want
  2. Step by Step: Break complex tasks into smaller steps
  3. Context Management: Provide relevant context upfront
  4. Validation: Ask for explanations of complex logic

Next Steps

After mastering the basics, explore:

  • Multi-Agent Patterns: See examples/assign/ for step-by-step patterns you can adapt to Codex
  • Workflow Integration: Combine with other providers
  • Custom Agent Profiles: Create specialized Codex agents
  • MCP Integration: Use Codex agents in MCP workflows

Support

For issues:

Contributing

To contribute Codex examples:

  1. Fork the repository
  2. Create new example in examples/codex-*/
  3. Follow the established pattern
  4. Update documentation
  5. Submit a pull request