harnex 0.2.0

data/skills/dispatch/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: dispatch
+description: Fire & Watch — the standard pattern for launching and monitoring harnex agent sessions. Use when dispatching implementation, review, or fix agents.
+---
+
+# Dispatch — Fire & Watch
+
+Every harnex agent dispatch follows three phases: **spawn**, **watch**, **stop**.
+
+## 1. Spawn
+
+Launch the agent in a tmux window so the user can observe it live:
+
+```bash
+harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
+  --context "Implement koder/plans/NN_name.md. Run tests when done. Commit after each phase."
+```
+
+For reviews (Claude):
+
+```bash
+harnex run claude --id cl-rev-NN --tmux cl-rev-NN \
+  --context "Review the implementation of plan NN against the spec in koder/plans/NN_name.md. Write findings to koder/reviews/NN_name.md"
+```
+
+For complex task prompts, write to a temp file and reference it:
+
+```bash
+cat > /tmp/task-impl-NN.md <<'EOF'
+Detailed instructions here...
+EOF
+
+harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
+  --context "Read and execute /tmp/task-impl-NN.md"
+```
+
+## 2. Watch
+
+Poll the agent's screen with `harnex pane`. Checking is cheap — a 20-line
+tail is a few hundred bytes.
+
+**Default: poll every 30 seconds.** This is fine for most work. The check
+itself costs almost nothing and catches completion quickly.
+
+**Progressive intervals** when you expect longer work:
+
+| Elapsed | Interval | Rationale |
+|---------|----------|-----------|
+| 0–2 min | 30s | Catch fast completions and early errors |
+| 2–10 min | 60s | Steady state for typical implementations |
+| 10+ min | 120s | Long-running work, reduce noise |
+
+```bash
+# Quick check — last 20 lines is enough to see if done or stuck
+harnex pane --id cx-impl-NN --lines 20
+
+# JSON metadata (includes capture timestamp)
+harnex pane --id cx-impl-NN --lines 20 --json
+```
+
+When checking, look for:
+- **At prompt** → agent finished, read last output for results
+- **Still working** → agent is reading files, running tests, editing code
+- **Error/stuck** → agent hit a blocker, may need intervention
+- **Permission prompt** → agent waiting for user approval, intervene
+
+### Background poll from Claude Code
+
+```bash
+# Run as a background task, check result when notified
+harnex pane --id cx-impl-NN --lines 20
+```
+
+Or use `--follow` for continuous monitoring:
+
+```bash
+harnex pane --id cx-impl-NN --lines 20 --follow
+```
+
+## 3. Stop
+
+When the agent is done (at prompt, work committed):
+
+```bash
+harnex stop --id cx-impl-NN
+```
+
+Always verify the agent's work landed before stopping:
+
+```bash
+# Quick sanity check
+harnex pane --id cx-impl-NN --lines 20
+# Confirm commits exist
+git log --oneline -5
+# Then stop
+harnex stop --id cx-impl-NN
+```
+
+## Naming Conventions
+
+| Step | ID pattern | tmux window | Example |
+|------|-----------|-------------|---------|
+| Implement | `cx-impl-NN` | `cx-impl-NN` | `cx-impl-42` |
+| Review | `cl-rev-NN` | `cl-rev-NN` | `cl-rev-42` |
+| Fix | `cx-fix-NN` | `cx-fix-NN` | `cx-fix-42` |
+| Plan write | `cx-plan-NN` | `cx-plan-NN` | `cx-plan-42` |
+| Plan fix | `cx-fix-plan-NN` | `cx-fix-plan-NN` | `cx-fix-plan-42` |
+
+**Rule**: Always use `--tmux <same-as-id>` so the tmux window name matches
+the session ID. Never use a different tmux name.
+
+## Full Dispatch Lifecycle
+
+```
+1. Mark plan IN_PROGRESS, commit
+2. harnex run codex --id cx-impl-NN --tmux cx-impl-NN
+3. Poll with harnex pane --lines 20 every 30s
+4. When done: verify commits, harnex stop
+5. harnex run claude --id cl-rev-NN --tmux cl-rev-NN (review)
+6. Poll with harnex pane --lines 20 every 30s
+7. When done: harnex stop, read review
+8. If NEEDS FIXES: harnex run codex --id cx-fix-NN (fix pass)
+9. If PASS: done
+```
+
+## Worktree Option
+
+Use worktrees only when you need **parallel isolation** — e.g., implementing
+one plan while another is being reviewed, or when the user explicitly asks.
+Do not default to worktrees for serial work.
+
+### Worktree Setup
+
+```bash
+# Commit all files the agent will need BEFORE creating the worktree
+# (untracked files don't carry over)
+git add koder/plans/NN_name.md
+git commit -m "docs(plan-NN): add plan"
+
+# Create worktree
+WORKTREE="$(pwd)/../$(basename $(pwd))-plan-NN"
+git worktree add ${WORKTREE} -b plan/NN_name master
+
+# Launch from worktree
+cd ${WORKTREE}
+harnex run codex --id cx-impl-NN --tmux cx-impl-NN \
+  --context "Implement koder/plans/NN_name.md. Run tests when done."
+```
+
+### Worktree Caveats
+
+- **cd first**: launch and manage sessions from the worktree directory
+- **Merge conflicts**: `koder/` state files may diverge — on merge, keep
+  master's versions of session-state files
+- **Cleanup**: `git worktree remove <path>` then `git branch -d plan/<branch>`
+
+## Checking Status
+
+```bash
+harnex status           # current repo sessions
+harnex status --all     # all repos
+```
+
+## What NOT to Do
+
+- **Never** launch agents with raw `tmux send-keys` or `tmux new-window`
+- **Never** use `--tmux NAME` where NAME differs from `--id`
+- **Never** pass `-- --cd <path>` to Claude sessions (unsupported flag)
+- **Never** poll with raw `tmux capture-pane` — use `harnex pane`
+- **Never** rely on `--wait-for-idle` alone — always use Fire & Watch
+- **Never** use `c-zai-dangerous` or direct CLI spawning outside harnex

data/skills/harnex/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: harnex
+description: Collaborate with other AI agents (Codex, Claude) via harnex. Use when the user asks to send a message to another agent, check agent sessions, spawn workers, relay instructions, or coordinate multi-agent work. Also activates when incoming messages contain "[harnex relay" headers.
+allowed-tools: Bash(harnex *)
+---
+
+# Harnex — Cross-Agent Collaboration
+
+If this is your first time using harnex, run `harnex guide` for the full
+getting started walkthrough, and `harnex recipes` for tested workflow patterns.
+
+Harnex wraps interactive terminal agents (Claude Code, Codex) and opens a local
+control plane so they can discover and message each other. You use it to **send
+messages to a peer agent**, **check session status**, **spawn worker sessions**,
+and **wait for them to finish**.
+
+## Detect your context
+
+Check environment variables to understand your role:
+
+| Variable | Meaning |
+|----------|---------|
+| `HARNEX_SESSION_CLI` | Which CLI you are (`claude` or `codex`) |
+| `HARNEX_ID` | Your session ID |
+| `HARNEX_SESSION_REPO_ROOT` | Repo root this session is scoped to |
+| `HARNEX_SESSION_ID` | Internal instance identifier |
+
+If these are set, you are **inside a harnex session** and can send messages to
+peer sessions or spawn new worker sessions.
+
+## Mode preference
+
+When starting another agent session for the user, default to a visible tmux
+session via `harnex run <cli> --tmux`. That is the preferred interactive mode
+because the user can watch the peer's work live.
+
+Use other modes only when the user asks for them or when visibility is not
+wanted:
+
+- prefer `--tmux` over a hidden foreground PTY for peer-agent work
+- use plain foreground `harnex run` only when the current terminal is meant to
+  become that peer's UI
+- use `--detach` only for explicitly headless/background workflows
+
+## Return channel first
+
+Before you start a peer session or send it work, decide how the result will get
+back to you.
+
+Preferred pattern when you are inside harnex:
+- Use your own `HARNEX_ID` as the return address
+- Tell the peer to send its final result back with `harnex send --id <YOUR_ID>`
+- Wait for the peer's reply; do not rely on scraping logs or tmux panes as the
+  primary way to collect the answer
+
+Fallback when you are not inside harnex:
+- Define another explicit return channel before delegating, such as a known file
+  path in the repo
+
+Do not launch a worker/reviewer without an explicit completion contract.
+
+## Two rules for every send
+
+**1. Keep messages short — use file references for long prompts.**
+Long inline prompts can stall delivery (PTY buffer limits) and break shell
+quoting. Instead, write the full task to a file and tell the peer to read it:
+
+```bash
+# Write the task to a file
+cat > /tmp/task-impl1.md <<'EOF'
+Implement phase 2 from koder/plans/03_output_streaming.md.
+... detailed instructions ...
+EOF
+
+# Send a short message pointing to it
+harnex send --id impl-1 --message "Read and execute /tmp/task-impl1.md. When done, send results back: harnex send --id $HARNEX_ID --message '<summary>'"
+```
+
+If the task is already written down (a plan file, issue, koder doc), just
+reference it directly — no need for a temp file.
+
+**2. Always tell the peer how to reply.**
+Every delegated task must include a return path. Without it, the peer finishes
+silently and you have no way to collect the result:
+
+```bash
+# Always end with the reply instruction
+harnex send --id impl-1 --message "Review src/auth.rb. When done: harnex send --id $HARNEX_ID --message '<your findings>'"
+```
+
+## Core commands
+
+### Send a message to a peer agent
+
+```bash
+harnex send --id <ID> --message "<text>"
+```
+
+- `--id` targets a specific session by its unique ID
+- `--message` is the prompt text injected into the peer's terminal
+- Message is auto-submitted (peer receives it as a prompt)
+- `--no-submit` types without pressing Enter
+- `--force` sends even if peer UI is not at a prompt (bypasses queue)
+- `--submit-only` sends only Enter (submit what's already in the input box)
+- `--wait-for-idle` blocks until the agent finishes processing (prompt→busy→prompt)
+- `--no-wait` returns immediately with a message_id (don't wait for delivery)
+- `--cli` filters by CLI type when multiple sessions share resolution scope
+
+When the target agent is busy, the message is **queued** (HTTP 202) and
+delivered automatically when the agent returns to a prompt. The sender polls
+until delivery completes using one overall `--timeout` budget (default 120s).
+
+### Atomic send+wait (recommended for orchestration)
+
+Use `--wait-for-idle` instead of separate `send` + `sleep` + `wait` commands:
+
+```bash
+# Instead of:
+harnex send --id cx-1 --message "implement the plan"
+sleep 5
+harnex wait --id cx-1 --until prompt --timeout 600
+
+# Use:
+harnex send --id cx-1 --message "implement the plan" --wait-for-idle --timeout 600
+```
+
+This eliminates the race condition where `wait --until prompt` sees the stale
+prompt state before the agent starts working. The `--timeout` budget covers
+the entire lifecycle (lookup + send + idle wait).
+
+**Multi-line messages** (when a file reference isn't practical): use a heredoc:
+
+```bash
+harnex send --id worker-1 --message "$(cat <<'EOF'
+Line one of the message.
+Line two of the message.
+EOF
+)"
+```
+
+### Check session status
+
+```bash
+harnex status            # sessions for current repo
+harnex status --all      # sessions across all repos
+```
+
+Shows live sessions with their ID, CLI, port, PID, age, and input state.
+
+### Inspect a specific session
+
+```bash
+harnex status --id <ID> --json
+```
+
+Returns JSON with input state, agent state, inbox stats, description,
+watch config, and timestamps.
+
+### Only when explicitly requested: spawn a detached worker session
+
+```bash
+# Headless (no terminal)
+harnex run codex --id impl-1 --detach -- --cd /path/to/worktree
+
+# In a tmux window (observable)
+harnex run codex --id impl-1 --tmux cx-p1 -- --cd /path/to/worktree
+```
+
+- `--detach` starts the session in the background, returns JSON with pid/port
+- `--tmux` creates a tmux window (implies `--detach`)
+- `--tmux NAME` sets a custom window title (keep names terse: `cx-p3`, `cl-r3`)
+- `--context TEXT` sets an initial prompt with session ID auto-included
+- `--description TEXT` stores a short session description in the registry/API
+- Returns immediately; use `harnex send` to inject work, `harnex wait` to block
+
+Do this only if the user explicitly asks for detached/background execution.
+
+#### Using `--context` to orient spawned agents
+
+`--context` prepends a context string as the agent's initial prompt, with the
+session ID automatically included as `[harnex session id=<ID>]`. The spawner
+decides what context to provide — harnex only adds the session ID.
+
+```bash
+# Fire-and-forget: give the task upfront
+harnex run codex --id impl-1 --tmux cx-p1 \
+  --context "Implement the feature in koder/plans/03_auth.md. Commit when done." \
+  -- --cd /path/to/worktree
+
+# Fire-and-wait: give context, then send work separately
+harnex run codex --id reviewer --tmux cx-rv \
+  --context "You are a code reviewer. Wait for instructions via harnex relay messages." \
+  -- --cd /path/to/repo
+harnex send --id reviewer --message "Review the changes in src/auth.rb"
+harnex wait --id reviewer
+```
+
+The context string is the spawner's responsibility — tailor it to the use case.
+
+### Wait for a session to exit
+
+```bash
+harnex wait --id impl-1
+harnex wait --id impl-1 --timeout 300
+```
+
+Blocks until the session process exits. Returns JSON with exit code and timing.
+Exit code 124 on timeout.
+
+## Relay headers
+
+When you send from inside a harnex session to a **different** session, harnex
+automatically prepends a relay header:
+
+```
+[harnex relay from=claude id=supervisor at=2026-03-14T12:00:00+04:00]
+<your message>
+```
+
+The peer sees this header and knows the message came from another agent. When
+you **receive** a message with a `[harnex relay ...]` header, treat it as a
+prompt from the peer agent — read the body and respond to it.
+
+Control relay behavior:
+- `--relay` forces the header even outside a session
+- `--no-relay` suppresses the header
+
+## Collaboration patterns
+
+### Reply to a peer
+
+When the user (or a relay message) asks you to reply to the other agent:
+
+```bash
+harnex send --id <TARGET_ID> --message "Your response here"
+```
+
+### Delegate work and get the answer back
+
+When you ask a peer agent to do work, include the return path in the task
+itself.
+
+Preferred when you are inside harnex:
+
+```bash
+harnex send --id reviewer --message "$(cat <<EOF
+Review the current working tree.
+
+Return your final findings to me with:
+harnex send --id $HARNEX_ID --message '<findings>'
+
+Use findings-first format with file paths and line numbers where possible.
+EOF
+)"
+```
+
+Then wait for the peer to answer you. Do not assume you can reconstruct the
+result later from detached logs or tmux capture.
+
+### Supervisor pattern
+
+Use this only when the user explicitly wants detached/background workers.
+
+A supervisor session spawns workers, sends them tasks, and waits for completion:
+
+```bash
+# Spawn workers
+harnex run codex --id impl-1 --tmux cx-p1 -- --cd ~/repo/wt-feature-a
+harnex run codex --id impl-2 --tmux cx-p2 -- --cd ~/repo/wt-feature-b
+
+# Send work and wait for completion (atomic)
+harnex send --id impl-1 --message "implement plan 150" --wait-for-idle --timeout 600
+harnex send --id impl-2 --message "implement plan 151" --wait-for-idle --timeout 600
+
+# Review phase
+harnex run claude --id review-1 --tmux cl-r1
+harnex send --id review-1 --message "review changes in wt-feature-a"
+harnex wait --id review-1
+```
+
+### File watch hook
+
+Sessions can watch a shared file (e.g. `--watch ./tmp/tick.jsonl`). When the
+file changes, harnex injects a `file-change-hook: read <path>` message. If you
+receive this hook, read the file and act on its contents.
+
+## Important rules
+
+1. **Always confirm with the user before sending** unless they explicitly asked
+   you to send a specific message. Sending injects a prompt into the peer's
+   terminal — it's an action visible to others.
+2. **Never auto-loop** relay conversations. One send per user request unless
+   told otherwise.
+3. **Check status first** if unsure whether a peer is running: `harnex status`
+4. **Use `--force` sparingly** — it bypasses the inbox queue and adapter
+   readiness checks. Can corrupt peer input if it's mid-response.
+5. **Relay headers are automatic** when sending from inside a session. Don't
+   manually prepend them.
+6. When composing a message to send, be concise and actionable — the peer agent
+   receives it as a prompt and will act on it.
+7. Do not spawn detached or tmux-backed sessions unless the user explicitly
+   asked for detached/background execution.
+8. Before delegating work, define the result return path. Prefer a reply back to
+   your own `HARNEX_ID` over logs, pane capture, or other indirect collection.

data/skills/open/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: open
+description: Open a work session in this repo — read koder/STATE.md first, inspect the current worktree, align on the active issue or plan, and establish the starting point before editing. Use when the user says "open session", "start work", "initialize", "orient yourself", or invokes "/open".
+---
+
+# Open Session Workflow
+
+When the user asks to initialize or open the session, run this sequence:
+
+## 1. Read the handoff
+
+- Read `koder/STATE.md` first
+- Note the `Current snapshot`, open issues and plans, and `Next step`
+- Open only the issue or plan files relevant to the current task
+
+## 2. Inspect the repo state
+
+- Run `git status --short`
+- Notice modified or untracked files before editing
+- Do not revert unrelated changes you did not make
+
+## 3. Establish the starting point
+
+- Summarize the important context for this session: relevant issue or plan, repo state, and the immediate next step
+- If the user already asked for implementation, continue into the work instead of stopping at orientation
+- Update `koder/STATE.md` during open only if it is clearly stale enough to mislead the session
+
+## Notes
+
+- Treat `koder/STATE.md` as the handoff document between sessions
+- Prefer updating existing issue or plan docs over creating new tracking files
+- Do NOT create issue docs unless the user explicitly asks

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: harnex
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Jikku Jose
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-31 00:00:00.000000000 Z
+dependencies: []
+description: A local PTY harness that wraps terminal AI agents (Claude, Codex) and
+  adds a control plane for discovery, messaging, and coordination.
+email:
+- jikkujose@gmail.com
+executables:
+- harnex
+extensions: []
+extra_rdoc_files: []
+files:
+- GUIDE.md
+- LICENSE
+- README.md
+- TECHNICAL.md
+- bin/harnex
+- lib/harnex.rb
+- lib/harnex/adapters.rb
+- lib/harnex/adapters/base.rb
+- lib/harnex/adapters/claude.rb
+- lib/harnex/adapters/codex.rb
+- lib/harnex/adapters/generic.rb
+- lib/harnex/cli.rb
+- lib/harnex/commands/guide.rb
+- lib/harnex/commands/logs.rb
+- lib/harnex/commands/pane.rb
+- lib/harnex/commands/recipes.rb
+- lib/harnex/commands/run.rb
+- lib/harnex/commands/send.rb
+- lib/harnex/commands/skills.rb
+- lib/harnex/commands/status.rb
+- lib/harnex/commands/stop.rb
+- lib/harnex/commands/wait.rb
+- lib/harnex/core.rb
+- lib/harnex/runtime/api_server.rb
+- lib/harnex/runtime/file_change_hook.rb
+- lib/harnex/runtime/inbox.rb
+- lib/harnex/runtime/message.rb
+- lib/harnex/runtime/session.rb
+- lib/harnex/runtime/session_state.rb
+- lib/harnex/version.rb
+- lib/harnex/watcher.rb
+- lib/harnex/watcher/inotify.rb
+- lib/harnex/watcher/polling.rb
+- recipes/01_fire_and_watch.md
+- recipes/02_chain_implement.md
+- skills/chain-implement/SKILL.md
+- skills/close/SKILL.md
+- skills/dispatch/SKILL.md
+- skills/harnex/SKILL.md
+- skills/open/SKILL.md
+homepage: https://github.com/jikkujose/harnex
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jikkujose/harnex
+  source_code_uri: https://github.com/jikkujose/harnex
+  bug_tracker_uri: https://github.com/jikkujose/harnex/issues
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key: 
+specification_version: 4
+summary: PTY harness for terminal AI agents
+test_files: []