hyh

A CLI orchestration tool for agentic workflows. Coordinate tasks with AI agents through a daemon-based task management system.

hyh (hold your horses) provides DAG-based task orchestration with atomic state transitions, designed for coordinating claude-code and other AI agents in development workflows.

Highlights

• DAG-based orchestration - Dependency resolution with cycle detection and topological validation
• Thread-safe operations - Concurrent task claiming with atomic state transitions via mutex protection
• Client-daemon architecture - Unix socket RPC for fast, reliable inter-process communication
• Pull-based task claiming - Workers claim tasks atomically, preventing race conditions
• Command execution - Run commands with mutex protection (local or Docker runtimes)
• Git integration - Safe git operations with dangerous option validation
• Python 3.13+ / 3.14 freethreaded - Modern Python with full type annotations

Getting started

Run hyh with uvx to get started quickly:

uvx hyh status

Or start a workflow from a plan file:

uvx hyh plan import --file plan.md
uvx hyh status

Installation

Install hyh as a persistent tool:

uv tool install hyh

Or with pip:

pip install hyh

For development installation, see Contributing.

Usage

# Check daemon status
hyh ping

# Import and manage plans
hyh plan import --file plan.md
hyh status

# Claim and complete tasks
hyh task claim
hyh task complete --id task-1

# Execute commands with mutex protection
hyh exec -- make test

# Safe git operations
hyh git -- status

Requirements

• Python 3.13+ (3.14 freethreaded supported)
• macOS or Linux
• uv (recommended) or pip

Getting help

If you have questions or want to report a bug, please open an issue in this repository.

Contributing

We welcome contributions! To get started:

git clone https://github.com/pproenca/hyh.git
cd hyh
make install
make test

See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.