harnex 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 814a587579199179b2b9fcd64b512c45c60ce06904834b9b7caac62e193b9306
+  data.tar.gz: 6f16ba96dc5e7dfb2fd08d99908b1a1dad4d373c0e47a395a1f3e1a62edb0705
+SHA512:
+  metadata.gz: f61b445033ab07d79b42695c91089d07a3050cb0cf9a51c8c6ef46259bf22bc48f7a5867332ac1609f09ae0a1dc28b9484ae8a0fee2cc85941e69b17ced30c84
+  data.tar.gz: 7f502e09fd03fd6608fbd81fee346aa0ecaeea15e908b0a5114f38a0c4c5fb45ac4d3f327f106a45c6aac69a69de9684686bb9a054b32c6f626068b2fabbcdb3

data/GUIDE.md

@@ -0,0 +1,242 @@
+# Getting Started with Harnex
+
+You've installed harnex. Here's how to actually use it.
+
+## Recommended mental model
+
+Treat harnex as a local supervisor harness, not as a conversation
+bus between agents.
+
+- Start a fresh worker for each step, usually with `--tmux`
+- Send one clear task, often by pointing the worker at a file
+- Use `--wait-for-idle` as a fence, then inspect with `harnex pane`
+- Ask the worker to write its output to a file when the next step
+  needs structured input
+- Stop the worker when that step is done
+
+For multi-step flows, chain fresh workers with file handoffs:
+Codex writes a plan, another Codex implements it, Claude reviews it,
+another Codex fixes it.
+
+## Your first session
+
+Start an agent the way you normally would, but through harnex:
+
+```bash
+harnex run codex
+```
+
+The agent looks and works exactly the same. Harnex runs alongside
+it — registering the session, listening for messages, and tracking
+whether the agent is busy or idle.
+
+Give it a name so other sessions can find it:
+
+```bash
+harnex run codex --id worker
+```
+
+## Sending messages
+
+From another terminal:
+
+```bash
+harnex send --id worker --message "implement the auth module"
+```
+
+If the agent is busy, the message queues and delivers
+automatically when the agent is ready. You don't have to wait
+or retry. Queueing exists, but the default workflow should still be
+one task per fresh worker.
+
+## Seeing what's running
+
+```bash
+harnex status
+```
+
+Shows all live sessions for the current repo with their ID, CLI
+type, age, and state (prompt/busy).
+
+## Running agents in tmux
+
+This is the recommended way to run multiple agents. Each one gets
+its own tmux window you can switch to anytime:
+
+```bash
+harnex run codex --id impl --tmux
+harnex run claude --id review --tmux
+```
+
+Switch between them with your normal tmux keys (`Ctrl-b n`,
+`Ctrl-b p`, or `Ctrl-b w` to pick from a list). This is the
+easiest way to monitor what each agent is doing — you see exactly
+what you'd see if you were running it directly.
+
+For longer-running work, `harnex pane` lets you peek at an
+agent's screen without switching windows:
+
+```bash
+harnex pane --id impl --lines 30
+```
+
+Or watch it live from your current terminal:
+
+```bash
+harnex pane --id impl --follow
+```
+
+## Sending work and waiting for it to finish
+
+Use `--wait-for-idle` to block until the agent finishes
+processing:
+
+```bash
+harnex send --id impl --message "implement the plan" --wait-for-idle --timeout 600
+```
+
+This is better than separate send + wait commands because there's
+no gap where you might check too early and think the agent is
+done when it hasn't started yet.
+
+Treat `--wait-for-idle` as the fence, not the report. After the
+send returns, use `harnex pane` or `harnex logs` to inspect what
+actually happened.
+
+## Sending large prompts
+
+PTY buffers and shell quoting don't love multi-kilobyte inline
+messages. For anything longer than a few sentences, write the
+task to a file and tell the agent to read it:
+
+```bash
+cat > /tmp/task-impl.md <<'EOF'
+Implement phase 2 from koder/plans/03_output_streaming.md.
+
+Focus on:
+- The HTTP endpoint for streaming output
+- Integration with the existing ring buffer
+- Tests for the new endpoint
+
+Do not modify the CLI commands.
+EOF
+
+harnex send --id impl --message "Read and execute /tmp/task-impl.md"
+```
+
+If the task is already written down — a plan file, an issue, a
+spec — just point to it:
+
+```bash
+harnex send --id impl --message "Implement koder/plans/plan_09_atomic_send_wait.md"
+```
+
+This is more reliable, easier to debug (you can read the file to
+see exactly what was sent), and avoids quoting headaches.
+
+## Capturing results
+
+For dependable multi-step work, prefer file handoffs over reply
+messages.
+
+Examples:
+
+```bash
+# Planning
+harnex send --id plan --message "Read koder/issues/13_atomic_send_wait.md and write a plan to /tmp/plan-13.md. Do not change code." --wait-for-idle --timeout 600
+
+# Review
+harnex send --id review --message "Review the current changes against /tmp/plan-13.md and write findings to /tmp/review-13.md. If clean, say so explicitly." --wait-for-idle --timeout 600
+```
+
+Why files work better:
+
+- The next worker can read exactly the same artifact you reviewed
+- The supervisor can inspect the artifact without scraping terminal text
+- If the session dies, the output still exists
+
+After the worker finishes, inspect the screen:
+
+```bash
+harnex pane --id review --lines 60
+```
+
+Optional: if you're inside a harnex-managed session yourself and
+really want a callback, you can still use `$HARNEX_ID` as the return
+address. Treat that as secondary, not the main control flow.
+
+## Stopping agents
+
+```bash
+harnex stop --id impl
+```
+
+This sends the agent's native exit sequence (e.g. `/exit` for
+Codex). The agent shuts down cleanly.
+
+## A reliable supervised workflow
+
+Use fresh instances for each stage. Codex plans and implements.
+Claude only reviews.
+
+```bash
+# 1. Plan with Codex
+harnex run codex --id cx-plan-13 --tmux
+harnex send --id cx-plan-13 --message "Read koder/issues/13_atomic_send_wait.md and write a concrete implementation plan to /tmp/plan-13.md. Do not change code." --wait-for-idle --timeout 600
+harnex pane --id cx-plan-13 --lines 60
+harnex stop --id cx-plan-13
+
+# 2. Implement with a fresh Codex
+harnex run codex --id cx-impl-13 --tmux
+harnex send --id cx-impl-13 --message "Read /tmp/plan-13.md, implement it, run tests, and write a short summary to /tmp/impl-13.md." --wait-for-idle --timeout 1200
+harnex pane --id cx-impl-13 --lines 80
+harnex stop --id cx-impl-13
+
+# 3. Review with a fresh Claude
+harnex run claude --id cl-rev-13 --tmux
+harnex send --id cl-rev-13 --message "Review the current changes against /tmp/plan-13.md. Write findings to /tmp/review-13.md. If there are no issues, say clean." --wait-for-idle --timeout 900
+harnex pane --id cl-rev-13 --lines 80
+harnex stop --id cl-rev-13
+```
+
+If the review finds issues, spawn another fresh Codex worker and tell
+it to read `/tmp/review-13.md`, fix the findings, run tests, and write
+an updated summary. Then review again with a fresh Claude instance.
+
+## Teaching your agents about harnex
+
+Harnex ships a skill file that tells AI agents how to use harnex
+commands. To make it available globally:
+
+```bash
+# For Claude Code
+ln -s /path/to/harnex/skills/harnex ~/.claude/skills/harnex
+
+# For Codex
+ln -s /path/to/harnex/skills/harnex ~/.codex/skills/harnex
+```
+
+After this, any Claude or Codex session — in any repo — can use
+harnex commands without being taught how. The skill activates
+automatically when agent collaboration is needed.
+
+## Recipes
+
+Tested workflows for common multi-agent patterns. Read them
+from the CLI:
+
+```bash
+harnex recipes             # list all recipes
+harnex recipes show 01     # read one
+```
+
+- **Fire and Watch** (`harnex recipes show 01`) — send work to a
+  fresh worker, watch its tmux screen, capture the result, stop it.
+- **Chain Implement** (`harnex recipes show 02`) — process a
+  batch as repeated fire-and-watch: Codex plan/implement,
+  Claude review, Codex fix, then review again if needed.
+
+## What's next
+
+For the full command reference, flags, HTTP API, and internals,
+see [TECHNICAL.md](TECHNICAL.md).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jikku Jose
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,119 @@
+# Harnex
+
+Run multiple AI coding agents from your terminal and coordinate them.
+
+Harnex wraps Claude Code and OpenAI Codex (or any terminal CLI) in a
+local harness so you can launch agents, send them tasks, watch their
+screens, and stop them cleanly — all from the command line.
+
+```bash
+gem install harnex
+```
+
+Requires **Ruby 3.x**. No other dependencies.
+
+## What it does
+
+```bash
+# Start an agent in tmux
+harnex run codex --id planner --tmux
+
+# Send it a task and wait for it to finish
+harnex send --id planner --message "Write a plan to /tmp/plan.md" --wait-for-idle
+
+# Peek at what it's doing
+harnex pane --id planner --lines 30
+
+# Stop it
+harnex stop --id planner
+```
+
+That's the core loop. Start a fresh agent for each step, hand it one
+job, watch it work, stop it when done.
+
+## Why use this
+
+- **You want agents to plan, implement, review, and fix — in sequence.**
+  Codex writes code. Claude reviews it. Another Codex fixes the review
+  findings. Each step is a fresh agent with clean context.
+
+- **You want to see what agents are doing.** `harnex pane` shows
+  the agent's live terminal. No black boxes.
+
+- **You don't want to babysit.** Send a task with `--wait-for-idle`,
+  walk away, check back when it's done.
+
+- **You want local-only orchestration.** Everything runs on your
+  machine. No cloud services, no API keys beyond what the agents need.
+
+## When you wouldn't use this
+
+- You only use one agent at a time (just run it directly)
+- You need cloud-hosted orchestration
+- Your agents aren't terminal-based
+
+## Supported agents
+
+| Agent | Support |
+|-------|---------|
+| Claude Code | Full (prompt detection, stop sequence, vim mode) |
+| OpenAI Codex | Full (prompt detection, stop sequence) |
+| Any terminal CLI | Generic wrapping (everything works except smart prompt detection) |
+
+## Multi-agent workflows
+
+The real power is chaining agents together:
+
+```bash
+# 1. Codex writes a plan
+harnex run codex --id cx-plan --tmux
+harnex send --id cx-plan --message "Plan the auth module, write to /tmp/plan.md" --wait-for-idle
+harnex stop --id cx-plan
+
+# 2. Fresh Codex implements the plan
+harnex run codex --id cx-impl --tmux
+harnex send --id cx-impl --message "Implement /tmp/plan.md, run tests" --wait-for-idle
+harnex stop --id cx-impl
+
+# 3. Claude reviews the implementation
+harnex run claude --id cl-review --tmux
+harnex send --id cl-review --message "Review changes against /tmp/plan.md, write /tmp/review.md" --wait-for-idle
+harnex stop --id cl-review
+```
+
+Harnex ships workflow skills that automate this pattern:
+
+- **[Dispatch](skills/dispatch/SKILL.md)** — the fire-and-watch pattern:
+  spawn an agent, poll its screen, stop it when done
+- **[Chain Implement](skills/chain-implement/SKILL.md)** — end-to-end
+  issue-to-code workflow: plan, review plan, implement, review code, fix
+
+Install skills into your repo so agents can use them:
+
+```bash
+harnex skills install dispatch chain-implement
+```
+
+## All commands
+
+| Command | What it does |
+|---------|-------------|
+| `harnex run <cli>` | Start an agent (`--tmux` for a visible window, `--detach` for background) |
+| `harnex send --id <id>` | Send a message (queues if busy, `--wait-for-idle` to block until done) |
+| `harnex stop --id <id>` | Send the agent's native exit sequence |
+| `harnex status` | List running sessions (`--json` for full payloads) |
+| `harnex pane --id <id>` | Capture the agent's tmux screen (`--follow` for live) |
+| `harnex logs --id <id>` | Read session transcript (`--follow` to tail) |
+| `harnex wait --id <id>` | Block until exit or a target state |
+| `harnex guide` | Getting started walkthrough |
+| `harnex recipes` | Tested workflow patterns |
+| `harnex skills install` | Install bundled skills for Claude/Codex |
+
+## Going deeper
+
+- [GUIDE.md](GUIDE.md) — getting started walkthrough with examples
+- [TECHNICAL.md](TECHNICAL.md) — full command reference, flags, HTTP API, architecture
+
+## License
+
+[MIT](LICENSE)