Codex CLI

Overview

OpenAI's Codex CLI uses a simple instructions-based system. Fulcrum generates a.codex/ directory with markdown instructions that guide Codex's behavior for your project.

Generated Structure

Running fulcrum sync --vendor codex generates:

.codex/
├── instructions.md          # Main instructions file
├── agents/                  # Agent definitions
│   ├── tech-lead.md
│   ├── backend-engineer.md
│   └── ...
└── skills/                  # Skill documentation
    ├── brainstorming.md
    ├── code-reviewer.md
    └── ...

Instructions File

The instructions.md file is the primary configuration:

# Project Instructions

## Overview
This is a TypeScript monorepo using React and Node.js.

## Agents
You can adopt different personas based on the task:

### Tech Lead (@tech-lead)
Focus on architecture, design patterns, and cross-cutting concerns.
Make decisions that consider long-term maintainability.

### Backend Engineer (@backend-engineer)
Focus on API design, database operations, and server-side logic.
Prioritize performance and security.

### Frontend Engineer (@frontend-engineer)
Focus on UI components, state management, and user experience.
Prioritize accessibility and responsiveness.

## Skills
Apply these methodologies when relevant:

### Brainstorming
Explore multiple approaches before committing to implementation.
Consider trade-offs and alternatives.

### Code Review
Check for security issues, performance problems, and maintainability.
Verify test coverage and documentation.

## Coding Standards
- Use TypeScript strict mode
- Follow ESLint configuration
- Write tests for new functionality
- Use conventional commit messages

Using Codex CLI

Codex CLI reads from the .codex/ directory automatically:

# Start an interactive session
codex

# Run with a specific prompt
codex "implement user authentication with JWT"

# Use agent persona
codex "@tech-lead review this architecture"

# Apply a skill
codex "brainstorm caching strategies for the API"

Agent Invocation

Reference agents using @ notation in your prompts:

# Architecture guidance
codex "@tech-lead design the database schema for multi-tenancy"

# Implementation
codex "@backend-engineer implement the authentication middleware"

# UI work
codex "@frontend-engineer create a responsive data table component"

Configuration Options

Customize the adapter in fulcrum.config.ts:

// fulcrum.config.ts
export default {
  vendors: {
    codex: {
      enabled: true,
      output: '.codex',
      format: 'markdown',    // or 'single-file'
      agents: {
        include: ['tech-lead', 'backend-engineer', 'frontend-engineer'],
        exclude: ['devops-engineer']
      },
      skills: {
        include: ['brainstorming', 'code-reviewer'],
        exclude: ['platform-architect']
      }
    }
  }
}

Single-File Mode

For simpler setups, use single-file mode to consolidate everything:

fulcrum sync --vendor codex --format single-file

This generates a single .codex/instructions.md with all agents and skills embedded, rather than separate files.

Sync Command

# Generate Codex CLI configuration
fulcrum sync --vendor codex

# Watch for changes and auto-sync
fulcrum sync --vendor codex --watch

# Sync all vendors at once
fulcrum sync

Comparison with Other Vendors