Add comprehensive Codex CLI usage tips for community

[sorryhyun]

Document practical tips and lessons learned from integrating Codex CLI:

• App Server mode architecture and JSON-RPC protocol
• Per-agent instance pattern for multi-agent apps
• Session management with thread persistence
• MCP server configuration at startup
• Configuration tips (disable skills, isolate cwd)
• Error handling and session recovery patterns
• Performance optimization (pooling, LRU eviction)
• Platform-specific notes (Windows, macOS)
• Troubleshooting guide and quick reference

[claude]

PR Review: Codex CLI Usage Tips Documentation

Overall Assessment ✅

This is an excellent addition to the documentation! The guide is comprehensive, well-structured, and provides valuable practical insights for developers integrating Codex CLI into production applications. The content is technically accurate based on the codebase implementation.

---

Strengths

📚 Comprehensive Coverage

• Covers the full lifecycle from installation to production deployment
• Includes architecture patterns, error handling, and performance optimization
• Platform-specific considerations (Windows, macOS, Linux)
• Practical code examples throughout

🎯 Well-Organized Structure

• Clear table of contents with 10 logical sections
• Progressive flow from basics to advanced topics
• Quick reference section at the end
• Consistent formatting with tables, code blocks, and callouts

🔍 Technical Accuracy

Verified against implementation in backend/providers/codex/:

• ✅ Environment variables match actual implementation (CODEX_MAX_INSTANCES, CODEX_IDLE_TIMEOUT, etc.)
• ✅ JSON-RPC methods and event types are correct
• ✅ File paths accurately reference actual code structure
• ✅ Authentication flow matches provider.py implementation
• ✅ Pool architecture correctly describes per-agent instance pattern

💡 Practical Value

• Real-world tips (disable skills, isolate cwd, prevent browser auto-open)
• Error recovery patterns with code examples
• Performance tuning guidance
• Troubleshooting section with common issues

---

Suggestions for Improvement

1. Minor Inconsistencies with Existing Docs

The new document uses slightly different terminology than docs/codex_app.md:

CODEX_CLI_TIPS.md:

• Uses "gpt-5.2" as model example

codex_app.md:

• References CODEX_MODEL environment variable

Suggestion: Align model references or clarify that these are examples. Consider adding:

```python
# Use environment variable for model
model = os.getenv("CODEX_MODEL", "gpt-5.2")

#### 2. **Authentication Section Could Be More Robust**

The example `check_codex_available()` function is basic. Consider enhancing it:

```python
async def check_codex_available() -> tuple[bool, str]:
    """Check if Codex CLI is installed and authenticated.
    
    Returns:
        Tuple of (is_available, error_message)
    """
    codex_path = shutil.which("codex")
    if not codex_path:
        return False, "Codex CLI not found in PATH. Install with: npm install -g @openai/codex"

    try:
        process = await asyncio.create_subprocess_exec(
            "codex", "login", "status",
            stdout=asyncio.subprocess.PIPE,
            stderr=asyncio.subprocess.PIPE,
        )
        stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=10.0)
        
        if process.returncode == 0:
            output = stdout.decode("utf-8").lower()
            if "logged in" in output:
                return True, ""
        
        return False, "Not authenticated. Run: codex login"
    except asyncio.TimeoutError:
        return False, "Authentication check timed out"
    except Exception as e:
        return False, f"Error checking authentication: {e}"

3. Section Ordering Optimization

Consider moving "Configuration Tips" earlier (before "Error Handling") since developers need those settings during initial setup:

Current: Getting Started → Architecture → App Server → Session → MCP → Config → Error Handling
Suggested: Getting Started → Architecture → App Server → Config → Session → MCP → Error Handling

4. Add Version Compatibility Note

Since Codex CLI is evolving, add a version note at the top:

> **Note:** This guide is based on Codex CLI version X.X.X (tested January 2026).  
> Some features may vary in different versions.

5. Cross-Reference Opportunities

Add links to related documentation:

## Related Documentation

- [App Server Integration](./codex_app.md) - Internal architecture details
- [Setup Guide](./SETUP.md) - Initial project setup
- [How It Works](./how_it_works.md) - Third-person perspective design

6. Table Formatting Enhancement

Some tables could benefit from center alignment for better readability:

| Method | Purpose |
|:------:|:--------|
| `thread/start` | Create new conversation thread |
| `thread/resume` | Resume existing thread |

---

Minor Issues

Typos/Grammar

• ✅ No significant typos found
• ✅ Grammar is clear and professional

Code Examples

• ✅ All Python examples use proper async/await syntax
• ✅ Bash examples are correct
• ⚠️ Consider adding error handling to more examples

Links

• ❌ Line 557: [ChitChats backend/providers/codex/](../backend/providers/codex/) - Verify this relative path works from docs/ directory
  • Suggestion: Use ../backend/providers/codex/ or /backend/providers/codex/ depending on rendering context

---

Security Considerations

✅ No security concerns identified

The document appropriately:

• Recommends disabling shell access for chat apps
• Mentions sandbox modes
• Suggests environment isolation for MCP servers
• Includes proper secret handling patterns

---

Test Coverage

N/A - This is documentation only (no code changes)

---

Performance Considerations

✅ Performance guidance is strong:

• Pool sizing recommendations
• LRU eviction strategy
• Chunked writes for large messages
• Idle timeout configuration

Suggestion: Add guidance on monitoring:

### Monitoring Pool Performance

```python
# Log pool stats periodically
async def log_pool_stats():
    pool = await CodexAppServerPool.get_instance()
    stats = {
        "active_instances": len(pool._instances),
        "total_threads": sum(len(i._threads) for i in pool._instances.values()),
        "memory_usage_mb": get_process_memory() / 1024 / 1024,
    }
    logger.info(f"Pool stats: {stats}")

---

### Documentation Quality

| Criterion | Rating | Notes |
|-----------|--------|-------|
| **Completeness** | ⭐⭐⭐⭐⭐ | Covers all major aspects |
| **Accuracy** | ⭐⭐⭐⭐⭐ | Verified against codebase |
| **Clarity** | ⭐⭐⭐⭐⭐ | Well-written, clear examples |
| **Structure** | ⭐⭐⭐⭐ | Logical flow (minor reordering suggested) |
| **Practicality** | ⭐⭐⭐⭐⭐ | Excellent real-world tips |

**Overall: 4.8/5** ⭐⭐⭐⭐⭐

---

### Recommendation

**✅ APPROVE with minor suggestions**

This is high-quality documentation that will be valuable to the community. The suggestions above are **optional enhancements** - the PR is ready to merge as-is.

**Impact:** 🎯 High-value addition for developers integrating Codex CLI

---

### Action Items (Optional)

If you'd like to address the suggestions:

1. Add version compatibility note at top
2. Move "Configuration Tips" section earlier
3. Add "Related Documentation" section with cross-references
4. Verify relative path link at bottom
5. Consider enhancing authentication check example

Great work on this comprehensive guide\! 🚀