How the Codex harness works for coding agents

A Codex harness is the runtime layer that turns a language model into a coding agent. It assembles context, exposes tools, executes actions within permission boundaries, preserves state, and continues work until a verifiable objective is complete. The open source Codex harness demonstrates a practical architecture for this job, separating the application interface from model inference while using a Responses API for tool calls and agent capabilities. For teams building their own agents, the key lesson is not to replicate one implementation exactly. It is to control context growth, make actions safe, reduce repeated-turn latency, and retain enough project state for coordinated work in an agent-first control plane. While teams can establish foundational agent harness primitives for any general application, a developer runtime requires specialized controls for file editing and local execution. See our guide on what an agent harness is for the underlying primitives this architecture builds on.

At a Glance

The architectural patterns behind reliable, fast, and controllable coding agents.

• Context discipline: Tool definitions, skills, and instructions must fit within a bounded context budget without burying useful information.
• Action model: Coding agents need structured file edits, shell access, asynchronous work, and controlled computer use.
• Safety boundary: Sandboxes and contextual approval review reduce the pressure to grant unrestricted access.
• Long-running work: Concrete goals, continuation loops, and compaction help agents complete tasks that exceed one context window.
• Latency: Persistent stateful connections can matter more than inference speed when an agent makes many tool calls.
  

The Codex architecture: A blueprint for developer harnesses

The open-source Codex reference implementation demonstrates how to decouple the developer interface from model-driven execution. Rather than building a monolith, the Codex architecture enforces two distinct protocol boundaries: an application server that interfaces with the developer client, and a Responses API that connects the harness to underlying inference. This separation ensures the runtime remains flexible; teams can modify the user interface or target model without altering core tool behaviors, permission boundaries, or task orchestration rules.

By studying the Codex repository, agent builders can observe a concrete model for managing file editing, command execution, and task state. Instead of relying on a model to handle every phase of execution natively, the harness manages the state machine, parses tools, and structures the context. For highly structured tasks, standardizing these rules is sufficient, but more dynamic environments may require transitioning beyond fixed AI harnesses toward adaptive architectures.

How should an agent build context without overwhelming the model?

Good context construction gives the model the minimum relevant information needed to act correctly. It must balance context size, flexibility for skills and integrations, and cacheability, because excessive or contradictory context increases cost and can confuse the model.

Context is not just the latest user request. A coding-agent runtime may need to assemble:

• System and model instructions
• Repository and workspace information
• Available skills and reusable workflows
• Tool schemas and permissions
• Model Context Protocol, or MCP, server capabilities
• Previous tool results, plans, and task state

The failure mode is predictable: every new integration adds descriptions, schemas, and examples until the model receives a crowded, expensive prompt. More context is not automatically better. It can introduce competing instructions, make tool selection worse, and consume tokens before useful work begins.

Use deferred tools for large registries

One practical solution is deferred tool loading. Rather than placing every tool definition into the initial context, the harness marks some tools as discoverable through a tool-search mechanism. The model can retrieve details only when it identifies a relevant capability.

This pattern matters most when a team has many MCP servers, plugins, or internal APIs. A model working on a local refactor does not need detailed schemas for every deployment, analytics, support, or billing tool. Keeping those definitions out of the initial prompt leaves room for the task itself.

Cap skill descriptions before they consume the task

Skills can also expand unpredictably. The Codex approach limits the skills list to a small percentage of the available context window, trimming descriptions as the list grows. The exact percentage is an implementation choice, but the design rule is durable: reserve most of the context window for the problem, evidence, and work in progress.

For teams managing multiple coding agents, this context should not live only in prompts. A shared system such as Levr’s agent-first project workspace keeps issues, acceptance criteria, test state, and workflow gates attached to the work itself. That gives agents durable project context without requiring every detail to be repeated in every task request.

Which actions should a coding agent be able to perform?

A useful coding agent needs more than text generation. It needs structured ways to edit files, inspect and run code, delegate work, and interact with external systems, all through tools whose permissions and outputs the harness can govern.

The Codex harness highlights three categories that agent builders should model separately.

File editing and shell operations

File edits work best as a structured operation rather than a vague instruction to rewrite code. Recent Codex models are trained to use an apply-patch style tool, allowing edits to be represented as diffs. This provides the harness with a clear, reviewable write path for creating and changing files.

Repository search, navigation, and command execution belong in a shell tool. Models commonly use fast text-search utilities such as ripgrep to locate symbols and inspect code. On Windows, native PowerShell support also matters because a coding agent should use the conventions of the environment it is operating in.

Asynchronous tasks and subagents

Some tasks should not block the primary agent. A harness can expose tools to spawn subagents, send them follow-up input, wait for their results, or stop them. The same asynchronous model can support background terminals that start long-running commands and receive later input through standard input.

Parallelism is useful only when ownership is clear. Delegate independent work, such as inspecting two unfamiliar modules or researching separate implementation options. Do not use subagents to create a noisy swarm around one small edit. The main agent still needs a way to reconcile results, resolve contradictions, and own the final change.

Scripted computer use

Computer use becomes more capable when the agent can script interactions instead of taking one UI action at a time. In the described browser workflow, the agent writes JavaScript against a persistent Node environment and browser session, using browser automation code to inspect pages and perform later actions.

A persistent browser session lets the agent reuse tabs and discovered page structure across turns. That can be faster than repeatedly rediscovering the same interface. It also raises the stakes for permissions, because scripted browser use can move quickly from reading information to submitting forms or transmitting data.

How do you sandbox coding agents without creating approval fatigue?

Sandboxes reduce the damage an agent can cause when it executes commands or changes files, while targeted approvals retain human control for higher-risk actions. The goal is not to approve everything, but to make the approval boundary proportional to the action and its context.

In the Codex design, filesystem interactions run through a sandbox layer. The implementation differs by operating system, using platform-appropriate isolation mechanisms on macOS and Linux, plus a dedicated open source sandbox for Windows.

While local file edits can be constrained through platform-appropriate filesystem sandboxes, deploying autonomous agents to production environments requires a comprehensive zero-trust agent sandboxing architecture built on hardware virtualization.

Sandboxing is essential because a model can misunderstand a task, choose an unexpected workaround, or make a destructive command too broad. These risks do not disappear because models improve. They become more important as teams ask agents to operate with greater autonomy.

Why blanket full access is a poor default

Repeated prompts for approval are frustrating, especially during a long task. The tempting response is to grant full access permanently. That may remove interruptions, but it also removes the safety boundary exactly when an agent is navigating unfamiliar code, external content, credentials, network calls, or destructive commands.

Instead, define access by capability and scope:

• Read access: Inspect repository files, logs, documentation, and permitted services.
• Write access: Modify only the workspace, branch, or directories required for the task.
• Execution access: Run approved development commands in an isolated environment.
• Network access: Restrict destinations and distinguish harmless checks from data transfer.
• Escalated actions: Require explicit review for sensitive paths, secrets, deletion, publishing, or external side effects.

Use contextual approval review

An auto-review subagent is one response to approval fatigue. The reviewer can receive the task history, requested tool call, authorization context, and a risk taxonomy, then judge whether the requested action matches the user’s intent.

The distinction is contextual. Deleting a temporary file after an explicit request may be appropriate. Deleting version-control history or transmitting project files to an external service without clear authorization is not. A read-only reviewer with no ability to create additional subagents narrows the reviewer’s own authority.

This aligns with guidance in the NIST AI Risk Management Framework: organizations should govern AI system behavior through ongoing measurement, management, and documented controls rather than relying on an assumption that automated systems will always behave as intended.

Give coding agents work with boundaries, evidence, and ownership.

Levr keeps issues, acceptance criteria, test runs, workflow gates, and attributed activity in one shared system so agent work remains visible from intent through review.

Explore agent-first project workflows

Why can network overhead become the agent performance bottleneck?

When model inference becomes fast and an agent makes many tool calls, repeated network payloads can dominate total task time. Persistent stateful connections reduce that overhead by sending only changed information instead of resending an entire turn history after every tool result.

Agent latency is cumulative. A typical task may require repository search, file reads, tool calls, patch application, test execution, error inspection, and retries. Even if each inference response is quick, serialized request and response overhead adds up across dozens of turns.

The described WebSocket mode replaces repeated server-sent event and HTTP exchanges with a persistent connection. Because the connection maintains state, the client can return only the new tool result rather than re-uploading every previous item.

That is a useful optimization only after the basic workflow is sound. Start by measuring where time goes: model inference, tool execution, network transfer, queueing, and human approvals. Optimize the actual bottleneck rather than assuming the model is always the slowest component.

The OpenAI tools documentation provides the underlying model for structured tool calls and tool outputs. The harness remains responsible for deciding how those calls are routed, executed, persisted, and constrained.

How should long-running coding agents know when to stop?

Long-running agents need a concrete objective, a continuation mechanism, and an explicit completion signal. A harness can continue the agent after each turn, but it should stop only when the agent can verify that the stated goal and acceptance conditions are satisfied.

A continuation loop can inject the objective back into the active context and keep the model working until it calls a dedicated tool indicating completion or changes the plan. This helps prevent the agent from stopping merely because it has produced a plausible response.

The quality of the goal determines the quality of the loop. Avoid broad requests such as “clean up the authentication system” when the desired result cannot be checked. Prefer goals with observable completion criteria:

• Replace a deprecated API in specified modules.
• Add a test covering a named regression.
• Run the defined test command and resolve failures caused by the change.
• Update the issue with changed files, test results, and remaining risks.

Concrete, verifiable objectives give an agent a completion condition that can be evaluated through tests, repository state, or review. They also give humans a clearer contract for deciding whether the output is ready to merge.

What is context compaction, and when should an agent use it?

Context compaction replaces a long interaction history with a smaller structured summary that preserves the active objective, decisions, findings, and unfinished work. It allows an agent to continue across long tasks without carrying every prior message indefinitely—see our Claude Certified Architect exam guide for how this applies to the Anthropic ecosystem specifically.

Without compaction, long-running workflows eventually fill the context window. Simply dropping older information is dangerous because the removed information may contain key constraints, failed approaches, permission decisions, or the original task definition.

A better compaction record preserves:

• The current objective and acceptance criteria
• Files inspected and changes already made
• Commands run and their relevant results
• Important design decisions and rejected options
• Known failures, blockers, and next steps
• Permission or safety decisions that still apply

Compaction should happen at a stable boundary, such as after a completed implementation phase, a test run, or a delegated task returns. It should not erase raw evidence needed for auditability. Keep durable activity history outside the model context, then give the model a concise operational summary for its next turn.

How can teams run coding agents with a shared control plane?

Teams can scale coding-agent work by making tasks, acceptance criteria, verification evidence, and approvals shared objects rather than private prompt history. This lets agents act autonomously where appropriate while giving developers and engineering managers a reliable view of progress and risk.

This matters in practice, not just in theory — Levr's control plane is heterogeneous by design, routing work to Codex alongside Claude Code, Cursor, Antigravity, Copilot, and open-weight models like Kimi, Qwen, or GLM on the same project, without requiring teams to standardize on a single harness.

One way to structure the workflow in Levr is:

1. Define intent in natural language: Create an issue with a narrow goal, relevant constraints, and structured acceptance criteria.
2. Assign work to the right agent: Let a coding agent read the issue context, inspect the repository, and update task state as it works.
3. Verify automatically: Tie tests and execution results to the work so completion requires evidence, not an unsupported status update.
4. Review and approve: Keep human checkpoints for design decisions, elevated permissions, pull requests, and release readiness.

This arrangement addresses a common coordination gap. A coding agent may finish a branch before a conventional tracker reflects what happened, why it happened, and whether validation passed. Shared issues and test records reduce the gap between agent execution and project reality.

Levr supports an agentic workflow where humans and coding agents operate against the same project objects. That is especially useful when multiple agents need shared memory, clear handoffs, attributed actions, and quality gates instead of disconnected prompts and status updates.

Every Harness, One Control Plane: The Levr Dashboard

A harness governs how one agent behaves — the Levr Dashboard governs visibility across all of them. Whether work is routed to Codex, Claude Code, or another agent, the dashboard aggregates runs, tool calls, and approval status into a single pane of glass, so teams see one consistent picture regardless of which harness did the work

The Levr Dashboard gives teams one consistent view across every agent harness, whichever one is doing the work.

What mistakes make coding-agent harnesses unreliable?

Unreliable harnesses usually fail through uncontrolled context growth, ambiguous goals, overly broad permissions, invisible background work, and missing verification. Avoiding these mistakes requires explicit boundaries in the runtime and equally explicit definitions of done in the project workflow.

• Loading every tool by default: Large tool registries crowd out task-relevant context. Use discovery or deferred loading.
• Confusing a plan with proof: An agent’s explanation is not evidence that code compiles, tests pass, or requirements are met.
• Making permissions binary: Full access versus no access creates bad incentives. Scope capabilities by filesystem, command, network destination, and risk.
• Using vague goals: The agent cannot reliably determine when “make it better” is complete. Give it testable completion criteria.
• Delegating without coordination: Subagents can duplicate work or conflict. Assign independent scopes and require a synthesizing owner.
• Discarding state without preserving history: Compact the working context, but retain action logs, tool results, and approvals for review.
• Optimizing inference before measurement: Tool execution, network transfer, and approval waits can dominate real task duration.
  

Technical Deep Dive FAQ

How does a coding-specific harness differ from a general-purpose agent harness?

While general-purpose harnesses focus on generic orchestration primitives like API integrations and structured text output, a coding-specific harness is tailored for local software development environments. For example, Codex manages specific developer-environment tasks: running code locally, handling terminal streams, and editing codebases. Instead of writing files arbitrarily, a coding harness uses tools like an apply-patch diff mechanism for surgical, auditable edits. It also coordinates local execution through OS-specific sandboxes—such as macOS sandbox profiles, Linux containers, or a dedicated Windows sandbox environment—ensuring that command execution and repository searches do not run with unrestricted system privileges.

What is the difference between a model and an agent?

A model generates or transforms content based on input. An agent combines a model with an objective, tools, memory, feedback loops, and the ability to take actions. For coding work, the difference is practical: a model can suggest a patch, while an agent can inspect the repository, create the patch, run tests, read failures, revise the change, and report evidence. The harness provides the execution and control layer that makes this loop possible.

Why does a coding agent need tool search?

Tool search prevents a large tool registry from consuming the context window before the agent begins work. Instead of loading every tool schema and description into the prompt, the harness exposes a mechanism for discovering relevant tools on demand. This reduces token use and lowers the chance that similar or irrelevant tools confuse selection. It is particularly useful for environments with many MCP servers, plugins, internal APIs, or specialized workflows.

What is deferred tool loading?

Deferred tool loading is a context-management pattern in which a tool exists in the agent environment but is not included in the initial model context. The agent must discover it through a search or retrieval mechanism before calling it. This keeps common tasks fast and focused while preserving access to less frequently used capabilities. The harness should still enforce permissions after discovery. Finding a tool should not automatically grant the right to perform sensitive actions with it.

Why use an apply-patch tool for file editing?

An apply-patch tool gives the coding agent a structured write mechanism based on explicit file diffs. It is easier to review and validate than an unbounded request to rewrite arbitrary files. A harness can check target paths, reject malformed patches, record the exact change, and apply it within a sandboxed workspace. Shell commands remain useful for inspection and automation, but separating patch application from general command execution creates a clearer and safer editing path.

How should coding-agent sandbox permissions work?

Sandbox permissions should follow least privilege. Start with read access to the relevant workspace, add write access only for task-scoped paths, and isolate command execution from sensitive host resources. Network access should be separately constrained, especially where secrets or data transfer are possible. Escalation should be contextual: a request explicitly authorized by the task may be acceptable, while the same action outside that scope should require review. Keep all actions attributable and inspectable afterward.

What is approval fatigue in agent workflows?

Approval fatigue occurs when an agent repeatedly asks a human to approve routine actions, leading people to approve without reading or grant broad access to avoid interruptions. Both outcomes weaken security. A better design automatically permits low-risk, task-aligned actions inside a sandbox and escalates actions with greater impact, such as broad deletion, credential access, external publishing, or data transmission. Context-aware review can use the task history to distinguish an expected action from an unexpected one.

How do subagents coordinate without duplicating work?

Subagents coordinate best when each receives a narrow scope, a defined output, and a communication channel back to a primary agent. Good delegated tasks include researching one subsystem, running a long test suite, or inspecting a separate implementation approach. The primary agent should own integration and final decisions. Shared project state also helps: when tasks, status, test evidence, and handoffs are visible to all participants, agents are less likely to overwrite each other or repeat completed work.

What is agent context compaction?

Agent context compaction is the process of replacing a long conversation and tool history with a concise state record for future turns. A useful compacted record includes the objective, completed work, current plan, relevant files, important tool results, unresolved failures, and next steps. It keeps long-running tasks viable when the full history no longer fits in the context window. Compaction should preserve critical constraints and leave a durable audit trail outside the active model prompt.

How do you measure coding-agent performance?

Measure the full workflow, not only model response time. Useful signals include time to first useful action, total task duration, number of tool calls, tool failure rate, approval rate, retries, test pass rate, rework after human review, and percentage of tasks completed with linked verification evidence. Engineering managers also need visibility into blocked work and workload by human and agent. These measures reveal whether the bottleneck is inference, network latency, tooling, unclear requirements, or review capacity.

Can coding agents safely work autonomously?

Coding agents can operate autonomously within a bounded workflow, but autonomy should be calibrated to the task and environment. Low-risk changes in an isolated workspace with clear tests may need limited oversight. Changes affecting production infrastructure, credentials, customer data, or irreversible external actions deserve stricter permissions and human review. The safest approach is not one global autonomy setting. It is a set of workflow gates, sandbox controls, test requirements, and escalation paths matched to the work’s potential impact.

Key Takeaways

Reliable coding agents need a runtime designed for context, actions, safety, and verification.

• Build less context: Load only what the task needs, and defer large tool registries until discovery is necessary.
• Make actions explicit: Separate patches, shell execution, browser interaction, and delegated work into governed tools.
• Use proportional controls: Sandboxes and contextual escalation are safer than either constant approvals or permanent full access.
• Define done clearly: Verifiable goals, test results, and explicit completion signals keep long-running agents on track.
• Keep work shared: A control plane connects agent activity to issues, evidence, review, and project accountability.

The best agent harness does not merely make a model more autonomous. It makes autonomous work observable, bounded, and easier to trust.

Further reading

• Codex, Behind the Harness
• OpenAI Codex open source repository
• OpenAI tools documentation
• NIST AI Risk Management Framework
• Levr agent-first project management
• Levr features for agents, issues, and testing
• Levr agentic workflow
  

Ship at agent speed

Give your coding agents a control plane, not just a prompt.

Levr connects coding agents to shared project context with issues, gates, test suites, activity history, and human approval points. Agents can work against the same live project objects as the rest of the engineering team.

Get early access to Levr

No credit card required during beta.