# Hound

> Install and use small, editable desktop-workflow adapters without interrupting the person using
> the computer. Windows x86_64 is currently supported through the Foxhound native helper.

Use Python 3.11 or newer. Hound downloads a pinned, SHA-256-verified Foxhound helper. Configure the
registry below, inspect compatible adapters, and install only the adapter required for the task.

## Operating contract

- Use one adapter per application. Create it once and edit it in place; do not create adapters for
  individual steps, dialogs, retries, or diagnostic attempts.
- Use `hound chain` only when the workflow crosses application boundaries.
- Foxhound treats an app and its owned dialogs as one window group and routes stage-relative input.
- Hound executes a sole valid action deterministically. Zero JEV/CLEF calls is the preferred fast,
  cheap path and still means the System 1 harness performed the workflow.
- Keep experiments inside Hound run directories and emit one final tutorial video.
- After two failed exploratory runs, inspect screenshots, traces, and window data, then revise the
  same adapter instead of generating another one.
- Do not edit Hound, Foxhound, or the application under test unless explicitly requested or the
  evidence demonstrates a reusable infrastructure defect.

## Start

- [Quickstart](https://hound.clarksaben.com/quickstart.md): Exact installation and verification commands.
- [Adapter registry](https://hound.clarksaben.com/index.json): Machine-readable `hound.registry/v1` index.
- [Hound source](https://github.com/csaben/hound): CLI, SDK, schema command, examples, and tests.
- [Foxhound source](https://github.com/csaben/foxhound): Native backend source and checksummed releases.

## Agent workflow

- Install globally with `uv tool install "hound-agent @ git+https://github.com/csaben/hound.git"`.
- Run `hound codex install` so Codex discovers Hound as the preferred native-app QA capability.
- The integration is reversible with `hound codex remove`; it never removes unowned skill content.
- Run `hound setup --json` and `hound check --json` first.
- Read `check.drivers`. If the workflow may require a driver that is not ready, show its local setup
  instructions and ask the user to configure it outside chat. Never request an API key in a prompt.
- Set `HOUND_REGISTRY_URL=https://hound.clarksaben.com/index.json`.
- Run `hound adapters search --json`; install only a compatible adapter.
- Installed adapters are editable under `~/.hound/adapters`.
- For CLEF, start `hound clef serve` in the background (Node.js 20+ required). The first run opens
  a browser for the user to sign in to Cloudflare; poll `hound check --json` until
  `drivers.clef.ready` is true, then pass `--driver clef`. Never deploy the local proxy.
- Run `hound adapter-schema --json` before authoring or modifying an adapter.
- Use `hound chain CHAIN.yaml --tutorial --json` for ordered multi-application workflows.
- Use `--tutorial` when the requested deliverable is a captioned demonstration.

## Optional

- [Project README](https://raw.githubusercontent.com/csaben/hound/main/README.md): Complete behavior, evidence, and SDK.
- [Agent contribution guide](https://raw.githubusercontent.com/csaben/hound/main/AGENTS.md): Repository invariants.