OpenClaude CLI Entrypoint and Fast-Path Optimization Explained

The OpenClaude CLI entrypoint is located at src/entrypoints/cli.tsx, which achieves fast-path optimization by parsing command-line arguments immediately and bypassing full application initialization for lightweight commands like --help and --version.

Understanding how OpenClaude achieves its snappy command-line startup requires examining the strategic architecture of its entrypoint system. The openclaude executable at bin/openclaude delegates to src/entrypoints/cli.tsx, which implements a deliberate fast-path mechanism to avoid loading the heavy Ink-based UI and configuration systems when they're not needed.

Where the CLI Entrypoint Lives

The execution flow for OpenClaude follows a clear two-stage pattern:

• bin/openclaude — The executable shim that launches the process
• src/entrypoints/cli.tsx — The primary TypeScript entrypoint containing the main() function

According to source comments in the repository, cli.tsx performs critical worktree setup before the full CLI loads. The src/utils/worktree.ts module contains an explicit comment indicating it is called early in cli.tsx prior to the heavy initialization sequence.

How the Fast-Path Optimization Works

The fast-path in cli.tsx operates through two coordinated mechanisms that ensure minimal latency for simple commands.

Top-Level Await of main()

The entrypoint uses a top-level await main() pattern. This guarantees the JavaScript engine executes the async main() function before evaluating any other module imports.

// src/entrypoints/cli.tsx
async function main(): Promise<void> {
  // Fast-path checks run here before heavy imports
}

await main();

By structuring the code this way, the fast-path logic completes before the Ink UI, plugin system, or network initialization code is ever loaded into memory.

Early-Exit Argument Checks

Inside main(), the CLI inspects process.argv for patterns that require no interactive session:

• --version — Returns version string and exits
• --help — Displays usage information and exits
• --yolo — Activates lightweight YOLO mode and exits

When these patterns match, the function prints the appropriate output and terminates the process immediately. The src/main.tsx module — which contains the actual interactive application — is never imported in these cases. Source comments confirm that main.tsx's command handling is intercepted by this fast-path in cli.tsx.

Supporting Early-Stage Utilities

Several utility modules enable this optimization by providing lightweight capabilities that don't require full initialization:

Utility	Purpose	Location
earlyInput.ts	Captures stdin input before the TUI spins up	src/utils/earlyInput.ts
worktree.ts	Prepares execution environment with minimal overhead	src/utils/worktree.ts

The earlyInput.ts module specifically exports helper functions for capturing early input that cli.tsx invokes right at startup, before any heavy dependencies load.

Practical Fast-Path Examples

These commands demonstrate the optimization in action:

# Returns version instantly without loading Ink UI

$ openclaude --version
v2.3.1

# Displays help and exits immediately

$ openclaude --help
Usage: openclaude [options] <command>

# YOLO mode shortcut bypasses full initialization

$ openclaude --yolo
Running in YOLO mode…

In each scenario, the process terminates after printing output. The heavy UI code in src/main.tsx remains unloaded, producing sub-second response times.

Implementation Architecture

The complete file structure supporting this fast-path:

bin/openclaude              → Executable entry shim
src/entrypoints/cli.tsx     → Fast-path logic and main()
src/main.tsx                → Full interactive application (conditionally loaded)
src/utils/earlyInput.ts     → Early stdin handling
src/utils/worktree.ts       → Lightweight environment setup

This architecture demonstrates a pattern applicable to any Node.js CLI: isolate argument parsing, defer heavy imports, and exit early when the answer requires no interactive session.

Summary

• The OpenClaude CLI entrypoint is src/entrypoints/cli.tsx, launched via bin/openclaude
• Fast-path optimization uses top-level await to run checks before module imports
• Lightweight commands (--help, --version, --yolo) trigger immediate process exit
• The full Ink UI in src/main.tsx loads only for commands requiring interactivity
• Supporting utilities in src/utils/earlyInput.ts and src/utils/worktree.ts enable early-stage functionality without heavy dependencies

Frequently Asked Questions

What makes the OpenClaude CLI start so quickly for simple commands?

The fast-path in src/entrypoints/cli.tsx parses arguments using top-level await before any heavy modules import. For commands like --version or --help, it prints and exits immediately without loading the Ink UI, configuration system, or plugins.

Where is the actual interactive application code located?

The full interactive session lives in src/main.tsx. According to source comments, this file's command handling is only reached when cli.tsx determines that the fast-path conditions are not met — meaning the user needs the complete TUI experience.

What is the --yolo fast-path command?

The --yolo flag triggers a lightweight execution mode that bypasses confirmation prompts and safety checks. Source analysis indicates this is handled as a fast-path command in cli.tsx, allowing rapid operation without the overhead of full initialization.

How does earlyInput.ts support the fast-path?

The src/utils/earlyInput.ts module provides helper functions for capturing stdin data before the terminal UI initializes. This lets cli.tsx process piped input or early keystrokes without waiting for the heavy input handling systems to load.

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