giuliastro/harness-remote

Harness Remote – AI 코딩 에이전트를 위한 로컬 우선 제어 플레인

개요

• 기존 AI 코딩 에이전트 (Codex CLI, Claude Code, OpenCode, Oh My Pi, PI) 위에 얹히는 가벼운 "리모컨" 계층입니다. 이러한 에이전트를 대체하는 것이 아니라, 에이전트가 만든 네이티브 세션을 발견하고 에이전트와 머신 간에 작업을 관찰, 일시 중지, 재개, 인계할 수 있게 합니다.

중요성

• AI 코딩 에이전트는 무거운 컨텍스트 (모델, 도구 사용, 자격 증명, 코드)를 모두 자신의 컴퓨터에 유지합니다. Harness Remote를 사용하면 데스크톱 앱, 웹/PWA 또는 Android 클라이언트에서 이러한 세션을 관리할 수 있으며 코드나 공급자 키를 클라우드 서비스로 옮길 필요가 없습니다.

주요 기능 (README에 설명된 대로)

기능	제공 내용
네이티브 세션의 권위 유지	기본 에이전트가 트랜스크립트, 추론, 도구 호출, 모델 동작을 계속 소유합니다. Harness Remote는 UI와 조정 계층만 추가합니다.
에이전트 간 연속성	한 에이전트 (예: OpenCode)로 작업을 시작한 다음 원래 프로젝트 ID를 유지하면서 다른 에이전트 (예: Claude)로 인계합니다.
머신 간 연속성	다른 컴퓨터에서 동일한 프로젝트를 계속하고 원래 세션 계보를 유지합니다.
로컬 우선 보안	모든 소스 코드, 자격 증명, 세션 데이터는 사용자 머신에 유지됩니다. 게이트웨이는 LAN 또는 VPN 뒤에서 실행할 수 있으며 공개적으로 노출되지 않습니다.
발견 및 기능 매트릭스	런타임에 Harness Remote는 실행 중인 에이전트 ("하네스")에게 지원되는 모델, 기본값, 권한을 하드코딩하지 않고 질의합니다.
멀티 플랫폼 클라이언트	• 데스크톱 앱 (Windows/macOS, Electron) – 자체 로컬 게이트웨이를 자동으로 시작합니다.\n• 웹/PWA – giuliastro.github.io/harness-remote에서 호스팅되거나 로컬로 실행됩니다.\n• Android – 게이트웨이에서 QR 코드를 스캔하여 연결합니다.
간단한 설치	제어하려는 머신에 Node 20+를 설치하고 지원되는 코딩 에이전트 CLI가 설치되어 있는지 확인한 다음 npx harness-remote (또는 GitHub 바로 가기)를 실행합니다.
프로젝트/워크스페이스 보기	머신 → 프로젝트 → 네이티브 세션 순으로 표시되어 활성 AI 코딩 세션을 한 창에서 모두 찾아볼 수 있습니다.

사용 방법

1. 게이트웨이 시작 – 코딩 에이전트 CLI가 이미 설치된 컴퓨터에서 실행합니다 (npx harness-remote). 게이트웨이는 에이전트를 감지하고 포트를 선택하고 임시 자격 증명을 생성하고 작은 데몬을 실행합니다.
2. 클라이언트 연결 – 데스크톱, 웹 또는 Android 클라이언트를 해당 게이트웨이에 연결합니다 (QR 코드 또는 수동 주소). 클라이언트에 네이티브 세션 목록이 표시됩니다.
3. 관찰 또는 제어 – 에이전트 출력을 보고, 새 프롬프트를 보내고, 턴을 중지하고, 권한 요청에 응답하거나 다른 에이전트나 머신에서 연속 작업을 만듭니다.
4. 나중에 재개 – 네이티브 세션이 원래 에이전트에 유지되므로 클라이언트를 닫고, 게이트웨이를 종료하고, 나중에 다시 연결하여 중단한 지점에서 정확히 다시 시작할 수 있습니다.

지원되는 에이전트 (README 기준)

• OpenCode 2 (네이티브 ACP 백엔드, 아직 검증 중)
• OpenCode Legacy (v1) – HTTP + 이벤트 스트림
• Claude Code – ACP 어댑터
• Codex CLI – ACP 어댑터
• Oh My Pi – ACP 어댑터
• PI – ACP 어댑터

보안 참고 사항

• 게이트웨이는 신뢰할 수 있는 LAN/VPN에서만 접근할 수 있어야 하며 공개 인터넷에 노출되지 않아야 합니다.
• --root는 선택 가능한 프로젝트로 표시되는 파일 시스템 영역을 제한하지만 기본 에이전트는 여전히 사용자의 일반 OS 권한으로 실행됩니다.

개발 상태

• Apache-2.0 라이선스의 오픈 소스.
• 리포지토리에는 Node.js 데몬, 브리지 테스트, 웹 클라이언트 (Vite), Electron 데스크톱 래퍼가 포함되어 있습니다. 각 구성 요소를 실행하는 스크립트가 제공됩니다 (npm start, npm run electron:dev 등).
• 문서에는 빠른 시작, 아키텍처 로드맵, 기능 매트릭스, OpenCode에 대한 안정성 계약이 포함되어 있습니다.

결론 Harness Remote는 기존 AI 코딩 에이전트에 로컬 우선, 다중 장치 오케스트레이션 계층을 추가하는 진정한 오픈 소스 도구로, 개발자는 코드와 자격 증명을 온프레미스로 유지하면서 원격 관찰과 에이전트 간 연속성의 편의를 얻을 수 있습니다.