# Basic Usage Examples

---

## ⚠️ CRITICAL: Always Use `codex exec`

**ALL commands in this document use `codex exec` - this is mandatory in Claude Code.**

❌ **NEVER**: `codex -m ...` (will fail with "stdout is not a terminal")
✅ **ALWAYS**: `codex exec -m ...` (correct non-interactive mode)

Claude Code's bash environment is non-terminal. Plain `codex` commands will NOT work.

---

## Example 1: General Reasoning Task - Queue Design

### User Request
"Help me design a queue data structure in Python"

### What Happens

1. **Claude detects** the coding task (queue design)
2. **Skill is invoked** autonomously
3. **Codex CLI is called** with gpt-5.1 (general high-reasoning model):

```bash
codex exec -m gpt-5.1 -s read-only \
  -c model_reasoning_effort=high \
  "Help me design a queue data structure in Python"
```

4. **Codex responds** with high-reasoning architectural guidance on queue design
5. **Session is auto-saved** for potential continuation

### Expected Output

Codex provides:
- Queue design principles and trade-offs
- Multiple implementation approaches (list-based, deque, linked-list)
- Performance characteristics (O(1) enqueue/dequeue)
- Thread-safety considerations
- Usage examples and best practices

---

## Example 2: Code Editing Task - Implement Queue

### User Request
"Edit my Python file to implement the queue with thread-safety"

### What Happens

1. **Skill detects** code editing request
2. **Uses gpt-5.1-codex-max** (maximum capability for coding - 27-42% faster):

```bash
codex exec -m gpt-5.1-codex-max -s workspace-write \
  -c model_reasoning_effort=high \
  "Edit my Python file to implement the queue with thread-safety"
```

3. **Codex performs code editing** with maximum capability model
4. **Files are modified** (workspace-write sandbox)

### Expected Output

Codex:
- Edits the target Python file
- Implements thread-safe queue using `threading.Lock`
- Adds proper synchronization primitives
- Includes docstrings and type hints
- Provides usage examples

---

## Example 3: Explicit Codex Request

### User Request
"Use Codex to design a REST API for a blog system"

### What Happens

1. **Explicit "Codex" mention** triggers skill
2. **Codex invoked** with coding-optimized settings:

```bash
codex exec -m gpt-5.1 -s read-only \
  -c model_reasoning_effort=high \
  "Design a REST API for a blog system"
```

3. **High-reasoning analysis** provides comprehensive API design

### Expected Output

Codex delivers:
- RESTful endpoint design (GET/POST/PUT/DELETE)
- Resource modeling (posts, authors, comments)
- Authentication and authorization strategy
- Data validation approaches
- API versioning recommendations
- Error handling patterns

---

## Example 4: Complex Algorithm Design

### User Request
"Help me implement a binary search tree with balancing"

### What Happens

```bash
codex exec -m gpt-5.1 -s read-only \
  -c model_reasoning_effort=high \
  "Help me implement a binary search tree with balancing"
```

### Expected Output

Codex provides:
- BST fundamentals and invariants
- AVL vs Red-Black tree trade-offs
- Rotation algorithms (left, right, left-right, right-left)
- Insertion and deletion with rebalancing
- Complexity analysis
- Implementation guidance

---

## Example 5: Maximum Reasoning with xhigh

### User Request
"Refactor the authentication system with comprehensive security improvements"

### What Happens

```bash
codex exec -m gpt-5.1-codex-max -s workspace-write \
  -c model_reasoning_effort=xhigh \
  "Refactor the authentication system with comprehensive security improvements"
```

### Expected Output

Codex provides:
- Deep architectural analysis of current system
- Comprehensive security vulnerability assessment
- Multi-layered refactoring strategy
- Implementation of security best practices
- Detailed reasoning about trade-offs
- Long-horizon planning for complex changes

**When to use xhigh**: Complex architectural refactoring, security-critical changes, long-horizon tasks where quality is more important than speed.

---

## Model Selection Summary

| Task Type | Model | Sandbox | Example |
|-----------|-------|---------|---------|
| General reasoning | `gpt-5.1` | `read-only` | "Design a queue" |
| Architecture design | `gpt-5.1` | `read-only` | "Design REST API" |
| Code review | `gpt-5.1` | `read-only` | "Review this code" |
| Code editing (standard) | `gpt-5.1-codex-max` | `workspace-write` | "Edit file to add X" |
| Code editing (maximum reasoning) | `gpt-5.1-codex-max` + `xhigh` | `workspace-write` | "Complex refactoring" |
| Implementation | `gpt-5.1-codex-max` | `workspace-write` | "Implement function Y" |
| Backward compatibility | `gpt-5.1-codex` | `workspace-write` | "Use standard model" |

**Note**: `gpt-5.1-codex-max` is 27-42% faster than `gpt-5.1-codex` and uses ~30% fewer thinking tokens. It supports a new `xhigh` reasoning effort level for maximum capability.

---

## Tips for Best Results

1. **Be specific** in your requests - detailed prompts get better reasoning
2. **Indicate task type** clearly (design vs. implementation)
3. **Mention permissions** when you need file writes ("allow file writing")
4. **Use continuation** for iterative development (see session-continuation.md)

---

## Next Steps

- **Continue a session**: See [session-continuation.md](./session-continuation.md)
- **Advanced config**: See [advanced-config.md](./advanced-config.md)
- **Full documentation**: See [../SKILL.md](../SKILL.md)