aradotso CodexGuide Reference
Skill by ara.so — Codex Skills collection.
CodexGuide is a comprehensive practical guide for OpenAI Codex that helps beginners, creators, developers, and teams learn how to effectively use Codex across different interfaces (CLI, desktop app, cloud, IDE extensions) and integrate it into real-world workflows.
What CodexGuide Covers
CodexGuide addresses three core questions:
- How to start: Which entry point, task, and settings should beginners use
- How to deliver: How to communicate requirements so Codex can read projects, modify files, run commands, and produce verifiable results
- How to accumulate: How to turn successful tasks into reusable templates, rules, cases, and safety boundaries for teams
The guide is organized into:
- Entry paths: Desktop app, CLI, Cloud/Web, IDE extensions, ChatGPT mobile
- Configuration topics: CLI options,
config.toml, MCP, Skills, Subagents, security approvals - Workflow methods: Task design, verification approaches, non-development workflows, team playbooks
- Practical cases: PPT, Draw.io, browser automation, Obsidian, Feishu, Figma, Notion, CI fixes
- Official references: OpenAI documentation index and authoritative sources
Accessing CodexGuide
Online Documentation
Visit the comprehensive documentation site:
# Online reading
https://codexguide.ai/
# Direct paths
https://codexguide.ai/guide/00-overview.html # Learning roadmap
https://codexguide.ai/platform/ # Platform comparison
https://codexguide.ai/configuration/ # Configuration topics
https://codexguide.ai/practice/ # Practice methods
https://codexguide.ai/recipes/ # Real-world cases
Local Development
Clone and run the documentation locally:
# Clone the repository
git clone https://github.com/freestylefly/CodexGuide.git
cd CodexGuide
# Install dependencies (requires Node.js 18+)
pnpm install
# Start development server
pnpm dev
# Build static site
pnpm build
Key Learning Paths
For First-Time Users
Start with desktop app (guide/01-app-installation.md)
- Download and install Codex desktop app
- Subscribe to Plus/Pro
- Understand the interface
- Complete first low-risk task
Mobile coordination (guide/04-mobile-control-desktop.md)
- Use ChatGPT mobile app to track desktop tasks
- Coordinate between devices
For Developers Integrating Codex
- CLI setup (guide/11-cli-installation.md):
# Install Codex CLI
npm install -g @openai/codex-cli
# Login
codex login
# Initialize in your project
cd your-project
codex init
# Run your first task
codex "add unit tests for the authentication module"
- Project configuration with AGENTS.md (guide/14-agents-md.md):
# AGENTS.md example structure
## Project Overview
Brief description of the project, tech stack, and purpose.
## Development Rules
- Code style guidelines
- Testing requirements
- File organization patterns
## Task Boundaries
- What Codex should do
- What requires human approval
- Security constraints
## Common Tasks
### Adding a feature
1. Create feature branch
2. Write tests first
3. Implement feature
4. Update documentation
### Fixing a bug
1. Reproduce the issue
2. Add regression test
3. Fix and verify
4. Update changelog
- Sandbox and approvals (guide/15-sandbox-approvals.md):
# config.toml example
[sandbox]
enabled = true
allowed_commands = ["npm", "git", "pytest"]
allowed_paths = ["src/", "tests/", "docs/"]
[approvals]
require_approval_for_commands = ["rm", "docker", "kubectl"]
require_approval_for_paths = [".env", "secrets/"]
require_approval_for_network = true
For Teams and Tool Builders
- Team playbook structure (practice/team-playbook.md):
## Team Codex Playbook
### Entry Point Selection
- CLI for local development
- Cloud for code review and collaboration
- IDE extensions for inline assistance
### Shared AGENTS.md
- Team coding standards
- Approval workflows
- Security boundaries
- Communication patterns
### Task Templates
#### Feature Development
- Requirements gathering
- Test-driven approach
- Documentation updates
- Code review process
#### Bug Fixes
- Reproduction steps
- Root cause analysis
- Fix verification
- Regression prevention
### Review and Iteration
- Weekly retrospectives
- Template updates
- Security audit
- Knowledge sharing
- Security configuration (configuration/security-admin.md):
# Security-focused config.toml
[security]
# Prevent access to sensitive files
blocked_paths = [
".env",
".env.*",
"secrets/",
"credentials/",
"*.pem",
"*.key"
]
# Require approval for destructive operations
dangerous_commands = [
"rm -rf",
"drop table",
"delete from",
"docker system prune",
"kubectl delete"
]
# Network restrictions
allow_network_access = false
allowed_domains = ["api.example.com", "docs.example.com"]
# Credential management
never_log_credentials = true
use_env_vars = true
Platform Comparison
CLI vs Desktop App vs Cloud vs IDE
Use CLI when:
- Working in existing projects with Git
- Need deep project context and multi-file edits
- Want to run commands and verify results locally
- Integrating with CI/CD pipelines
Use Desktop App when:
- First-time user learning Codex
- Need visual interface and file tree
- Want to preview changes before applying
- Working on personal projects with lower risk
Use Cloud/Web when:
- Collaborating with team on code review
- Sharing Codex sessions with others
- Need access from any browser
- Working on documentation or analysis
Use IDE Extensions when:
- Want inline code suggestions
- Need context-aware completions
- Prefer staying in your editor (VS Code, Cursor, etc.)
- Working on focused, file-level tasks
Configuration Topics
CLI Options
# Basic usage
codex "task description"
# Specify files
codex "refactor this file" --files src/app.js
# Approve all changes automatically (use with caution)
codex "add logging" --auto-approve
# Use specific model
codex "optimize performance" --model gpt-4
# Dry run (show plan without executing)
codex "migrate database" --dry-run
# Include specific context
codex "fix bug" --context tests/,docs/
# Set working directory
codex "update configs" --cwd ./backend
MCP (Model Context Protocol) Integration
{
"mcp": {
"enabled": true,
"providers": [
{
"name": "github",
"type": "repository",
"config": {
"owner": "your-org",
"repo": "your-repo"
}
},
{
"name": "slack",
"type": "communication",
"config": {
"workspace_id": "${SLACK_WORKSPACE_ID}"
}
}
]
}
}
Skills and Subagents
# skill.yaml example
name: python-testing-expert
description: Expert in Python testing with pytest
triggers:
- write tests for this Python module
- add pytest fixtures
- mock external dependencies
capabilities:
- pytest
- unittest
- mocking
- fixtures
- parametrization
instructions: |
When writing Python tests:
1. Use pytest as the default framework
2. Organize tests in test_*.py files
3. Use fixtures for setup/teardown
4. Mock external API calls
5. Include docstrings explaining test purpose
6. Aim for >80% coverage
Common Workflow Patterns
Development Task Flow
# 1. Start with clear task description
codex "implement user authentication with JWT tokens"
# 2. Review proposed changes
# Codex will show files to be modified and plan
# 3. Approve or iterate
# Type 'y' to approve, 'n' to reject, or provide feedback
# 4. Verify results
npm test
npm run lint
# 5. Commit changes
git add .
git commit -m "feat: add JWT authentication"
Non-Development Workflows
Content Creation:
# Generate documentation
codex "create API documentation from source code"
# Create presentations
codex "generate PowerPoint outline for quarterly review"
# Organize knowledge base
codex "convert meeting notes to Obsidian markdown with tags"
Browser Automation:
# Web scraping
codex "scrape product data from this e-commerce site"
# Form filling
codex "automate form submission for these entries"
Data Processing:
# CSV manipulation
codex "merge these three CSV files and remove duplicates"
# Data analysis
codex "analyze sales data and generate summary report"
Troubleshooting
Common Issues
Authentication errors:
# Re-login
codex logout
codex login
# Check authentication status
codex whoami
Permission errors:
# Check sandbox configuration
cat ~/.config/codex/config.toml
# Temporarily disable sandbox for debugging (use carefully)
codex "task" --no-sandbox
Context not loaded:
# Explicitly specify context files
codex "task" --context src/,tests/,README.md
# Re-initialize project
rm -rf .codex
codex init
Changes not applied:
# Check git status
git status
# Review Codex session logs
codex logs
# Use verbose mode
codex "task" --verbose
Real-World Examples
Example 1: Adding Tests to Existing Code
# Task: Add comprehensive tests for a Python module
codex "add pytest tests for src/auth/jwt.py with at least 90% coverage"
# Codex will:
# 1. Analyze existing code
# 2. Create tests/auth/test_jwt.py
# 3. Add fixtures in tests/conftest.py
# 4. Mock external dependencies
# 5. Add parametrized tests for edge cases
Generated test file:
import pytest
from unittest.mock import patch, MagicMock
from src.auth.jwt import create_token, verify_token, TokenExpiredError
@pytest.fixture
def mock_user():
return {
"id": 123,
"email": "user@example.com",
"role": "admin"
}
def test_create_token_success(mock_user):
token = create_token(mock_user)
assert isinstance(token, str)
assert len(token) > 0
def test_verify_token_valid(mock_user):
token = create_token(mock_user)
payload = verify_token(token)
assert payload["id"] == mock_user["id"]
assert payload["email"] == mock_user["email"]
@pytest.mark.parametrize("invalid_token", [
"",
"invalid.token.string",
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.invalid",
])
def test_verify_token_invalid(invalid_token):
with pytest.raises(ValueError):
verify_token(invalid_token)
@patch('src.auth.jwt.datetime')
def test_token_expiration(mock_datetime, mock_user):
# Mock time to test expiration
mock_datetime.utcnow.return_value = datetime(2026, 1, 1)
token = create_token(mock_user, expires_in=3600)
# Move time forward past expiration
mock_datetime.utcnow.return_value = datetime(2026, 1, 2)
with pytest.raises(TokenExpiredError):
verify_token(token)
Example 2: Creating AGENTS.md for a React Project
codex "create an AGENTS.md file with rules for our React TypeScript project"
Generated AGENTS.md:
# AGENTS.md
## Project Overview
React TypeScript application with Material-UI components and Redux Toolkit for state management.
## Tech Stack
- React 18.2
- TypeScript 5.0
- Material-UI 5.x
- Redux Toolkit
- React Router 6
- Vite
## Development Rules
### Code Style
- Use functional components with hooks
- Prefer named exports over default exports
- Use TypeScript strict mode
- Follow ESLint and Prettier configurations
- Maximum component file size: 300 lines
### Component Structure
```typescript
// src/components/ExampleComponent.tsx
import React from 'react';
import { Box, Typography } from '@mui/material';
interface ExampleComponentProps {
title: string;
onAction: () => void;
}
export const ExampleComponent: React.FC<ExampleComponentProps> = ({
title,
onAction
}) => {
return (
<Box>
<Typography variant="h5">{title}</Typography>
</Box>
);
};
State Management
- Use Redux Toolkit for global state
- Use local state for component-specific data
- Create slices in
src/store/slices/ - Use typed hooks from
src/store/hooks.ts
Testing Requirements
- Unit tests for utility functions
- Component tests with React Testing Library
- Minimum 70% coverage
- Mock API calls in tests
File Organization
src/
├── components/ # Reusable UI components
├── pages/ # Route-level components
├── store/ # Redux store and slices
├── hooks/ # Custom React hooks
├── utils/ # Utility functions
├── types/ # TypeScript type definitions
└── api/ # API client code
Task Boundaries
Codex Should
- Create new components following established patterns
- Add unit and component tests
- Update type definitions
- Refactor code while maintaining functionality
- Add inline documentation
Requires Human Approval
- Changing Redux store structure
- Modifying authentication logic
- Updating dependencies
- Deleting files or components
- API endpoint changes
Never Do
- Commit API keys or secrets
- Disable TypeScript checks
- Remove error handling
- Deploy to production
### Example 3: CI/CD Fix Workflow
```bash
# Diagnose CI failure
codex "analyze GitHub Actions failure in latest commit and fix the failing test"
# Codex will:
# 1. Read .github/workflows/ci.yml
# 2. Check recent commit diff
# 3. Identify failing test from logs
# 4. Fix the root cause
# 5. Update test if needed
# 6. Verify locally before committing
Best Practices
Task Design
- Be specific: "Add error handling to the login function" is better than "improve code"
- Provide context: Reference specific files, functions, or requirements
- Set boundaries: Specify what should and shouldn't change
- Include verification: Describe how to test the changes
Security
- Never commit secrets: Use environment variables
- Review before approval: Don't auto-approve without understanding changes
- Use sandbox mode: Restrict file and command access
- Audit regularly: Review what Codex has access to
Team Adoption
- Start small: Begin with low-risk tasks
- Create templates: Build a library of successful task patterns
- Share learnings: Document what works and what doesn't
- Iterate rules: Update AGENTS.md based on experience
- Regular retrospectives: Discuss Codex usage in team meetings
Resources
- Official Documentation: https://codexguide.ai
- GitHub Repository: https://github.com/freestylefly/CodexGuide
- OpenAI Codex Official: https://openai.com/codex/
- CLI Getting Started: https://help.openai.com/en/articles/11096431-openai-codex-cli-getting-started
- Codex Cloud Docs: https://platform.openai.com/docs/codex
Contributing to CodexGuide
CodexGuide welcomes contributions:
# Fork and clone
git clone https://github.com/YOUR_USERNAME/CodexGuide.git
cd CodexGuide
# Create feature branch
git checkout -b feature/your-contribution
# Install and test
pnpm install
pnpm dev
# Make changes to docs/ directory
# Follow existing structure and style
# Submit pull request
git add .
git commit -m "docs: add section on X"
git push origin feature/your-contribution
Contribution areas:
- Beginner-friendly tutorial improvements
- Real-world case studies
- Common errors and solutions
- Team practices and workflows
- Official documentation updates
See CONTRIBUTING.md for detailed guidelines.