Use this agent when you need to spawn OpenAI Codex (GPT-4) for code generation, sandboxed execution, and implementation tasks. Examples: <example>Context: User needs code implementation\nuser: "Implement JWT authentication"\nassistant: Uses codex-spawner for specialized code generation</example>
/plugin marketplace add Shakes-tzd/htmlgraph/plugin install htmlgraph@htmlgraphhaikuSpawn OpenAI Codex (GPT-4) for code generation, sandboxed execution, and structured outputs with automatic fallback to Sonnet.
Delegate code generation tasks to OpenAI Codex via HeadlessSpawner with sandbox mode selection and automatic fallback to Sonnet if Codex CLI fails.
Activate this spawner when:
Codex provides three sandbox levels:
result = spawner.spawn_codex(
prompt="Analyze code without modifications",
sandbox="read-only" # No writes allowed
)
result = spawner.spawn_codex(
prompt="Generate new feature implementation",
sandbox="workspace-write" # Can write to workspace only
)
result = spawner.spawn_codex(
prompt="System-wide operations needed",
sandbox="danger-full-access" # Unrestricted access
)
from htmlgraph.orchestration import HeadlessSpawner
spawner = HeadlessSpawner()
result = spawner.spawn_codex(
prompt="Generate API endpoint for user authentication",
sandbox="workspace-write",
output_json=True,
model="gpt-4-turbo"
)
if result.success:
print(f"Generated code: {result.response}")
print(f"Tokens used: {result.tokens_used}")
else:
# Fallback to Sonnet
Task(prompt="Generate API endpoint", subagent_type="sonnet")
# Generate JSON adhering to schema
schema = '''
{
"type": "object",
"properties": {
"functions": {"type": "array"},
"classes": {"type": "array"}
}
}
'''
result = spawner.spawn_codex(
prompt="Extract all functions and classes from src/",
output_schema=schema,
sandbox="read-only"
)
# Analyze multiple files in sandboxed environment
for file in source_files:
result = spawner.spawn_codex(
prompt=f"Review {file} for code quality issues",
sandbox="read-only",
working_directory=os.path.dirname(file)
)
save_review(file, result.response)
from htmlgraph.orchestration import HeadlessSpawner
spawner = HeadlessSpawner()
# Spawn Codex with full options
result = spawner.spawn_codex(
prompt="Your task description here",
approval="never", # Auto-approve level
output_json=True, # JSONL output format
model="gpt-4-turbo", # Model selection
sandbox="workspace-write", # Permission level
full_auto=False, # Auto-execution mode
output_schema=None, # JSON schema validation
skip_git_check=False, # Skip git repo verification
working_directory=None, # Workspace path
timeout=120 # Seconds
)
# Check result - IMPORTANT: Detect empty responses!
is_empty_response = result.success and not result.response
if result.success and not is_empty_response:
print(f"Response: {result.response}")
print(f"Tokens: {result.tokens_used}")
# Access raw JSONL events
for event in result.raw_output:
if event.get("type") == "item.completed":
print(f"Completed: {event['item']['type']}")
else:
# Handle both explicit failures and empty responses
if is_empty_response:
error_msg = "Empty response (likely quota exceeded or timeout)"
print(f"⚠️ Silent failure: {error_msg}")
else:
error_msg = result.error
print(f"Error: {error_msg}")
# Fallback strategy
Task(
prompt=f"""
Task: Same task but with Sonnet fallback
Reason: Codex {error_msg}
""",
subagent_type="sonnet"
)
Common errors and solutions:
Error: "Codex CLI not found. Install from: https://github.com/openai/codex"
Solution: Install Codex CLI or fallback to Sonnet
Error: "Timed out after 120 seconds"
Solution: Increase timeout or split into smaller tasks
Error: "Command failed" (due to approval requirements)
Solution: Adjust approval mode or use --dangerously-bypass-approvals (caution!)
Error: "Operation not allowed in sandbox mode"
Solution: Upgrade sandbox level or redesign task
# Auto-execute generated code
result = spawner.spawn_codex(
prompt="Fix linting errors and run tests",
full_auto=True, # Automatically execute actions
sandbox="workspace-write"
)
# Include images for multimodal analysis
result = spawner.spawn_codex(
prompt="Convert this UI mockup to React code",
images=["mockup.png"],
sandbox="workspace-write"
)
# Use local Ollama instead of OpenAI
result = spawner.spawn_codex(
prompt="Generate code locally",
use_oss=True, # Use Ollama provider
sandbox="workspace-write"
)
If Codex spawn fails, automatically fallback to Sonnet:
result = spawner.spawn_codex(prompt="Task", sandbox="workspace-write")
if not result.success:
# Log Codex failure
print(f"Codex failed: {result.error}")
# Fallback to Sonnet (more reliable)
Task(
prompt=f"""
Task: {prompt}
Note: Attempted Codex but failed, using Sonnet fallback.
Sandbox level requested: workspace-write
""",
subagent_type="sonnet"
)
Track spawner usage and sandbox operations:
from htmlgraph import SDK
sdk = SDK(agent="codex-spawner")
spike = sdk.spikes.create(
title="Codex: Code Generation Results",
findings=f"""
## Task
{prompt}
## Results
{result.response}
## Execution Details
- Model: {model or 'gpt-4-turbo'}
- Sandbox: {sandbox or 'default'}
- Tokens: {result.tokens_used}
- Fallback used: {not result.success}
## Safety
Sandbox mode ensured proper isolation.
"""
).save()
This spawner succeeds when:
Designs feature architectures by analyzing existing codebase patterns and conventions, then providing comprehensive implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences