Metadata-Version: 2.4
Name: haindy
Version: 0.2.0
Summary: Autonomous AI Testing Agent with multi-agent architecture
Author: Federico Keegan
License: MIT
Project-URL: Homepage, https://github.com/Haindy/haindy
Project-URL: Repository, https://github.com/Haindy/haindy
Project-URL: Issues, https://github.com/Haindy/haindy/issues
Keywords: testing,automation,ai,multi-agent,desktop-automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Testing :: Acceptance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=2.23.0
Requires-Dist: google-genai>=1.64.0
Requires-Dist: anthropic>=0.84.0
Requires-Dist: cryptography>=46.0.5
Requires-Dist: platformdirs>=4.9.2
Requires-Dist: rich>=14.3.3
Requires-Dist: pydantic>=2.12.5
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pillow>=12.1.1
Requires-Dist: numpy>=2.1.0
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: jsonlines>=4.0.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: tiktoken>=0.12.0
Requires-Dist: evdev>=1.9.3; sys_platform == "linux"
Requires-Dist: fb-idb>=1.1.7; sys_platform == "darwin"
Requires-Dist: pynput>=1.7.7; sys_platform == "darwin"
Requires-Dist: mss>=9.0.2; sys_platform == "darwin"
Requires-Dist: keyring>=25.0.0
Provides-Extra: dev
Requires-Dist: pytest==9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Requires-Dist: pytest-cov==7.0.0; extra == "dev"
Requires-Dist: black==26.1.0; extra == "dev"
Requires-Dist: isort==8.0.0; extra == "dev"
Requires-Dist: mypy==1.19.1; extra == "dev"
Requires-Dist: ruff==0.15.2; extra == "dev"
Requires-Dist: pre-commit==4.5.1; extra == "dev"
Dynamic: license-file

# HAINDY

[![CI](https://github.com/Haindy/haindy/actions/workflows/ci.yml/badge.svg)](https://github.com/Haindy/haindy/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/haindy.svg)](https://pypi.org/project/haindy/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

Computer-use for coding agents. HAINDY gives AI coding tools (Claude Code, Codex CLI, OpenCode, and others) the ability to see the screen, click, type, and test real applications across desktop, Android, and iOS.

```bash
pip install haindy
haindy setup
```

## What it does

Your coding agent calls HAINDY to interact with a live UI. Every command returns structured JSON.

```bash
haindy session new --desktop                                       # start a session
haindy act "click the Login button" --session <ID>                 # execute an action
haindy test "sign in and verify the dashboard loads" --session <ID> # dispatch a multi-step test
haindy test-status --session <ID>                                  # poll test progress / result
haindy explore "find the notification settings screen" --session <ID> # dispatch exploration
haindy explore-status --session <ID>                               # poll explore progress / result
haindy screenshot --session <ID>                                   # capture current state
haindy session close --session <ID>                                # clean up
haindy session prune --older-than 7                                # remove old dead sessions
```

Under the hood, each action goes through a computer-use AI provider (OpenAI, Google Gemini, or Anthropic Claude) that takes a screenshot, reasons about the UI, and performs real OS-level input -- mouse, keyboard, scroll -- against the actual application. No DOM hooks, no selectors, no browser automation.

### Supported platforms

| Platform | Automation method |
|----------|------------------|
| Linux/X11 | uinput + xdotool + ffmpeg |
| macOS | pynput + mss |
| Android | ADB |
| iOS | idb |

```bash
haindy session new --desktop
haindy session new --android --android-serial emulator-5554
haindy session new --ios --ios-udid <UDID>
```

## Agent integration

HAINDY ships with bundled skills that `haindy setup` installs automatically for detected AI CLIs. Once installed, your coding agent can discover and use HAINDY directly.

Supported CLIs: Claude Code, Codex CLI, OpenCode.

### act vs test vs explore

- **`act`** -- execute a single action ("click the submit button", "type hello into the search field")
- **`test`** -- dispatch a multi-step scenario with outcome validation, then poll `test-status`
- **`explore`** -- dispatch an open-ended goal, then poll `explore-status`

Use `test` whenever you care about verifying a result and can describe the scenario precisely. Use `explore` when the goal is clear but the path is not.

### Session variables

Store values your agent can reference across commands:

```bash
haindy session set USERNAME alice@example.com --session <ID>
haindy session set PASSWORD --value-file credentials.txt --secret --session <ID>
haindy session vars --session <ID>
```

## Batch mode

HAINDY also includes a pipeline of specialized AI agents that can plan and execute tests autonomously from a requirements file -- no coding agent required:

```
Requirements ──> Scope Triage ──> Test Planner ──> Situational Agent ──> Test Runner ──> Report
```

```bash
haindy run --plan requirements.txt --context context.txt
haindy run --mobile --plan requirements.txt --context context.txt    # Android
haindy run --ios --plan requirements.txt --context context.txt       # iOS
```

This produces an HTML report with screenshots, pass/fail results, and a JSONL execution log.

## Configuration

### Credentials

```bash
haindy auth login openai      # stored in system keychain
haindy auth login google
haindy auth login anthropic
haindy auth status             # verify
```

### Providers

HAINDY uses two providers independently: one for planning/analysis, one for computer-use actions.

```bash
haindy provider set openai                   # planning/analysis
haindy provider set-computer-use google      # computer-use
```

### Settings file

Create `~/.haindy/settings.json` for persistent non-secret configuration:

```json
{
  "agent": { "provider": "openai" },
  "computer_use": { "provider": "google" },
  "openai": { "model": "gpt-5.4", "computer_use_model": "gpt-5.4" },
  "google": { "model": "gemini-3-flash-preview", "computer_use_model": "gemini-3-flash-preview" },
  "anthropic": { "model": "claude-sonnet-4-6", "computer_use_model": "claude-sonnet-4-6" },
  "execution": {
    "automation_backend": "desktop",
    "actions_action_timeout_seconds": 600
  },
  "logging": { "level": "INFO" }
}
```

Environment variables override all other sources. Timeout settings use seconds. In `settings.json`, use `execution.actions_action_timeout_seconds`; the older `execution.actions_action_timeout_ms` key is only accepted as a legacy read-time alias. See [`.env.example`](.env.example) for the full list.

## Platform prerequisites

| Platform | Requirements |
|----------|-------------|
| Linux/X11 | `ffmpeg`, `xdotool`, `xclip`, `/dev/uinput` access |
| macOS | Grant Accessibility + Screen Recording to your terminal (System Settings > Privacy & Security) |
| Android | `adb` installed, device/emulator reachable |
| iOS (macOS) | `brew install idb-companion`, device paired |

`haindy doctor` checks all of these for you. See [docs/RUNBOOK.md](docs/RUNBOOK.md) for detailed setup.

## Development

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.lock
pip install -e ".[dev]"
```

```bash
ruff check .          # lint
ruff format --check . # format check
mypy haindy           # type check
pytest                # tests
```

## Architecture

| Directory | Purpose |
|-----------|---------|
| `haindy/tool_call_mode/` | Tool-call CLI, daemon, IPC, session state |
| `haindy/agents/computer_use/` | Multi-provider computer-use session orchestrator |
| `haindy/agents/` | Scope triage, test planner, situational, action, and test runner agents |
| `haindy/desktop/` | Linux/X11 automation (uinput, xdotool, ffmpeg) |
| `haindy/macos/` | macOS automation (pynput, mss) |
| `haindy/mobile/` | Android (ADB) and iOS (idb) automation |
| `haindy/config/` | Settings, env vars, settings file loader |
| `haindy/orchestration/` | Multi-agent workflow coordination |
| `haindy/monitoring/` | JSONL logging, HTML report generation |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines and how to submit changes.

## License

[MIT](LICENSE)
