# 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

# 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

# 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"

# 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

# 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

## 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-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

# 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": {
    "enabled": true,
    "providers": [
      {
        "name": "github",
        "type": "repository",
        "config": {
          "owner": "your-org",
          "repo": "your-repo"
        }
      },
      {
        "name": "slack",
        "type": "communication",
        "config": {
          "workspace_id": "${SLACK_WORKSPACE_ID}"
        }
      }
    ]
  }
}

# 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

# 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"

# 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"

# Web scraping
codex "scrape product data from this e-commerce site"

# Form filling
codex "automate form submission for these entries"

# CSV manipulation
codex "merge these three CSV files and remove duplicates"

# Data analysis
codex "analyze sales data and generate summary report"

# Re-login
codex logout
codex login

# Check authentication status
codex whoami

# Check sandbox configuration
cat ~/.config/codex/config.toml

# Temporarily disable sandbox for debugging (use carefully)
codex "task" --no-sandbox

# Explicitly specify context files
codex "task" --context src/,tests/,README.md

# Re-initialize project
rm -rf .codex
codex init

# Check git status
git status

# Review Codex session logs
codex logs

# Use verbose mode
codex "task" --verbose

# 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

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)

codex "create an AGENTS.md file with rules for our React TypeScript project"

# 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>
  );
};

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

### 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

# 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