Metadata-Version: 2.4
Name: harnex-cli
Version: 0.1.0
Summary: Typer CLI for running Codex or Claude coding agents against a project.
Requires-Python: >=3.12
Requires-Dist: platformdirs>=4.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# 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:

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

For development and tests:

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

## Usage

List supported agents:

```bash
harnex-cli agent list
```

Show the current default agent:

```bash
harnex-cli agent current
```

Select the default agent:

```bash
harnex-cli agent select codex
harnex-cli agent select claude
```

Run a one-shot prompt in the current directory:

```bash
harnex-cli run "Fix the failing tests"
```

Run against another project:

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

Read the prompt from stdin:

```bash
cat prompt.txt | harnex-cli run -
```

Override the agent for one command:

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

Open the selected agent's interactive CLI:

```bash
harnex-cli open
```

Open an agent against another project:

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

Check the environment:

```bash
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:

```text
~/.config/harnex/config.toml
```

Example:

```toml
default_agent = "codex"
```

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

For tests or isolated runs, set `HARNEX_CONFIG_FILE`:

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

## Python API

Use the Typer app from another Typer program:

```python
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:

```python
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:

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

Claude run command:

```bash
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:

```bash
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
