사용 설명서

Evo Mac은 macOS에서 쓰는 Evo AI 에이전트 데스크톱 앱입니다(코드네임 evo-mac). 같은 Evo 에이전트 엔진을 Evo CLI(터미널)와 함께 쓰며, 같은 Evo 계정으로 로그인합니다. 폴더를 하나 골라 세션을 열고 대화하면, 에이전트가 그 폴더의 파일을 읽고 고치고 승인한 명령을 실행합니다. 이 문서는 0.2.8 버전을 기준으로 화면에 보이는 기능을 모두 안내합니다. 설치·업데이트는 소개를 먼저 보세요. Windows에서는 짝 제품인 Evo Windows를 씁니다.

화면 캡처는 로그인하지 않은 점검용 Mac(개발판)에서 찍었습니다. 로그인 코드, 시험 계정 이메일, 홈 경로, 호스트 이름은 가렸습니다.

앱이 그리는 글자는 macOS의 시스템 언어 설정을 따라 한국어 또는 영어로 나옵니다. 메뉴 막대와 시스템 대화 상자처럼 macOS가 직접 그리는 글자도 같은 언어를 씁니다.

메인 창 구성

창은 기본적으로 세션 목록 · 채팅 · 터미널의 3칸이고, 터미널 오른쪽에 브라우저 칸을 더 열 수 있습니다.

• 왼쪽: 세션 목록. 열린 세션 묶음이 위에 있고, 닫힌 세션은 마지막으로 활동한 날짜에 따라 오늘·어제·지난 7일·지난 30일·이전 묶음에 나뉩니다. 묶음 안은 최근 순이고 빈 묶음은 보이지 않습니다. 각 줄에는 제목(첫 입력 앞부분 또는 지정한 이름), 작업 폴더, 마지막으로 바뀐 시각이 있습니다. 열린 세션은 채운 말풍선과 초록 점으로, 닫힌 세션은 흐린 윤곽선 말풍선으로 구분됩니다. 초록 점은 실행 중이면 도는 표시가 되고, 승인을 기다리면 주황 점이 됩니다. 받은 요청의 안 읽은 수는 줄마다 배지로 보입니다. 열려 있는 세션 줄에는 닫기(×) 단추가 있고, 메뉴에서 “세션 열기”·“세션 닫기”·“세션 지우기…”·“복사해 이어 가기”를 고를 수 있습니다. 세션이 없으면 “세션이 없습니다”가 보입니다.
• 세션 묶음 접기: 묶음 머리(▸ 이름)를 누르면 그 묶음이 접히거나 펴집니다. 접힌 묶음은 이름 뒤에 세션 수가 보이고, 처음에는 지난 30일과 이전이 접혀 있습니다. 바꾼 접힘은 앱을 다시 켜도 남습니다. 접힌 묶음의 세션을 열면 그 묶음이 펴지고, 묶음 머리를 더블클릭해도 세션은 열리지 않습니다. 앱 안의 모든 스크롤 영역(세션 목록, 대화 칸, 입력 칸, 코드 블록·표, 설정 창·시트)은 트랙과 화살표가 없는 얇은 막대를 쓰며, 스크롤하거나 마우스를 올리면 보이고 잠시 뒤 사라집니다. macOS의 “스크롤 막대 보기” 설정과 상관없이 같습니다.
• 가운데: 채팅. 위쪽에 모델·권한 모드를 고르는 메뉴, 계정 메뉴가 있고, 그 아래 대화 내용과 맨 아래 입력창이 있습니다. 입력창 아래에는 상태 줄이 있습니다.
• 오른쪽: 터미널 칸. 사용자가 직접 쓰는 셸 탭과, 에이전트가 실행하는 명령을 보여주는 “에이전트” 탭으로 나뉩니다. 앱을 켤 때마다 접힌 상태로 시작합니다.
• 터미널 오른쪽: 브라우저 칸. 에이전트가 만든 웹 페이지나 띄운 로컬 서버를 앱 안에서 보는 칸입니다. 기본적으로 닫혀 있습니다.
• 칸 사이의 경계를 끌어 너비를 바꿀 수 있고, 채팅·터미널·브라우저 칸은 항상 세션 목록 오른쪽 전체를 채웁니다. 한 칸을 넓히면 옆 칸이 그만큼 줄어듭니다. 터미널·브라우저 칸을 닫았다가 다시 열면 이전 너비로 돌아오고, 이 너비는 앱을 다시 켜도 남습니다. 칸을 끝까지 끌어 접으면 닫힌 것으로 봅니다.
• 터미널·브라우저 칸 머리줄 끝의 “최대화” 단추를 누르면 그 칸이 세션 목록 오른쪽 전체를 채우고(다른 칸은 접힘), 단추가 “되돌리기”로 바뀝니다. 그 칸을 닫거나 세션을 바꾸면 풀립니다. 앱을 다시 켜면 항상 보통 배치로 시작합니다.
• 도구 막대: 모델, 권한 모드(이름이 항상 글자로 보임), 터미널 열기·닫기, 설정 톱니바퀴, 계정 메뉴가 있습니다. 새 버전이 있으면 “새 버전” 단추도 나타납니다.
• 메뉴: 앱 메뉴(“업데이트 확인…”, 설정…=⌘,), 대화 메뉴(대화 압축…=⌘⇧K, 대화 지우기=⌥⌘K, 컨텍스트와 사용량…, 목표(Goal)…=⌘⇧G, 상태와 진단…=⌥⌘I, 생각·도구 결과 모두 펼치기=⌃O), dispatch 메뉴(받은 요청=⌘⇧I, 활성 세션과 보내기=⌘⇧D, 워크그룹…, 버그 신고=⌘⇧U)가 있습니다. 세션이 없을 때도 열리는 창(상태와 진단, 버그 신고)과, 세션이 있어야 켜지는 메뉴(대화 메뉴 대부분)가 있습니다.
• 빈 화면: 세션이 없을 때는 evo 마크와 “evo”, 안내, 로그인·새 세션 버튼이 보입니다. 세션은 있지만 아직 아무 대화가 없으면 마크와 “무엇을 할까요?”, 작업 폴더, 할 수 있는 일 네 줄이 보입니다.
• 빈 세션 목록과 세션 항목 아이콘: 세션 목록 항목에는 말풍선 아이콘, 작업 폴더 이름 앞에는 폴더 아이콘이 붙습니다.
• 상태 줄 “칩”: 상태 줄에서 누를 수 있는 항목(컨텍스트·토큰, 목표, dispatch)은 옅은 둥근 배경의 “칩”으로 보이고 마우스를 올리면 배경이 진해집니다. 모델·권한 모드는 더 큰 칩 모양 메뉴로, 상태 줄에서만 바꿉니다(도구 막대 메뉴와 별개).
• 답변의 Markdown은 보기 좋게 그려집니다: 제목(단계별로 글자 크기 차이), 목록(중첩·번호), 표(칸 맞춤, 헤더 굵게, : 정렬), 인용(세로줄), 가로줄, 코드 블록(고정폭 글꼴, 언어 이름과 “복사” 단추, 긴 줄은 접힘). 코드 안의 글자는 색깔로 칠해지지 않습니다(CLI와 다른 점).
• 대화가 맨 아래에 있을 때만 새 출력을 자동으로 따라 내려갑니다. 위로 스크롤해 두면 그 자리에 머물고, 가운데 아래에 눌러서 맨 아래로 가는 ↓ 최신으로(새 출력이 있으면 ↓ 새 출력 · 최신으로) 단추가 나타납니다.

대화 내용이 표시되는 방식

• 생각 과정: 모델이 답하기 전에 생각한 내용은 생각 과정 · 3초(1초 미만이면 시간 표시 없음, 생각 중이면 생각하는 중…) 머리줄로 접혀서 보입니다. 누르면 펼쳐집니다. 세션을 다시 열면 걸린 시간은 다시 보이지 않습니다. 설정에서 “생각 과정 펼침”을 켜면 처음부터 모두 펼쳐진 채로 보입니다.
• 도구 호출 묶기: Bash·Read·Grep·Glob·WebFetch·WebSearch 호출이 답 글 없이 이어지면 ⚙ 파일 6개 읽음, 패턴 2개 검색처럼 한 줄로 묶여 접힙니다. 실패한 호출은 묶음을 끊고 혼자 보이며, 그 앞뒤의 성공 호출은 각각 접힙니다. 끝나지 않은 호출이 있는 묶음은 접지 않습니다. 그 줄을 누르면 그 묶음만 펼치거나 다시 접을 수 있습니다. Edit·Write·하위 에이전트·MCP 도구 호출은 묶이지 않고 각각 보입니다.
• 실행 중인 묶음: 실행이 도는 동안 대화 맨 끝의 묶음은 ⚙ <끝난 호출 요약> · <지금 호출> · <경과 시간> 한 줄로 제자리에서 갱신되고, 시간은 1초마다 바뀝니다. 지금 도는 호출이 없고 아직 시작하지 않은 호출(승인 대기·차례 기다림)만 남으면 그 호출을 시간 없이 보입니다. 이 줄을 누르면 묶인 카드들이 펼쳐집니다. 지금 호출이 셸 명령이면 그 출력의 마지막 3줄이 줄 아래에 흐린 고정폭 글자로 보이고, 명령이 끝나면 사라집니다. 실행이 끝나면 같은 자리에서 보통 묶음 줄로 바뀌고, 실패한 호출은 묶음 밖에 그대로 보입니다.
• 도구 결과: Read·Grep·Glob처럼 읽기만 하는 도구의 성공 결과는 ✓ 46줄처럼 한 줄만 보입니다. 그 밖의 결과(실패 포함)는 앞 3줄과 … +N줄만 보이고, 카드의 펼침 단추로 전체를 볼 수 있습니다. 끝난 호출 카드의 머리줄에는 그 호출이 돈 시간이 1.2초·1분 5초·1시간 2분 3초처럼 보입니다(0.1초 미만은 표시하지 않음). 승인을 기다린 시간은 빼며, 다시 연 세션에는 시간이 없습니다.
• Edit·Write 카드: 머리줄에 Edit <경로> +A −D 또는 Write <경로> +A가 보이고, 그 아래에 바뀐 내용이 diff로 그려집니다. 지운 줄은 빨간 띠, 더한 줄은 초록 띠로 카드 폭까지 채우고 앞에 파일의 줄 번호(지운 줄은 옛 번호, 더한 줄은 새 번호)를 답니다. 지운 줄과 더한 줄이 짝을 이루면 줄 안에서 바뀐 부분만 더 진하게 표시합니다. 20줄까지 보이고 넘으면 … +N줄로 접히며, 펼침 단추로 전체를 봅니다. 한 곳만 바꾼 Edit은 머리줄 끝에 at line N이 붙고, 여러 곳을 바꿨거나 승인을 기다리는 중이면 번호 없이 보입니다. 승인 대기·실행 중·실패한 호출의 diff는 흐리게 보입니다.
• 한꺼번에 펼치기/접기: 대화 메뉴 “생각·도구 결과 모두 펼치기”(⌃O)를 누르면 지금 보이는 생각 과정·도구 묶음·도구 결과를 한꺼번에 펼치거나 접습니다. 이 동작은 그 실행에서만 적용되며, 하나씩 펼치거나 접은 항목은 그 반대로 바뀝니다.
• 턴 결과와 압축 표시: 각 실행이 끝나면 완료·중지됨·턴 한도·오류와 턴 수, 입력·출력 토큰이 한 줄로 보입니다. 대화가 압축되면 그 지점에도 표시가 들어갑니다.

로그인

1. 창 오른쪽 위 계정 메뉴에서 “조직 계정으로 로그인…” 또는 “개인 계정으로 로그인…“을 고릅니다(둘 중 빌드에 설정된 것만 보입니다. 사내 전용 빌드는 조직 로그인만 있을 수 있습니다).
2. 로그인 시트에 코드가 큰 글씨로 보입니다. 복사 버튼으로 복사하거나, “브라우저 열기”를 눌러 완성된 주소를 바로 엽니다.
3. 브라우저에서 로그인을 마치면 앱이 기다리던 창이 닫히고, 그 세션에서 쓸 수 있는 모델 목록이 채워집니다. 기본 모델이 정해져 있지 않으면 목록의 첫 모델을 씁니다.
4. 기다리는 동안 “취소”를 누르면 로그인을 그만둘 수 있습니다.

로그인하지 않으면 입력창 자리에 “로그인이 필요합니다”가 보이고 메시지를 보낼 수 없습니다(Evo CLI 개인 모드와 같습니다). 마지막에 쓴 로그인은 다음에 앱을 열 때도 이어지며, 로그인했던 세션의 서버에 더 물을 필요가 없으면 다시 로그인 화면을 거치지 않고 바로 씁니다.

로그아웃도 같은 계정 메뉴에서 합니다. 로그아웃하면 그 계정으로 연결했던 MCP 서버·evo-dispatch 연결이 모두 끊어지고, 저장해 둔 모델 목록 파일도 지워집니다.

계정 종류: 조직 계정으로 로그인하면 조직이 정한 Evo 모델만 쓸 수 있고, 직접 provider를 추가할 수 없습니다. 개인 계정으로 로그인하면 Evo 모델과 함께 Anthropic·OpenAI·OpenAI 호환·Ollama·LiteLLM provider를 직접 추가해 쓸 수 있습니다. 로그인 전과 로그아웃 뒤에는 어느 쪽도 모델이 없습니다.

조직 키 파일(기관 전용 빌드): 설정 창 계정 탭에서 “조직 키 파일 가져오기…“로 관리자가 서명해 준 파일을 불러올 수 있습니다. 이 파일에는 조직 로그인 서버 주소, 만료일, (있다면) 조직용 업데이트 서버 주소와 조직용 dispatch 서버 주소가 담겨 있습니다. 서명이 앱이 신뢰하는 키로 되어 있지 않거나, 형식이 잘못됐거나, 만료됐으면 가져오기가 거부되고 이유가 보입니다. 가져온 뒤에는 계정 탭에서 조직 이름, 서명 키 id, 만료일, 연결되는 업데이트·dispatch 서버 여부를 확인할 수 있습니다(실제 주소는 화면에 찍히지 않습니다). “지우기”를 누르면 확인을 거쳐 파일을 지우고 빌드 기본 조직 로그인으로 돌아갑니다. 조직 로그인 서버가 바뀌면 이전 서버의 로그인 정보는 지워집니다.

세션 관리

새 세션 만들기

1. “새 세션…”(⌘N)을 누르고 작업할 폴더를 고릅니다(선택 창에서 새 폴더도 만들 수 있습니다).
2. 그 폴더(또는 git 저장소라면 저장소 루트)를 처음 여는 경우 “이 폴더를 신뢰합니까?” 확인 창이 뜹니다. 안내문과 함께 “evo가 이 폴더의 파일을 읽고 바꾸고, 승인한 명령을 실행할 수 있습니다”가 보입니다. 그 폴더의 .evo/ 설정에 자동으로 실행될 것(hooks, MCP 서버, 언어 서버 명령, 사용자 정의 에이전트)이 있으면 그 목록도 함께 보입니다. .evo/config.local.json의 실행 항목도 같은 목록에 보이고, 그 파일에 permissions·permissionMode 같은 권한 설정이 있으면 권한 설정 (config.local.json) 줄이 더해지고, model이나 모델·서버 주소·키 관련 항목이 있으면 모델·서버·키 설정 (config.local.json) 줄이 더해집니다. 앞의 줄은 그 폴더의 파일이 무엇을 바꾸는지, 뒤의 줄은 대화와 키가 어디로 가는지를 확인 창에서 바로 보게 하기 위한 것입니다.
3. “신뢰하고 열기”를 누르면 세션이 만들어지고, 그 폴더와 하위 폴더는 다음부터 다시 묻지 않습니다. “취소”를 누르면 세션을 만들지 않습니다.

믿을 수 있는 폴더만 엽니다. 신뢰 목록은 앱 데이터 폴더에 저장되며, 홈 폴더나 디스크 루트(/)는 저장되지 않아 매번 다시 묻습니다. 설정 창 권한 탭의 “신뢰한 폴더”에서 신뢰 목록을 하나씩 또는 모두 지울 수 있습니다(지운 폴더는 다음에 다시 묻습니다).

이어 하기

왼쪽 목록에서 열린 세션을 고르면 저장된 대화 기록을 채팅 항목으로 그려 보여주고, 다음에 보내는 입력부터 그 대화를 이어갑니다. 세션을 누르면 기다리지 않고 바로 열리며, 대화 기록은 뒤에서 읽어 도착하는 대로 채웁니다. 기록을 읽는 동안에는 빈 환영 화면 대신 작은 진행 표시가 보입니다. 이미 열어 본 대화를 기억하고 있는 세션은 다시 읽지 않고 그 자리에서 보여 줍니다. 모델, 권한 모드, “이 세션 동안 허용”한 규칙은 세션을 저장할 때의 값을 그대로 되살립니다.

세션 여러 개 열기

• 앱에서 동시에 열어 둘 수 있는 세션은 10개입니다. 11번째를 열려고 하면 열지 않고 “열린 세션은 10개까지입니다. 다른 세션을 닫은 뒤 여세요.“를 알립니다.
• 한 세션은 한 앱 프로세스만 엽니다. 열면 세션 폴더의 잠금을 잡고 닫으면 풉니다. 다른 evo-mac 앱이 잡고 있는 세션은 목록에 “다른 evo-mac에서 사용 중”으로 보이며, 열지 못하고 미리보기만 됩니다.
• 세션 목록에서 닫힌 세션을 한 번 누르면 그 세션을 바로 열지 않고 읽기 전용 미리보기(지난 대화, 입력 칸 자리에 “열기” 단추)로 보여 줍니다. 미리보기는 세션 잠금을 잡지 않고 dispatch에도 알리지 않습니다. 첫 클릭은 다른 클릭을 기다리지 않고 바로 반영됩니다.
• 미리보기에서 더블클릭, Enter, “열기” 단추, 또는 세션 목록 메뉴의 **“세션 열기”**로 그 세션을 열어 대화를 이어 갈 수 있습니다. 더블클릭해도 첫 클릭을 기다리지 않고 바로 열립니다.
• 한 세션이 실행 중이어도 다른 세션을 보거나 열 수 있으며, 실행은 뒤에서 이어 갑니다.

세션 닫기

열린 세션 줄의 × 단추나 세션 목록 메뉴의 “세션 닫기”로 닫습니다. 닫을 때 확인 창은 없습니다. 보던 세션을 닫으면 채팅은 빈 화면으로 돌아가고, 세션은 목록과 기록에 그대로 남습니다. 실행 중인 세션은 닫을 수 없습니다.

세션 지우기

세션 목록 메뉴의 “세션 지우기…“를 고르면 확인 창(“이 세션을 지울까요?”, 단추 “휴지통으로 옮기기”·“취소”)이 뜹니다. 지우면 세션 폴더(대화 기록, 메타 정보, 하위 에이전트 기록)가 macOS 휴지통으로 옮겨져 필요하면 되살릴 수 있습니다. 작업 폴더의 실제 파일과 폴더별 자동 메모리는 지워지지 않습니다.

지울 수 없는 경우와 안내 문구:

• 실행 중: “실행 중에는 세션을 지울 수 없습니다.”
• 다른 evo-mac이 그 세션을 쓰고 있을 때: “다른 evo-mac이 쓰고 있는 세션은 지울 수 없습니다.”
• 그 세션의 백그라운드 작업(하위 에이전트)이 아직 도는 중: “이 세션의 백그라운드 작업이 아직 돌고 있어 지울 수 없습니다. 작업을 멈춘 뒤 지우세요.”
• 휴지통으로 옮기지 못한 경우: 한국어로 이유와 “세션은 그대로 있습니다”를 알립니다(경로 같은 상세 오류 원문은 보이지 않습니다).

복사해 이어 가기

세션 목록 메뉴의 “복사해 이어 가기”를 고르면 지금 세션의 대화 기록을 그대로 복사해 새 세션을 만들고 바로 엽니다. 원본은 바뀌지 않습니다. “이 세션 동안 허용”한 도구와 하위 에이전트 실행 기록은 복사되지 않습니다. 복사한 뒤에는 “세션 <원본 8자>을 복사해 새 세션 <새 8자>에서 이어 갑니다. 원래 세션은 그대로입니다”가 안내되고, 목록에는 <원본 8자>의 복사본 줄이 붙습니다. 다른 앱 창이 쓰고 있는 세션도 복사할 수 있지만, 실행 중인 세션은 복사할 수 없습니다.

세션 잠금 (다른 창·CLI와 겹치지 않기)

한 세션은 한 번에 한 앱 프로세스만 엽니다. 이미 다른 evo-mac(다른 창, 다른 실행본, 개발판 등)이 열어 둔 세션은 목록에 “다른 evo-mac에서 사용 중”으로 표시됩니다. 이런 세션을 고르면 열리지 않고 “이 세션은 다른 evo-mac이 쓰고 있어 열지 않았습니다. 그쪽에서 이어 가거나, 세션 목록의 ’복사해 이어 가기’로 복사본에서 이어 가세요”가 안내됩니다. Evo CLI는 데이터 폴더가 달라 앱 세션과 겹치지 않습니다.

입력 편의

입력창은 일반 텍스트 영역입니다. Enter는 보내기, Shift+Enter(또는 Option+Enter)는 줄바꿈입니다. 한글 등 입력기로 글자를 조합하는 중의 Enter는 조합을 확정할 뿐 보내지 않습니다.

입력 기록

• 보낸 입력(대기열에 넣은 것과 !로 시작한 셸 명령 포함)은 최근 500개까지 저장됩니다. 바로 앞과 같은 입력은 한 번만 남습니다.
• 커서가 입력창 첫 줄에 있을 때 ↑를 누르면 이전 입력을 차례로 불러옵니다. 처음 누를 때 쓰던 글은 따로 기억해 두고, ↓로 최근 입력까지 다시 내려오면 그 글로 돌아옵니다. 입력창이 비어 있고 대기열이 있으면 ↑는(아래 “실행 중 메시지 대기열” 참고) 대기열을 입력창으로 되돌립니다.
• ⌃R(Control+R)로 입력 기록 찾기 칸이 열립니다. 친 글이 들어 있는 가장 최근 입력을 보여주고(없으면 (no match)), ⌃R을 다시 누르면 더 이전 것을 찾습니다. ↩는 찾은 입력을 입력창에 넣고(바로 보내지 않음), Esc는 원래 쓰던 입력으로 돌아갑니다.

긴 글 붙여넣기

4줄(줄바꿈 3번) 이상이거나 500자(유니코드 문자 기준)를 넘는 붙여넣기는 입력창에서 Claude Code와 같은 모양으로 접혀 보입니다. 줄바꿈이 있으면 [Pasted text #1 +41 lines], 한 줄이면 [Pasted text #2]입니다. 보낼 때와 세션 기록에는 원문이 그대로 들어갑니다. 자리표시 바로 뒤에서 ⌫, 바로 앞에서 ⌦를 누르면 그 붙여넣기 전체가 한 번에 지워집니다(사람이 직접 친 같은 모양 글자는 한 글자씩 지워집니다). 붙여넣은 글은 넣을 때 이스케이프 시퀀스를 걷어 내고, CRLF를 LF로 바꾸고, 탭을 공백 4칸으로 펴고, 제어 문자와 방향 표시 문자를 지웁니다.

@ 파일 참조

입력 맨 앞이나 공백·줄바꿈 뒤에서 @를 치면 입력창 위에 세션 작업 폴더의 파일·폴더 목록(최대 8개)이 뜹니다. @ 뒤에 친 글자가 포함된 경로만 걸러져 보이고(이름 앞부분 일치가 가장 먼저), ↑/↓(또는 ⌃P/⌃N)로 고르고 Tab 또는 ↩로 넣습니다. 파일은 @경로 , 폴더는 @폴더/로 들어가며 폴더를 고르면 목록이 그 안으로 바뀝니다. Esc로 닫으면 입력을 바꿀 때까지 다시 뜨지 않습니다. 입력이 /나 !로 시작하면 이 목록이 뜨지 않습니다.

메시지를 보낼 때 @경로마다 그 파일(또는 폴더 안 항목 목록)의 내용이 자료로 함께 전달됩니다. 작업 폴더 밖 경로, .gitignore 대상, 바이너리 파일, 읽기 거절 규칙에 걸리는 파일, 일반 파일이 아닌 것(파이프·소켓 등)은 붙지 않고 대화에 이유가 안내됩니다. @그림.png처럼 이미지 파일을 가리키면 이미지로 붙습니다. 대화에는 ⎿ @main.go (3 lines)처럼 한 줄 요약만 보이고, 세션을 다시 열어도 같은 줄로 보입니다.

! 셸 명령

입력이 !로 시작하면(단, ! 바로 뒤가 숫자이면 평범한 메시지로 취급됩니다 — 예: !131 병합 승인…) ↩를 누르는 즉시 그 명령을 세션 작업 폴더에서 바로 실행합니다. 승인 창을 거치지 않고(직접 친 것이 곧 동의), 세션 권한 모드의 OS 샌드박스 안에서 에이전트 Bash 도구와 같은 규칙(기본 시간 제한 2분, 출력 길이 제한)으로 실행합니다. 대화에는 !명령과 실행 결과 카드가 보이고, 그 결과는 다음에 모델이 보는 사용자 메시지로 저장됩니다(이 명령 자체는 모델이 자동으로 실행하는 것이 아닙니다). 명령이 도는 동안에는 셸 명령도 메시지 보내기도 할 수 없습니다. 0이 아닌 종료 코드로 끝난 명령의 결과 카드는 실패로 표시되고 종료 코드 N이 함께 보이며, 접히지 않습니다.

이미지 첨부

• 붙이는 방법: 입력창 옆 파일 첨부(클립) 단추로 여러 장 고르기, ⌘V 붙여넣기(이미지 데이터·스크린숏·이미지 파일 경로 모두 인식), 채팅이나 입력창에 파일을 끌어다 놓기.
• 이미지가 아닌 파일이나 폴더를 끌어다 놓거나 첨부 단추로 고르면 @상대경로 참조로 입력에 들어갑니다(위 “@ 파일 참조”와 같은 규칙).
• 붙일 때마다 입력창 커서 위치에 [Image #N] 표시가 들어가고, 입력창 위에 작은 그림·파일 이름·크기와 빼기 단추가 보입니다. 보낼 때는 이 표시가 글에 남아 있는 이미지만 전송됩니다.
• PNG·JPEG·GIF·WebP만 받습니다. 긴 변이 2000px·5MB를 넘으면 자동으로 줄여서 보냅니다. 형식이 아니거나 너무 크면(50MB 넘음, 줄여도 5MB 넘음) 붙지 않고 이유가 안내됩니다.
• 실행 중에는 이미지가 붙은 메시지를 대기열에 넣을 수 없습니다(“이미지가 붙은 메시지는 대기열에 넣지 않습니다. 실행이 끝난 뒤 보내세요”).
• 지금 쓰는 모델이 이미지를 받지 못하는 모델이면 보내지 않고 “이 모델은 이미지를 받지 않습니다. 이미지를 받는 모델을 고르거나 이미지 없이 보내세요”가 안내됩니다.

/ 슬래시 명령

입력 전체가 /와 Evo CLI에 있는 명령 이름(대소문자 구분 없음)으로 시작하고 그 뒤가 빈칸이거나 끝이면, 모델에 보내지 않고 같은 일을 하는 메뉴·창을 대신 엽니다. 명령은 입력 기록에 남고 입력창은 비워집니다. 이름과 순서는 Evo CLI /help와 같습니다. 예를 들어 /clear는 대화 지우기(지금 세션을 그 자리에서 비움), /compact [지시]는 대화 압축, /context·/cost·/usage는 컨텍스트와 사용량, /status·/doctor·/memory·/version은 상태와 진단, /goal은 목표 창(set <목표>·status·pause·resume·clear는 창 없이 바로 실행), /model·/model <id>는 모델 보기·바꾸기, /config·/mcp·/provider·/permissions·/agents·/hooks는 설정의 해당 탭, /update는 업데이트 확인(/update --loop는 업데이트로 다시 시작해도 /loop 루프를 이어 감), /persona는 내장 페르소나 목록·적용·해제(/persona <이름>, /persona off), /inbox는 받은 요청, /dispatch는 활성 세션과 보내기(name [<이름>|-]로 이름 보기·바꾸기 포함), /workgroup은 워크그룹 창(create·send [n]·leave [n]은 창을 열어 대상을 고르게 하고, stop·start는 창 없이 그 자리에서 실행하며, create --back은 백그라운드 담당 계획을 보여 줌), /workflow는 워크플로우 메뉴(/workflow <명령> [인자]는 그 자리에서 실행), /loop는 반복 실행(/loop [간격] <내용>·list·stop [n|all]), /recap은 세션이 어디까지 왔는지 한 줄, /restart는 앱을 다시 시작해 이 세션을 다시 염(--loop는 반복 실행을 이어 감), /remote는 원격 제어 호스트 상태(/remote pair는 기기 페어링 안내), /login·/logout, /resume·/resume <id>는 세션 고르기, /exit·/quit는 앱 끝내기, /help는 명령 목록입니다. /vim·/mouse는 “터미널 UI 전용 명령이라 앱에는 없습니다”로 안내됩니다.

모르는 이름(예: /foo)을 치면 “알 수 없는 명령: /foo“와 명령 목록이 안내되고 입력은 지워지지 않습니다. /usr/bin/env처럼 첫 낱말에 /가 또 있으면 경로로 보고 보통 메시지로 보냅니다. 공백 없이 /이름까지만 친 상태에서는 그 이름으로 시작하는 명령 목록이 입력창 위에 뜹니다. Option+Enter를 누르면 /로 시작하는 입력도 명령으로 보지 않고 그대로 모델에 보냅니다. 실행 중에는 세션을 바꾸는 명령(/clear, /compact, /model <id>, /login, /logout, /resume <id>, /goal set·resume·clear)은 “실행이 끝난 뒤에 쓸 수 있습니다”로 안내되고 나머지 명령은 실행 중에도 쓸 수 있습니다.

모델과 provider

모델은 상태 줄의 모델 칩(⌄ 메뉴)에서 고릅니다. 실행 중에는 바꿀 수 없습니다. 목록은 로그인한 계정이 제공하는 evo 모델, 직접 추가한 provider 모델, claude·codex·copilot CLI 래퍼 순서로 묶음을 나누어 보이고, 묶음이 하나뿐이면 머리글이 생략됩니다. 따로 고르지 않으면 로그인 계정의 기본 모델(없으면 목록 첫 모델)을 씁니다. 세션별로 고른 모델이 저장되고, 마지막에 고른 모델은 새 세션의 기본값으로도 쓰입니다.

provider 추가 (개인 계정)

설정 창 모델 탭에서 “provider 추가”를 누르면 종류(Anthropic, OpenAI, OpenAI 호환, Ollama, LiteLLM) → 접속 주소 → API 키(그 주소에 이미 키가 있으면 묻지 않음) → “확인”(실제로 모델 목록을 받아 봄) → 모델 고르기 → “추가” 순서로 진행합니다. 확인에 실패하면 키를 저장하지 않습니다.

• 모델마다 컨텍스트 크기, 자동 압축 토큰 수, 이미지 지원 여부(받음·안 받음·모름), 입력·출력 가격을 고치거나 지울 수 있습니다.
• API 키는 macOS 키체인에 저장됩니다(설정 파일에 평문으로 남지 않습니다). 키를 찾는 순서는 환경 변수 → 키체인 → (직접 손으로 써 넣은 경우만) 설정 파일입니다. 화면에는 실제 키 대신 “환경 변수 이름” · “키체인” · “설정 파일” · “없음” · “필요 없음”만 보입니다.
• 로그인 모델과 내가 추가한 모델의 id·주소가 같으면 로그인 키로 합쳐 쓰고, 다르면 로그인 모델에 evo/<id>라는 별도 이름이 붙습니다.
• 조직 계정으로 로그인하면 이 탭에는 “조직 설정(<이름>)을 사용 중입니다…“만 보이고 내 provider는 추가할 수 없습니다. (조직 로그인 중에도 개인 로그인 provider는 추가할 수 있습니다.)

agent CLI 래퍼 (claude · codex · copilot)

개인 계정으로 로그인했을 때만, 다른 회사의 agent CLI를 evo의 “모델”처럼 쓸 수 있습니다. 모델 탭의 스위치로 각각 켭니다.

• claude CLI 래퍼: 컴퓨터에 설치되어 로그인까지 되어 있는 claude CLI(버전 2.1.305 이상 2.2.0 미만)를 모델로 씁니다. 스위치를 켤 때 claude를 찾고 버전과 로그인 상태를 차례로 확인합니다. 로그인이 안 되어 있으면 켜지지 않고, 대신 선택한 세션의 터미널 칸에 로그인 명령이 입력된 상태로 보여줍니다. 모델 메뉴에는 claude CLI가 알려주는 모델 이름(“claude CLI” 묶음)으로 보입니다. claude는 evo가 내주는 도구만 쓰고, 모든 도구 실행은 evo의 권한 확인(승인 창·권한 모드)을 그대로 거칩니다.
• Codex CLI 래퍼(시험용): Codex CLI(버전 0.142.4 이상 0.143.0 미만)를 Ollama 서버의 모델로 돌립니다. OpenAI 로그인은 쓰지 않습니다. Ollama 서버에서 받은 모델마다 codex/<모델>이라는 행이 생깁니다.
• Copilot CLI 래퍼(시험용): GitHub Copilot CLI(버전 1.0.80 이상 1.1.0 미만)를 Ollama 서버의 모델로 돌립니다. GitHub 로그인·통신은 쓰지 않습니다. 모델은 copilot/<모델>로 나타납니다.
• 세 래퍼 모두 생각 모드·생각 수준 설정을 그대로 전달하고, 첫 질문 전에 CLI 프로세스를 미리 띄워 둬 답이 빨라지게 합니다. 실행을 멈추면 CLI 프로세스를 끝내지 않고 그 CLI의 “중단” 기능으로 그 턴만 멈춥니다.
• claude 래퍼는 claude CLI가 알려주는 비용 증가분을 세션에 누적해 ≈$0.0348처럼 ≈ 기호와 함께 보여줍니다. 이 값은 API 정가 기준이라 구독으로 쓰는 경우 실제 청구액과 다를 수 있다는 안내가 함께 붙습니다.

내장 페르소나(역할)

/persona로 이번 세션의 역할을 하나 골라, 모델이 그 역할의 관점으로 답하게 할 수 있습니다. Evo 프로그램(CLI·앱)이 같은 목록·같은 글을 쓰는 내장 역할만 있으며, 사용자가 직접 정의 파일로 더할 수는 없습니다.

• /persona는 분야를 먼저 고르고 그 분야의 역할을 고르는 시트를 엽니다. 첫 화면에 지금 역할이 있는 분야에 커서가 있고, 분야를 열면 역할과 그 영어 설명이 나옵니다. 역할을 두 번 누르거나 골라 “적용”하면 그다음 메시지부터 반영됩니다. “분야로”로 한 단계 돌아갑니다.
• /persona list는 지금 역할과 분야별 역할 목록을 대화에 그대로 보여 줍니다. /persona <이름>으로 바로 적용하고, /persona off(또는 /persona none)로 해제합니다. 적용·해제는 “페르소나: 이름 (다음 메시지부터)“처럼 알려 주며, 그다음 메시지부터 반영됩니다.
• 역할은 시스템 프롬프트에 덧붙는 짧은 지시일 뿐입니다. 이 세션의 규칙·권한 규칙·권한 모드, 사용자가 분명히 한 지시를 넘지 않습니다. 하위 에이전트에는 적용되지 않습니다.
• 고른 역할은 세션 기록에 남아, 세션을 닫았다 열거나 대화를 이어 가도 유지됩니다.
• 워크그룹과의 관계: 그룹 멤버의 지금 역할이 목록과 받은 요청에 함께 보이고, 역할이 없는 세션은 그룹 요청을 스스로 실행하지 않습니다(워크그룹 참고).

0.2.8부터 내장 역할은 11개 분야 36종입니다.

분야	역할
지휘 (lead)	orchestrator — 사용자와의 단일 창구: 일을 나누어 다른 역할에게 넘기고, 담당이 막히면 담당이 스스로 풀도록 이끎(대신하지 않음)
기획·설계 (planning & design)	architect — 소프트웨어 설계자: 구조·인터페이스·데이터 흐름·트레이드오프 planner — 제품 기획자: 요구사항·범위·수용 기준
개발 (development)	developer-backend-go — Go 백엔드: 단순함·오류 처리·동시성 developer-backend-java — Java/Spring 백엔드: API·트랜잭션·테스트 developer-backend-node — Node.js 백엔드: API·비동기·테스트 developer-backend-python — Python 백엔드: API·타이핑·테스트 developer-front-react — React 프런트엔드: 컴포넌트·상태·접근성 developer-front-vue — Vue 프런트엔드: 컴포넌트·반응성·접근성 developer-mobile-android — Android 모바일 개발자: Kotlin·Jetpack·Gradle 빌드 developer-mobile-ios — iOS 모바일 개발자: Swift·SwiftUI/UIKit·Xcode 빌드 publisher — 웹 퍼블리셔: 시맨틱 HTML·CSS·반응형 레이아웃·브라우저 호환
디자인 (design)	designer-uiux — UI/UX 설계자: 사용 흐름·화면·접근성
품질·보안 (quality & security)	tester — 테스트 엔지니어: 시험 사례·경계·회귀 verifier — 검증자: 요구사항 대비 검토와 근거 security — 보안 엔지니어: 위협·취약점·비밀정보
운영 (operations)	devops — DevOps 엔지니어: CI/CD·컨테이너·관측성 network-engineer — 네트워크 엔지니어: 라우팅·방화벽·VPN·DNS·문제 해결 system-engineer — 시스템 엔지니어: 서버·OS·저장소·백업·모니터링
문서·글쓰기 (writing)	technical-writer — 기술 문서 작성자: 안내서·참조·README·릴리스 노트 report-writer — 보고서·제안서 작성자: 구조·근거·요약
번역 (translation)	translation-pm — 번역 프로젝트 관리자(리드): 범위·언어·용어집과 번역–감수–검토–교정 단계, 납품 translator — 번역·교정자: 충실한 번역·용어·교정 reviser — 감수자: 원문과 문장별로 대조하는 이중언어 검사(오역·누락·용어) translation-reviewer — 번역 검토자: 대상 언어로만 읽어 자연스러움·분야 정확성·독자 적합성 proofreader — 교정자: 납품 전 마지막 확인(오탈자·띄어쓰기·문장부호·서식·숫자) terminologist — 용어 담당자: 언어쌍별 프로젝트 용어집·금지어·스타일 가이드
데이터·분석 (data)	data-analyst — 데이터 분석가: 질문·SQL·지표·근거 있는 결론 data-engineer — 데이터 엔지니어: 파이프라인·스키마·데이터 품질 ml-engineer — 머신러닝 엔지니어: 특징·학습·평가·서빙
비즈니스 (business)	product-manager — 제품 관리자: 문제·우선순위·로드맵·성과 지표 business-analyst — 비즈니스 분석가: 프로세스·요구사항·격차 분석 marketer — 마케터: 포지셔닝·메시지·콘텐츠·캠페인 customer-support — 고객 지원: 답변·문제 해결·FAQ·에스컬레이션
공공·산출물 (public sector)	public-deliverables — 공공 정보화 사업 산출물 작성자: 요구사항 정의서·설계서·방법론 준수 audit-responder — 감리 대응자: 감리 지적·개선 조치·증적

목록 화면에는 각 역할 옆에 위 설명의 영어 한 줄이 그대로 나옵니다.

권한 모드와 자동 모드

권한 모드는 상태 줄의 방패 모양 칩에서 고르며 세션마다 따로 저장됩니다. 화면에 보이는 이름은 Evo CLI와 같은 다섯 가지입니다(메뉴에는 CLI와 같은 한 줄 설명이 붙습니다).

모드	동작
default mode (기본)	읽기만 하는 작업은 바로 하고, 파일 변경·명령 실행은 승인을 묻습니다
edits mode (파일 편집 허용)	작업 폴더 안 파일 편집은 묻지 않고 하며, 그 밖은 default와 같습니다
plan mode (계획, 읽기 전용)	읽기만 하고, 무엇이든 바꾸는 도구 호출은 거절합니다
auto mode	edits mode와 같이 동작하되, 그 밖의 애매한 호출은 분류기 모델이 자동으로 허용·차단을 판단합니다 (아래 “자동 모드” 참고)
yolo mode (묻지 않기)	아무것도 묻지 않고 실행합니다. 위험을 이해하고 신중하게 씁니다

새 세션의 기본 권한 모드는 auto mode입니다. 이미 있는 세션을 열면 저장해 둔 모드를 그대로 씁니다. 설정 창에서 새 세션의 기본 모드를 default·edits·plan·auto 중에서 바꿀 수 있습니다(yolo mode는 새 세션 기본값으로 고를 수 없습니다).

yolo mode로 바꿀 때는 확인 창이 먼저 뜹니다. 선택지는 “아니오, 취소”(기본값, Enter로 바로 수락되지 않음) · “예, 위험을 이해했습니다” · “예, 다음부터 묻지 않기”입니다. 마지막을 고르면 사용자 설정에 그 선택이 저장되어 다음부터는 확인 없이 바로 yolo mode로 바뀝니다(설정 목록의 “yolo mode 확인 생략”으로 다시 켤 수 있습니다). 관리자가 조직 정책으로 yolo mode 자체를 막아 두었으면 메뉴에서 고를 수 없습니다.

자동 모드(auto mode)

• auto mode에서는 권한 규칙과 모드로 정해지지 않아 “사람에게 물었을” 도구 호출만 분류기(같은 세션 모델, 또는 따로 지정한 분류 모델)가 판단합니다. 거부(deny)·항상 묻기(ask) 규칙은 분류기가 뒤집지 못합니다.
• 분류기는 최근 사용자 메시지, 최근 도구 호출, 지금 판단할 호출을 보고 allow 또는 block과 이유를 한 번만 답합니다. 답이 비거나 이상하면 판단 실패로 보고 사람에게 묻습니다.
• 같은 세션 안에서 같은 도구·같은 입력은 한 번 허용되면 다시 묻지 않고 기억합니다. 단, 작업 폴더 밖 경로를 쓰는 호출이나 차단·오류가 난 호출은 기억하지 않습니다. 새 메시지를 보내면 그 전까지의 허용 기억이 비워집니다.
• 차단 한도가 있습니다: 연속 3번 또는 세션 누적 20번 차단되면 그 세션은 그 즉시 default mode로 돌아가고(실행 중이면 남은 호출부터 default 규칙으로 바뀜) 알림이 뜹니다. 다시 auto를 고르면 횟수가 초기화됩니다.
• 도구 카드에는 auto 허용: …, auto 차단: …(빨간색), auto가 판단하지 못해 묻습니다: …가 표시됩니다.
• 판단은 확률적인 보조 수단이며 보안 경계가 아닙니다. 되돌릴 수 없는 작업은 deny·ask 규칙으로 따로 막아 둬야 합니다.

OS 샌드박스

권한 모드에 따라 셸 명령이 실행되는 범위가 macOS sandbox-exec로 제한됩니다.

모드	샌드박스 정책
default · edits mode · auto mode	workspace-write: 세션 작업 폴더와 임시 폴더에만 쓸 수 있습니다
plan mode	read-only: 쓰기가 전혀 허용되지 않습니다
yolo mode	샌드박스 없음(off)

세션 폴더 안의 .evo 폴더(권한·설정을 담는 폴더)는 workspace-write에서도 쓰기가 거부됩니다. 샌드박스 안에서는 .git/hooks·.git/config·.git/commondir에도 쓸 수 없고, .git 항목 자체를 바꾸거나 옮길 수 없습니다(그 안의 다른 파일 쓰기와 git add·git commit은 됩니다). 그래서 샌드박스 안에서는 git config·git push -u처럼 설정을 쓰는 명령이 실패합니다. 샌드박스를 쓸 수 없는 환경이면 샌드박스 없이 실행하되 출력 뒤에 (sandbox unavailable: …)가 붙어 알 수 있습니다. 상태 줄의 모드 칩에 마우스를 올리면 지금 샌드박스 상태 설명이 보입니다. 사용자가 직접 쓰는 터미널 칸의 셸, MCP 서버, 네트워크 접근은 이 샌드박스의 영향을 받지 않습니다.

도구 실행 승인과 권한 규칙

에이전트가 파일을 바꾸거나 명령을 실행하려 할 때, 권한 모드가 바로 허용하지 않으면 승인 시트가 뜹니다. 도구 이름, 실행할 명령(또는 바꿀 파일), 묻는 이유가 보이고, 다음 중 하나를 고릅니다.

Edit·Write를 물을 때는 입력 글(file_path: …) 대신 머리줄(<경로> +A −D)과 바뀔 내용의 diff가 보입니다. 지운 줄은 빨간 띠, 더한 줄은 초록 띠로 표시되고, 아직 적용 전이라 승인을 기다리는 diff는 흐리지 않게 보입니다. 그 밖의 도구는 지금처럼 명령이나 입력 글을 보입니다.

• 거부: 실행하지 않습니다.
• 이 세션 동안 허용: 제안된 규칙(예: Bash(npm install:*))을 보여주고, 고르면 지금 세션 동안은 같은 호출을 다시 묻지 않습니다.
• 한 번 허용: 이번 호출만 허용합니다.

기본으로 선택된 버튼은 없어서 Enter를 눌러도 실수로 승인되지 않습니다. Esc는 거부와 같습니다. “이 세션 동안 허용” 뒤에는 “항상 허용: <규칙>“을 “이 프로젝트에서” 또는 “모든 프로젝트에서” 저장할 수 있는 선택지도 함께 보입니다. 저장하면 채팅에 저장된 곳이 안내됩니다.

세션 허용(또는 “항상 허용”)으로 넘어갈 수 없는 승인도 있습니다: 관리자나 사용자가 “항상 묻기(ask)“로 정한 규칙, hook이 승인을 요구한 경우, .evo 폴더 안의 설정·신뢰 목록·에이전트 정의 파일을 고치는 쓰기, .git 안(경로 조각에 .git이 있는 곳)에 쓰는 것, 다른 도구가 코드를 실행하는 자리에 쓰는 것, 작업 폴더 밖에서 실행하는 셸 명령입니다. 이런 경우에는 “이 세션 동안 허용”·“항상 허용” 선택지가 보이지 않고 “한 번 허용”과 “거부”만 있습니다.

권한 규칙

설정 창 권한 탭에서 허용(allow)·묻기(ask)·거부(deny) 규칙을 추가·삭제할 수 있습니다. 범위는 이 세션(앱 메모리, 앱을 끄면 사라짐) · 이 프로젝트(<세션 폴더>/.evo/config.local.json) · 모든 프로젝트(사용자 설정) 중에서 고릅니다. 규칙 문법 예:

• 셸: Bash(npm run test:*)(앞부분 일치), Bash(git log * main)(glob)
• 경로: Edit(src/**)(작업 폴더 기준), Read(//etc/**)(절대 경로)
• WebFetch(domain:<호스트>)

평가 순서는 거부 → 묻기 → 보호 설정 파일 → .git 안 쓰기 → 코드가 실행되는 자리 → 권한 모드 → 작업 폴더 밖 셸 명령 → 세션 허용 → 허용 → (그 밖에는) 묻기입니다. 이 탭에는 범위별로 등록된 규칙 목록과 관리자가 정한 규칙(읽기만 가능)도 함께 보입니다. “신뢰한 폴더” 목록도 같은 탭에 있습니다(위 “새 세션 만들기” 참고).

• 경로 규칙과 링크: Read·Edit·Write·Glob·Grep의 경로 규칙은 적은 경로와 링크를 풀어 실제 경로도 함께 봅니다. 거부·묻기 규칙은 둘 중 하나만 맞아도 적용되고, 허용 규칙은 둘 다 맞을 때만 허용합니다. 그래서 docs가 secrets를 가리키는 링크여도 Read(secrets/**) 거부가 docs/…에 적용됩니다.
• .git 안 쓰기: 경로 조각에 .git(대소문자 무관)이 있는 곳에 Write·Edit·NotebookEdit로 쓰면 권한 모드·allow 규칙·세션 허용과 관계없이 늘 묻습니다. git이 그 자리의 설정과 훅을 git status·git diff에서도 실행하기 때문입니다. Windows가 .git으로 받는 형태(끝의 점·공백, :스트림 꼬리, 짧은 이름)도 같게 봅니다.
• 코드가 실행되는 자리: 작업 폴더 안이라도 다른 도구가 코드를 실행하는 파일에 쓰면 늘 묻습니다(에이전트·편집기 설정 폴더, git 설정 파일과 core.hooksPath 폴더, .envrc, lefthook*, 빌드 파일, 이름이 무엇이든 Gradle 스크립트, mypy.ini·.pylintrc·setup.cfg·tox.ini·rust-analyzer.toml 같은 검사기 설정, 언어 서버가 불러오는 node_modules·.venv·.yarn·.pnp, 지침 파일 등). yolo·plan mode는 자기 판정을 따릅니다.
• 읽기 전용 셸 명령의 범위: 묻지 않고 허용되는 읽기 전용 명령은 범위가 정해져 있습니다. cd는 작업 폴더 안의 폴더 하나로만 가고(cd ~·두 번 이상의 cd는 묻습니다), git은 작업 폴더의 저장소에서만 묻지 않습니다. Read(…) 거부·묻기 규칙이 하나라도 있으면 읽기 전용 명령도 묻습니다.
• 도구 입력의 키 이름: 도구 입력의 키가 정의와 대소문자만 다르면(예: File_path) 실행하지 않고 invalid input: key "File_path" must be spelled "file_path" 오류로 알립니다.
• 승인한 파일에만 쓰기: Write·Edit은 권한 검사가 본 실제 파일에만 씁니다. 검사 뒤에 경로가 바뀌면(중간 폴더가 링크가 되는 등) 아무것도 쓰지 않고 the path changed after it was checked로 거절합니다.

판정 기록과 승인율

모든 승인·거부·자동 판단은 세션 파일에 도구 이름과 판정 결과만(명령어·경로·내용은 남기지 않음) 기록됩니다. 설정 창 권한 탭의 “판정 기록”에서 선택한 세션의 허용·거부·물음 수와 승인율(허용 N, 거절 N, 물음 N(승인 N, 거절 N) · 승인율 80.0% (4/5))을 볼 수 있고, “모든 세션 세기”로 앱의 모든 세션을 합친 통계와 도구별 집계도 볼 수 있습니다. 상태와 진단 창에도 지금 세션의 같은 수치가 보입니다.

모드 추천

권한 모드 메뉴의 “모드 추천…”(세션이 있고 실행 중이 아닐 때 보임)을 누르면, 분류 모델이 최근 사용자 입력과 쓴 도구를 보고 default · edits mode · plan mode 중 하나와 이유를 추천합니다. 결과 창에서 “이 세션에 적용”을 눌러야만 그 세션의 모드가 바뀝니다(설정에는 남지 않음). 지금 모드와 같거나 실행 중이면 적용할 수 없습니다.

도구 결과 크기와 호출 안내

• Read 결과는 파일 내용 전체를 합쳐 100,000자까지 모델에 전달합니다(0.2.7부터 Evo CLI와 같은 상한). 그보다 길면 그 자리에서 자르고 [output truncated at 100000 characters]를 덧붙입니다. 한 줄 길이에는 따로 상한이 없고, 읽지 않은 줄이 남으면 [showing lines a-b of n; pass offset/limit to read more]로 알려 줍니다.
• 한 답에 도구를 하나씩 부르는 답이 3번 이어지면, 다음 단계가 서로의 결과에 기대지 않을 때는 여러 도구를 한 답에 함께 부르거나 Bash로 잇으라는 안내 한 줄((guidance: …))이 결과 뒤에 붙습니다. 실행 한 번에 한 번만 붙고, 실행·권한 판단·결과 형식은 바뀌지 않습니다.
• 셸 명령으로 파일을 읽는 호출(예: cat·sed)이 한 실행에서 5번 쌓이면, 파일을 읽을 때는 Read·Grep을 쓰라는 안내가 붙습니다(0.2.8). 실행을 막지는 않습니다.

다음 질문 제안

실행이 성공적으로(중단·오류 없이) 끝나면 같은 모델로 짧은 호출을 한 번 더 해 사용자가 다음에 입력할 만한 문장을 만들고, 입력창이 비어 있는 동안 그 자리에 흐리게 보여줍니다. Tab 또는 →로 입력창에 채울 수 있고(바로 보내지는 않음), 입력창에 글을 쓰면 숨었다가 다 지우면 다시 보입니다. 보내기, Esc, 다른 세션 고르기, 새 실행 시작, 설정에서 끄기로는 제안이 버려지고, 답이 늦게 왔을 때 입력창에 글이 있으면 그 답도 버립니다. 목표(Goal)가 진행 중이거나, 대기열에 메시지가 남아 다음 실행이 바로 이어지거나, 설정에서 꺼 두었으면(기본은 켜짐) 제안하지 않습니다. 이 호출에 쓴 토큰은 세션 사용량에 포함되지만 세션 파일에는 저장되지 않습니다.

목표(Goal) 기능

목표 기능은 사람이 매번 다음 지시를 주지 않아도 에이전트가 스스로 턴을 이어가며 목표를 향해 작업하게 하는 자율 루프입니다.

• 대화 메뉴 “목표(Goal)…”(⌘⇧G)에서 목표 글을 적고 “목표 정하고 시작”을 누릅니다.
• 목표가 진행 중일 때 모델이 도구 없이 답을 마치면 그때마다 검증기(별도 모델 호출)가 “met(달성)·not_met(미달성)·impossible(불가능)·waiting(사용자 답 대기)” 중 하나로 판단합니다. 미달성이면 계속하라는 지시가 자동으로 다음 턴에 들어가고, 달성이면 목표가 끝나며, 불가능이면 멈춥니다.
• 사용자 답 대기: 모델의 마지막 답이 사용자의 답·확인·결정을 기다리는 상태면 에이전트가 대신 답할 수 없으므로 검증기가 waiting으로 판단하고 목표를 멈춥니다. 이때는 혼자 계속 돌지 않고, 사용자가 다음 메시지를 보내면 그 목표가 이어집니다. 사용자가 직접 멈춘 목표는 메시지를 보내도 다시 돌지 않습니다(목표 창의 “다시 시작”으로만 재개).
• 모델은 propose_goal(목표 제안)·get_goal(상태 확인)·update_goal(완료·막힘 보고) 세 가지 도구를 쓸 수 있습니다. 모델이 스스로 목표를 제안해도 바로 시작되지 않고, 사용자가 “모델이 목표를 제안했습니다” 승인 창에서 승인해야만 목표가 정해지고 시작됩니다. 이 승인은 권한 모드나 규칙으로 건너뛸 수 없습니다.
• 예산: 토큰(기본 3천만)·턴 수·활성 시간에 상한을 둘 수 있고, 검증에 쓸 모델도 따로 지정할 수 있습니다(설정 창 일반 탭 “목표 토큰 예산”·“목표 검증 모델”). 예산을 다 쓰면 한 번 인계 턴을 준 뒤 다음 멈춤에서 멈춥니다.
• 목표 창의 표시: 검증 이유는 줄바꿈을 공백으로 바꾼 한 줄로 보여 주고 160자를 넘으면 뒤를 생략합니다. “활성 시간” 줄은 12m3s / 1h0m0s처럼 쓴 시간과 상한을 보여 주며, 목표가 진행 중이고 세션이 실행 중이면 1초마다 늘어납니다(멈춘 세션·꺼 둔 동안은 늘지 않음).
• 목표 창에서 멈춤·다시 시작·지우기를 할 수 있고, 실행 중지 버튼을 누르면 진행 중인 목표도 함께 멈춥니다. 대화 중에는 목표가 정해짐·검증 결과·달성·멈춤·막힘 같은 상태 줄이 보이고, 상태 줄에는 목표 칩이 ◎ goal 12m(진행 중, 활성 시간)·◎ goal waiting(사용자 답 대기)·◎ goal paused(그 밖의 멈춤)로 붙습니다.
• 하위 에이전트(아래)로 실행하는 작업에는 목표 기능이 적용되지 않습니다.

하위 에이전트 (subagent·작업)

하위 에이전트는 메인 대화와 별도의 작업 지시를 받아 따로 돌아가는 작은 에이전트입니다.

• 정의 파일: 사용자 전체에 적용되는 정의는 앱 데이터 폴더의 agents/*.md, 프로젝트 전용 정의는 세션 폴더의 .evo/agents/*.md에 둡니다(이름이 같으면 프로젝트 정의가 우선). 각 파일은 머리 부분에 이름·설명(필수)·쓸 수 있는 도구를 적고, 그 아래에 그 하위 에이전트의 시스템 프롬프트를 적습니다. 정의 파일 하나라도 형식이 잘못되면 그 실행에서는 하위 에이전트 기능 전체가 빠지고 이유가 안내됩니다.
• 내장 하위 에이전트: 정의 파일이 없어도 general-purpose 하위 에이전트는 늘 쓸 수 있습니다. 코드 검색·조사·여러 단계 작업을 혼자 처리하고 여러 개를 동시에 돌릴 수 있으며, Agent 도구를 뺀 모든 내장 도구를 씁니다. 같은 이름(general-purpose)의 정의 파일이 있으면 그 파일이 이 내장 정의를 대신합니다.
• 모델은 Agent 도구로 하위 에이전트를 부릅니다(이름, 지시, 짧은 설명, 백그라운드 여부). 모르는 이름을 부르면 쓸 수 있는 이름 목록과 함께 오류가 됩니다.
• 백그라운드(기본값): 바로 “작업을 시작했습니다”가 안내되고 뒤에서 돌아갑니다. 메인 대화를 멈춰도 하위 에이전트는 계속 돕니다. 동시에 20개까지 돌 수 있습니다. 끝나면 다음 실행에서 모델을 부르기 직전에 결과(완료·실패·취소)가 알려집니다.
• 앞에서 실행: 끝날 때까지 기다려 마지막 답을 그 자리에서 돌려받습니다.
• 실행 현황 칸(입력창 위)에 돌고 있는 하위 에이전트마다 이름·할 일·지금 쓰는 도구·토큰·경과 시간이 한 줄로 보이고, 백그라운드 줄에는 멈춤 버튼이 있습니다. 대화에는 작업 시작·완료·실패·취소 줄이 보입니다.
• 하위 에이전트는 메인 대화 내용을 보지 않고, 그 세션의 지금 권한 모드·규칙·세션 허용을 그대로 쓰며, 승인이 필요한 호출은 물을 수 없어 거부됩니다(권한 규칙으로 미리 허용해 둬야 합니다). 하위 에이전트끼리 더 중첩해서 부를 수는 없습니다.
• 설정 창 에이전트 탭에서 선택한 세션 폴더 기준의 정의 목록, 정의 파일 문제, 폴더 열기를 확인할 수 있습니다.

실행 중 메시지 대기열

실행 중에 Enter를 누르면 메시지가 바로 가지 않고 대기열에 쌓입니다. 입력창 위에 “대기 중 N개 (↑ 고치기 · ⌘↩ 바로 보내기)“와 메시지 미리보기(최대 3개, 나머지는 “… +N개 더”)가 보입니다.

• 쌓인 메시지는 실행이 끝날 때까지 기다리지 않고, 모델을 부르기 직전마다(도구 실행이 끝난 뒤에도) 그때까지 쌓인 것을 모두 순서대로 넣습니다.
• 입력창이 비어 있을 때 ↑를 누르면 쌓인 메시지 전체가 한 줄씩 입력창으로 되돌아와 고칠 수 있습니다(대기열은 비워짐). 다시 Enter를 누르면 한 메시지로 다시 쌓입니다.
• ⌘↩(바로 보내기)는 쌓인 메시지와 지금 입력 중인 글을 하나로 합쳐, 실행 중이면 그 실행을 멈추고 새 메시지로 바로 시작합니다.
• 이미지·@ 파일·! 셸 명령이 든 메시지는 대기열에 넣을 수 없고, 실행이 끝난 뒤에 보내야 합니다.

되풀이 실행과 세션 요약

/loop — 같은 요청을 일정 간격으로 되풀이

/loop는 프롬프트나 슬래시 명령을 이 세션에서 일정 간격으로 되풀이합니다(0.2.8).

• 거는 법: /loop 5m <내용> 또는 /loop <내용> every 5m처럼 씁니다. 간격은 초·분·시간·일(s·m·h·d, 초·분·시간·일)로 쓰고, 생략하면 10분이며 1분보다 짧게 주면 1분으로 맞춥니다. 처음 한 번은 그 자리에서 바로 실행합니다.
• 보고 멈추기: /loop list로 도는 루프를 보고, /loop stop [n|all]로 하나 또는 모두 멈춥니다(번호를 생략하면 가장 최근 것).
• 한도: 한 세션에 10개까지 걸 수 있고, 루프 안에서 다시 루프를 걸 수는 없습니다. 세션을 닫거나 7일이 지나면 끝납니다.
• 세션이 바쁠 때: 차례가 되었는데 세션이 실행 중이면 5초마다 다시 확인해 실행이 끝난 뒤 넣습니다.
• 업데이트·재시작: /update --loop·/restart --loop로 앱을 다시 시작해도 걸어 둔 루프가 이어집니다(/restart는 이 세션을 다시 열어 잇습니다).
• 알림 줄과 목록에는 긴 프롬프트의 첫 줄만 짧게 보입니다.

/recap — 세션이 어디까지 왔는지 한 줄

• /recap은 지금 세션의 진행 중인 일·한 것·남은 것을 한 줄로 요약해 보여 줍니다.
• 3분 넘게 앱을 비웠다 돌아오면 앱이 백그라운드에서 미리 만들어 두었다가 같은 자리에 보여 줍니다. 사용자 프롬프트가 3개 이상인 세션에서만 만듭니다.
• 이 줄은 세션 파일에 쓰지 않고 모델도 보지 못합니다. ※ recap: … 꼴의 한 줄로, 400자를 넘으면 줄여서 보여 줍니다.
• 자리 비움 요약이 필요 없으면 설정 일반의 “자리 비움 요약”(ui.awaySummary)을 false로 두거나 EVO_AWAY_SUMMARY를 0·false·off로 두고 앱을 시작합니다. 끄면 돌아와도 자동 요약이 뜨지 않습니다.

압축·컨텍스트·사용량

입력창 아래 상태 줄에 모델 | 모드 | ctx 12% 15.7K/131K | ↑12.3K ↓678과 같은 정보가 항상 보이고, 실행 중이면 turn 3·run 4.5s가 덧붙습니다. 대화가 압축 시점의 90%를 넘으면 · compact soon이 붙습니다.

• 자동 압축: 대화가 모델 컨텍스트 크기(또는 설정한 토큰 수)의 일정 비율(기본 85%)을 넘기기 전에 자동으로 오래된 내용을 요약합니다. 연속 3번 실패하면 그 세션은 자동 압축을 끄고, 성공하거나 세션을 새로 열면 다시 켜집니다. 모델이 “대화가 너무 길다”고 답하면 한 번 압축하고 같은 턴을 다시 보냅니다. 0.2.8부터는 압축 1단계에서 오래된 도구 호출 입력의 긴 글도 줄이고, 모델이 알려 준 마지막 호출 토큰을 Evo CLI와 같은 조건으로 판단합니다.
• 수동 압축(대화 메뉴 “대화 압축…”, ⌘⇧K): 지금 대화를 압축한 새 세션을 만들어 그리로 옮겨 줍니다(같은 폴더·모델·모드, 제목도 그대로). 이전 세션은 목록에 그대로 남습니다. 요약 지시를 적어 넣을 수도 있습니다.
• 대화 지우기(대화 메뉴 “대화 지우기”, ⌥⌘K): 지금 세션을 그 자리에서 비웁니다. 세션 목록의 그 줄이 그대로 남고 새 세션이 생기지 않으며, 세션 id·작업 폴더·모델·권한 모드도 그대로입니다. 지우기 전에 자동 메모리를 먼저 저장하고, 저장하지 못하면 “자동 메모리를 쓰지 못했습니다: <사유>“를 덧붙여 알립니다. 지운 뒤에는 “대화를 지웠습니다. 지금 세션에서 빈 대화로 이어집니다.“가 안내됩니다.
  • 대화 기록은 첫 머리줄만 남기고 비웁니다. 세션 제목과 “이 세션 동안 허용”한 도구, 앱이 기억하던 그 세션의 상태(목표, 검색 예산, 사용량, 자동 압축 실패 수, auto 모드의 연속 차단 수, 다음 질문 추천)도 처음으로 돌아갑니다. 하위 에이전트 실행 기록과 dispatch 이름은 남습니다.
  • 실행 중이거나 압축 중에는 쓸 수 없습니다. /help와 입력창의 명령 목록에도 “대화 지우기 (지금 세션을 그 자리에서 비웁니다)“로 나옵니다.
  • 대화를 요약해 새 세션으로 옮기는 “대화 압축…“과는 다릅니다. 압축은 이전 세션을 목록에 그대로 남기고 새 세션으로 이어 갑니다.
• 컨텍스트와 사용량 창(상태 줄의 ctx·토큰 칩을 누르면 열림): 컨텍스트 크기 출처, 대화 토큰과 비율, 지침 파일 크기, 압축 시점 설명, 세션의 입력·출력 토큰 합계와 예상 비용(모델에 가격 정보가 있을 때만 계산됩니다, $1,234.5678 형식)을 보여줍니다.

터미널 칸

터미널 칸은 두 가지 용도로 나뉩니다.

• 셸 탭(“셸 1”, “셸 2”, …): 사용자가 직접 쓰는 진짜 로그인 셸입니다. 세션 작업 폴더에서 열리고, 탭 옆 +로 더 열 수 있습니다. 세션을 바꾸거나 다른 칸을 봐도 셸은 계속 살아 있다가 앱을 끄면 끝납니다. 셸이 끝나면 머리줄에 종료 코드가 보이고 ↻로 다시 엽니다. 이 셸의 입력·출력은 모델에 전혀 전달되지 않으며, 에이전트는 이 셸을 쓰지 않습니다.
• 에이전트 탭: 모델이 Bash 도구로 실행하는 명령이 실제 터미널(PTY)에 그대로 보이는 탭입니다. 명령이 입력을 기다리면(출력이 0.6초 이상 멈추고 마지막 줄이 비밀번호·[y/N] 같은 질문 형태일 때) 터미널 칸이 저절로 열리고 이 탭으로 바뀌며, 채팅 입력창 위에도 안내가 보입니다. 이때 사용자가 직접 입력한 값은 그 명령에만 전달되고 모델에는 가지 않습니다(모델에는 제어 문자를 지운 출력과 종료 코드만 전달됩니다).
• 터미널 칸은 앱을 켤 때마다 접힌 상태로 시작하고(에이전트 명령이 입력을 기다리면 저절로 열림), 도구 막대의 “터미널” 단추나 보기 메뉴로 여닫습니다.
• 셸은 $SHELL → 계정 셸 → /bin/zsh 순서로 고르고, 로그인 셸(-l)로 실행해 Finder에서 연 앱에서도 사용자 PATH를 쓸 수 있게 합니다.

브라우저 칸

에이전트가 만든 웹 페이지를 앱을 벗어나지 않고 바로 볼 수 있는 칸입니다. 저절로 열리지 않고, 다음 두 경우에 채팅 아래 안내 띠로 묻습니다.

• 에이전트가 .html·.htm 파일을 쓴 경우: “웹 페이지를 만들었습니다: index.html — 브라우저 칸에서 열까요?”
• 셸 명령 출력에 http://localhost:포트(또는 127.0.0.1·0.0.0.0·[::1]) 주소가 나온 경우

“열기”(⌘⇧O)를 누르면 터미널 칸 오른쪽에 브라우저 칸이 열리고 그 페이지가 보입니다. “아니요”면 묻지 않고 닫습니다. 같은 세션에서 같은 주소는 한 번만 묻고, 칸이 이미 그 주소를 보여주고 있으면 묻지 않고 새로 고칩니다. 도구 막대 “브라우저” 단추(⌘⇧B)로 직접 여닫을 수도 있습니다.

칸에는 뒤로·앞으로·새로 고침, 주소 칸(/나 ~로 시작하면 세션 폴더의 파일), 기본 브라우저로 열기 단추가 있습니다. 세션마다 독립된 저장 공간을 쓰고 쿠키·방문 기록을 남기지 않으며, 페이지에서 앱의 다른 기능을 부를 수 없습니다. 세션 폴더 밖의 파일은 열리지 않습니다.

MCP 서버 연동

Model Context Protocol(MCP) 서버를 연결해 에이전트가 쓸 수 있는 도구를 늘릴 수 있습니다.

• 설정은 앱 데이터 폴더의 settings.json의 mcp_servers 목록에 저장됩니다(Evo CLI와 같은 형식, ~/.evo는 읽지 않습니다). 설정 창 MCP 탭에서 추가·삭제하면 이 파일에 반영됩니다.
• 서버는 HTTP(Streamable HTTP)나 stdio(로컬 프로세스) 중 하나로 연결합니다. 앱을 켤 때 모든 서버에 동시에 연결을 시도하고, 서버마다 15초 안에(evo 로그인 계정이 기본으로 붙이는 dispatch·dispatch-bugs 서버는 3초 안에) 준비돼야 합니다. 한 서버가 실패해도 다른 서버는 영향받지 않습니다. 0.2.8부터 연결하지 못한 원격 HTTP 서버는 그 뒤 실행을 시작할 때마다 다시 연결을 시도합니다.
• 도구 이름은 mcp__서버__도구 형식으로 모델에 보입니다. 이름이 겹치면 먼저 등록된 서버가 우선하고 경고가 보입니다. 결과는 50,000자에서 잘립니다.
• MCP 도구도 읽기 전용이 아니므로 권한 모드에 따라 승인을 묻습니다(auto mode에서는 분류기가 판단).
• 프로젝트 폴더별 MCP 목록: 세션 작업 폴더의 .evo/config.local.json이나 .evo/config.json에 mcp_servers를 적어 두면 그 폴더의 세션은 사용자 설정 목록 대신 그 목록을 씁니다(로그인 기본 dispatch 서버는 그래도 그대로 붙습니다). MCP 탭에는 이 폴더별 목록이 사용자 목록과 따로 표시됩니다.
• 관리자 설정의 MCP 목록: 조직이 관리자 설정 파일(/Library/Application Support/evo/managed-settings.json)에 mcp_servers를 정해 두면 그 목록이 앱의 목록이 됩니다. 사용자 설정과 폴더별 목록은 쓰지 않고, 로그인 기본 dispatch 서버만 함께 붙습니다. 관리 목록이 있는 동안 MCP 탭에는 “조직의 관리자 설정이 MCP 서버 목록을 정했습니다”가 보이고 서버 추가·삭제를 할 수 없습니다. 관리 목록이 풀리면 “다시 연결”로 폴더별 목록을 다시 읽으며, 앱을 다시 켤 필요는 없습니다.
• MCP 탭에서 서버마다 이름, 종류와 주소(또는 실행 명령), 연결 상태, 제공하는 도구 목록을 확인하고, 서버를 추가·삭제하거나 “다시 연결”할 수 있습니다. 설정 파일이 깨졌으면 화면에서 추가·삭제하지 않고 문제를 보여줍니다(사용자가 적어 둔 항목을 실수로 지우지 않기 위해서입니다).
• 설정 파일의 서버 항목에 다음 두 키를 더할 수 있습니다(0.2.7).
  • tls_pin_sha256: 서버 인증서 공개키(SPKI)의 SHA-256을 표준 base64 44자로 적습니다. 적으면 시스템 인증서·호스트 이름·유효 기간 대신 이 키만 보고 서버를 믿으며, 다른 키가 오면 연결을 끊고 받은 키를 알려 줍니다(https 주소에만 쓸 수 있고, 리다이렉트로 따라간 주소도 같은 키여야 합니다).
  • auth_client_id: 그 서버 전용 로그인 클라이언트 이름입니다(auth: "org"인 서버에만, 64자 이내 영문·숫자로 시작, . _ - 허용). 적으면 evo 로그인의 토큰 대신 그 클라이언트의 토큰으로 접속합니다. 로그인 기본 dispatch 서버(dispatch: true)에는 쓸 수 없습니다.
• 리소스·프롬프트·샘플링, 도구의 이미지 결과는 아직 지원하지 않습니다.

LSP 진단

Write·Edit 도구로 파일을 성공적으로 고치면, 그 파일 확장자에 맞는 언어 서버(사용자가 직접 설치해야 합니다, 앱이 설치·갱신하지는 않습니다)에 보내 진단(오류·경고)을 받아 대화와 모델에 함께 전달합니다.

기본으로 지원하는 언어와 서버:

언어	명령	확장자
Go	gopls	.go
TypeScript	typescript-language-server --stdio	.ts .tsx .js .jsx .mjs .cjs
Python	pylsp	.py .pyi
Rust	rust-analyzer	.rs
C/C++	clangd	.c .h .cpp .cc .cxx .hpp .hh
Java	jdtls	.java

설정 파일의 lsp 키로 끄거나(false), 다른 언어를 더하거나 명령을 바꿀 수 있습니다. 서버가 찾아지지 않거나 시작에 실패하면 그 언어의 진단은 그 세션(앱을 켜 둔 동안)에서만 꺼지고 실행은 멈추지 않습니다. 대화에는 LSP 파일이름:줄: 문제 내용 (심각도) 같은 알림 줄이 보이고, 상태와 진단 창에도 “LSP 진단” 상태가 표시됩니다. 완성·호버·정의로 이동 같은 다른 LSP 기능은 지원하지 않습니다.

웹 검색 설정

로그인한 뒤에만 에이전트가 WebSearch 도구를 쓸 수 있습니다. 기본은 로그인 서버가 중계하는 검색(세션당 20회까지)입니다. 설정 창(또는 일반 탭 안의 “웹 검색” 탭)에서 다음을 바꿀 수 있습니다.

• 제공자: 로그인 서버 검색 중계(기본) · Brave Search · Tavily · 다른 검색 중계(relay) 주소.
• API 키(Brave·Tavily·relay 키, macOS 키체인에 저장).
• 중계를 쓸 때 시도할 도구 순서.
• 세션당 검색 한도(비워 두면 20회).

설정이 잘못되면 실행을 막지 않고, 모델이 검색을 시도할 때 그 문제를 결과로 알려줍니다. 관리자가 조직 전체의 검색 중계를 강제로 지정해 두었으면 그 값이 잠겨 보이고 사용자가 바꿀 수 없습니다.

Hooks

Hooks는 에이전트 이벤트가 일어날 때마다 사용자가 지정한 셸 명령을 실행해 동작을 가로채거나 기록을 남기는 기능입니다. 설정 파일의 hooks 키에 이벤트별로 {"matcher": "Bash|Edit", "command": "…"} 형태로 등록합니다.

• 지원하는 이벤트 8종: PreToolUse(도구 실행 전 승인에 관여), PostToolUse(도구 실행 후 결과를 바꿀 수 있음), UserPromptSubmit(사용자 입력을 막을 수 있음), Notification(대기열 메시지가 들어갈 때), Stop·SubagentStop(모델이 답을 마칠 때), SessionStart(새 세션의 첫 실행), PreCompact(압축 전).
• hook 명령은 세션 작업 폴더에서 30초까지 실행됩니다. 표준 입력으로 이벤트 정보를 JSON으로 받고, 종료 코드 2는 “막기”이며, 표준 출력에 JSON 객체(permissionDecision, decision: "block" 등)를 내면 그 결정을 읽습니다.
• 설정 층(관리자·사용자·프로젝트·프로젝트 로컬)의 hook 목록은 모두 이어 붙여서 실행됩니다. 여러 층에 같은 hook이 있으면 한 번만 실행됩니다. 관리자가 “조직 hook만 실행”을 지정했으면 다른 층의 hook은 무시됩니다.
• hook 설정 자체가 잘못된 형식이면(JSON 구조 오류, 정규식 오류 등) 그 세션의 실행과 수동 압축을 하지 않고 “hooks 설정이 잘못되어 실행하지 않았습니다”가 안내됩니다. Hooks 탭에서 선택한 세션 폴더 기준으로 합쳐진 hook 목록과 설정 문제를 확인할 수 있습니다.

자동 메모리

세션이 끝날 때마다(앱 세션은 끝이 없으므로, 실행이 끝날 때마다) 그 세션에서 한 일의 요약(작업 폴더, 결과, 쓴 도구, 고친 파일, 처음 몇 개 프롬프트)을 앱 데이터 폴더의 projects/<폴더 slug>/memory/ 아래에 영어 Markdown 파일로 자동 저장합니다. 같은 폴더의 다음 세션을 시작할 때, 이전 세션들의 요약 목차(MEMORY.md, 최신 20개)가 첫 메시지 앞에 자동으로 붙어 모델이 그 폴더에서 전에 무슨 일을 했는지 참고할 수 있습니다.

• 설정 auto_memory.enabled(기본 켜짐, 모든 설정 층)로 끌 수 있습니다. 끄면 쓰지도 읽지도 않습니다. 설정 창 일반 탭 “자동 메모리”에서 바꿉니다.
• 컨텍스트와 사용량 창에 “자동 메모리” 상태(켜짐·요약 수 또는 꺼짐)와 “메모리 폴더 열기” 버튼이 있습니다.
• 사용자 프롬프트가 없었거나, 프롬프트 하나에 도구를 전혀 쓰지 않은 경우에는 요약을 쓰지 않습니다.

사용 기록(Langfuse)

조직 계정으로 로그인하면 사용 기록(모델 호출·도구 실행의 추적 정보)이 evo-api를 거쳐 항상 전송됩니다. 개인 계정도 0.2.7부터 같은 경로로 기본 전송됩니다(사용자 결정 2026-11-05). 처음 전송될 때 한 번 안내가 뜨고, 거기서 끄거나 아래 방법으로 끌 수 있습니다.

• 끄기: 설정 창 “사용 기록” 탭에서 “evo 서비스로 보내기”를 끄거나, 설정 파일(settings.json)에 "telemetry": false를 둡니다. 끄면 아무 곳에도 보내지 않으며, 원하면 사용자가 지정한 Langfuse 서버로만 보낼 수 있습니다.
• 설정 항목: Langfuse 서버 주소, 공개 키·비밀 키(macOS 키체인에 저장, 환경 변수 이름도 지정 가능), 프롬프트와 답변까지 보낼지(기본 꺼짐), 도구 출력을 가릴지(기본 켜짐), 도구 입력·출력 최대 바이트, 사용자 신원 보내는 방식(그대로·해시·보내지 않음).
• 전송 내용은 모델·토큰 수·시간·도구 이름에 프롬프트와 도구 출력 본문을 더한 것입니다. evo 서비스의 기본 설정은 본문을 버리고 모델·토큰 수·시간·도구 이름·계정 이름만 남깁니다.
• 전송은 실행이 끝날 때 한 번(실행 결과가 없이 끝나도) 이루어지며, 실패해도 화면에 오류가 뜨지 않습니다.
• 공유 프로젝트 설정 파일(.evo/config.json)에는 이 설정을 둘 수 없습니다. 다른 사람의 저장소를 복제해서 열었다고 해서 그 사람이 설정한 곳으로 내 대화가 보내지지 않게 하기 위한 안전장치입니다.
• 관리자가 조직 층에서 이 설정을 강제했으면 탭에서 잠겨 보이고 바꿀 수 없습니다.
• Evo Chat의 “내 기록” 화면에서 이 앱이 보낸 사용 기록(시각·모델·토큰·지연 시간)을 확인할 수 있습니다(관측성 연동이 켜져 있을 때).
• 실행 종료 이유와 비용: trace의 루트 metadata에 실행이 왜 끝났는지(terminal_reason)와 비용(cost_usd)이 담깁니다. 종료 이유는 stop(정상), max_turns, interrupted(멈춤), prompt_blocked(입력 제출 hook이 막음), error입니다. 비용은 모델이 알린 값을 먼저 쓰고, 없으면 세션 모델의 가격표로 계산하며, 둘 다 없으면 넣지 않습니다.
• 하위 에이전트 실행: 하위 에이전트 하나가 돌 때마다 그 Agent 도구 span 아래에 agent 관측 하나가 붙고, 그 아래에 하위 실행의 모델 호출과 도구 span이 그려집니다.

설정 창 구성

도구 막대의 설정 톱니바퀴나 앱 메뉴(“설정…”, ⌘,)로 엽니다. 로그인 여부와 상관없이 열리며, Esc로 닫습니다(⌘W와 같음). 탭은 다음과 같습니다.

• 계정: 로그인 전에는 로그인 버튼. 로그인 후에는 표시 이름, 아이디, 이메일, 계정 종류(조직·개인), 모델 키 만료 시각, 기본 모델, 쓸 수 있는 모델 수, 로그아웃. 조직 키 파일 가져오기·지우기도 이 탭에 있습니다. 토큰·키·서버 주소는 화면에 보이지 않습니다.

• 일반: 설정 목록(권한 모드 기본값, 자동 압축 켜기/시점/토큰 수, auto 분류 모델, yolo mode 확인 생략, 자동 메모리, 목표 토큰 예산/검증 모델, 업데이트 알림, 원격 제어, 다음 질문 제안, 생각 모드/생각 수준, 질문당 턴 상한, 생각 과정 펼침), 모든 세션 지침 파일(EVO.md) 열기, 데이터 폴더 보기. 항목마다 그 값을 정한 층(기본값·사용자·프로젝트·관리자)이 표시되고, 더 높은 층이 정한 값은 잠겨서 이유와 함께 보입니다.

  

• 글꼴: 채팅과 터미널 글꼴·크기를 따로 정합니다(9~32pt). 바꾸면 열려 있는 채팅·입력창·모든 터미널에 바로 적용됩니다.

  

• 모델: provider 추가·키 관리·환경 변수 지정, 모델별 컨텍스트 크기/이미지 지원/가격 수정, claude·Codex·Copilot CLI 래퍼 스위치.

• 권한: 허용·묻기·거부 규칙 목록(범위별), 판정 기록과 승인율, 신뢰한 폴더 목록.

  

• MCP: 등록된 MCP 서버 목록과 상태, 추가·삭제·다시 연결, 프로젝트 폴더별 목록.

• 에이전트: 하위 에이전트 정의 목록(이름·설명·도구·파일), 정의 문제, 정의 폴더 열기.

• Hooks: 이벤트별 등록된 hook 목록, 설정 문제, 조직 hook만 실행 여부.

• 워크플로우: 봉인된 워크플로우 팩의 판과, 세션 폴더의 워크플로우 설치 여부·Bootstrap Gate 상태(읽기만, 워크플로우 참고).

• 사용 기록: Langfuse 연동 설정(위 “사용 기록(Langfuse)” 참고).

• 웹 검색: 제공자·키·도구 순서·세션 한도(위 “웹 검색 설정” 참고).

• 정보: 앱 버전, 빌드 번호, 오픈소스 라이선스.

  

설정은 네 층으로 나뉘어 적용됩니다(위가 이김): 관리자(조직이 배포, /Library/Application Support/evo/managed-settings.json) > 프로젝트 로컬(<세션 폴더>/.evo/config.local.json) > 프로젝트(<세션 폴더>/.evo/config.json) > 사용자(앱 데이터 폴더의 settings.json). ~/.evo는 어떤 층에서도 읽지 않습니다(Evo CLI와 독립적으로 동작하기 위한 설계입니다). 공유되는 프로젝트 설정 파일에는 모델 키, provider, 권한 모드, 텔레메트리 같은 보안·개인 설정을 둘 수 없고, 두면 그 파일 전체가 무시되고 이유가 안내됩니다.

상태와 진단 창

대화 메뉴 “상태와 진단…”(⌥⌘I)으로 엽니다(세션이 없어도 열립니다). 세 부분으로 나뉩니다.

• 상태: 세션, 로그인 계정(종류와 이름/이메일), 모델, 이미지 지원 여부, 권한 모드, 시작 모드, 샌드박스 상태, 컨텍스트 사용량, MCP 서버·연결 수, dispatch 이름(있으면), 하위 에이전트 수, 앱 버전, 작업 폴더.
• 진단(✓/✗ 체크리스트): 로그인, 모델 호출 준비, 데이터 폴더 쓰기, git 설치 여부, 샌드박스, 실패한 MCP 서버, 설정 파일 문제, hooks 설정 문제, 하위 에이전트 정의 문제, 시스템 버전, 사용 기록 전송 상태. git은 macOS Command Line Tools가 없으면 설치 창을 띄우지 않고 ✗와 git: 없음 (xcode-select --install로 설치) 안내만 보입니다.
• 지침과 메모리: 읽은 지침 파일 경로와 크기, 자동 메모리 상태. AGENTS.md·EVO.md가 git 루트·작업 폴더 밖 파일로의 링크이거나(보통 파일이 아닌 링크 포함) Read 거부 규칙에 걸리면 그 파일은 싣지 않고, 싣지 않은 파일 이름을 instruction files not loaded (a link out of the folder, or a Read deny rule): … 한 줄로 알립니다. 앱 데이터 폴더의 사용자 EVO.md는 사용자 것이므로 이 검사에서 빠집니다.

“글로 복사”를 누르면 세 부분을 모두 텍스트로 클립보드에 담아, 문의할 때 붙여넣기 쉽게 해 줍니다. “다시 확인”으로 값을 새로 읽습니다. 버전 줄은 <버전> (commit <짧은 해시>, <빌드 날짜>, 빌드 <번호>[, institution <기관 id>]) 형식으로 표시됩니다(기관 id는 기관용 빌드에서만 보입니다).

점검용 시간 출력(EVO_TIMING=1): 이 환경 변수를 켜고 앱을 시작하면 기다린 구간마다 timing: <이름> <밀리초>가, 같은 구간을 여러 번 재면 timing: <이름> n=<횟수> p50=<밀리초> p90=<밀리초> max=<밀리초>가 앱 출력에 남습니다. 느린 구간을 찾을 때만 쓰는 점검용이며, 평소 화면 동작이나 실행 결과는 바뀌지 않습니다.

도구가 응답하지 않을 때

도구 호출이 자기 제한 시간(timeout_ms)을 30초 넘겨도 끝나지 않거나, 도구가 프로세스를 남긴 채 유예 시간을 넘길 때, 세션 폴더에 transcript.stuck-<YYYYMMDDTHHMMSS>.txt(UTC)를 한 번 남깁니다.

• 한 호출에 한 장만 만들고 덮어쓰지 않으며, 같은 초에 또 생기면 파일 이름 뒤에 -2, -3을 붙입니다. 파일은 소유자만 읽을 수 있는 권한(0600)으로 저장됩니다.
• 파일에는 도구 이름·시각·프로세스 id, 앱의 자식 프로세스 목록(이름과 상태만), 스레드 상태를 얻는 방법(sample <pid> 1 1) 안내가 적힙니다.
• 파일 경로는 대화 안에서 알려 주고, 그 세션이 화면에 없으면 앱 알림 줄에 보여 줍니다. 하위 에이전트 실행도 같은 규칙으로 그 실행의 폴더에 남깁니다.

evo-dispatch 세션 연동과 버그 신고

evo-dispatch는 여러 Evo 세션(이 앱, 다른 컴퓨터의 Evo CLI, Evo Chat 등)이 서로 짧은 작업 요청을 주고받는 연동 기능입니다. 로그인했고 dispatch 서버가 연결되어 있으면 자동으로 켜집니다(개인 계정은 로그인만 하면 기본 dispatch 서버가 설정 없이 자동으로 붙습니다). 0.2.6부터 세션끼리 주고받는 요청은 늘 종단간 암호화됩니다(아래 “세션 요청 암호화”).

받은 요청과 보내기

• 상태 줄 끝에 dispatch <이름>과 연결 상태(연결 중·오프라인), 안 읽은 요청이 있으면 · 요청 N건이 보입니다. 누르면 요청이 있으면 받은 요청 창, 없으면 활성 세션 창이 열립니다.
• dispatch 메뉴 “받은 요청”(⌘⇧I)에서 이 세션으로 들어온 요청을 보고, 하나를 고르면 읽음으로 처리됩니다. 받은 요청은 저절로 실행되지 않습니다. “이 요청으로 지시하기”를 눌러야 다음 메시지에 자료로 붙습니다. 예외는 같은 워크그룹 멤버가 보낸 서명 확인된 그룹 요청으로, 아래 “워크그룹”의 조건을 모두 갖추면 그 세션이 스스로 실행합니다.
• dispatch 메뉴 “활성 세션과 보내기”(⌘⇧D)에서 내 다른 활성 세션(같은 계정으로 로그인한 다른 evo-mac·evo-windows·Evo CLI·Evo Chat 세션 등) 목록을 보고 하나를 골라 제목과 본문을 보냅니다. 앱이 dispatch에 알리는 세션은 열린 세션 전부이고, 이 앱에서 열어 둔 다른 세션도 목록에 나옵니다. 상태 줄·받은 요청 창·활성 세션 창은 지금 보고 있는 세션 기준으로 표시됩니다.
• 세션 이름은 이 창에서 세션마다 바꿀 수 있습니다(빈칸이나 -면 “이름 없음”). 바꾸면 그 즉시 활성 신호에 반영되고, 그 세션 기록에 남아 세션을 닫았다가 다시 열거나 앱을 다시 켜도 마지막 이름으로 이어집니다. 압축처럼 새 세션으로 이어 가는 경우에도 이름이 옮겨 갑니다. 이름을 정한 적 없는 세션과 규칙(영문·숫자로 시작, 영문·숫자·. _ -만, 64자 이내)에 맞지 않는 이름을 쓴 세션은 설정의 기본 이름을 씁니다.
• 모델이 직접 다른 세션으로 요청(또는 답장)을 보내려 하면, 바로 보내지 않고 대화 안에 받는 주소·종류·제목·본문을 보여주는 승인 창이 뜹니다. 내용을 확인하고 비밀정보가 없을 때만 “승인하고 보내기”를 누릅니다.

세션 요청 암호화

세션 사이의 요청·답장(활성 세션 창과 워크그룹 창에서 보낸 것, 모델의 dispatch_send)은 늘 종단간 암호화됩니다. 제목·본문·링크는 받는 세션의 기기 키로만 열리고 dispatch 서버는 읽지 못하며, 보낸 기기가 서명해 보낸 이와 내용이 중간에서 바뀌지 않았는지 확인합니다. 버그 신고와 개발 요청(/mcp/dev)은 세션 요청이 아니므로 이 암호화 대상이 아닙니다.

• 보낼 때: 받을 세션이 모두 기기 키를 올려 두었을 때만 봉투로 보냅니다. 키가 없는 받는 세션이 하나라도 있거나(암호화를 모르는 Evo 프로그램), 이 기기의 키를 읽을 수 없으면 보내지 않고 이유를 보여 줍니다(예: dispatch: not sent — …; session messages are always encrypted, so nothing was sent). 평문으로 대신 보내지 않습니다.
• 받을 때: 보낸 기기의 서명을 먼저 확인한 뒤 내용을 풉니다. 확인된 메시지의 머리줄에는 · 암호화됨(서명 확인)이 붙습니다. 서명이나 복호화가 실패하면 목록에는 [encrypted message not opened]만 보이고 읽기 창도 열지 않습니다. 평문으로 취급하지 않습니다.
• 기기 키: 처음 쓸 때 이 Mac용 키 두 개를 만들어 키체인에 둡니다(로그인과 같은 키체인, 이 Mac에서만). 개인 키는 기기 밖으로 나가지 않고 공개 키만 dispatch에 올립니다. 키를 지우면 그 기기로 온 안 읽은 암호 메시지는 풀 수 없습니다.
• 기기 키 변경 경고: 상대 기기의 공개키가 이 Mac이 처음 본 값과 다르면 대화에 경고를 남깁니다. 보내기·받기를 막지는 않습니다 — 앱을 다시 설치해도 키가 바뀌기 때문입니다. 처음 보는 키와 바뀌지 않은 키에는 경고가 없습니다. 이 목록은 이 Mac의 키체인에만 남습니다.
• 재전송 확인: 이 기기가 이미 연 봉투의 ct_sha256을 기억해 두었다가, 같은 봉투가 다른 메시지 id로 다시 오면 열지 않습니다(replay). 같은 봉투가 같은 id로 다시 오면(목록 → 읽기) 그대로 엽니다. sent_at이 30일보다 오래된 메시지는 재전송과 구별할 수 없어 열지 않고, 봉투의 작성 시각과 sent_at이 10분 넘게 벌어지면 경고와 함께 엽니다. 이 기억도 30일이 지나면 지웁니다.
• 워크그룹 표시 서명(v2): 워크그룹 실행 표시(자동 여부·그룹 id·연쇄 단계)가 붙은 요청은 그 표시까지 서명에 묶는 v2 봉투로 보냅니다. 중간에서 표시를 바꾸거나 떼면 열리지 않으며, v2를 모르는 이전 버전 앱에는 그룹 요청이 [encrypted message not opened]로 보입니다.
• 암호화가 가리는 것은 제목·본문·링크입니다. 보낸 이·받는 이·시각·이름·글 크기 같은 메타데이터는 가려지지 않습니다.

워크그룹

내 활성 세션 몇 개를 하나의 그룹으로 묶고, 그룹에 보낸 요청을 받은 세션이 스스로 실행하고 답하게 합니다. dispatch에 연결되어 있어야 하며, 세션마다 자동 처리를 따로 켜고 끕니다.

• 여는 곳: dispatch 메뉴 “워크그룹…” 또는 /workgroup(=/workgroup list)입니다. /workgroup create·send [n] [역할|별칭]·leave [n]도 같은 창을 열며, send·leave에 번호를 주면 그 그룹을 고른 채 엽니다. 그룹이 하나면 번호를 생략합니다. create --back은 창 대신 백그라운드 담당 계획을 보여 줍니다(아래 백그라운드 담당).
• 묶기: 창의 “새 워크그룹 (묶을 다른 세션)“에서 다른 활성 세션을 고르고 “묶기”를 누릅니다. 이 세션도 그룹에 들어갑니다. 묶으려면 이 세션에 역할(페르소나)이 있어야 합니다. 역할이 없으면 만들지 않고 “이 세션에는 역할이 없습니다. /persona <이름>으로 정합니다 … 역할이 생길 때까지 그룹 요청은 받은 요청에 남습니다”라고 안내합니다. “내 워크그룹”에는 멤버 별칭과 그 멤버의 지금 역할이 wg-ab12 (tester)처럼 보이고 내 세션에는 (me)가 붙습니다. “다시 불러오기”로 목록을 새로 읽습니다.
• 보내기: 그룹을 고르고 “그룹에 보낼 메시지”에 첫 줄 제목, 나머지 본문을 적은 뒤 “그룹에 보내기”를 누릅니다(⌘↩). 모델을 거치지 않고 그대로 전송되므로 비밀정보는 넣지 않습니다. 받을 세션 중 키가 없는 세션이 있으면 보내지 않고 이유를 보여 줍니다. /workgroup send [n] [역할|별칭]처럼 역할이나 별칭을 주면 그룹 전체가 아니라 그 멤버 한 명에게 보냅니다(별칭이 같은 이름을 먼저 찾고, 그다음 역할로 찾습니다. 같은 역할 멤버가 둘 이상이면 별칭을 주어야 합니다).
• 나가기: 그룹을 고르고 “나가기”를 누릅니다.
• 자동 처리 조건: 받은 세션이 그룹 요청을 스스로 실행하려면 다음을 모두 만족해야 합니다. ① 이 세션에 역할이 있음 ② 보낸 요청의 실행 표시가 “자동” ③ 받는 주소가 그룹이고 실행 표시의 그룹 id와 같음 ④ 보낸 세션이 그 그룹의 나 아닌 멤버 ⑤ 서명이 확인됨(v2 봉투) ⑥ 연쇄 단계가 20 미만. 하나라도 아니면 실행하지 않고 받은 요청에 남깁니다.
• 실행하지 않는 이유: 그룹 요청이 스스로 실행되지 않았으면 받은 요청에 그 이유를 한 번 적어 줍니다(자동 실행 표시 없음·서명 미확인·연쇄 상한·실행 표시의 그룹과 받는 주소 불일치·이 세션이 그 그룹에 없음·보낸 세션이 그룹 멤버가 아님·보낸 세션이 자기 자신·역할 없음). 확인에 실패하면 2초 뒤 최대 3번 다시 확인합니다.
• 같은 역할은 한 세션만: 그룹 전체로 온 요청은 같은 역할을 가진 멤버 가운데 별칭이 앞선 한 세션만 처리합니다. 그 세션은 처리 사실을 남기고, 다른 같은 역할 세션은 요청을 열지 않고 둡니다(웹 멤버는 이 조정에서 빠집니다. 웹은 요청을 보여 주기만 합니다).
• 오케스트레이터의 넘김: orchestrator 역할의 세션이 그룹 요청을 자동 처리하는 중에는 받은 일을 그룹의 다른 멤버에게 넘길 수 있습니다. 넘기기는 답 하나에 멤버마다 한 번이고, 받는 주소는 그 그룹의 다른 멤버 별칭이어야 하며 연쇄 단계는 1 늘어납니다. 그 밖의 보내기는 지금처럼 승인 창을 거칩니다.
• 답장은 확인 없이 한 번: 자동 처리한 세션이 그 요청의 답장(dispatch_send, kind: "reply", reply_to)을 보낼 때는 승인 창이 뜨지 않습니다. 받는 주소와 연쇄 표시가 그 요청의 답장과 정확히 같을 때만이며, 요청마다 한 번입니다. 그 밖의 내용이면 지금처럼 승인 창을 거칩니다.
• 연쇄와 실행 수: 받은 세션이 답장을 보낼 때 연쇄 단계를 1 늘리며, 20에 이르면 표시 없이 보내 사람이 이어받게 합니다. 한 세션이 자동으로 하는 실행은 20번까지이고 /workgroup start로 횟수를 다시 셉니다.
• 끄기·켜기: 창의 “이 세션에서 그룹 요청 자동 처리 (최대 20번)” 스위치, 또는 /workgroup stop·start입니다. 끈 세션의 그룹 요청은 실행되지 않고 받은 요청에 남습니다.
• 안전 경계: 그룹 요청도 이 세션의 규칙·페르소나·권한 모드·권한 규칙 안에서 실행되며, 그것들을 넘지 않습니다. 비밀을 드러내거나 승인을 건너뛰는 이유가 되지 않습니다. 실행 중에 도착하면 대기열에 들어갑니다.

백그라운드 담당

0.2.8부터는 그룹 멤버를 각자 자기 프로젝트 폴더에서 도는 백그라운드 세션으로 만들 수 있습니다. 오케스트레이터(지금 세션)는 그 위 폴더에 남습니다.

• 만들기: /workgroup create --back <담당>=<폴더>[@<모델>] …입니다(예: developer-backend-go=./api@<모델 id> tester=./web). 담당 이름은 내장 페르소나 이름이어야 하고, 폴더는 담당마다 다르며 .evo/workflow.json이 있는 워크플로우 프로젝트여야 합니다(오케스트레이터의 폴더는 쓸 수 없습니다).
• 계획 먼저: 무엇을 어디서 어떤 모델로 시작하는지 계획을 보여 주고 /workgroup confirm으로 시작, /workgroup cancel로 버립니다. --yes를 붙이면 계획을 보인 뒤 확인 없이 바로 시작합니다.
• 실행 방식: 담당은 확인 없이(yolo) 실행하고 자기 폴더 안에서만 파일을 씁니다(confine). 그 폴더는 신뢰 폴더로 기록됩니다.
• 새 프로젝트를 먼저 만들기: <담당>=new:<이름>으로 담당의 워크플로우 프로젝트를 먼저 만듭니다. 위치는 --group <경로>·--personal·--new-group <경로>로 정하거나 new:<그룹>/<이름>·new:~/<이름>으로 씁니다(--host, --session-agent도 받습니다). 만든 GitLab 프로젝트는 나중에 지우지 않습니다.
• 더하기·빼기·끝내기: /workgroup add [n] [--yes] …로 더하고, /workgroup remove <별칭>으로 빼고, /workgroup end로 모두 끝냅니다. 이 세션이 끝나도 담당은 끝납니다.
• 부모 저장소: 오케스트레이터의 폴더가 git 작업 트리이면 담당 폴더를 그 저장소의 .git/info/exclude에 넣어 저장소 안에 저장소가 생기지 않게 합니다.
• 다시 시작: 앱을 다시 시작하면 담당은 자기 세션으로 이어집니다(~/.evo/workgroup/restart-<이름>.json).
• --sh는 앱에 없습니다. 그 스크립트는 Evo CLI를 실행하므로, 앱에서는 입력 기록(↑)에서 같은 /workgroup create --back 줄을 다시 보냅니다.

그룹 메시지 바로 받기

• 세션을 dispatch에 열어 둔 동안 앱은 푸시 채널을 하나 열어 둡니다. 같은 그룹의 새 메시지가 오면 다음 활성 신호(20초)를 기다리지 않고 바로 자동 처리 조건을 확인합니다.
• 푸시 이벤트에는 내용이 없고 새 메시지 id만 담깁니다. 자동 처리 조건은 활성 신호로 알게 될 때와 같고, 푸시는 확인을 앞당길 뿐입니다.
• 서버가 푸시 채널을 지원하지 않으면 5분 뒤에 다시 시도하며, 그동안에도 활성 신호의 안 읽은 수로 같은 자동 처리가 이뤄집니다. 연결이 끊기면 1초부터 두 배씩(최대 30초) 기다렸다 다시 열고, 45초 동안 아무 신호도(ping 포함) 없거나 서버가 세션을 끝내면 끊긴 것으로 보고 다시 엽니다.
• /clear·/compact·/resume처럼 세션 id가 바뀌면 연결을 끊고 새 세션으로 다시 엽니다.

버그 신고

dispatch 메뉴 “버그 신고…”(⌘⇧U)로 엽니다. 내가 올린 버그가 상태(접수·확인 중·처리 끝)별로 보이고, 처리가 끝나면 처리한 쪽이 남긴 메모가 함께 보입니다. 올린 버그를 취소하는 기능은 없습니다.

버그를 올릴 때는 분류(기본은 Mac 앱, 다른 제품이면 그 분류를 고름) → 제목 → 내용 → 화면 캡처(선택, 최대 3장: “evo 창 캡처”·붙여넣기·파일에서 고르기) → 확인 순서입니다. 1MiB가 넘는 이미지는 자동으로 줄여서 올라갑니다. 올리기 전에 미리보기가 보이므로, 비밀정보나 다른 사람의 개인정보가 찍히지 않았는지 확인해야 합니다. 토큰·비밀번호·내부 IP처럼 보이는 글을 쓰면 화면에 경고가 뜨지만 전송을 막지는 않습니다. 모델도 “버그 신고해 줘”처럼 요청하면 같은 공간에 버그를 올릴 수 있습니다.

워크플로우

0.2.8부터 앱에서 GitLab 워크플로우 작업(Issue·MR·파이프라인·저장소 설정)을 합니다. Evo CLI(evo workflow …)의 메뉴·명령·판정을 그대로 옮긴 것이지만, 앱에는 evo workflow 실행 파일이 없고 세션의 Workflow 도구가 그 일을 합니다. 쓰는 동작은 도구가 계획을 먼저 보여 주고 확인을 받은 뒤에 실행합니다.

워크플로우 팩

• 앱 빌드에 워크플로우 팩(t3)을 CLI 생성기가 만든 것과 같은 모양으로 봉인해 넣었습니다. 서버에 붙지 않고도 규칙·표준·스킬 문서를 읽습니다.
• 팩은 읽기 전용입니다. 앱에서 팩 내용을 고치지 않습니다.

/workflow 메뉴

/workflow는 Evo CLI와 같은 이름·순서의 메뉴 시트를 엽니다. 항목은 새 프로젝트 만들기 · 이 저장소에 워크플로우 설치 · 상태 점검 · Issue 초안·게시·검사 · MR 보기·만들기·병합 · 파이프라인 보기 · 라벨·CI·보호·훅 설정 · 팩 올리기입니다.

• 하위 동작이 여럿인 항목(Issue·MR·설정)은 한 단계 더 열리고 “← 뒤로”로 돌아옵니다. 인자가 필요한 동작은 /workflow <명령> 까지 입력창에 넣어 주고 나머지를 채우게 합니다.
• /workflow <명령> [인자]는 메뉴를 거치지 않고 그 자리에서 실행합니다. 명령은 new·init·doctor·status·bootstrap·upgrade·issue·mr·pipeline·setup·list·show·search·validate입니다.
• setup hook(커밋 전 검사 훅)은 앱에 아직 없습니다. Evo CLI의 evo workflow setup hook으로 설치하라고 안내합니다.
• Workflow 도구가 있는 세션에서 Bash로 glab issue·glab mr·glab ci를 쓰면 같은 일을 하는 Workflow 도구를 쓰라고 한 줄 안내합니다.

팩 문서 찾기 (WorkflowShow)

/workflow list·show·search는 봉인된 팩의 문서를 찾고, 읽고, 검색합니다. list·search에는 Evo CLI의 --seed에 해당하는 입력도 줄 수 있고, templates는 Issue 틀을 Issue 종류 이름으로 보여 줍니다.

Issue (WorkflowIssue)

• 초안: 계약(JSON)과 본문을 만들고, 스키마·계약·authoring·lifecycle 검증을 Evo CLI와 같은 판정으로 돌립니다.
• 게시: 준비(prepare) → 확인 → GitLab에 쓰기 → 다시 읽어 확인 → 감사 기록 순서로 진행합니다. 이미 게시한 Issue를 고치려 하면 그렇게 하지 말라고 안내하고, 덧붙일 것은 댓글(note)로 남깁니다.
• 읽기·닫기: 읽기 모드는 GitLab을 바꾸지 않습니다. 닫기는 계획(close_plan)을 보여 주고 확인한 뒤 실행합니다.
• 워크플로우를 설치(init)하기 전에는 쓰기가 막힙니다. 봉인 파일과 프로젝트 기록(.evo/workflow.json)을 확인하는 검사(Bootstrap Gate)를 쓰기 전에 먼저 합니다.

MR·파이프라인

• WorkflowMR: MR 상태 보기·만들기·병합을 합니다. 만들기와 병합은 무엇이 바뀌고 무엇이 병합되는지 먼저 보여 주고, 사용자가 승인한 뒤에만 실행합니다.
• WorkflowPipeline: 파이프라인 상태를 보거나(status) 끝날 때까지 기다립니다(wait).

저장소 워크플로우 설정 (WorkflowSetup)

• init: 이 저장소에 워크플로우를 설치합니다(봉인 파일·프로젝트 기록 .evo/workflow.json·검증기·Issue 틀). 처음 설치할 때 에이전트 ID를 제안하고, 이후에는 기록의 ID를 다시 묻지 않습니다.
• bootstrap: 봉인 파일을 다시 만들어 다시 봉인합니다.
• upgrade: 같은 원본의 새 보정 판으로 옮깁니다. 사용자가 고친 파일은 덮어쓰지 않습니다.
• setup labels·setup ci·setup protect: 분류표·담당·validation:passed 라벨, CI 검증 잡과 include 한 줄, 기본 브랜치·develop 보호와 병합 조건을 Evo CLI와 같게 만듭니다.
• doctor·status: 읽기만 합니다. 워크플로우 프로젝트와 GitLab 상태, 빠진 것, 팩·설치 여부·Bootstrap Gate를 알려 줍니다.
• init·bootstrap·setup …처럼 쓰는 동작은 계획을 먼저 보여 주고 확인을 받습니다.

새 프로젝트 만들기 (/workflow new)

• Evo CLI와 같은 질문을 합니다: 위치(개인·그룹·새 그룹), 이름, 지금 폴더 안에 새 폴더로 만들지, 목표(선택).
• 계획 미리보기가 통과한 뒤에만 GitLab 그룹·프로젝트·CI 변수를 만들고, 그 새 폴더에 워크플로우를 설치합니다.
• 중간에 실패해도 이미 만든 GitLab 프로젝트는 남습니다(나중에 지우지 않습니다). 목표를 정했으면 첫 Issue를 엽니다.

설정 창의 워크플로우 탭

설정 창의 “워크플로우” 탭은 봉인된 팩의 판과, 지금 세션 폴더의 워크플로우 설치 여부·Bootstrap Gate 상태를 읽기만 해서 보여 줍니다.

원격 제어

VPN 안의 기기에서 이 앱의 세션을 보고, 글을 보내고, 승인에 답할 수 있습니다. 호스트는 Evo CLI가 맡고(evo remote serve·pair·devices·rm), 앱은 열어 둔 세션을 그 호스트에 올리는 쪽입니다.

• 켜는 곳: 설정 → 일반 탭의 “원격 제어” 스위치(remote.enabled, 기본 꺼짐)입니다. 꺼져 있으면 아무 연결도 하지 않습니다. 스위치 옆에는 상태(꺼짐 / 호스트 없음 / 연결됨·올린 세션 수)만 보입니다. 관리자 설정이 정한 값은 사용자가 바꿀 수 없습니다.
• 준비: PC에서 Evo CLI의 evo remote serve로 호스트를 켜 두어야 합니다. 앱은 CLI가 만든 ~/.evo/remote/host.json에서 호스트의 루프백 포트와 접속 토큰을 읽습니다(앱이 ~/.evo에서 읽는 유일한 파일). 호스트가 없거나 끊기면 처음 0.1초부터 시작해 기다리는 시간을 늘려 가며(최대 2초) 다시 붙고, 그동안에도 앱 화면과 실행은 멈추지 않습니다. 기기 페어링과 기기 관리는 CLI 명령으로 합니다.
• 올라가는 내용: 열어 둔 세션마다 폴더·제목·모델·실행 여부와 그때까지의 대화 기록(최근 것부터 6 MiB·2500개)을 보냅니다. 그 뒤로는 새 기록, 답변 글자와 생각의 흐름, 실행 중인 셸 출력, PC 화면에 뜨는 알림 줄(실행 오류·명령 결과)이 이어서 갑니다. 세션을 닫거나 지우면 목록에서 빼고, 실행 시작·끝과 제목·모델 변경은 그때마다 알립니다.
• 기기에서 보내는 입력: 기기의 입력칸은 이 앱의 입력칸과 같게 동작합니다. 세션이 쉬고 있으면 실행을 열고, 실행 중이면 대기열에 넣습니다. /model <이름>, /clear, /compact, /goal …처럼 인자로 끝나는 명령은 PC와 같게 실행하고, 창이나 시트를 여는 명령(설정, 인자 없는 /model·/resume, /permissions, /mcp 등)은 PC에 창을 열지 않고 기기에 안내만 보냅니다. 세션을 바꾸는 명령(/clear·/compact·/goal …·/model <이름>)은 그 세션이 PC 화면에 보일 때만 실행합니다. PC 입력칸의 초안은 건드리지 않습니다. 기기의 입력도 PC와 똑같이 지금 세션의 권한 모드와 권한 규칙을 따릅니다(0.2.8).
• 기기에서 막는 것: 앱 끄기(/quit), 권한을 바꾸는 것(/permissions의 모드·규칙, 승인 모드, yolo), /provider·모델 서버·키 설정, /update·업데이트 설치, /workflow, /dispatch send, 로그인·로그아웃·조직 키입니다. !셸 줄은 기기에서도 그 자리에서 실행합니다(0.2.8). /config는 보기만 되고, @경로는 파일을 붙이지 않고 글자 그대로 갑니다.
• 승인: 승인이 필요하면 PC 승인 창과 함께 기기에도 선택지가 보입니다. 기기에는 “한 번 허용”·“이 세션 동안 허용”·“거절” 가운데 PC 창에 있는 것만 가고, “항상 허용”(규칙 저장)은 보내지 않습니다. Bash·MCP 도구·보호 설정 파일 쓰기·코드가 실행되는 자리 쓰기·.git 안 쓰기·작업 폴더 밖 셸은 거절만 할 수 있습니다(허용은 PC에서만). PC와 기기 중 먼저 온 답 하나만 반영하고, 기기가 먼저 답하면 PC 승인 창은 닫힙니다. 승인을 기다리는 중에 온 “중지”는 거절로 봅니다.
• 원격 보호 상태: 기기가 입력을 보내거나 승인에 답하면 켜지고 앱을 끌 때까지 꺼지지 않습니다. 앱 하나에 세션이 여럿이므로 앱의 모든 세션에 걸립니다. 켜질 때 “기기가 원격으로 참여했습니다 — 앱을 끌 때까지 보호 상태입니다” 알림이 한 번 뜨고 상태 막대에 표시가 남습니다. 이 상태에서는 언어 서버 진단을 켜지 않고 자동 메모리도 쓰지 않습니다. 거절만 되는 대상은 권한 모드(yolo·auto·edits 포함)·세션 허용·허용 규칙·hook 허용과 관계없이 늘 묻고 PC만 허용합니다(plan mode는 원래대로 읽기만 합니다). 읽기 전용 셸 명령은 그대로 돌지만 git은 늘 묻습니다.
• 주의: host.json에는 루프백 접속에 쓰는 토큰이 들어 있습니다. 이 파일을 다른 곳에 복사하거나 공유하지 말고, 노출이 의심되면 CLI에서 기기를 지우고 호스트를 다시 시작해 토큰을 새로 만드세요. 앱은 이 파일이 심볼릭 링크가 아니고 남이 쓸 수 없는 폴더에 있을 때만 믿습니다.

조직 키/기관 (기관 전용 빌드)

조직(기관)이 자체적으로 배포하는 evo-mac 빌드는 일반 빌드와 같은 소스에서 몇 가지 빌드 변수만 다르게 설정합니다.

• 상태와 진단 창·정보 탭의 버전 줄에 institution <기관 id>가 덧붙습니다.
• 조직 로그인에 쓰는 신뢰 공개 키 목록이 빌드에 고정되어 있어, 그 조직 전용 서명 키로 서명된 “조직 키 파일”만 가져올 수 있습니다(위 “로그인” 참고).
• 가져온 조직 키 파일에 업데이트 서버 주소(update.url)가 있으면 앱 업데이트를 조직 자체 Nexus 서버에서 받고, dispatch 서버 주소(dispatch.url)가 있으면 조직 로그인 때 그 dispatch 서버가 자동으로 연결됩니다.
• 관리자 설정(조직이 모든 사용자 컴퓨터에 배포하는 managed-settings.json)이 있으면, 다른 어떤 층도 그 값을 덮지 못합니다. 이 파일을 읽을 수 없거나 형식이 잘못되면 앱이 시작하지 않고 창 전체에 이유와 “다시 확인” 단추만 보입니다(조직 정책이 조용히 빠져나가지 않도록 하기 위한 설계입니다).
• 관리자 설정으로 강제할 수 있는 항목: 새 세션의 시작 권한 모드(잠김), yolo mode 금지, 사용 기록(Langfuse) 강제 설정, 조직 지정 검색 중계, “조직 hook만 실행”. EVO_MANAGED_SETTINGS 같은 환경 변수로 이 파일 경로를 바꿀 수는 없습니다(정해진 경로만 읽습니다).
• 개인 로그인 기본 dispatch 서버 주소는 기관용 빌드에는 들어가지 않습니다(조직 로그인의 dispatch.url만 쓰입니다).

앱 업데이트

• 앱을 열 때 백그라운드로 새 버전이 있는지 확인합니다(최대 5초만 기다리고, 느리면 조용히 넘어갑니다). 결과는 24시간 동안 다시 묻지 않도록 캐시됩니다. 새 버전이 있으면 도구 막대에 “새 버전” 단추가 나타납니다.
• 확인이 실패하면 이유를 괄호에 붙여 알립니다. 접속 실패는 업데이트 서버에 접속하지 못했습니다 (<원인>), 200·404가 아닌 답은 업데이트 서버가 <상태>으로 답했습니다, 내용이 버전이 아니면 업데이트 서버의 버전을 읽을 수 없습니다 (…)입니다. 서버 주소는 표시하지 않습니다.
• 앱 메뉴 “업데이트 확인…”, 정보 탭, 또는 도구 막대 “새 버전” 단추로 업데이트 창을 엽니다.
• “설치하고 다시 시작”을 누르면 설치 파일을 내려받아 체크섬과 서명을 확인한 뒤 지금 앱을 바꿔 넣고 앱을 다시 엽니다. 직전에 보던 세션은 다시 열린 앱에서 자동으로 열립니다.
• 채널(줄) 옮기기: 창 아래의 “정식판으로 옮기기…”(개발판에서) 또는 “개발판으로 옮기기…”(정식판에서)로 다른 채널로 옮길 수 있습니다. 지금보다 낮은 버전으로 옮겨 설치될 수도 있으며, 그 경우 “지금 버전에만 있는 기능은 쓸 수 없게 됩니다”라는 안내가 함께 뜹니다. 세션과 설정은 채널을 옮겨도 그대로 남습니다. 바로 설치되지 않고 확인 창에서 “<버전> 설치하고 다시 시작”을 눌러야 설치됩니다.
• dmg를 다시 내려받아 재설치할 필요가 없습니다. 업데이트는 되돌릴 수 없습니다(이전 버전을 보관하지 않습니다).
• 설정 ui.updateNotice(일반 탭 “업데이트 알림”)로 시작할 때의 자동 확인을 끌 수 있습니다.
• 기관 전용 빌드는 조직 키 파일의 주소가 있으면 조직 자체 Nexus 서버에서, 없으면 기본 Nexus 서버에서 받습니다. 관리자·사용자 설정의 “Nexus 서버 주소”로 폐쇄망 안 자체 Nexus를 지정할 수도 있습니다.

알려진 제한

• Apple Developer ID 서명과 공증 없이 임시(Ad-hoc) 서명으로 배포됩니다. macOS Gatekeeper가 처음 열 때 막으므로, Finder에서 앱을 우클릭하고 “열기”를 눌러야 합니다(또는 시스템 설정 > 개인정보 보호 및 보안에서 허용). 임시 서명이라 판마다 서명이 달라, 업데이트할 때마다 macOS 키체인 접근을 다시 물을 수 있습니다. “항상 허용”을 누르면 그 판에서는 다시 묻지 않습니다. 서명·공증은 이후 버전에서 별도로 다룰 예정입니다.
• Intel Mac(macOS 15)에서 “그래도 열기”로 처음 열면 Dock 아이콘만 뛰고 창이 뜨지 않는 사례가 있습니다. 브라우저로 받은 격리 표시(com.apple.quarantine) 때문에 macOS가 첫 실행 확인 중 앱을 멈춰 둔 것으로, 앱 자체의 결함은 아닙니다. 시작하기의 명령을 한 번 실행하면 이후 평소처럼 열립니다. Apple Silicon Mac은 영향이 없습니다.
• 명령줄 도구(-p, headless 실행, evo chat)는 없습니다. 앱은 대화형 전용입니다.
• vim 모드, 마우스 모드, 외부 편집기 열기 같은 터미널 UI 전용 기능은 해당하지 않습니다(네이티브 macOS 입력과 도구 막대 메뉴로 대신합니다).
• 최소 macOS 13 이상, Apple Silicon·Intel 모두 지원되는 universal 앱입니다.

단축키 모음

아래는 이 문서 안에서 언급한 단축키를 모아 둔 표입니다(macOS 기준).

단축키	동작
⌘N	새 세션
⌘,	설정
⌘↩	실행 중 바로 보내기(대기열+입력 중인 글을 합쳐 지금 실행으로)
⌃O	생각 과정·도구 결과 모두 펼치기/접기
⌃R	입력 기록에서 찾기
↑ (입력창 첫 줄, 비어 있을 때는 대기열)	이전 입력 불러오기 / 대기열 되돌리기
⌘⇧K	대화 압축…
⌥⌘K	대화 지우기(지금 세션을 그 자리에서 비움)
⌘⇧G	목표(Goal)…
⌥⌘I	상태와 진단…
⌘⇧B	브라우저 칸 열고 닫기
⌘⇧O	브라우저로 열까요 띠의 “열기”
⌘⇧I	받은 요청(dispatch)
⌘⇧D	활성 세션과 보내기(dispatch)
⌘⇧U	버그 신고…
Shift+Enter / Option+Enter	입력창에서 줄바꿈(Option+Enter는 /·! 입력을 명령으로 해석하지 않고 그대로 보내는 효과도 겸함)
Esc	승인 시트 거부, 열린 창/시트 닫기, 다음 질문 제안 버리기
Tab / → (빈 입력창)	다음 질문 제안 채우기

더 보기

• 설치와 첫 실행, 업데이트는 Evo Mac 시작하기에 있습니다.
• 터미널에서 같은 기능을 쓰려면 Evo CLI 사용 설명서를 보세요.
• 세션 사이에 작업을 주고받거나 버그를 신고하려면 Evo Dispatcher 시작하기를 보세요.