Metadata-Version: 2.4
Name: liteharness
Version: 0.1.0
Summary: Portable cross-CLI agent orchestration. Hook-polled inbox, conversation discovery, task tracking.
Author-email: Ryan Devlin <ryan@litesuite.dev>
Maintainer-email: Ryan Devlin <ryan@litesuite.dev>
License: MIT
Project-URL: Homepage, https://litesuite.dev/liteharness
Project-URL: Documentation, https://litesuite.dev/liteharness
Project-URL: Repository, https://github.com/ahostbr/liteharness
Project-URL: Issues, https://github.com/ahostbr/liteharness/issues
Project-URL: Changelog, https://github.com/ahostbr/liteharness/blob/main/CHANGELOG.md
Keywords: ai,agents,orchestration,claude,gemini,codex,mcp,multi-agent,cli,pty
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.9
Provides-Extra: embed
Requires-Dist: onnxruntime>=1.18.0; extra == "embed"
Requires-Dist: numpy>=1.26.0; extra == "embed"
Requires-Dist: huggingface_hub>=0.23.0; extra == "embed"
Requires-Dist: tokenizers>=0.19.0; extra == "embed"
Dynamic: license-file

# LiteHarness

Portable cross-CLI agent orchestration for Claude Code, Codex, Copilot, and any CLI agent. Spawn, name, message, and programmatically control agent sessions from pure Python.

## Install

```bash
pip install -e packages/liteharness
```

## Quick Start

```bash
# Initialize (creates dirs, detects CLIs, installs hooks)
liteharness init

# Discover active agents
liteharness discover

# Send a message
liteharness send <agent-id> "fix the auth bug" --from <your-id>

# Spawn a new Claude session (visible terminal tab)
liteharness spawn --model opus --name "Recon" --prompt "review the PR"

# Spawn headless with full stdin/stdout control
liteharness pty-daemon
liteharness spawn --pty --model haiku --name "Worker"
liteharness send-input <agent-id> "/compact"
liteharness read-output <agent-id>
```

## Features

### Agent Spawning

Three modes for spawning Claude Code sessions:

| Mode     | Flag         | Visible | Stdin Control | Use Case                   |
| -------- | ------------ | ------- | ------------- | -------------------------- |
| Terminal | (default)    | Yes     | No            | Agents you want to watch   |
| PTY      | `--pty`      | No      | Full          | Automation, Karpathy loops |
| Headed   | UIAutomation | Yes     | Full          | Best of both worlds        |

### ConPTY Daemon

Headless agent control via Windows ConPTY (pywinpty). Token-authenticated TCP daemon on port 7450.

```bash
liteharness pty-daemon              # Start daemon
liteharness spawn --pty --model opus --name "Worker"
liteharness send-input <id> "/compact"   # Send slash commands
liteharness send-input <id> "fix it"     # Send prompts
liteharness read-output <id>             # Read terminal output
liteharness pty-list                     # List sessions
liteharness pty-kill <id>                # Kill session
```

**Security:** Bearer token auth, executable whitelist (claude/codex/python only), shell metachar block, agent ID validation, max 20 sessions, input length caps.

### UIAutomation (Headed Mode)

Read and write to visible Windows Terminal panes via PowerShell UIAutomation. Uses clipboard paste for atomic input (no race conditions).

```bash
liteharness wt-list-panes                        # Find windows/panes
liteharness send-input --headed <handle:pane> "text"  # Paste into terminal
liteharness read-output --headed <handle:pane>        # Read terminal buffer
```

```python
from liteharness.terminal_automation import list_panes, read_buffer, send_input

panes = list_panes()
output = read_buffer(window_handle, pane_id)
send_input(window_handle, pane_id, "/compact")  # auto-appends Enter
```

### Agent Naming

Every agent gets a deterministic two-word name derived from its UUID (e.g., SwiftRelay, IronWatch). Same UUID always produces the same name. Override with `--name`.

```bash
liteharness discover
# [active] Sentinel (fa88c542) claude-code/opus — 0s ago
# [active] PrimeFlint (b2db8be8) claude-code/opus — 7m ago
```

### Inter-Agent Messaging

Maildir-style inbox with hook-polled delivery. Agents discover each other automatically via presence files.

```bash
liteharness send <agent-id> "message" --from <your-id>
liteharness list                    # List inbox
liteharness discover                # Find active agents
```

### Hook Integration

Auto-installs hooks for supported CLIs:

- **Claude Code** — SessionStart registration, PostToolUse inbox polling
- **Codex CLI** — `codex_hooks.json` routes through Codex JSON adapters for SessionStart, PostToolUse, and UserPromptSubmit
- **Copilot CLI** — Project-level .github/hooks/
- **OpenCode / KiloCode** — Plugin-based hooks

## Commands

| Command                    | Description                                                |
| -------------------------- | ---------------------------------------------------------- |
| `init`                     | Initialize LiteHarness, detect CLIs, install hooks         |
| `status`                   | Show root, agent ID, inbox counts, active agents           |
| `send <to> <msg>`          | Send a message to another agent                            |
| `list`                     | List inbox messages                                        |
| `discover [N]`             | Discover N most recent active agents                       |
| `spawn [opts]`             | Spawn a new Claude Code session                            |
| `sessions <cmd>`           | Save/restore Claude, Codex, and Copilot terminal sessions  |
| `register`                 | Update agent presence (--agent-id, --cli, --model, --name) |
| `pty-daemon`               | Start the ConPTY daemon                                    |
| `send-input <id> <text>`   | Send text to a PTY or headed terminal                      |
| `read-output <id>`         | Read output from a PTY or headed terminal                  |
| `pty-list`                 | List active PTY sessions                                   |
| `pty-kill <id>`            | Kill a PTY session                                         |
| `wt-list-panes`            | List Windows Terminal windows/panes                        |
| `wt-focus <handle> <pane>` | Focus a specific WT pane                                   |
| `query-patterns`           | Query task patterns (BM25)                                 |
| `embed-query`              | Hybrid RAG pattern query                                   |
| `record-pattern`           | Record a task outcome pattern                              |

### Terminal Session Restore

Save and restore visible terminal agents:

```bash
liteharness sessions save morning-layout
liteharness sessions restore morning-layout
liteharness sessions restore morning-layout --layout tabs --dry-run
liteharness sessions status
liteharness sessions list
```

Restore defaults to `windows`, which opens one top-level Windows Terminal window per restored agent. Use `--layout tabs` for legacy grouped tabs or `--layout panes` for one window with split panes. Snapshots and config live under `~/.liteharness/sessions/`.

## Architecture

```
~/.liteharness/
  agents/          # Presence files (heartbeat, model, CLI)
  names/           # Name overrides (plain text, immune to clobbering)
  inbox/
    new/           # Unread messages
    cur/           # In-progress messages
    done/          # Completed messages
    tmp/           # Atomic write staging
  tasks/           # Task store
  patterns/        # Pattern learning
  pty_daemon.lock  # PTY daemon token + port
  config.json      # Global config
```

## Requirements

- Python 3.10+
- Windows 10+ (for ConPTY and UIAutomation features)
- `pywinpty` (included on Windows Python installations)
- Claude Code CLI (for spawning agents)

## License

MIT
