liteharness 0.1.0

Portable cross-CLI agent orchestration. Hook-polled inbox, conversation discovery, task tracking.

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

pip install -e packages/liteharness

Quick Start

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

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).

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

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.

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.

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:

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