OpenAI Codex CLI vs Gemini CLI

OpenAI Codex CLI vs Gemini CLIComparisonUpdated 2026-03-16

SUMMARY

OpenAI Codex CLI (CLI) uses markdown configuration while Gemini CLI (CLI) uses markdown. They differ on 2 of 11 compared features. Both tools provide AI-assisted development but take different approaches to project configuration.

FEATURE COMPARISON

Feature	OpenAI Codex CLI	Gemini CLI	Notes
Config format	markdown	markdown
Hierarchy support	✓	✓	Whether config files can be placed at multiple directory levels
Global config	✓	✓	User-wide configuration outside any project
Project config	✓	✓
Subdirectory scoping	✓	✗	Config files in subdirectories that apply only to that subtree
File inclusion / imports	✗	✗	Ability to include or reference other files from config
Ignore file	.codexignore	✗
IDE integration	CLI	CLI
Schema / structure	Free-form (Markdown)	Free-form (Markdown)	Whether config uses structured schema or free-form content
Git committed	✓	✓	Whether primary config files are intended to be version-controlled
Encoding	UTF-8	UTF-8

FILE MAPPING

Purpose	OpenAI Codex CLI	Gemini CLI
Project instructions	AGENTS.md	GEMINI.md
Project instructions	AGENTS.override.md	.gemini/styleguide.md
Settings / configuration	~/.codex/config.toml	.gemini/settings.json

SIDE-BY-SIDE CODE SAMPLES

OpenAI Codex CLI

AGENTS.md

markdown

# AGENTS.md

## Project Overview

This is a Next.js 14 e-commerce application using the App Router,
Server Components, and Drizzle ORM with PostgreSQL.

## Code Conventions

- Use TypeScript strict mode throughout
- Prefer Server Components; use "use client" only when necessary
- Name files with kebab-case: `product-card.tsx`, not `ProductCard.tsx`
- Co-locate tests: `product-card.test.tsx` next to `product-card.tsx`

## Architecture

- `app/`           — Next.js App Router pages and layouts
- `components/`    — Shared UI components
- `lib/`           — Utilities, database client, auth helpers
- `actions/`       — Server Actions for mutations

## Testing

- Use Vitest for unit tests, Playwright for E2E
- Mock database calls using `lib/test-utils.ts` helpers
- Every new component needs at least one test

## Build Commands

```bash
pnpm dev          # Start dev server
pnpm build        # Production build
pnpm test         # Run Vitest
pnpm test:e2e     # Run Playwright
pnpm lint         # ESLint check
```

Gemini CLI

GEMINI.md

markdown

# Project Context

## Stack
- Node.js 22 with TypeScript 5.x
- Express.js for the API server
- Prisma ORM with PostgreSQL
- React 19 with Vite for the frontend

## Architecture
- Monorepo with pnpm workspaces
- packages/api — Express REST API
- packages/web — React SPA
- packages/shared — Shared types and utilities

## Commands
- pnpm dev — Start all services
- pnpm test — Run vitest across all packages
- pnpm lint — ESLint + Prettier check
- pnpm db:migrate — Run Prisma migrations

## Conventions
- Use barrel exports (index.ts) for public APIs
- Error responses use RFC 7807 Problem Details format
- All API endpoints require authentication except /health

KEY DIFFERENCES

1. Subdirectory scoping

OpenAI Codex CLI: Supported. Gemini CLI: Not supported.

2. Ignore file

OpenAI Codex CLI: .codexignore. Gemini CLI: Not supported.

WHICH SHOULD I USE?

Recommendation

Choose based on your IDE/CLI preference. If you use OpenAI Codex CLI, configure AGENTS.md. If you use Gemini CLI, configure GEMINI.md. Many projects include config files for multiple tools so each team member can use their preferred editor.

PORTABILITY TIP

sync-instructions.sh

bash

# Maintain a single source of truth:
cp AI-INSTRUCTIONS.md CLAUDE.md
cp AI-INSTRUCTIONS.md .cursorrules
cp AI-INSTRUCTIONS.md AGENTS.md