Where to Find Agent Harnesses for Different Coding Agents in orx

The agent harness implementations that enable orx to communicate with coding agents like Claude Code, OpenCode, Cursor, and Codex are located in the src/local/harness/ directory of the alphaXiv/OpenResearch repository.

The orx project uses a modular abstraction layer to standardize interactions with various AI coding assistants. Each supported agent implements a common Rust trait defined in the harness module, allowing the rest of the codebase to interact with different tools through a uniform interface regardless of their underlying protocols.

Location and Structure of Agent Harnesses in orx

All agent harness code resides under src/local/harness/ in the repository root. This directory contains both the shared trait definition and agent-specific implementation modules.

The Harness Trait Definition

The core contract for all agent integrations is defined in src/local/harness/mod.rs. This file declares the Harness trait that every agent must implement:

#[async_trait]
pub trait Harness {
    fn id(&self) -> &'static str;
    fn name(&self) -> &'static str;
    fn supports_chat(&self) -> bool;
    async fn detect(&self) -> Option<HarnessInfo>;
    async fn run_turn(&self, ctx: &mut TurnCtx) -> TurnResult;
    async fn one_shot(&self, request: OneShot<'_>) -> Option<String>;
    // …additional helper methods
}

This trait abstracts the differences between agent binaries, exposing standardized methods for detection, execution, and configuration.

Agent-Specific Implementation Files

Each supported coding agent has a dedicated Rust module implementing the Harness trait:

• Claude Code: src/local/harness/claude.rs — implements the ClaudeCode struct with Claude CLI skill-shim support
• OpenCode: src/local/harness/opencode.rs — implements the OpenCode struct sharing the CLAUDE_SKILL constant with Claude Code
• Cursor: src/local/harness/cursor.rs — implements the Cursor struct as a lightweight wrapper around the Cursor CLI
• Codex: src/local/harness/codex.rs — implements the Codex struct with dual protocol support for app-server and legacy exec modes

Key Methods in the Agent Harness Interface

Every harness implementation must handle four critical responsibilities through the trait methods:

1. Detection (detect) — Locates the agent binary, verifies installation, checks authentication status, and returns HarnessInfo if usable
2. Turn Execution (run_turn) — Spawns the agent process, handles JSON-RPC event streaming for the "app-server" protocol or legacy exec paths, and updates the conversation context
3. One-Shot Requests (one_shot) — Provides quick completions without establishing persistent sessions, useful for single prompts
4. Capability Reporting (supports_chat, id, name) — Exposes metadata that the UI uses to present available agents and features to users

Implementation Highlights for Major Agents

Codex Harness with Dual Protocol Support

The Codex harness in src/local/harness/codex.rs handles both modern and legacy interaction modes. For Codex versions ≥ 0.144, it uses the app-server protocol; older versions fall back to direct execution.

Key logic appears at lines 283–315, where the detect implementation parses model catalogs and negotiates permission policies. The struct also exposes configuration options for permission modes and reasoning levels through the HarnessOptions system.

Claude Code and OpenCode Skill Integration

Both the Claude Code and OpenCode harnesses utilize a skill-shim architecture. The ClaudeCode struct implements a skill_shim method returning the shared CLAUDE_SKILL constant, enabling consistent tool-use capabilities across both agents. The OpenCode harness follows an identical pattern in src/local/harness/opencode.rs, ensuring feature parity for these similarly architected tools.

Cursor CLI Wrapper

The Cursor harness provides a lightweight integration in src/local/harness/cursor.rs. Its detect logic specifically handles binary location for the Cursor CLI, with streamlined process management compared to the more complex protocol handling required by Codex.

Adding a New Agent Harness to orx

To extend orx support for a new coding agent, create a new file in src/local/harness/ and implement the Harness trait:

// src/local/harness/myagent.rs
use async_trait::async_trait;

pub struct MyAgent;

#[async_trait]
impl Harness for MyAgent {
    fn id(&self) -> &'static str { "myagent" }
    fn name(&self) -> &'static str { "MyAgent" }
    fn supports_chat(&self) -> bool { true }

    async fn detect(&self) -> Option<HarnessInfo> {
        // Locate binary, check version, authentication, etc.
        // Return a populated HarnessInfo or None if not usable.
    }

    async fn run_turn(&self, ctx: &mut TurnCtx) -> TurnResult {
        // Spawn the agent process, stream JSON-RPC events, update ctx.
    }

    async fn one_shot(&self, request: OneShot<'_>) -> Option<String> {
        // Quick request handling, similar to codex_one_shot.
    }
}

After implementation, register the new harness in src/local/harness/mod.rs to enable automatic discovery by the CLI.

Summary

• All agent harness implementations reside in src/local/harness/ within the alphaXiv/OpenResearch repository.
• The Harness trait defined in mod.rs standardizes interactions across Claude Code, OpenCode, Cursor, and Codex.
• Each agent module implements detect(), run_turn(), and one_shot() to handle binary detection, conversational turns, and quick completions.
• The Codex harness supports both modern app-server protocols and legacy execution modes, with specific implementation details at lines 283–315 of codex.rs.
• New agents require implementing the Harness trait and registering in the module index.

Frequently Asked Questions

What directory contains the agent harness implementations in orx?

The concrete implementations are located in src/local/harness/. This directory contains the trait definition in mod.rs and individual modules like claude.rs, codex.rs, cursor.rs, and opencode.rs for each supported agent.

Which trait defines the interface for coding agents in orx?

The Harness trait, defined in src/local/harness/mod.rs, establishes the common interface. It requires methods for agent identification (id, name), capability detection (detect), conversational execution (run_turn), and single-prompt handling (one_shot).

How does the Codex harness handle different protocol versions?

The Codex harness in src/local/harness/codex.rs implements dual protocol support. For Codex versions 0.144 and above, it uses the modern "app-server" protocol with JSON-RPC communication. Earlier versions fall back to a legacy exec path. The detection logic at lines 283–315 determines available capabilities during initialization.

Where can I find utilities for detecting agent binaries?

Binary detection utilities reside in src/local/harness/detect.rs, which provides shared functions for probing system paths, parsing version strings, and reading configuration files. Additional option definitions for UI-exposed settings live in src/local/harness/options.rs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}