Claude Code vs Codex vs Gemini CLI: The Harness Matters More Than the Model

Developers often compare AI coding agents by asking one question:

Which model is smartest?

That is increasingly the wrong question.

Claude Code, OpenAI Codex, and Gemini CLI can all inspect repositories, edit files, execute commands, run tests, and automate development tasks. Their real differences come from the systems surrounding the models:

• How they collect context
• Which tools they can access
• How they request permission
• How they recover from failure
• How easily they fit into scripts and team workflows

The model matters. But the agent harness determines how that intelligence behaves inside a real codebase.

Quick comparison

Area	Claude Code	OpenAI Codex	Gemini CLI
Best fit	Deep repository work	Structured coding automation	Open and customizable CLI workflows
Interface	Terminal-first agent	CLI and broader Codex workflows	Open-source terminal agent
Project context	CLAUDE.md	Repository instructions and task context	GEMINI.md
Automation	Hooks, print mode and scripts	CLI, structured workflows and integrations	Non-interactive mode, JSON and stream output
Extensibility	MCP and hooks	MCP, skills and external commands	MCP, extensions and custom tools
Main advantage	Strong codebase reasoning	Controlled execution and workflow integration	Openness and provider ecosystem
Main tradeoff	Can become expensive on long sessions	Results depend heavily on task specification	Fast-moving releases may introduce regressions

There is no universal winner. The correct choice depends on the type of work being delegated.

Claude Code: best for deep repository work

Claude Code is designed to operate directly inside a project from the terminal. It can search files, understand relationships across a repository, edit code, run commands and iterate against test results.

Its biggest strength is not merely code generation. It is maintaining a useful mental model of a codebase while moving through a multi-step task.

That makes it particularly useful for:

• Investigating unfamiliar repositories
• Planning large refactors
• Tracing bugs across multiple modules
• Updating implementations and related tests together
• Reviewing architectural decisions
• Executing tasks that require repeated reasoning

Projects can provide persistent instructions through CLAUDE.md. Teams can use this file to describe architecture, commands, conventions, testing requirements and boundaries the agent should respect.

Claude Code also supports Model Context Protocol integrations, allowing it to interact with external tools and data sources instead of treating the repository as an isolated folder.

Its CLI also supports structured output, including JSON and streaming JSON, which makes it possible to use Claude Code inside scripts rather than only through interactive sessions.

Where Claude Code fits best

Use Claude Code when the task sounds like:

Understand how this subsystem works, identify the root cause, propose a fix, implement it and verify that nothing else broke.

That is different from asking an assistant to produce one isolated function.

Main limitation

Long exploratory sessions can consume substantial context and tokens. Without clear repository instructions, agents may repeatedly search the same areas or make technically valid changes that conflict with local conventions.

Claude Code performs better when the repository contains:

• Clear project instructions
• Reliable test commands
• Small, reviewable task boundaries
• Explicit rules for generated files and migrations
• Permission limits for destructive operations

The better the environment, the less intelligence gets wasted rediscovering basic facts.

OpenAI Codex: best for structured execution

Codex is strongest when coding work needs to become a repeatable workflow rather than an extended conversation.

It is well suited to tasks such as:

• Implementing clearly scoped changes
• Updating documentation from source code
• Creating internal developer commands
• Running repeatable evaluation tasks
• Automating maintenance work
• Integrating coding actions with team systems

OpenAI’s official Codex examples increasingly extend beyond writing code. They include maintaining documentation, creating command-line tools, preparing product requirements and combining repository context with external organizational information.

This represents an important shift.

A coding agent is no longer only a developer sitting inside the terminal. It can become an execution layer between repositories, issue trackers, documentation systems, logs and internal tools.

Where Codex fits best

Use Codex when the task sounds like:

Take this defined issue, make the required changes, run the relevant checks and return a reviewable result.

Codex benefits from clear acceptance criteria. The more precisely the expected result can be verified, the easier it is to delegate safely.

Main limitation

Structured execution does not eliminate ambiguity.

If a task contains vague product decisions, hidden architectural assumptions or unclear ownership boundaries, the agent may confidently produce a complete solution to the wrong interpretation.

Codex should not be treated as a replacement for task definition. It amplifies the quality of the task it receives, including the bad parts.

Gemini CLI: best for open and customizable workflows

Gemini CLI is an open-source terminal agent released under the Apache 2.0 licence.

It supports:

• Interactive terminal sessions
• Non-interactive prompts
• JSON output
• Streaming JSON events
• Multiple project directories
• Persistent context through GEMINI.md
• MCP servers
• Extensions and custom commands
• Built-in tools such as web search

This makes Gemini CLI particularly interesting for developers who want to inspect, modify or extend the agent environment instead of accepting a fully closed workflow.

Its non-interactive mode can be used in shell scripts:

gemini -p "Explain the architecture of this repository"

Structured output can be requested for automation:

gemini -p "Run the tests and summarize failures" \
  --output-format json

For long-running workflows, it can stream newline-delimited events:

gemini -p "Run tests, fix failures and report the result" \
  --output-format stream-json

Gemini CLI also supports MCP and custom tool discovery, providing several ways to connect the agent to external systems.

Where Gemini CLI fits best

Use Gemini CLI when the task sounds like:

Build a transparent terminal workflow that I can customize, script, inspect and connect to other tools.

It is especially relevant for:

• Open-source toolchains
• Experimental agent workflows
• CI scripts
• Model and tool research
• Developers already working heavily with Google’s ecosystem

Main limitation

Gemini CLI publishes preview, stable and nightly release channels. That is useful for rapid experimentation, but preview and nightly builds may carry regressions or incomplete validation. Production workflows should pin versions and avoid casually tracking the newest build simply because it exists.

What empirical research says

Most coding-agent comparisons are based on demos, benchmarks or one developer’s preferred stack.

Recent research paints a less convenient picture.

A 2026 study analysed 7,156 pull requests created by Codex, GitHub Copilot, Devin, Cursor and Claude Code. It found that task type had a major effect on acceptance.

Documentation changes had an acceptance rate of 82.1%, while new-feature work reached 66.1%. That 16-point difference was larger than the usual performance gap between agents.

The study found:

• Claude Code led on documentation and feature tasks
• Cursor performed strongly on fix tasks
• Codex maintained relatively strong results across task categories
• No agent performed best on every type of work

The useful conclusion is not that one tool won.

It is that the task category may matter more than the brand of agent performing it.

Reliability is still the uncomfortable part

Another study examined more than 3,800 publicly reported bugs across Claude Code, Codex and Gemini CLI.

More than 67% were functionality-related. API, integration and configuration problems accounted for 36.9% of identified root causes.

Common symptoms included:

• API failures
• Terminal problems
• Broken commands
• Tool-invocation errors
• Command-execution failures

The research found that tool invocation and command execution were among the most failure-prone parts of the agent workflow.

This matters because developers often evaluate agents using successful demonstrations.

Production systems must be evaluated using failure recovery.

A useful coding agent needs to do more than produce correct code when everything works. It must also behave predictably when:

• A command exits unexpectedly
• Authentication expires
• A tool returns malformed data
• Tests are flaky
• Repository instructions conflict
• A dependency has changed
• The agent reaches a permission boundary

The polished demo is the least interesting part of the system.

Model versus harness

A coding agent can be simplified into five layers:

Model
  ↓
Context management
  ↓
Tool selection
  ↓
Execution environment
  ↓
Verification and recovery

Developers usually focus on the first layer.

Production failures frequently occur in the remaining four.

Two agents using similarly capable models can behave very differently because one:

• Reads project instructions more reliably
• Searches fewer irrelevant files
• Uses tools more efficiently
• Requests permission at better moments
• Runs the correct tests
• Recognizes failed execution
• Preserves state between steps

This is why switching models does not automatically fix a weak agent workflow.

Sometimes the agent does not need a smarter model. It needs better context, narrower tools and a clearer definition of completion.

Which one should you choose?

Choose Claude Code when:

• Repository understanding is the main challenge
• Tasks regularly cross several files
• You perform architectural investigation
• You want strong interactive reasoning
• Your team can maintain useful project instructions

Choose Codex when:

• Tasks have clear acceptance criteria
• You want repeatable coding automation
• Work needs to connect with other systems
• You are building delegated engineering workflows
• Execution and review need clearer separation

Choose Gemini CLI when:

• Open source matters
• You want to inspect or extend the agent
• CLI scripting is central to your workflow
• You need JSON or streaming output
• You are experimenting with MCP and custom tools

A better evaluation method

Do not evaluate coding agents using one prompt that generates a landing page.

That test mostly measures how effectively the agent can produce something visually convincing before anyone reads the code.

Instead, create a small internal evaluation set based on real work:

1. Fix a bug spanning multiple modules.
2. Add a feature with existing architectural constraints.
3. Refactor code without changing behaviour.
4. Update tests after an API change.
5. Explain an unfamiliar subsystem.
6. Diagnose a deliberately broken build.
7. Follow repository-specific security rules.
8. Stop safely when requirements are ambiguous.

For each task, record:

• Completion rate
• Human corrections required
• Tests passed
• Unnecessary files changed
• Tokens or credits consumed
• Time spent reviewing
• Permission violations
• Recovery after failed commands

The best tool is not the one that generates the most code.

It is the one that produces the highest percentage of changes you are willing to merge.

Final verdict

Claude Code, Codex and Gemini CLI are converging on a similar interface: an agent that can inspect a repository, call tools, execute commands and modify code.

Their meaningful differences now lie in workflow design.

• Claude Code is strongest for deep, interactive repository reasoning.
• Codex is strongest for defined tasks and structured execution.
• Gemini CLI is strongest for open, customizable terminal automation.

None should be trusted without tests, permission boundaries and human review.

The next generation of coding-agent competition will not be decided only by which company releases the smartest model.

It will be decided by which harness turns intelligence into reliable engineering work.