TL;DR

  • Pinrail은 명령어를 실행할 수 있는 코딩 에이전트가 사람의 검토가 필요한 단계에서 멈추고, 사용자의 결정을 받아 작업을 이어가는 데스크톱 앱임.
  • macOS와 Linux에서 작동하며 Claude Code, Codex, Cursor, OpenCode 등 명령어 실행이 가능한 에이전트를 지원하고, Windows 지원은 예정 단계임.
  • 검토마다 코드 변경 사항, 이미지 등 내용에 맞춘 화면을 제공하고, 결정과 메모를 에이전트가 활용할 수 있는 Markdown 또는 JSON으로 전달함.
  • 검토 항목은 프로젝트별 받은 편지함에 모이며, 결정·폐기·철회·만료 상태를 명령어의 종료 코드로 확인할 수 있음.
  • 앱에는 다섯 가지 핵심 플러그인이 포함되며, Rust, Tauri, React 기반 데스크톱 앱과 CLI, 플러그인 SDK 및 테스트 도구로 구성됨.

Pinrail 소개

  • Pinrail은 코딩 에이전트가 작업을 수행하기 전에 사용자에게 검토를 요청하는 데스크톱 앱임. 사용자는 에이전트가 제안한 내용을 전용 화면에서 검토하고, 에이전트는 그 결정에 따라 작업을 이어감.
  • Claude Code, Codex, Cursor, OpenCode처럼 명령어를 실행할 수 있는 에이전트와 연동됨. macOS와 Linux에서 작동하며 Windows 지원은 준비 중임.
  • 초기 개발 단계이므로 다듬어지지 않은 부분과 릴리스 사이의 변경이 있을 수 있음.

도입 배경

  • 에이전트는 작업을 잘 수행하지만, 사용자 이름으로 댓글을 게시하거나 고객에게 이메일을 보내거나 프로덕션 환경을 변경하는 등 사람의 판단이 필요한 단계가 있음.
  • 채팅에서 이런 작업을 승인하려면 긴 텍스트를 읽고 답을 입력해야 하지만, Pinrail은 각 검토 상황에 맞는 전용 화면을 제공함.
  • 에이전트는 지침에 지정된 단계에서만 검토를 요청하며, 사용자가 지정하지 않은 다른 단계에서는 요청하지 않음.
  • 검토 화면은 내용에 맞춰 구성됨. 코드 검토에서는 에이전트의 의견이 표시된 변경 사항(diff)을 보여주며, 생성 이미지 검토에서는 이미지를 표시하고 변경할 부분에 상자를 그릴 수 있음.
  • 사용자의 결정은 구조화된 형태로 전달됨. 에이전트가 활용할 수 있는 Markdown이나 스크립트용 JSON으로 승인·거부 항목과 메모를 돌려줌.
  • 모든 데이터는 사용자 기기에 보관됨. 앱은 로컬 루프백 주소에서만 API를 제공하고, 검토와 결정도 로컬에 저장함.

작동 방식

  • 에이전트가 사용자 검토가 필요한 단계에 도달하면 pinrail submit 명령어를 실행하고, 사용할 플러그인과 제목, JSON 페이로드를 전달함. --wait 옵션을 사용하면 검토 결과가 나올 때까지 명령어와 에이전트가 대기함.
  • Pinrail은 사용자에게 알림을 보내고, 검토 항목을 프로젝트별 받은 편지함에 표시함.
  • 사용자는 플러그인 화면에서 검토를 결정함. 코드 검토에서는 에이전트가 제시한 각 의견을 승인하거나 거부하고, 메모를 남길 수 있음.
  • 검토 결과를 에이전트에 전달하면 명령어가 결정을 출력하고 종료되며 에이전트가 작업을 재개함. 예시에서는 src/deliver.ts:42의 재시도 지연 의견을 승인하고 src/log.ts:18의 로그 변경 의견을 거부하며, 나머지 세 항목은 미결 상태로 남음.
  • 명령어의 종료 코드는 검토가 결정됐는지, 중단 지시와 함께 폐기됐는지, 철회됐는지, 만료됐는지를 나타냄.
  • 변경을 요청하면 에이전트가 새 검토 차수를 제출하며, 앱은 이전 판단을 새 차수 옆에 표시함.

시작하기

  • 다운로드 페이지나 최신 릴리스에서 앱을 설치함. macOS 앱은 서명 및 공증을 거침.
  • 처음 실행할 때 열리는 설정 절차를 따름. 이 과정에서 pinrail 명령어가 설치되고, 컴퓨터에서 찾은 에이전트에 Pinrail 스킬이 추가되며, 권장 플러그인이 설치됨.
  • 에이전트에게 자연어로 요청해 Pinrail을 사용하도록 할 수 있음. 예를 들어 저장소에서 먼저 처리할 할 일 목록을 Pinrail로 물어보게 하거나, 프로젝트를 살펴보고 작업 전 사용자 검토가 유용한 지점을 제안하게 할 수 있음.
  • 첫 검토 안내는 시작 절차를 설명하며, 에이전트 지침 문서는 원하는 단계마다 에이전트가 검토를 요청하도록 설정하는 방법을 설명함.

플러그인

  • 검토 유형마다 에이전트가 보내는 페이로드, 사용자가 내리는 결정, 결정에 사용하는 화면을 포함하는 플러그인이 있음. 앱에는 다음 다섯 가지 핵심 플러그인이 포함됨.
  • code-review: 에이전트가 제안한 검토 의견이 포함된 변경 사항을 표시하며, 의견별 승인·거부·수정이 가능함.
  • list: 항목을 제목별로 묶어 표시하며, 항목별 승인·거부와 메모를 지원함.
  • feedback: 선택지, 예·아니요, 자유 형식 답변으로 질문에 한 번에 응답함.
  • markdown: 계획이나 명세서 같은 문서를 섹션별로 읽고 의견을 남김.
  • image: 생성 이미지 가운데 선택하고, 상자와 핀으로 변경할 부분을 표시함.
  • forgeplane/pinrail-plugins의 예제 플러그인은 HTML 페이지, 이메일, 달력, 로고, 색상 팔레트, 3D 모델, 애니메이션, 오디오, 비디오, 디자인 캔버스, 전후 비교, 거래를 다룸. 각 플러그인은 ZIP 파일로 배포되며 앱의 설정에서 설치함.

플러그인 작성

  • 플러그인은 매니페스트, JSON 스키마 두 개, HTML 화면으로 구성되며 빌드 단계가 필요하지 않음.
  • pinrail plugins new <name> 명령어로 플러그인 뼈대를 만들 수 있음. 플러그인 SDK인 pinrail-sdk는 앱 없이 브라우저에서 화면을 실행하고 Playwright로 테스트함.
  • 화면은 React, Vue, Svelte 또는 다른 프레임워크로도 만들 수 있음. 자세한 내용은 플러그인 작성 문서에서 확인할 수 있음.

저장소 구성

  • desktop/: API, 저장소, 플러그인을 포함한 Rust 코어, Tauri 셸, React UI로 구성된 앱.
  • cli/: 에이전트가 실행하는 pinrail 명령어.
  • plugins/: 핵심 플러그인.
  • sdk/: 플러그인 SDK, 개발 셸, 테스트 하네스.
  • skill/: 에이전트가 Pinrail 사용법을 익히도록 하는 스킬.
  • e2e/: 헤드리스 코어를 대상으로 CLI와 앱 UI를 검증하는 엔드투엔드 테스트.
  • docs/: 웹사이트에 게시되는 문서.
  • website/: 웹사이트.

개발

  • Node 버전은 mise.toml에 고정되며 mise install로 설정함. Rust 버전은 rust-toolchain.toml에 지정되고 rustup이 읽음.
  • mise run dev:desktop은 라이브 리로드가 적용된 앱을 실행하고, mise run test는 모든 테스트 스위트를 실행하며, mise run lint는 CI와 같이 rustfmt, clippy, 타입 검사, 라이선스 검사를 실행함.
  • CONTRIBUTING.md에는 각 테스트 스위트와 실행 방법이 설명되어 있으며, 풀 리퀘스트를 열기 전에 읽도록 안내함. 취약점은 SECURITY.md의 절차에 따라 신고함.

라이선스

  • Pinrail은 Apache License 2.0으로 배포됨. 저작권 및 서드파티 고지는 NOTICE에 있음.