@jmoyers/harness 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joshua Moyers
+
+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.

package/README.md

@@ -0,0 +1,145 @@
+# Harness
+
+Harness is a terminal-native control plane for agentic coding on your local machine.
+
+Run many agent threads in parallel across `codex`, `claude`, `cursor`, `terminal`, and `critique`, while keeping each thread in project context with one fast TUI and one typed realtime API.
+
+## What You Can Do
+
+- Run many agent threads in parallel across `codex`, `claude`, `cursor`, `terminal`, and `critique`.
+- Keep native CLI ergonomics in one keyboard-first workspace.
+- Jump between threads in milliseconds, with 400+ FPS rendering under local workloads.
+- Use `critique` threads for very fast diff/review loops, with native terminal access when you need to drop to commands.
+- Keep long-running threads alive in the detached gateway so reconnects do not kill work.
+- Add automation last through the typed realtime API (`projects`, `threads`, `repositories`, `tasks`, subscriptions).
+- Plan work as scoped tasks (`project`, `repository`, `global`) and pull only `ready` tasks.
+- Gate automation globally/per-repository/per-project (enable/disable + freeze), with optional project branch pinning and project-local task focus mode.
+- See project/thread lifecycle updates from other connected clients in real time (no client restart rehydration loop).
+- Get gateway-canonical thread status icons/text for structured agent threads, plus fixed one-cell title glyphs for `terminal`/`critique` threads (single server projection, no client-side status interpretation).
+- Capture interleaved status debugging timelines (incoming status sources + outgoing status line/notice outputs) with a toggle and CLI commands.
+- Capture focused render diagnostics (unsupported control sequences + ANSI integrity failures) with a dedicated toggle and CLI commands.
+- Open a command palette with `ctrl+p`/`cmd+p`, live-filter registered actions, and execute context-aware thread/project/runtime controls.
+- Open the active project's GitHub repository from the command palette.
+- Open or create a GitHub pull request for the currently tracked non-default project branch directly from the command palette.
+
+## Demo
+
+![Harness multi-thread recording](assets/poem-recording.gif)
+
+## Quick Start
+
+### Prerequisites
+
+- Bun `1.3.9+`
+- Rust toolchain (used for the PTY helper; `bun install` auto-installs via `rustup` if missing)
+- At least one agent CLI you plan to use (`codex`, `claude`, `cursor`, or `critique`)
+
+### Install and Run
+
+```bash
+bun install
+bun link
+harness
+```
+
+Harness connects to the current gateway session (or starts it in the background).
+
+Use an isolated named session when you want separate state:
+
+```bash
+harness --session perf-a
+```
+
+## Critique Support
+
+Harness includes first-class `critique` threads:
+
+- Available in the New Thread modal.
+- Runs with `--watch` by default.
+- Auto-install path enabled by default via `bunx critique@latest` when `critique` is not installed.
+- `mux.conversation.critique.open-or-create` is bound to `ctrl+g` by default.
+
+`ctrl+g` behavior is project-aware:
+
+- If a critique thread exists for the current project, it selects it.
+- If not, it creates and opens one in the main pane.
+
+`session.interrupt` is also surfaced as a mux keybinding action (`mux.conversation.interrupt`) so teams can bind a dedicated in-client thread interrupt shortcut without overloading quit semantics.
+
+## GitHub PR Integration
+
+When GitHub auth is available (`GITHUB_TOKEN` or an authenticated `gh` CLI), Harness can:
+
+- Show `Open GitHub for This Repo` for active projects with a detected GitHub remote.
+- Detect the tracked branch for the active project and show `Open PR` (if an open PR exists) or `Create PR` only when the tracked branch is not the repository default branch.
+- Continuously sync open PR CI/check status into the control-plane store for realtime clients.
+- If auth is unavailable, PR actions fail quietly and show a lightweight hint instead of surfacing hard errors.
+
+## API for Automation
+
+Harness exposes a typed realtime client for orchestrators, policy agents, and dashboards:
+
+```ts
+import { connectHarnessAgentRealtimeClient } from './src/control-plane/agent-realtime-api.ts';
+
+const client = await connectHarnessAgentRealtimeClient({
+  host: '127.0.0.1',
+  port: 7777,
+  subscription: { includeOutput: false },
+});
+
+client.on('session.status', ({ observed }) => {
+  console.log(observed.sessionId, observed.status);
+});
+
+await client.close();
+```
+
+Key orchestration calls are available in the same client:
+
+- `client.tasks.pull(...)`
+- `client.projects.status(projectId)`
+- `client.projects.settings.get(projectId)` / `client.projects.settings.update(projectId, update)`
+- `client.automation.getPolicy(...)` / `client.automation.setPolicy(...)`
+## Configuration
+
+Runtime behavior is config-first via `harness.config.jsonc`.
+
+Example (critique defaults + hotkey override + OpenCode theme selection):
+
+```jsonc
+{
+  "critique": {
+    "launch": {
+      "defaultArgs": ["--watch"]
+    },
+    "install": {
+      "autoInstall": true,
+      "package": "critique@latest"
+    }
+  },
+  "mux": {
+    "ui": {
+      "theme": {
+        "preset": "tokyonight",
+        "mode": "dark",
+        "customThemePath": null
+      }
+    },
+    "keybindings": {
+      "mux.conversation.critique.open-or-create": ["ctrl+g"]
+    }
+  }
+}
+```
+
+`mux.ui.theme.customThemePath` can point to any local JSON file that follows the OpenCode theme schema (`https://opencode.ai/theme.json`).
+
+## Documentation
+
+- `design.md` for architecture and system design principles.
+- `agents.md` for execution and quality rules.
+
+## License
+
+MIT (`LICENSE`)

package/native/ptyd/Cargo.lock

@@ -0,0 +1,16 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "libc"
+version = "0.2.182"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6800badb6cb2082ffd7b6a67e6125bb39f18782f793520caee8cb8846be06112"
+
+[[package]]
+name = "ptyd"
+version = "0.1.0"
+dependencies = [
+ "libc",
+]

package/native/ptyd/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "ptyd"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+libc = "0.2"

package/native/ptyd/src/main.rs

@@ -0,0 +1,257 @@
+use libc::{c_char, c_int, pid_t};
+use std::ffi::CString;
+use std::io;
+use std::os::fd::RawFd;
+use std::process::ExitCode;
+use std::{mem, ptr};
+
+const OPCODE_DATA: u8 = 0x01;
+const OPCODE_RESIZE: u8 = 0x02;
+const OPCODE_CLOSE: u8 = 0x03;
+
+fn errno_code() -> Option<i32> {
+    io::Error::last_os_error().raw_os_error()
+}
+
+fn write_all_fd(fd: RawFd, mut buf: &[u8]) -> Result<(), ()> {
+    while !buf.is_empty() {
+        let written = unsafe { libc::write(fd, buf.as_ptr().cast(), buf.len()) };
+        if written < 0 {
+            if errno_code() == Some(libc::EINTR) {
+                continue;
+            }
+            return Err(());
+        }
+        let w = written as usize;
+        buf = &buf[w..];
+    }
+    Ok(())
+}
+
+fn signal_child(child_pid: pid_t, sig: c_int) {
+    let pgid = unsafe { libc::getpgid(child_pid) };
+    if pgid < 0 {
+        return;
+    }
+
+    if pgid == child_pid {
+        let _ = unsafe { libc::killpg(pgid, sig) };
+    } else {
+        let _ = unsafe { libc::kill(child_pid, sig) };
+    }
+}
+
+fn parse_and_apply_frames(incoming: &mut Vec<u8>, master_fd: RawFd, child_pid: pid_t) -> Result<(), ()> {
+    loop {
+        if incoming.is_empty() {
+            return Ok(());
+        }
+
+        match incoming[0] {
+            OPCODE_DATA => {
+                if incoming.len() < 5 {
+                    return Ok(());
+                }
+                let n = u32::from_be_bytes([incoming[1], incoming[2], incoming[3], incoming[4]]) as usize;
+                if incoming.len() < 5 + n {
+                    return Ok(());
+                }
+
+                if n > 0 {
+                    write_all_fd(master_fd, &incoming[5..5 + n])?;
+                }
+                incoming.drain(0..(5 + n));
+            }
+            OPCODE_RESIZE => {
+                if incoming.len() < 5 {
+                    return Ok(());
+                }
+
+                let cols = u16::from_be_bytes([incoming[1], incoming[2]]);
+                let rows = u16::from_be_bytes([incoming[3], incoming[4]]);
+
+                let mut ws: libc::winsize = unsafe { mem::zeroed() };
+                ws.ws_col = cols;
+                ws.ws_row = rows;
+                let rc = unsafe { libc::ioctl(master_fd, libc::TIOCSWINSZ, &ws) };
+                if rc < 0 {
+                    return Err(());
+                }
+
+                signal_child(child_pid, libc::SIGWINCH);
+                incoming.drain(0..5);
+            }
+            OPCODE_CLOSE => {
+                signal_child(child_pid, libc::SIGHUP);
+                incoming.drain(0..1);
+            }
+            _ => {
+                incoming.drain(0..1);
+            }
+        }
+    }
+}
+
+fn child_exit_code(status: c_int) -> i32 {
+    if libc::WIFEXITED(status) {
+        return libc::WEXITSTATUS(status);
+    }
+    if libc::WIFSIGNALED(status) {
+        return 128 + libc::WTERMSIG(status);
+    }
+    1
+}
+
+fn run() -> i32 {
+    let args: Vec<String> = std::env::args().skip(1).collect();
+    if args.is_empty() {
+        return 2;
+    }
+
+    let cstrings: Vec<CString> = match args
+        .iter()
+        .map(|arg| CString::new(arg.as_str()))
+        .collect::<Result<Vec<_>, _>>()
+    {
+        Ok(v) => v,
+        Err(_) => return 2,
+    };
+    let mut argv: Vec<*const c_char> = cstrings.iter().map(|s| s.as_ptr()).collect();
+    argv.push(ptr::null());
+
+    let mut master_fd: c_int = 0;
+    let mut slave_fd: c_int = 0;
+    let open_rc = unsafe {
+        libc::openpty(
+            &mut master_fd,
+            &mut slave_fd,
+            ptr::null_mut(),
+            ptr::null_mut(),
+            ptr::null_mut(),
+        )
+    };
+    if open_rc != 0 {
+        return 1;
+    }
+
+    let pid = unsafe { libc::fork() };
+    if pid < 0 {
+        unsafe {
+            libc::close(master_fd);
+            libc::close(slave_fd);
+        }
+        return 1;
+    }
+
+    if pid == 0 {
+        if unsafe { libc::setsid() } < 0 {
+            unsafe { libc::_exit(1) };
+        }
+
+        if unsafe { libc::ioctl(slave_fd, libc::TIOCSCTTY as libc::c_ulong, 0) } < 0 {
+            unsafe { libc::_exit(1) };
+        }
+
+        if unsafe { libc::dup2(slave_fd, libc::STDIN_FILENO) } < 0 {
+            unsafe { libc::_exit(1) };
+        }
+        if unsafe { libc::dup2(slave_fd, libc::STDOUT_FILENO) } < 0 {
+            unsafe { libc::_exit(1) };
+        }
+        if unsafe { libc::dup2(slave_fd, libc::STDERR_FILENO) } < 0 {
+            unsafe { libc::_exit(1) };
+        }
+
+        unsafe {
+            libc::close(master_fd);
+            libc::close(slave_fd);
+            libc::execvp(argv[0], argv.as_ptr());
+            libc::_exit(127);
+        }
+    }
+
+    unsafe {
+        libc::close(slave_fd);
+    }
+
+    let mut incoming: Vec<u8> = Vec::with_capacity(8192);
+    let mut io_buf = vec![0_u8; 65_536];
+    let mut stdin_open = true;
+
+    loop {
+        let mut status: c_int = 0;
+        let waited = unsafe { libc::waitpid(pid, &mut status, libc::WNOHANG) };
+        if waited == pid {
+            unsafe { libc::close(master_fd) };
+            return child_exit_code(status);
+        }
+
+        let stdin_fd = if stdin_open { libc::STDIN_FILENO } else { -1 };
+        let mut pfds = [
+            libc::pollfd {
+                fd: stdin_fd,
+                events: libc::POLLIN,
+                revents: 0,
+            },
+            libc::pollfd {
+                fd: master_fd,
+                events: libc::POLLIN,
+                revents: 0,
+            },
+        ];
+
+        let poll_rc = unsafe { libc::poll(pfds.as_mut_ptr(), pfds.len() as _, 100) };
+        if poll_rc < 0 {
+            if errno_code() == Some(libc::EINTR) {
+                continue;
+            }
+            unsafe { libc::close(master_fd) };
+            return 1;
+        }
+
+        if stdin_open && (pfds[0].revents & libc::POLLIN) != 0 {
+            let n = unsafe { libc::read(libc::STDIN_FILENO, io_buf.as_mut_ptr().cast(), io_buf.len()) };
+            if n == 0 {
+                stdin_open = false;
+            } else if n < 0 {
+                if errno_code() != Some(libc::EINTR) {
+                    stdin_open = false;
+                }
+            } else {
+                let n_usize = n as usize;
+                incoming.extend_from_slice(&io_buf[..n_usize]);
+                if parse_and_apply_frames(&mut incoming, master_fd, pid).is_err() {
+                    unsafe { libc::close(master_fd) };
+                    return 1;
+                }
+            }
+        }
+
+        if (pfds[1].revents & libc::POLLIN) != 0 {
+            let n = unsafe { libc::read(master_fd, io_buf.as_mut_ptr().cast(), io_buf.len()) };
+            if n == 0 {
+                let mut status2: c_int = 0;
+                let _ = unsafe { libc::waitpid(pid, &mut status2, 0) };
+                unsafe { libc::close(master_fd) };
+                return child_exit_code(status2);
+            }
+            if n < 0 {
+                if errno_code() == Some(libc::EINTR) {
+                    continue;
+                }
+                unsafe { libc::close(master_fd) };
+                return 1;
+            }
+            let n_usize = n as usize;
+            if write_all_fd(libc::STDOUT_FILENO, &io_buf[..n_usize]).is_err() {
+                unsafe { libc::close(master_fd) };
+                return 1;
+            }
+        }
+    }
+}
+
+fn main() -> ExitCode {
+    let code = run();
+    ExitCode::from((code & 0xFF) as u8)
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@jmoyers/harness",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "packageManager": "bun@1.3.9",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "scripts/build-ptyd.sh",
+    "scripts/control-plane-daemon.ts",
+    "scripts/cursor-hook-relay.ts",
+    "scripts/harness-animate.ts",
+    "scripts/harness-bin.js",
+    "scripts/harness-core.ts",
+    "scripts/harness-inspector.ts",
+    "scripts/harness.ts",
+    "native/ptyd/Cargo.lock",
+    "native/ptyd/Cargo.toml",
+    "native/ptyd/src",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "harness": "scripts/harness-bin.js"
+  },
+  "scripts": {
+    "migrate:bun": "bash ./scripts/migrate-to-bun.sh",
+    "harness": "bun scripts/harness.ts",
+    "harness:core": "bun scripts/harness-core.ts",
+    "build:ptyd": "bash ./scripts/build-ptyd.sh",
+    "postinstall": "bun run build:ptyd",
+    "codex:live": "bun scripts/codex-live.ts",
+    "codex:pty:vte:passthrough": "bun scripts/codex-pty-vte-passthrough.ts",
+    "codex:live:mux": "bun scripts/harness-core.ts",
+    "codex:live:mux:record": "bun scripts/harness-core.ts --record",
+    "codex:live:mux:client": "bun scripts/harness-core.ts --harness-server-host 127.0.0.1 --harness-server-port 7777",
+    "codex:live:mux:launch": "bun scripts/codex-live-mux-launch.ts",
+    "mux:fixture:daemon": "bun scripts/control-plane-daemon-fixture.ts",
+    "mux:fixture:launch": "bun scripts/mux-fixture-launch.ts",
+    "terminal:recording:gif": "bun scripts/terminal-recording-to-gif.ts",
+    "codex:live:tail": "bun scripts/codex-live-tail.ts",
+    "codex:live:snapshot": "bun scripts/codex-live-snapshot.ts",
+    "control-plane:daemon": "bun scripts/control-plane-daemon.ts",
+    "terminal:parity": "bun scripts/terminal-parity.ts",
+    "terminal:differential": "bun scripts/terminal-differential-checkpoints.ts",
+    "previm:passthrough": "bun run build:ptyd",
+    "vim:passthrough": "bun scripts/vim-passthrough.ts",
+    "prebenchmark:latency": "bun run build:ptyd",
+    "benchmark:latency": "bun scripts/benchmark-pty-latency.ts",
+    "perf:mux:startup": "bun scripts/perf-mux-startup-report.ts",
+    "perf:mux:selector": "bun scripts/perf-mux-selector-report.ts",
+    "perf:mux:hotpath": "bun scripts/perf-mux-hotpath-harness.ts",
+    "perf:mux:launch:startup:loop": "bun scripts/perf-mux-launch-startup-loop.ts",
+    "perf:codex:startup:loop": "bun scripts/perf-codex-startup-loop.ts",
+    "loc": "bun scripts/loc-report.ts",
+    "loc:verify": "bun scripts/check-max-loc.ts --max-loc 2000",
+    "loc:verify:enforce": "bun scripts/check-max-loc.ts --max-loc 2000 --enforce",
+    "deadcode": "bun scripts/check-dead-code.ts",
+    "coverage:check": "bun scripts/check-coverage.ts --lcov .harness/coverage-bun/lcov.info --config harness.coverage.jsonc",
+    "release": "bun scripts/release.ts",
+    "lint": "oxlint --deny-warnings --disable-unicorn-plugin -c .oxlintrc.json src test scripts packages/harness-ai/src",
+    "format": "oxfmt --config .oxfmtrc.json src test scripts packages/harness-ai/src",
+    "format:check": "oxfmt --check --config .oxfmtrc.json src test scripts packages/harness-ai/src",
+    "typecheck": "tsc --noEmit",
+    "test": "bun run build:ptyd && bun test",
+    "test:integration:codex-status": "bun scripts/integration-codex-status-sequence.ts",
+    "test:integration:codex-status:long": "bun scripts/integration-codex-status-sequence.ts --timeout-ms 180000 --prompt \"Write three short poems titled Dawn, Voltage, and Orbit. Before each poem, perform one repository inspection action and include one factual line from that action. Use at least three total tool actions and do not edit any files.\"",
+    "smoke:harness-ai": "bun scripts/harness-ai-smoke.ts",
+    "smoke:harness-ai:parity": "bun scripts/harness-ai-parity-smoke.mts",
+    "test:coverage": "bun run build:ptyd && bun test --coverage --coverage-reporter=lcov --coverage-dir .harness/coverage-bun && bun run coverage:check",
+    "verify": "bun run format:check && bun run lint && bun run typecheck && bun run deadcode && bun run test:coverage",
+    "verify:strict": "bun run verify && bun run loc:verify:enforce"
+  },
+  "devDependencies": {
+    "@ai-sdk/anthropic": "^3.0.45",
+    "@types/node": "^22.17.0",
+    "ai": "^6.0.91",
+    "oxfmt": "^0.33.0",
+    "oxlint": "^1.48.0",
+    "typescript": "^5.9.2",
+    "zod": "^4.3.6"
+  },
+  "dependencies": {
+    "@napi-rs/canvas": "^0.1.92",
+    "gifenc": "^1.0.3"
+  }
+}

package/scripts/build-ptyd.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+RUSTUP_INSTALL_URL="https://sh.rustup.rs"
+
+add_cargo_to_path() {
+  export PATH="$HOME/.cargo/bin:$PATH"
+}
+
+source_cargo_env_if_present() {
+  local env_path="$HOME/.cargo/env"
+  if [[ -f "$env_path" ]]; then
+    # shellcheck disable=SC1090
+    source "$env_path"
+  fi
+}
+
+have_cargo() {
+  command -v cargo >/dev/null 2>&1
+}
+
+print_rust_required_message() {
+  cat <<'EOF' >&2
+error: Rust toolchain is required to build the native PTY helper.
+
+Install Rust manually:
+  https://www.rust-lang.org/tools/install
+
+Or allow automatic install (default behavior):
+  bun install
+
+To disable automatic install and fail fast:
+  HARNESS_AUTO_INSTALL_RUST=0 bun install
+EOF
+}
+
+install_rustup_noninteractive() {
+  if ! command -v curl >/dev/null 2>&1; then
+    echo "error: curl is required to auto-install Rust with rustup." >&2
+    print_rust_required_message
+    exit 1
+  fi
+  echo "installing Rust toolchain via rustup..."
+  curl --proto '=https' --tlsv1.2 -sSf "$RUSTUP_INSTALL_URL" | sh -s -- -y
+}
+
+ensure_rust_toolchain() {
+  add_cargo_to_path
+  source_cargo_env_if_present
+  if have_cargo; then
+    return
+  fi
+
+  # Default to automatic rustup install for non-interactive setup flows.
+  if [[ "${HARNESS_AUTO_INSTALL_RUST:-1}" == "0" ]]; then
+    print_rust_required_message
+    exit 1
+  fi
+  install_rustup_noninteractive
+
+  source_cargo_env_if_present
+  add_cargo_to_path
+  if ! have_cargo; then
+    echo "error: Rust installation completed but cargo was not found in PATH." >&2
+    print_rust_required_message
+    exit 1
+  fi
+}
+
+ensure_rust_toolchain
+cargo build --manifest-path native/ptyd/Cargo.toml --release
+mkdir -p bin
+cp native/ptyd/target/release/ptyd bin/ptyd