Minimal, universal, terminal-based agent queue that works alongside existing coding-agent harnesses inside Orca IDE, Herdr, and Ghostty terminal panes.
┌──────────────────────────────────────────────────────────┐
│ Harness Queue (hq) v0.1 │
│ Host: Orca IDE · Location: term_d5d8770b │
│ Target: OpenAI Codex (term_7b2d3b68) │
└──────────────────────────────────────────────────────────┘
? Select mode:
1) Auto-resume (default — press [Enter])
Resume with the built-in continuation prompt.
2) Auto-send
Queue your own prompts for automatic delivery.
› Choice [1] or enter prompt directly:
- Interactive TUI Mode (
hq --tui): Fullscreen terminal interface powered byratatuiwith live split-panel overview of queued items, real-time agent status badges (● WATCHING,⚙️ BUSY,⏳ QUOTA WAIT,✓ READY), scrollable event logs, and an interactive prompt input field. - Unified CLI (
hqorhq --cli): Callinghqorhq --cliruns the default CLI experience. Only--tuidiffers. - Infinite / Multiple Prompt Queueing: Queue prompt
#1,#2,#3... indefinitely! While the agent is working or waiting for quota resets, you can queue subsequent prompts anytime. They are dispatched automatically in FIFO order as soon as the agent becomes ready. - Image Compatibility: Seamlessly paste image paths (e.g.
@/var/folders/.../orca-paste-....png, direct file paths, or relative paths). Images are automatically detected, validated for file existence, sized, and forwarded with rich multimodal context to agents like Codex, Claude Code, and Pi.
- Terminal Auto-Detection: Works seamlessly inside Orca IDE terminal splits, Herdr panes, and Ghostty split terminals with zero manual configuration.
- Pure Open-Source CLI & IPC: Zero AppleScript, zero accessibility hacks, zero synthetic mouse movements. Built purely with native CLI and JSON-RPC APIs for full open-source portability.
- Zero Wrappers Required: Launch your agent normally (OpenAI Codex, Claude Code, OpenCode, OMP, Pi, Google Antigravity). HQ automatically discovers and pairs with the neighboring agent in the same workspace folder.
- Intuitive 0-Learning-Curve UX:
- Press
[Enter]to start Auto-resume immediately. - Or type your prompt directly to queue Prompt #1 without navigating extra menus.
- Or run
hq "your prompt"from the command line to start queueing in one step.
- Press
- Two Mutually Exclusive Modes:
- Mode 1 (Auto-resume): Predefined prompt (
"Continue the unfinished work. Inspect the session history and repository state before making changes. Do not repeat completed tasks.") dispatched automatically upon confirmed quota availability and agent readiness. - Mode 2 (Auto-send): Interactive queueing of custom prompts and images with automatic delivery when the agent becomes idle.
- Mode 1 (Auto-resume): Predefined prompt (
- Continuous FIFO Queue: HQ never exits after submitting the first prompt; it immediately accepts the next prompt so you can queue prompts while the agent works.
- Process-Pinned Safety: Automatically pins the target terminal handle and process. Prompts are never silently dispatched to replaced processes or closed panes.
- Ultra-Lightweight & Fast: Single standalone binary written in Rust with zero heavy runtime dependencies and < 5ms startup.
Choose any method to install or run hq in your terminal:
brew install --build-from-source https://raw.githubusercontent.com/Rome-NotBeepBoop/harness-queue/main/Formula/hq.rbcurl -fsSL https://raw.githubusercontent.com/Rome-NotBeepBoop/harness-queue/main/install.sh | bashcargo install --git https://github.com/Rome-NotBeepBoop/harness-queue.gitgit clone https://github.com/Rome-NotBeepBoop/harness-queue.git
cd harness-queue
# Install globally to ~/.local/bin and ~/.cargo/bin:
just install
# Or compile the standalone binary to target/release/hq:
just compileIf you have just installed, you don't even need to install hq:
# Run CLI mode directly
just
# Run interactive TUI mode directly
just tui# Launch default CLI mode
hq
# Or explicitly
hq --cli
# Launch with an initial prompt
hq "reply with 'hello'"# Launch interactive TUI mode
hq --tui
# Launch TUI with an initial prompt or image
hq --tui "@/path/to/screenshot.png fix the CSS layout"In TUI mode:
- Prompt Queue (Left): Real-time list of all queued items with status badges (
[⏳ QUEUED],[➤ SENDING],[✓ SENT]) and image tags ([🖼️ screenshot.png (142 KB)]). - Event Log (Right): Timestamped history of events (
✓ Prompt #1 sent!,◷ Waiting for Pi to finish prompt #1...,✓ Usage reset detected). - Input Field (Bottom): Type new prompts or paste image paths anytime and hit
[Enter]to enqueue. - Detach Cleanly: Press
[Esc],[Ctrl+C], or typeqto detach safely without killing the agent.
When working in terminals like Orca IDE, Herdr, or Ghostty, images can be pasted or typed directly:
› Next prompt (or image path):
@/var/folders/f3/.../orca-paste-1793100415562.png fix the alignment of this button
HQ automatically:
- Detects
@/path/to/image.pngor direct/path/to/image.pngreferences. - Validates that the file exists and computes its size (e.g.
428 KB). - Embeds the file path and multimodal context into the prompt sent to the agent.
- Displays
✓ Image attached: [🖼️ Image: orca-paste-1793100415562.png (428.1 KB)].
Supported formats: .png, .jpg, .jpeg, .gif, .webp, .svg, .bmp, .tiff, .ico.
| Terminal Environment | Detection Method | Prompt Delivery | Notes |
|---|---|---|---|
| Orca IDE | Native CLI (orca terminal) + TERM_PROGRAM=Orca |
Native IPC (orca terminal send) |
Auto-detects same-tab splits and active agent sessions. |
| Herdr | Herdr CLI (herdr pane) + HERDR_PANE_ID |
Direct agent IPC (herdr agent prompt) |
Auto-detects adjacent directional panes. |
| Ghostty | Ghostty environment + CLI window inspection | Native split pane send | macOS native split panes. |
- OpenAI Codex (
codexCLI) — Full support with structured JSON-RPC quota detection - Claude Code (
claudeCLI) - OpenCode (
opencodeCLI) - OMP (
ompCLI) - Pi (
piCLI) - Google Antigravity (
agy/antigravity)
You don't need to manually build or install any binary. Use just to run hq directly:
# Launch hq in default CLI mode
just
# Launch hq in interactive TUI mode
just tui
# Compile release binary to target/release/hq
just compile
# Install hq globally to ~/.local/bin and ~/.cargo/bin
just install
# Uninstall hq
just uninstall
# Run with an initial prompt
just run "Check tests and summarize"
# Run the test suite (58 tests)
just test
# Check lints and types
just checkMIT / Apache-2.0