giuliastro/harness-remote

Harness Remote – A local‑first control plane for AI coding agents

What it is

• A thin “remote‑control” layer that sits on top of existing AI‑powered coding agents (Codex CLI, Claude Code, OpenCode, Oh My Pi, PI). It does not replace those agents; it merely discovers the native sessions they create and lets you observe, pause, resume, and hand‑off work across agents and machines.

Why it matters

• AI coding agents keep all the heavy‑weight context (model, tool usage, credentials, code) on your own computer. Harness Remote lets you manage those sessions from a desktop app, a web/PWA, or an Android client without ever moving the code or the provider keys to a cloud service.

Key features (as described in the README)

Feature	What you get
Native Sessions stay authoritative	The underlying agent still owns the transcript, reasoning, tool calls, and model behaviour. Harness Remote only adds a UI and coordination layer.
Cross‑agent continuation	Start a task with one agent (e.g., OpenCode), then hand it off to another (e.g., Claude) while preserving the original project identity.
Cross‑machine continuation	Continue the same project on a different computer, again keeping the original session lineage.
Local‑first security	All source code, credentials, and session data stay on your machines; the gateway can be run behind a LAN or VPN, never exposed publicly.
Discovery & capability matrix	At runtime Harness Remote queries the running agent (the “harness”) for supported models, defaults, and permissions, rather than hard‑coding them.
Multi‑platform clients	• Desktop app (Windows/macOS, Electron) – starts its own local gateway automatically.\n• Web/PWA – hosted at giuliastro.github.io/harness-remote or run locally.\n• Android – scans a QR code from the gateway to connect.
Simple installation	On the machine you want to control, install Node 20+, ensure a supported coding‑agent CLI is installed, then run npx harness-remote (or the GitHub shortcut).
Project/Workspace view	Machines → Projects → native Sessions, giving a single pane to browse all active AI coding sessions.

How you use it

1. Start a gateway on a computer that already has a coding‑agent CLI installed (npx harness-remote). The gateway detects agents, picks ports, generates temporary credentials, and runs a small daemon.
2. Connect a client – desktop, web, or Android – to that gateway (via QR code or manual address). The client shows the list of native sessions.
3. Observe or control – watch the agent’s output, send new prompts, stop a turn, answer permission requests, or create a continuation on a different agent or machine.
4. Resume later – because the native session stays with the original agent, you can close the client, shut down the gateway, and later reconnect to pick up exactly where you left off.

Supported agents (as of the README)

• OpenCode 2 (native ACP backend, still under validation)
• OpenCode Legacy (v1) – HTTP + event stream
• Claude Code – ACP adapter
• Codex CLI – ACP adapter
• Oh My Pi – ACP adapter
• PI – ACP adapter

Security notes

• The gateway should only be reachable on a trusted LAN/VPN; it is not meant to be exposed to the public internet.
• --root limits the filesystem area that appears as selectable projects, but the underlying agent still runs with the user’s normal OS permissions.

Development status

• Open‑source under Apache‑2.0.
• The repo contains a Node.js daemon, bridge tests, a web client (Vite), and an Electron desktop wrapper. Scripts for running each component are provided (npm start, npm run electron:dev, etc.).
• Documentation includes quick‑start, architecture roadmap, capability matrix, and a reliability contract for OpenCode.

Bottom line Harness Remote is a genuine, open‑source tool that adds a local‑first, multi‑device orchestration layer for existing AI coding agents, letting developers keep their code and credentials on‑premise while gaining the convenience of remote observation and cross‑agent continuity.