OpenResearch CLI (`orx`) Internal Structure: A Deep Dive into the Rust Architecture

The OpenResearch CLI (orx) is a single-binary Rust application organized into distinct layers—entry point, command routing, local mode, remote clients, and job runners—with strict separation between offline-local functionality and remote API operations.

The orx command-line tool from the alphaXiv/OpenResearch repository follows a modular architecture that separates concerns between CLI parsing, local computation, and remote API communication. Understanding how the OpenResearch CLI (orx) structure is organized helps developers extend compute backends, debug agent integrations, or contribute to the core Rust codebase.

Entry Point and Command Dispatch (src/main.rs)

The application starts in src/main.rs, which defines the top-level clap-driven argument structure. This file contains the Cli struct and the Command enum that enumerates every user-visible sub-command.

The entry point sets up the async runtime, parses arguments, and dispatches to the appropriate handler through a match expression:

match cli.command {
    Some(Command::Login(args)) => login::run(args).await,
    // …
}

(source: src/main.rs lines 63-66)

Each variant of the Command enum maps directly to a module under src/commands/. The main.rs file orchestrates the initial setup but delegates all business logic to specialized command modules.

Command Routing Layer (src/commands/)

The src/commands/mod.rs file aggregates all command implementations and establishes the run convention. Every sub-command module (such as login, projects, or up) exposes an async run function that receives the corresponding argument struct and returns anyhow::Result<()>.

This pattern enforces consistent error handling across the CLI. Error bubbles propagate naturally through the async stack, allowing network I/O and compute operations to fail gracefully without blocking the runtime.

Local Mode Architecture (src/local/)

The local mode represents the core offline functionality of the OpenResearch CLI (orx) structure. The src/local/mod.rs module handles all work that stays completely on the local machine—including the SQLite store, local Git branches, and launching compute backends—with no references to the remote API client.

This layer defines the canonical list of compute targets through constants BACKENDS, FLAVORED_BACKENDS, and FLAVOR_REQUIRED_BACKENDS. When executing orx up, the system resolves compute defaults using helper functions apply_compute_default and resolve_compute_default:

let (backend, flavor) = resolve_compute_default(...);
match backend.as_str() {
    "hf" => jobs::hf::run(flavor, …).await,
    "modal" => jobs::modal::run(flavor, …).await,
    // …
}

(source: src/local/mod.rs lines 84-100 and src/commands/up.rs)

Sub-modules under src/local/ include projects, experiments, resolve, git, skills, and compute-specific back-ends (hf, modal, k8s, ssh, slurm, ray, openresearch).

Remote API and Configuration

When online functionality is required, the CLI uses src/client.rs (containing generated DTOs) and the src/remote/ directory for low-level HTTP wrappers. This separation ensures that remote communication is isolated from local operations.

State persistence is handled by three key files:

• src/config.rs – Manages ~/.orx/config.toml for user preferences and compute defaults
• src/store.rs – Provides SQLite abstraction for projects, experiments, and runs
• src/workspace_state.rs – Maintains in-memory representation of a running workspace

Background Jobs and Compute Backends (src/jobs/)

The src/jobs/ directory contains modular job runners for each supported compute backend. Each module (such as tinker.rs, ssh.rs, ray.rs, or modal.rs) implements a concrete backend launch strategy.

Jobs implement a run method that spawns the appropriate process—whether a Docker container, SSH command, or cloud API call—and writes execution logs back to the SQLite store defined in src/store.rs. This architecture makes adding new compute targets a matter of implementing a new job module.

Agent Integration and Permission Gating (src/local/harness/)

The src/local/harness/ directory bridges the OpenResearch CLI (orx) structure with external coding agents (Claude, Codex, OpenCode, Cursor). It contains the permission gate system that controls what agents are allowed to execute.

The hidden plan-gate and mcp-gate commands implement a server-side permission bridge. These read a JSON payload from stdin, evaluate whether the requested sub-command is read-only, and output an allow/deny decision:

let payload = read_stdin();
if readonly_verbs_are_real_commands(&payload.command) {
    println!("allow");
} else {
    println!("deny");
}

(source: src/local/harness/plan_gate.rs)

This gating mechanism ensures agents cannot perform destructive operations without explicit user approval.

Supporting Systems

Telemetry – Anonymous usage statistics are handled by src/telemetry.rs and the Telemetry command, respecting user opt-out preferences stored in src/config.rs.

Updates – Self-update logic for the CLI binary and macOS app bundle resides in src/updates/, exposed through the Update and InstallCli commands.

Summary

• The entry point in src/main.rs uses clap to parse arguments and dispatch to async command handlers.
• Command routing follows a strict convention in src/commands/mod.rs, with each sub-command implementing an async run function returning anyhow::Result.
• Local mode (src/local/) operates entirely offline using src/store.rs for SQLite persistence and src/local/mod.rs for backend resolution.
• Remote functionality is isolated in src/client.rs and src/remote/, keeping the local mode free of API dependencies.
• Job runners in src/jobs/ provide backend-agnostic compute dispatch through modular implementations.
• Agent harness (src/local/harness/) enforces security through the plan-gate permission system.

Frequently Asked Questions

What file handles the CLI argument parsing in the OpenResearch CLI?

The src/main.rs file defines the Cli struct using the clap derive macro, along with the Command enum that enumerates all available sub-commands. This file contains the top-level match statement that dispatches parsed arguments to the appropriate command handler.

How does orx handle offline operations without API calls?

The src/local/ module contains no references to src/client.rs, ensuring complete isolation from remote APIs. It operates against the local SQLite store in src/store.rs and the filesystem, making commands like orx up fully functional without internet connectivity.

What is the purpose of the plan-gate command in the alphaXiv/OpenResearch codebase?

The plan-gate command is a hidden utility in src/local/harness/plan_gate.rs that implements a permission bridge for coding agents. It reads a JSON payload from stdin, validates whether the requested operation is read-only, and prints "allow" or "deny" to stdout, preventing agents from executing destructive commands without authorization.

Which module manages the SQLite database for local projects?

The src/store.rs module provides the primary SQLite abstraction layer, handling persistence for projects, experiments, and run histories. This module is used exclusively by the local mode architecture in src/local/ to maintain state without requiring remote API calls.

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