harnex-cli 0.1.0

Typer CLI for running Codex or Claude coding agents against a project.

harnex-cli

harnex-cli is a Typer-based command line tool for running either the codex or claude coding agent against a local project.

The CLI does not choose a specific LLM model such as gpt-*, sonnet, or opus. In this MVP, the selectable target is the external coding agent CLI: codex or claude.

Features

• Select codex or claude as the default coding agent
• Run one-shot prompts against a project
• Open the selected agent's interactive CLI
• Mount the Typer app inside another Typer application
• Call the execution API directly from Python
• Check local prerequisites with doctor

Requirements

• Python 3.12 or newer
• codex CLI installed and authenticated
• claude CLI installed and authenticated, if you want to use Claude

The MVP intentionally runs agents with full-access permission flags:

• Codex uses --dangerously-bypass-approvals-and-sandbox
• Claude uses --permission-mode bypassPermissions

Use it in a repository or git worktree where you are comfortable letting the selected agent edit files.

Installation

From this repository:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

For development and tests:

python -m pip install -e '.[test]'

Usage

List supported agents:

harnex-cli agent list

Show the current default agent:

harnex-cli agent current

Select the default agent:

harnex-cli agent select codex
harnex-cli agent select claude

Run a one-shot prompt in the current directory:

harnex-cli run "Fix the failing tests"

Run against another project:

harnex-cli run --project /path/to/project "Update the README"

Read the prompt from stdin:

cat prompt.txt | harnex-cli run -

Override the agent for one command:

harnex-cli run --agent claude "Review this codebase"

Open the selected agent's interactive CLI:

harnex-cli open

Open an agent against another project:

harnex-cli open --project /path/to/project --agent codex

Check the environment:

harnex-cli doctor

Configuration

The default agent is stored in an OS-specific user config directory using platformdirs.

On macOS, the expected config file is:

~/.config/harnex/config.toml

Example:

default_agent = "codex"

If no config file exists, codex is used as the default agent.

For tests or isolated runs, set HARNEX_CONFIG_FILE:

HARNEX_CONFIG_FILE=/tmp/harnex-config.toml harnex-cli agent select claude

Python API

Use the Typer app from another Typer program:

from typer import Typer
from harnex_cli.app import app as harnex_app

app = Typer()
app.add_typer(harnex_app, name="harnex")

Or call the API directly:

from harnex_cli.api import run_agent, open_agent

result = run_agent(
    "Fix the failing tests",
    agent="codex",
    project_root="/path/to/project",
)

print(result.exit_code)
print(result.stdout)
print(result.stderr)

open_agent("claude", project_root="/path/to/project")

Command Behavior

harnex-cli run captures stdout and stderr from the selected agent.

Codex run command:

codex exec --cd <project_root> --dangerously-bypass-approvals-and-sandbox -

Claude run command:

claude -p --permission-mode bypassPermissions --output-format json

harnex-cli open does not capture output. It connects the selected agent CLI directly to the current terminal so the agent's interactive UI can work normally.

Development

Run tests:

python -m pytest

Current test coverage includes:

• Agent name parsing
• Command construction for Codex and Claude
• Project root validation
• Mocked subprocess execution
• Config save/load behavior
• Typer command behavior with CliRunner
• Python API request flow

MVP Boundaries

This project does not currently implement:

• Local model discovery
• Ollama or LM Studio integration
• Model-name selection UI
• A custom REPL
• A session store
• Normalized diffs across agents