CUELO — AI Coding Agent Workspace & Harness for omp (oh-my-pi)

CUELO is an open-source AI coding agent workspace and harness for omp (oh-my-pi).

Use the same ~/.omp/agent sessions, credentials and model configuration from the terminal and browser. The web workspace provides session management, model configuration, skills, worktrees, usage views and PWA access. The public harness provides multi-agent orchestration and model-routing rules; some integrations require separately configured services, as detailed below.

한국어: CUELO는 omp(oh-my-pi)를 위한 오픈소스 AI 코딩 에이전트 작업 공간이자 하네스입니다. 웹 앱은 omp SDK를 서버 안에서 실행하고, omp CLI와 같은 ~/.omp/agent 디렉터리를 씁니다. 터미널에서 하던 세션을 브라우저에서 이어 가고, 다시 터미널로 돌아가도 기록·계정·모델 설정을 공유합니다.

내장 OMP 코어는 18.12.3입니다. 별도로 설치한 omp CLI의 버전은 웹 업데이트와 독립적이며, 앱에 포함된 CLI를 omp 명령으로 사용하는 설치에서는 웹과 같은 코어를 사용합니다.

문서 하네스는 기존 Word·Excel·PowerPoint 문서를 열고 편집하거나 변환할 때 LibreOffice를 우선 사용합니다. 원본은 보존하고 출력 결과를 확인하며, 매크로·전용 기능·서식 호환성이 필요하거나 사용자가 지정하면 MS Office를 사용합니다.

장기 백그라운드 작업은 관측 기한이 되면 대기를 깨워 상태를 확인하게 합니다. 이미 끝난 결과는 먼저 회수하며, 작업을 자동으로 취소하거나 재실행하지 않습니다. 하네스 안내에 적용 범위와 확인 방법이 있습니다.

소스가 없는 .NET 어셈블리와 JavaScript/Electron 배포물은 REA 선택 연결 안내에 따라 정적으로 조사할 수 있습니다. Linux에서 기존 MCP 연결·도구 상속·제한 세션 동작을 검증했으며, 프로젝트별 등록은 승인 뒤에만 수행합니다. Windows REA 호환성은 아직 확인하지 않았습니다.

CUELO의 목적은 작업 중 확인한 실패와 막힘을 기억·작업 규칙·실행 절차에 반영해, 사람이 같은 문제를 다시 지적하지 않아도 다음 작업에서 실수를 줄이는 것입니다. 원인을 확인하고 필요한 부분만 바꾸며, 다음 작업에서 적용과 효과를 확인하는 것까지를 지향합니다. 기록을 저장했다는 이유만으로 자동 개선이 끝났다고 보지는 않습니다.

작업 규칙은 추가 개선을 제안할 때 해결할 실제 실패, 가장 작은 수정이라고 판단한 이유, 관측 가능한 완료 기준을 먼저 설명하도록 정합니다. 근거가 빠진 개선은 구현을 보류하며, 테스트 통과와 사용자 환경의 실제 동작 확인은 구분합니다.

세션은 관련 작업을 시작할 때 미결 항목과 미해결 실패를 현재 근거로 분류하고, 이미 승인된 범위 안의 실행 가능한 일만 원인 확인·처리·재검증한 뒤 문서를 맞춥니다. 막힌 실패는 증거와 재검증 기준을 HANDOFF.md에 남겨 다음 관련 세션이 이어받습니다. 백그라운드에서 스스로 고치는 기능은 아닙니다. 자세한 내용은 하네스 안내를 참고하세요.

WSL에서 작업하는 프로젝트에 기존 Windows 사본이 연결되어 있으면, 작업 완료 후 검증·게시한 소스와 문서를 Windows 사본에도 같은 커밋으로 반영합니다. Windows에 별도로 남은 변경이나 갈라진 이력은 덮어쓰지 않고 알립니다. 실시간 양방향 동기화는 아니며, 설치된 프로필·인증정보·실행 산출물·독립 CLI는 복사하지 않습니다. Windows 전용 장비 프로젝트는 기존 위치와 도구를 유지합니다.

Anthropic 구독 계정이 모두 주간 한도에 닿으면, 미리 둔 예비 API 키로 요청을 이어 갈 수 있습니다. 5시간 한도만 찬 경우에는 지금처럼 리셋을 기다리고, 주간 한도가 리셋되면 다시 구독 계정을 씁니다. 키는 폴백할 때만 읽고 에이전트가 실행하는 셸에는 넘기지 않습니다. 키를 두는 위치와 조건은 하네스 안내에 있습니다.

문서가 없는 프로젝트에서 처음 소스를 커밋하면, 커밋 결과에 그 프로젝트의 인계 문서와 작업 기록을 만들라는 알림이 붙습니다. 알림만 표시하고 커밋을 막지는 않습니다.

주제별로 저장한 교훈을 정정하면 최초 기록과 최신 정정의 출처를 구분해 조회할 수 있습니다. 회상 목록에도 확인 가능한 전역·프로젝트 범위와 정정 정보를 표시합니다. 기억은 현재 요청과 저장소의 적용 조건을 대조하는 참고 자료이며 실행 승인을 대신하지 않습니다. 이전 교훈 본문을 별도 이력으로 쌓지는 않습니다. 자세한 보존 범위는 하네스 안내를 참고하세요.

교훈의 근거 파일명이나 제목에 비밀 토큰 형태의 문자열이 있으면 저장 전에 거절합니다. 거절된 정정은 기존 기억을 바꾸지 않습니다.

이전 세션이나 압축 전 대화에서 빠진 사용자 지시·정정은 원문 회수 도구로 다시 확인할 수 있습니다. 현재 프로젝트와 각 세션의 선택된 분기를 기준으로 찾으며, 보관 세션·다른 프로젝트는 명시한 경우에만 포함합니다. 검색 한도에 걸리면 결과가 일부임을 표시하고, 원문을 읽기만 하며 현재 승인으로 되살리지 않습니다.

하네스의 일반 비-UI 작업은 구성된 구현 후보 가운데 과제의 남은 판단과 검증 방법에 맞는 후보를 추천합니다. 한도 소진 때만 다른 후보를 쓰는 방식은 아니며, 근거가 부족하면 기존 기본값을 유지합니다. 추천은 Main의 선택을 돕는 정보이고 진행 중인 담당자의 모델을 바꾸지 않습니다.

컨텍스트 창과 압축 시작점은 따로 관리합니다. 실제 요청·압축 뒤 재탐색·보고 비용을 근거로 설정을 조정하고, 누락된 값은 미상으로 남기는 운영을 따릅니다. 외부 사례의 절감률을 보장하지 않으며 압축 뒤 기존 결정과 검증 증거를 이어받습니다. 설정과 해석은 하네스 안내를 참고하세요.

작업을 시작할 때 회상된 교훈과 현재 요청의 적용 조건·예외·충돌을 점검해 에이전트에게 참고 안내를 제공합니다. 같은 입력은 반복 점검하지 않으며, 판단이 불명확하거나 점검에 실패해도 작업을 막지 않습니다. 현재 지시와 승인 범위가 우선입니다.

Keywords: AI coding agent · agent harness · multi-agent orchestration · omp · oh-my-pi · model routing · developer tools

이 저장소로 되는 것과 따로 필요한 것

구분	내용
앱·런타임 설치 뒤 동작	세션 탐색·실시간 대화·분기/fork, 모델 역할, provider·플러그인·스킬 관리, 파일 미리보기, 비밀번호 잠금, 캐릭터 알림 등. 대화에는 별도 제공자 인증이 필요합니다
사용자가 준비할 것	Node.js·Bun과 자신의 모델 제공자 계정·모델 선택. 소스 checkout/전체 Git 기능에는 Git(Windows는 Git for Windows)도 필요합니다. 인증정보·세션·설정은 사용자의 로컬 ~/.omp/agent에 저장합니다
로컬 사이드카 (공개)	계정 사용량 카드, 사이드 챗(/btw), SubAgent 아카이브의 실행 소스도 포함합니다. start가 앱과 함께 실행합니다. usage의 CLI fallback·stats에는 별도 omp CLI가 필요합니다
OMP 하네스 (공개)	Main/Maker 역할 분담, 발주·검수 계약, task guard, 판단 라우팅(Jev), 캐릭터 말투, 명령 가드의 규칙·SOP·확장과 앱 SDK core 패치입니다. setup으로 설치합니다. 하네스 안내에 Jev의 외부 자격 경계가 있습니다
포함하지 않는 것	개발자의 로그인 정보·API 키·개인 계정 및 모델 설정·개인 skill·대화와 작업 기록·PC별 운영 자료. 공개 설치는 필요한 비개인 운영 기본값만 제공하고 모델은 사용자가 고릅니다

CUELO에서 할 수 있는 것

세션과 대화

• 프로젝트별로 지난 omp 세션을 찾아 이어 가고, 실시간으로 스트리밍되는 대화에서 도구 호출·비용·컨텍스트 사용량을 봅니다.
• 이전 메시지에서 갈래를 나누거나(세션 안 분기), 별도 세션으로 fork합니다.
• 작업 공간(프로젝트·worktree)을 바꾸면 그곳에서 마지막으로 열어 둔 세션으로 돌아갑니다.
• goal 모드의 자동 이어 가기와 todo 진행 상황을 대화창 위에서 확인합니다. 실행을 취소하면 자동 이어 가기가 멈추며, 일시정지된 목표는 /goal resume으로 재개합니다.
• 실행 중에 Steer로 지시를 바꾸면, 도구 호출이 없는 모델 요청은 서버의 전환 신호를 기다리지 않고 새 지시로 다시 요청합니다. 이미 보인 답변은 유지하며, 재요청에 따라 사용량이 늘 수 있습니다.
• 작업 로그 패널에서 이번 턴의 과정 항목과 턴마다 쓴 파일을 따로 봅니다. 도구 실행은 한 줄로 접혀 실행 중·완료·실패(종료 코드 포함)가 구분되고, 실패한 실행만 펼쳐진 채 나옵니다. 편집은 추가·삭제 줄 수만 보이다가 누르면 변경 내용이 열립니다.
• 입력창에 이미지·문서 외에 음성(받아쓰기), 코드·설정 파일(본문 첨부), 그 밖의 파일(저장 후 경로 첨부)을 붙여넣기·드롭·선택으로 넣습니다. 저장형 첨부는 기본 파일당 100MB이며 설정에서 한도를 바꿀 수 있습니다. 큰 음성은 처리 계획과 계정 사용량 안내를 확인한 뒤 압축·분할 전사를 시작합니다. 음성 받아쓰기는 Google Antigravity 계정이 필요합니다. 대화·분기·초안에서 사용 중인 파일은 보존하고, 미사용이 확인된 첨부만 7일 유예 후 자동 정리합니다. 첨부와 자동 정리 안내를 확인하세요.
• 에이전트가 생성하거나 확인한 이미지와 eval 셀이 출력한 그림이 그 턴의 대화 흐름에 썸네일로 보이고, 누르면 크게 열립니다.
• Ctrl+K 팔레트로 대화 내용을 검색해 해당 메시지로 이동합니다. 압축으로 사라진 과거 메시지는 제외하고, 현재 볼 수 있는 메시지를 세션당 최대 3건 보여 줍니다. 긴 대화 안에서는 Ctrl+F로 찾고, 오른쪽 질문 레일로 내가 한 질문 사이를 오갑니다.
• 서버나 PC가 갑자기 꺼지면, 복구 대상인 진행 중 대화를 서버 재시작 뒤 자동으로 이어갑니다. 사용자 답변·승인을 기다리던 대화와 이전 버전의 기록은 자동으로 재개하지 않으며, 이어지지 않은 대화에는 중단 알림을 표시합니다. 컨텍스트 압축 중에는 경과 시간을 표시합니다.
• 모델 선택기 맨 위에 자주 고른 모델이 나오고, 팔레트에서 넓은 대화 폭을 켤 수 있습니다.
• 입력창 아래 줄은 Main 프리셋 → 그 제공자의 모델 → 추론 강도 순서입니다. "자동, 최대 high"처럼 상한을 고를 수 있고, Auto가 실제로 적용한 값은 「현재 추론 강도」로 따로 표시합니다. 실행 중에 지시를 덧붙이면 Auto가 다시 판단해 강도를 올릴 수 있고, 같은 답변 안에서는 내리지 않습니다. 새 대화는 선택한 상한 적용을 마친 뒤 첫 메시지를 보내며, 적용에 실패하면 재전송 때 다시 시도합니다.
• 도구 옆 시간에는 모델 응답 생성 시간을 포함하지 않습니다. 실행 전에 취소된 도구나 완료 시각을 확인할 수 없는 옛 기록에는 시간을 추정해 붙이지 않습니다.
• 자동 제목과 수동 「이름 짓기」는 요청 언어를 따릅니다. 한국어 요청에는 한국어 제목을 붙이고 파일명·명령·제품명은 원문을 유지합니다. 이미 붙은 제목은 바꾸지 않습니다.
• 클라우드에서는 GitHub 저장소를 선택하거나 URL을 입력해 가져온 뒤 프로젝트로 열 수 있습니다. GitHub 연결과 서버 폴더 열기를 한 화면에서 제공하며, 클라우드 기능을 켜지 않은 인스턴스의 화면은 그대로입니다. 설정·인증·작업물 보존과 이전 방법은 Docker 안내를 확인하세요.

계정과 자원

• 계정별 사용량 카드: 한도 창, 이번 구간 실측, 리셋 권장을 한 화면에 보여 줍니다. 기록이 없으면 숫자를 지어내지 않고 「기록 부족」으로 표시합니다.
• 계정은 이메일 대신 캐릭터 얼굴과 별칭으로 구별합니다. 주소를 상시 노출하지 않기 위해서입니다.
• 사이드바 아래 사용량에서 「순서 편집」을 누르면 계정마다 위로·아래로 버튼이 생깁니다. 한 계정의 한도는 함께 움직이고, 고른 순서는 이 브라우저에 저장돼 새로고침해도 유지됩니다. 순서는 화면 표시에만 적용되며, 처음 보는 계정은 맨 뒤에 붙습니다.
• 로그인이 만료되거나 쓸 수 없게 된 계정도 사용량에서 사라지지 않고 이유와 함께 남습니다. 다시 로그인해야 풀리는 계정에만 「재로그인」 버튼이 붙으며, 누르면 Models의 해당 제공자 로그인 화면이 대상 계정(얼굴·별칭·가린 주소)과 함께 열립니다. 로그인은 그 화면에서 직접 시작하고, 끝나면 사용량을 다시 읽어 같은 계정이 돌아왔을 때만 복구됐다고 알립니다. 다른 계정으로 로그인하면 원래 계정의 오류는 그대로 남습니다. 직접 꺼 둔 계정은 지금처럼 목록에 나오지 않습니다.
• 모델 통계의 캐시율은 일반 입력·캐시 읽기·캐시 쓰기를 모두 분모에 넣습니다. 캐시를 보고하지 않는 경우와 보고 여부를 모르는 경우는 0%와 구별합니다. 가격표가 없는 사용량은 무료로 표시하지 않으며, 일부만 계산한 추정 비용과 캐시율에는 그 범위를 알립니다. 추정 비용은 토큰 단가 환산값이지 실제 청구액이나 구독 한도가 아닙니다.
• 효율 패널(Run X-Ray · Experiment Lab): ~/.omp/stats.db와 세션 기록에 이미 쌓인 값만 읽어 실행별 병목과 구성 비교를 보여 줍니다. 각 run에는 시작 시점에 설치돼 있던 하네스 버전(짧은 revision)이 붙습니다. 구성 비교는 기본적으로 지금처럼 구성별로 묶고 각 묶음이 어떤 하네스 버전의 run을 담았는지 함께 보여 주며, 「하네스별로 나누기」를 켜면 같은 구성을 하네스 버전별로 나눠 나란히 비교하고, 하네스 버전 하나만 골라 볼 수도 있습니다. 하네스 버전은 CUELO의 WSL 업데이트 도구가 남기는 갱신 기록에서만 읽습니다. 그 기록이 없는 PC, 첫 기록 이전의 run, 기록 밖에서 버전이 바뀐 구간은 추측하지 않고 unknown으로 표시합니다.
  • 실행 도중 모델이나 추론 강도가 달라진 구성은 첫 값이 같은 단일 구성과 따로 묶습니다. 혼합 구성의 관측값 집합이 같더라도 요청별 조합·순서까지 같다는 뜻은 아니며, 기록 없는 값과 원인은 추정하지 않습니다.
  • run을 열고 「요청별로 보기」를 누르면 모델 요청마다 끼어든 안내 메시지, 도구 호출과 걸린 시간, 모델·토큰 사용을 세션 기록에서 다시 맞춰 보여 줍니다. 요청마다 보낸 시스템 프롬프트는 기록되지 않아 근사치라고 표시하고, 비밀값처럼 보이는 글자는 가립니다.
  • 세션 목록·프로젝트 문서·효율 집계를 불러올 때 반복하던 작업을 줄였습니다. 표시 항목과 집계 기준, 파일 접근 권한은 유지합니다.

여러 에이전트와 함께 일하기

• SubAgent 아카이브: 진행 중·완료된 자식 에이전트의 기록을 열어 봅니다.
• 서브에이전트를 발주한 답변 안에 접힌 카드가 붙어, 맡긴 일마다 실행 상태와 Main의 검수 판정을 한 줄로 보여 줍니다. 펼치면 Maker별 시도가 재작업 순서대로 묶여 실행 상태·검사 수·판정과 함께 나오고, 지금 세션에서 실행한 Maker는 「자세히」로 바뀐 파일·검사·판정 사유를 연 뒤 뒤로 돌아올 수 있습니다. 이전 실행의 기록만 남은 Maker는 확인할 수 없다고 표시합니다. 실행이 끝났어도 Main이 판정을 남기지 않았으면 「검수 미기록」으로 표시하며, 끝난 것을 통과로 치지 않습니다. 서브에이전트가 실행 중이거나 판정을 기다리는 동안에는 입력창 위에 한 줄 요약이 고정되고, 누르면 그 카드로 스크롤해 강조합니다.
• 실행 중인 서브에이전트는 패널 카드와 답변 카드 상세에 지금 단계(조사 › 구현 › 검증 › 보고)와 경과 시간이 몇 초마다 갱신되어 보입니다. 같은 모델의 과거 실행 가운데 지금보다 오래 걸린 실행들을 근거로 남은 시간 범위와 대략의 진행률을 함께 보여 주며, 표본 수도 표시합니다. 할 일 목록을 쓰는 서브에이전트는 그 진행 기준 추정을 따로 덧붙입니다. 과거 기록이 부족하면 남은 시간은 숨기고, 과거 실행 대부분보다 길어지면 그렇다고 알립니다. 추정이지 약속이 아닙니다.
• 대화가 압축돼도 서브에이전트 카드·진행줄과 할 일 목록은 현재 분기의 기록을 이어서 보여 줍니다. 압축으로 원래 답변이 가려진 카드는 압축 지점에서 다시 열 수 있으며, 새로고침해도 복원됩니다. 이후 실행 상태와 검수 판정은 새 관측에 맞춰 갱신됩니다.
• 끝난 턴의 마지막 답변 아래에 변경 파일·검사·실패·미확인 요약이 붙습니다. 펼치면 Main과 서브에이전트의 작업, 검사·리뷰와 재수정 흐름을 그래프로 보고 노드에서 관련 기록·변경 파일·문서를 열 수 있습니다. 넓은 카드에서는 단계가 상자로 한 줄에 놓이고, 카드 폭이 740px 이하이면 일어난 순서대로 적는 세로 레일로 바뀝니다. 실제 진행 중에는 지금 단계의 진행 표시만 움직이고, 완료되면 결과만 정지한 상태로 남습니다. 서브에이전트 카드를 펼치면 조사·구현·검증·보고·Main 판정 흐름을 같은 그래프로 봅니다. 업무 종류와 동시 실행은 기록으로 확인된 경우에만 표시합니다. .omp 작업 폴더나 시스템 임시 폴더에 쓴 임시 파일은 변경 파일로 세지 않습니다.
• 검사 후 다시 수정한 작업은 이전 통과 결과를 현재 검증으로 표시하지 않습니다. 확인되지 않은 검사·복합 명령은 「판정 미확인」으로, 답을 읽지 못한 교차리뷰는 「리뷰 불가」로 구분합니다. 실행 중 끼어든 지시가 같은 작업을 이어 가면 이전 작업 흐름을 함께 보여 줍니다. 비공개 파일만 게시해 공개 CI가 생기지 않은 것으로 확인되면 CI는 「필요 없음」으로 표시하고, CI·배포가 없던 턴은 끝난 뒤 그 단계를 「필요 없음」으로 닫습니다.
• 실행 중에 보낸 입력은 「지금 지시」와 「완료 후 요청」으로 나뉘어, 접수·전달 대기·대화에 들어감 단계를 따로 보여 줍니다. 전달을 확인하지 못하면 그렇다고 표시합니다. 스크린샷만 보낸 입력도 「이미지 N개」로 표시합니다. 기본 목록에는 최근 4개만 보이고, 「이전 N개 더 보기」로 나머지를 펼칠 수 있습니다. 실제 대기 중인 입력은 목록에서 숨겨져도 유지되며, 펼친 목록에서 거둘 수 있습니다.
• 자식 에이전트의 발화가 해당 턴 아래 대화 흐름에 끼어들어 누가 무슨 말을 했는지 이어서 읽힙니다.
• 공개 하네스는 시작을 기다리거나 재작업 중인 에이전트에게 같은 파일을 중복 배정하지 않도록 확인합니다. 잘못된 작업 유형은 발주 준비 단계에서 알려주며, 에이전트 역할을 생략하면 메이커를 사용합니다. 완료 결과와 Main이 검수한 결과의 출처를 구분하고, 재작업 이력과 최종 수용을 따로 남깁니다. 적용 경계는 하네스 안내를 따릅니다.
• 여러 작업을 한꺼번에 맡길 때 공통 준비 확인의 반복을 줄였습니다. 작업별 담당 경로와 충돌 확인은 유지하며, 다음 발주에서는 바뀐 조건을 다시 확인합니다.
• 요청별 Maker 발주 한도는 실제로 시작한 Maker만 셉니다. 승인 거부·거절로 실행되지 않은 발주는 한도를 쓰지 않고, 취소한 Maker는 이름이 같아도 그 Maker 몫만 돌려받습니다(하네스 안내).
• 발주 준비와 실행은 같은 작업 계약을 읽습니다. 캐릭터 호출 예외는 이번 사용자 요청에만 적용하며, 다른 세션으로 옮길 때 이전 요청의 호출·안내 상태를 넘기지 않습니다. 같은 세션을 다시 불러올 때는 진행 중인 상태를 유지합니다.
• 완료된 위임 작업은 검수 판정과 기록을 함께 마감하고, 최종 답변 전에 판정 기록 누락을 확인합니다. 근거가 부족한 결과를 자동 합격으로 처리하지 않습니다. 보류로 남긴 발주를 새 발주로 다시 맡기면 그 보류를 알려 주고, Main이 옛 시도를 닫아 끝난 일이 「Main 보류」로 남지 않게 합니다.
• 긴 완료 보고도 검수 근거와 해당 작업의 원래 요청을 함께 확인하도록 전달합니다. 정체된 작업은 알림 전달, Main의 상태 확인, 후속 지시 전달을 구분하며, 조회나 지시만으로 문제가 해결됐다고 표시하지 않습니다.
• 메이커의 기본 추론 강도와 허용 범위는 별개입니다. 작업별 허용 범위 안에서도 선택한 모델이 실제로 지원하는 강도만 사용하며, 상한을 높여도 기본 강도를 자동으로 최대로 바꾸지 않습니다.
• 필요한 MCP 서버만 요청별로 연결하는 선택 모드를 지원합니다. 설치·인증·권한 변경은 먼저 승인을 받고 에이전트가 지원합니다. 설정과 적용 범위는 요청별 MCP 선택 연결을 확인하세요.
• 사이드 챗(/btw): 본 대화를 끊지 않고 옆 패널에서 따로 묻습니다. 답변은 본 대화와 같은 캐릭터 얼굴·스티커·마크다운으로 보이고, 세션마다 초안이 따로 보관됩니다. 사이드 챗 문답은 본 대화에 남지 않으며, 답변의 「메인에 보내기」를 누를 때만 문답과 추가 지시가 본 대화로 전달됩니다(본 대화가 실행 중이면 steer, 아니면 새 요청).
• ChatGPT 상담(SHION): 로컬 shim이 전용 ChatGPT 탭에서 받은 답을 현재 omp 세션에 투영하고, 상담 기록과 실패 기록이 대화창에 표시됩니다.
• 실시간 음성: 브라우저 마이크로 Codex live 음성 세션을 엽니다. “끊어”, “알았어, 끊어봐”, “아니 통화 종료하라고”처럼 단독 종료 요청을 말하면 최종 전사를 받은 뒤 마이크와 통화를 종료합니다. 설정 → 통화 음성에서 통화와 통역이 쓰는 Codex 목소리를 고를 수 있습니다(한국어 햇살·하늘 포함). 통화 답변은 통화를 시작할 때의 Main 캐릭터 얼굴과 이름으로 표시되고 「기본 음성」이라고 함께 보입니다. 입력창에는 통화 시작·종료 버튼만 남으며, 좁은 화면에서는 모델 선택 등 다른 조작부와 겹치지 않게 줄바꿈합니다. 자세한 내용은 라이브 통화를 확인하세요.

통역

• 사이드바의 「통역」을 고르면 작업 화면 위에 통역 화면이 열립니다. 한국어·영어·베트남어·일본어·태국어 가운데 내 언어와 상대 언어를 고르고 「통역 시작」을 누르면, 휴대폰을 두 사람 사이에 두고 각자 말하기만 하면 됩니다. 누가 말하든 상대 언어로 바로 소리 내어 옮깁니다. 버튼을 번갈아 누를 필요가 없습니다.
• 통역은 연결된 ChatGPT 계정의 Codex 라이브 음성 통화로 합니다. 통화에는 고른 두 언어로 만든 짧은 통역 지시만 들어가고, 작업 세션·하네스 규칙·대화 기록은 들어가지 않으며 작업을 위임하지도 않습니다. 목소리는 설정 → 통화 음성에서 고른 Codex 목소리입니다.
• 화면에는 오간 말이 말풍선 자막으로 쌓입니다. 큰 글씨가 통역, 작은 글씨가 들은 원문입니다. 글자(한글·가나·태국 문자·베트남어 성조 부호 등)로 누가 말했는지 가려 내 말은 오른쪽, 상대 말은 왼쪽에 둡니다. 영어와 베트남어처럼 같은 글자를 쓰는 짝에서 이름·숫자만 말해 가를 수 없으면 왼쪽에 둡니다.
• 통역 화면을 열거나 언어를 바꾸거나 통역을 끝내면, 고른 언어 짝으로 통화를 미리 연결해 25초쯤 기다립니다. 그 안에 「통역 시작」을 누르면 연결을 기다리지 않고 바로 듣기 시작하고, 그보다 늦으면 전처럼 누른 뒤에 연결합니다. 미리 연결할 때는 마이크를 열지 않습니다. 마이크는 「통역 시작」을 누른 뒤에야 켜집니다. 화면을 닫으면 미리 연결한 통화도 끊습니다.
• 통역 중에 언어를 바꾸면 새 언어 짝으로 다시 연결합니다. 「대화로」를 누르면 통화와 마이크를 끝냅니다. 마이크는 HTTPS 주소에서만 켜지며, 통역 기록은 화면이 열려 있는 동안만 보관하고 서버에 저장하지 않습니다. 직접 입력해 번역하는 칸과 말풍선 다시 듣기는 없습니다.
• 작업 화면으로 돌아가도 선택한 세션·작성 중인 초안·진행 중인 작업은 그대로입니다.

알림과 표현

• 완료·실패·승인 요청·선택 요청 등 상황에 맞는 캐릭터 스티커와 음성으로 알립니다(RIN · MIO · YUKI · ISANA · NOVA · SHION · HIKARI).
• 설정 → 캐릭터에서 「기본 / 사무실 모드」를 고르면 PC 서버 전체에 적용됩니다. 사무실 모드는 이 PC의 프로필(characters-office/)에 둔 캐릭터 세트를 읽어 YUKI 자리의 얼굴·이름·스티커·완료 음성을 바꾸며, 그 세트가 없으면 기본 캐릭터가 그대로 쓰입니다.
• 브라우저 알림과 PWA 설치를 지원합니다.
• 직접 저장한 교훈·스킬은 저장한 답변이나 과정 바로 뒤의 카드에서 확인합니다. 교훈 자동 기록을 켠 경우 자동 저장 알림도 작업 과정을 접어도 대화에 남습니다. 요청에 이름이 없고 필요성도 확인되지 않은 MCP 후보는 보류 안내로 나열하지 않습니다.
• 교훈 자동 기록의 응답 수·토큰·캐시·보고 비용·소요 시간을 기존 로그에서 확인할 수 있습니다. 본대화의 과거 사용량은 제외하며, 보고되지 않은 값은 0으로 추정하지 않습니다. 모델이나 학습 예산을 자동 변경하지는 않습니다. 하네스 안내를 참고하세요.
• 사용자 정의 도구의 입력 이름이 JSON Schema 키워드와 같아도 속성 구조를 보존합니다. 도구 정의가 잘못 변환되어 대화 요청 전체가 거절되는 문제를 수정했습니다.
• Main이 하위 작업에 새 지시를 보내면, 아직 도구 호출이 시작되지 않은 모델 요청은 응답을 끝없이 기다리지 않고 새 지시로 이어집니다. 실행 중인 도구는 중복 실행하거나 강제로 중단하지 않습니다.
• 하위 작업의 응답·도구 진행·사용자 입력 대기를 구분하고, 진행이 오래 확인되지 않으면 Main에게 점검 알림을 보냅니다. 알림만으로 작업을 실패 처리하거나 자동 중단하지 않습니다.
• 한국어가 기본인 인터페이스입니다(영어·중국어 간체도 선택 가능).

omp-web에서 이어받은 기반 기능

• 모델 역할(default, smol, slow, plan, commit, task 등)별 모델 지정·전환 — TUI의 /model과 같은 config.yml을 씁니다.
• 입력창의 / 명령은 대기 중뿐 아니라 실행 중에도 Enter·Steer·Follow-up으로 실행할 수 있습니다. 내장 명령은 즉시 처리하고, 발견된 확장·스킬·프롬프트 템플릿 명령은 해당 명령 경로로 전달합니다. 사용할 수 없거나 실행 중 허용되지 않는 명령은 안내하며 일반 채팅으로 전송하지 않습니다.
• 응답을 기다리며 보낸 Steer를 실시간으로 반영할 수 없을 때, 아직 답변이나 도구 호출이 나오지 않았다면 현재 추론 요청만 끊고 새 지시로 이어갑니다. 이미 보인 답변이나 도구 호출은 보존하며, 거절된 지시는 다음 요청에 전달합니다. 대화 전체를 중단하지 않습니다.
• 에이전트가 일반 구현 방식을 고르는 질문에 추천안을 붙여 물으면, 2분 동안 답이 없을 때 추천안으로 진행합니다. 질문 창에 그 안내가 표시되고, 옵션을 고르거나 답을 입력하면 대기 시간이 다시 시작됩니다. 자동 선택은 사용자 승인으로 치지 않으며, 배포·삭제·비용·계정·권한 확인 질문은 답할 때까지 기다립니다.
• Main이 OpenAI 모델에서 Fast를 켜면 새로 만드는 OpenAI 계열 SubAgent도 Fast로 요청합니다. Anthropic·Google SubAgent에는 Fast를 자동으로 넘기지 않고, Fast가 꺼져 있으면 SubAgent도 표준 처리로 요청합니다.
• 네이티브 창을 다루는 computer.run에서 버튼을 한 번 누른 뒤, 원하는 행·문구·값이 나타날 때까지 로컬 읽기로만 다시 확인하고 결과만 돌려줍니다. 기다리는 동안 다시 누르지 않으며, 제한 시간 초과·취소·읽기 오류를 서로 구분해 알립니다. 저장·전송처럼 결과가 남는 클릭의 승인 절차는 바뀌지 않습니다(사용법).
• provider 로그인·API 키, models.yml, 플러그인, 스킬을 웹에서 관리합니다. 플러그인 비활성화 설정을 저장해도 이미 불러온 플러그인은 CUELO 런타임을 재시작해야 멈춥니다. 「세션 다시 불러오기」는 플러그인을 해제하지 않습니다.
• 스킬 검색은 검색 서비스 오류와 정상적인 검색 결과 없음을 구분해 안내합니다. 보조 검색 경로에서도 설치 수가 0회·1회인 스킬을 빠뜨리지 않습니다.
• 프로젝트 파일 탐색과 소스·문서·이미지·오디오·PDF 미리보기, Git worktree 전환. 파일·서브에이전트·작업 로그 패널은 같은 한 줄 머리줄을 쓰고, 오른쪽에 고정한 보조 패널은 넓게 봤다가 Escape로 원래 크기로 돌아옵니다. 이때 파일 보기 방식과 스크롤 위치가 유지됩니다.
• 파일 패널에 열린 파일이 없으면, 선택한 프로젝트의 현재 상태(HANDOFF.md)·문서 지도(doc/README.md)·최근 작업 기록(doc/history) 바로가기를 보여 줍니다. 있는 문서만 열 수 있고, 없음·읽기 권한 밖·프로젝트 미선택을 구분해 표시하며 파일을 새로 만들지 않습니다.
• 프로젝트 신뢰: 설정에서 프로젝트별 승인을 관리·해제하고, 실행 중에는 작업을 끊지 않고 신뢰 승인을 예약합니다. 신뢰하지 않은 저장소의 확장·훅·도구·MCP는 실행하지 않습니다(docs/project-trust.md).
• 비밀번호 잠금(HTTP Basic Auth, scrypt 해시 저장)과 /recover 복구(docs/authentication.md).

실행하기

CUELO는 GitHub 소스와 npm 패키지 cuelo로 설치합니다. npm의 omp-web은 upstream 프로젝트이며 CUELO와 별개입니다. 기존 omp CLI만 설치한 PC에도 omp-web 없이 CUELO를 추가할 수 있습니다. 기존 config.yml·계정·세션을 보존하는 순서는 대표 설치 경로에 있습니다.

개발·검증 환경은 Windows와 Linux(WSL2 Ubuntu 24.04)입니다. 공개 CI는 Windows에서 실행합니다. macOS는 개발·테스트 환경이 아니므로 동작과 지원을 보장하지 않습니다.

서버는 Bun 1.4.2 이상에서만 실행됩니다(omp SDK가 TypeScript 소스와 bun: 내장 모듈을 사용). Node.js 22.19.0 이상도 install.mjs와 npm에 필요합니다. Git은 소스 checkout과 Git 작업(worktree·commit 등)에 필요하지만 npm 설치와 기본 대화에는 필요하지 않습니다. 메모리 패키지가 선언한 선택적 ONNX peer는 onnxruntime-node:1.21.0으로 제공합니다. Transformers가 요구하는 별도 버전은 자체 의존성으로 유지하며, 설치 오류를 피하려고 peer 검증을 끄지 않습니다. Mnemopi의 로컬 임베딩은 별도 fastembed와 모델을 첫 사용 때 내려받을 수 있습니다.

# Bun 설치
powershell -c "irm bun.sh/install.ps1 | iex"    # Windows
curl -fsSL https://bun.sh/install | bash        # Linux

# CUELO 받기와 실행
git clone https://github.com/gim47656-ship-it/CUELO.git
cd CUELO
node install.mjs setup
node install.mjs start

소스 빌드 없이 npm으로 설치하려면 Node.js 22.19.0 이상과 Bun 1.4.2 이상을 준비한 뒤 실행합니다.

npm install -g cuelo
cuelo setup
cuelo start
# 다른 터미널에서 서비스 확인
cuelo health

setup은 공개 하네스의 없는 파일만 추가합니다. npm 설치본에는 production 빌드가 포함되어 있어 다시 빌드하지 않습니다. 실행 중인 CUELO가 있다면 종료하거나 cuelo start --port-base 31141로 별도 포트를 사용하세요.

앱과 세 사이드카가 같은 터미널에서 실행됩니다. 브라우저에서 http://127.0.0.1:30141을 열고 본인 계정으로 로그인한 뒤 모델을 선택하세요. 기본은 127.0.0.1 전용이며, Ctrl+C로 실행한 서비스를 종료합니다.

다른 터미널에서 node install.mjs health(npm 설치는 cuelo health)로 네 서비스의 응답을 확인합니다. 기존 설치와 다른 포트가 필요하면 start와 health 양쪽에 --port-base 31141처럼 지정합니다. 이 검사는 제공자 인증·Jev 판정·사용량 응답을 검증하지 않습니다.

처음 설치하거나 Claude·Codex에 설치를 맡길 때는 **새 Windows 설치와 실행 안내**를 기준으로 하세요. 포함 파일과 외부 필수 항목, Jev 제공자 키·역할 설정, 기능별 CLI/Git 요구사항이 따로 적혀 있습니다. 기존 프로필 파일은 자동으로 덮어쓰지 않으며, 제공자 로그인·권한 승인·모델 선택은 사용자 단계입니다. 빈 Windows PC 전체를 실제 검증한 것은 아닙니다.

앱만 따로 실행하는 기존 실행기 옵션:

bun bin/cuelo.js --port 8080           # 포트 변경
bun bin/cuelo.js --hostname 0.0.0.0    # 신뢰하는 네트워크에만 노출
bun bin/cuelo.js --no-open             # 브라우저 자동 열기 끄기
bun bin/cuelo.js --authenticated       # 비밀번호 잠금 켜기
bun bin/cuelo.js --reset-password      # 비밀번호 재설정

원격에서 쓸 때는 평문 HTTP를 인터넷에 열지 말고, 신뢰할 수 있는 HTTPS 리버스 프록시나 VPN 뒤에 두세요. CUELO는 권한이 큰 에이전트를 실행합니다.

업데이트

새 CUELO 릴리스가 나오면 사이드바 아래에 알림이 뜹니다. CUELO는 스스로 설치하지 않습니다. 소스에서 실행 중이면 서비스를 종료한 뒤 소스를 갱신하고 다시 설치·시작하세요. 실행 중인 개발 서버의 .next/에 빌드를 겹쳐 쓰지 마세요.

업데이트 대기 화면에서 실패가 확인되더라도 서버가 다시 요청을 받을 수 있고 원래 대화가 확인되면 그 대화로 자동 복귀합니다. 복귀한 화면은 진행 중인 답변이나 이미 끝난 실패 안내를 따라잡으며, 복귀 자체가 명령을 다시 보내지는 않습니다.

Windows의 WSL Ubuntu에서 실행 중인 CUELO를 갱신하는 동안에는 WSL 연결을 유지하고, 열려 있는 화면에 세션 정지·준비·패키지 교체·확인 단계를 표시합니다. 서버가 내려가 응답하지 않는 동안에는 마지막으로 확인한 단계를 그대로 표시하고 아직 확인하지 못한 단계로 앞서가지 않으며, 갱신이 끝나면 원래 대화로 돌아옵니다. 새 서버가 실행 중이고 응답하면 갱신 완료 화면에서 멈추지 않고 마칩니다. 서비스가 멈춘 것을 확인한 뒤에만 파일과 프로필을 바꾸고, 실패하면 실행 중이던 버전을 그대로 두거나 이전 버전으로 복구합니다. 복구가 끝난 갱신도 완료로 인식합니다.

WSL 갱신에서는 시스템 시각이 보정되어도 실행 중인 서버를 같은 서버로 인식해, 진행 중인 대화의 중단·재개 절차를 건너뛰지 않습니다. WSL 갱신은 실행 중인 서버와 분리해 새 버전을 미리 빌드한 뒤 교체합니다. 빌드 캐시는 재사용하고 다시 만들 산출물은 복사하지 않아 준비 과정의 디스크 쓰기를 줄입니다.

기존 프로필의 하네스·역할 설정은 앱 업데이트만으로 자동 덮어쓰지 않습니다. 0.6.1의 설정 전환은 기존 하네스 갱신을 확인하고, 반영 후 CUELO와 omp를 다시 시작하세요.

git pull --ff-only
node install.mjs setup
node install.mjs start

공개 웹 소스 릴리스와 변경 내용은 GitHub Releases에서 확인하세요. 새 package.json 버전이 공개 main에 올라가 CI가 성공하면 GitHub 릴리스와 npm cuelo 게시가 자동으로 실행됩니다(릴리스 절차).

사이드카 서비스

사용량 카드, 사이드 챗, SubAgent 아카이브는 로컬 사이드카 서비스에서 데이터를 받습니다. 실행 소스는 공개 저장소의 Tools/CUELO_Setup/files/에 있고, node install.mjs start가 함께 실행합니다. 개발자의 인증정보나 대화 기록을 제공하는 서비스가 아니라, 각 사용자 PC의 데이터를 읽는 서비스입니다.

기능	주소
계정 사용량·리셋	http://127.0.0.1:30142
사이드 챗	http://127.0.0.1:30143
SubAgent 아카이브	http://127.0.0.1:30144

사이드카가 없으면 해당 패널은 「연결 안 됨」으로 표시되고, 나머지 기능은 그대로 동작합니다.

사이드챗은 보조 패널의 「캐릭터」 다음 탭에서 엽니다. 패널 폭이 좁으면 탭이 다음 줄로 이어져 마지막 탭도 숨지 않습니다.

Docker

Dockerfile과 docker-compose.yml로 컨테이너에서 실행할 수 있습니다. omp 홈 디렉터리(~/.omp)를 마운트해야 합니다. 자세한 내용은 docs/docker.md를 보세요.

개발

bun install --backend=copyfile
bun run prepare:source  # SDK 호환 패치를 이 작업 사본에 적용
bun run dev          # http://127.0.0.1:30141
bun run typecheck
bun run lint
bun run test         # 앱·설치기 테스트
bun run test:coverage  # 앱·설치기 테스트 + 커버리지 표

개발 서버를 쓰는 동안 같은 출력 경로에 bun run build를 돌리지 마세요. .next/를 덮어써서 개발 서버가 깨집니다. 검증용 production 빌드는 별도 소스 복사본이나 격리된 CUELO_DIST_DIR에서 실행하세요.

의존성을 다시 설치하거나 갱신한 뒤에는 bun run prepare:source를 다시 실행하세요. 이미 설치된 작업 사본에서도 bun install은 패치된 SDK 패키지를 원본으로 다시 깔기 때문에, 준비 단계를 빼면 호환 패치가 빠진 채로 실행됩니다. 이 준비 단계는 작업 사본의 SDK만 다루며 사용자 프로필이나 실행 중인 설치본을 변경하지 않습니다.

참고 문서: OMP 하네스 · 인증 · 프로젝트 신뢰 · worktree · 다국어 · Docker · Windows·WSL 도구 속도 비교 · Maker 코드 품질 평가

계보와 라이선스

CUELO는 @ddallabenetta의 omp-web을 기반으로 하고, omp-web은 @agegr의 pi-web에서 갈라져 나왔습니다. CUELO 앱은 독립적으로 개발·배포하며 upstream 앱의 릴리스를 자동으로 따르지 않습니다. 기반 소스의 출처는 UPSTREAM.json에 기록되어 있습니다.

CUELO의 에이전트 엔진은 omp (oh-my-pi)입니다. omp 소스를 이 저장소에 복사하지 않고 @oh-my-pi/* npm 패키지(MIT, Copyright (c) 2025 Mario Zechner, Copyright (c) 2025-2026 Can Bölük)를 의존성으로 씁니다. 각 패키지의 라이선스 전문은 설치된 패키지 안의 LICENSE에 들어 있습니다.

캐릭터(RIN · MIO · YUKI · ISANA · NOVA · SHION · HIKARI)의 그림·음성·스티커와 docs/hero.webp는 CUELO 고유 자산입니다.

함께 싣는 글꼴은 모두 SIL Open Font License 1.1입니다. 본문은 Wanted Sans, 코드는 JetBrains Mono이고, 제목은 G마켓 산스를 웹용으로 나누고 변환한 것입니다. 원래 이름은 수정본에 쓸 수 없어서 "CUELO Display"라는 이름으로 싣습니다. 라이선스 전문은 public/fonts/ 아래 각 글꼴 폴더에 있습니다.

코드: MIT License