coding-cli-runtime 0.1.0

Reusable CLI runtime primitives for provider-backed automation workflows

coding-cli-runtime

A Python library for orchestrating LLM coding agent CLIs — Claude Code, Codex, Gemini CLI, and GitHub Copilot.

These CLIs each have different invocation patterns, output formats, error shapes, and timeout behaviors. This library normalizes all of that behind a common CliRunRequest → CliRunResult contract, so your automation code doesn't need provider-specific subprocess handling.

What it does (and why not just subprocess.run):

• Unified request/result types across all four CLIs
• Timeout enforcement with graceful process termination
• Provider-aware failure classification (retryable vs fatal)
• Built-in model catalog with defaults, reasoning levels, and capabilities
• Interactive session management for long-running generation tasks
• Zero runtime dependencies

Installation

pip install coding-cli-runtime

Requires Python 3.10+.

Examples

Execute a provider CLI

import asyncio
from pathlib import Path
from coding_cli_runtime import CliRunRequest, run_cli_command

request = CliRunRequest(
    cmd_parts=("codex", "--model", "o4-mini", "--quiet", "exec", "fix the tests"),
    cwd=Path("/tmp/my-project"),
    timeout_seconds=120,
)
result = asyncio.run(run_cli_command(request))

print(result.returncode)        # 0
print(result.error_code)        # "none"
print(result.duration_seconds)  # 14.2
print(result.stdout_text[:200])

Swap codex for claude, gemini, or copilot — the request/result shape stays the same. A synchronous variant run_cli_command_sync is also available.

Pick a model from the provider catalog

from coding_cli_runtime import get_provider_spec

codex = get_provider_spec("codex")
print(codex.default_model)   # "gpt-5.3-codex"
print(codex.model_source)    # "codex_cli_cache", "override", or "code"

for model in codex.models:
    print(f"  {model.name}: {model.description}")

The catalog covers all four providers — each with model names, reasoning levels, default settings, and visibility flags.

Model lists are resolved with a three-tier fallback:

1. User override — drop a JSON file at ~/.config/coding-cli-runtime/providers/<provider>.json to use your own model list immediately, without waiting for a package update.
2. Live CLI cache — for Codex, the library reads ~/.codex/models_cache.json (auto-refreshed by the Codex CLI) when present. Other providers fall through because their CLIs don't expose a machine-readable model list.
3. Hardcoded fallback — the model list shipped with the package.

Override file format:

{
  "default_model": "claude-sonnet-4-7",
  "models": [
    "claude-sonnet-4-7",
    {
      "name": "claude-opus-5",
      "description": "Latest opus model",
      "controls": [
        { "name": "effort", "kind": "choice", "choices": ["low", "high"], "default": "low" }
      ]
    }
  ]
}

Set CODING_CLI_RUNTIME_CONFIG_DIR to change the config directory (default: ~/.config/coding-cli-runtime).

Decide whether to retry a failed run

from coding_cli_runtime import classify_provider_failure

classification = classify_provider_failure(
    provider="gemini",
    stderr_text="429 Resource exhausted: rate limit exceeded",
)

if classification.retryable:
    print(f"Retryable ({classification.category}) — will retry")
else:
    print(f"Fatal ({classification.category}) — giving up")

Works for all four providers. Recognizes auth failures, rate limits, network transients, and other provider-specific error patterns.

Key types

Type	Purpose
CliRunRequest	Command spec: cmd, cwd, env, timeout, stream paths
CliRunResult	Result: returncode, stdout/stderr, duration, error code
ErrorCode	none · spawn_failed · timed_out · non_zero_exit
ProviderSpec	Provider catalog entry with models, controls, defaults
FailureClassification	Classified error with retryable flag and category

run_interactive_session() manages long-running CLI processes with timeout enforcement, process-group cleanup, transcript mirroring, and automatic retries. Only cmd_parts, cwd, stdin_text, and logger are required — observability labels like job_name and phase_tag default to sensible values so external callers don't need to invent them.

Prerequisites

This package does not bundle any CLI binaries or credentials. You must install and authenticate the relevant provider CLI yourself before using the execution helpers.

Status

Pre-1.0. API may change between minor versions.

License

MIT