인터페이스 및 세션 관리

이 장에서는 VelaTerm의 구성 방식을 설명합니다. 창 레이아웃, 트리 관리, 탭과 분할 창의 동작, 상태 점과 필터링, 보관, 전체 검색, 종료 시 작업 공간 저장을 다루며, 다른 장은 모두 이 내용을 바탕으로 합니다.

1. 레이아웃

원격 접속과 원격 서버에 연결 버튼은 데스크톱 앱에 표시됩니다. 자세한 내용은 원격 개발 및 관리를 참조하십시오. 피드백 버튼을 누르면 브라우저에서 VelaTerm 피드백 페이지가 열립니다. Windows와 Linux에서는 Alt 키를 누르면 파일, 터미널, 도움말 메뉴가 있는 메뉴 막대가 표시됩니다.

양쪽 패널은 제목 표시줄의 버튼으로 숨길 수 있으며, 가장자리를 드래그하여 크기를 조절할 수 있습니다.

2. 트리: 프로젝트, 컬렉션, 그룹, 세션

• 프로젝트는 디스크의 디렉터리이자 하위 트리의 루트입니다. "프로젝트 만들기"(새 폴더 생성), "프로젝트 가져오기"(기존 폴더 열기, ⌘O) 또는 "Git에서 클론"으로 만듭니다.
• 컬렉션은 폴더가 없는 최상위 컨테이너로, 특정 프로젝트에 속하지 않는 세션을 모아 둡니다. 사이드바 하단의 "새 컬렉션" 버튼으로 만듭니다.
• 그룹은 세션을 정리하기 위한 노드이며 깊이에 제한 없이 중첩할 수 있습니다.
• 세션은 작업 단위로, 에이전트, 브라우저 페이지 또는 터미널입니다. 작업 디렉터리는 기본적으로 프로젝트 루트이며, 세션의 "편집" 양식에서 변경할 수 있습니다.

행 위에 마우스 포인터를 올리면 ＋ 버튼(프로젝트와 그룹에서는 "새 세션", 세션에서는 "새 하위 세션")이 나타나며, 프로젝트와 그룹에서는 새 그룹을 만드는 버튼도 나타납니다.

대부분의 작업은 컨텍스트 메뉴에서 할 수 있습니다.

프로젝트 메뉴와 그룹 메뉴는 생성 항목으로 시작합니다.

• "새 브라우저 페이지"(데스크톱 앱)와 "새 터미널". "새 터미널"은 해당 디렉터리에서 임시 터미널을 엽니다(§5).
• 최근에 사용한 에이전트의 "새 … 세션" 항목 세 개와 "더 많은 에이전트 세션". "더 많은 에이전트 세션"에는 모든 에이전트, 저장된 프리셋, "새 에이전트 세션"(검색 가능한 선택기), "실행 인자 지정 후 생성…"이 있습니다.
• "새 worktree 세션…"과 "새 계획/실행 세션…". 세션 생성 및 Git 협업과 계획 및 실행을 참조하십시오.
• "세션 가져오기…"(프로젝트에만 있음)와 "세션 재개…". AI 에이전트 세션 §4를 참조하십시오.

프로젝트 메뉴에는 이어서 "새 그룹", "표시", "실험 기능"(코드 그래프 및 코드 감사), "프로젝트 정보"(또는 "컬렉션 정보"), "이름 바꾸기", "프로젝트 제거"(또는 "컬렉션 삭제")가 있습니다. 그룹 메뉴에는 "Git" 하위 메뉴, "새 하위 그룹", "Worktree로 이동…", "표시", "이름 바꾸기", "그룹 보관", "그룹 삭제"가 있습니다.

세션 메뉴에는 세션의 유형과 상태에 맞는 항목이 표시됩니다.

• "열기", "새 탭에서 열기", "오른쪽 분할에서 열기", "아래쪽 분할에서 열기", "활성 분할 창에서 열기"(§4).
• "새 하위 세션", "세션 포크", "세션 내보내기…", "세션 지식 베이스로 정리", "Git" 하위 메뉴.
• "표시", "세션 정보"(Option/Alt 키를 누르고 있으면 전체 실행 명령 표시), "편집", "이름 바꾸기", "이동…".
• "프로세스 종료"(실행 중일 때), "세션 보관", "세션 삭제".

그 밖의 트리 작업은 다음과 같습니다.

• 이동: 노드를 드래그하거나 "이동…"을 사용합니다. 세션을 다른 세션 아래로 옮기면 그 세션의 하위 세션이 됩니다.
• 이름 바꾸기: "이름 바꾸기"를 선택하면 그 자리에서 이름을 편집할 수 있습니다. 이름을 지정하지 않은 세션은 첫 메시지를 바탕으로 이름이 정해집니다.
• 표시: "표시"는 프로젝트, 그룹 또는 세션에 이모지 표시를 추가합니다. 🔥 긴급, ⭐ 중요, 🐛 버그, ✅ 완료, 🚧 진행 중, 📌 고정, 💡 아이디어, ⚠️ 주의 중에서 선택할 수 있으며, 현재 표시를 다시 선택하면 제거됩니다.
• 다중 선택: ⌘/Ctrl 키를 누른 채 클릭하면 세션을 하나씩 선택하거나 선택 해제하고, Shift 키를 누른 채 클릭하면 범위를 선택합니다. 이때 컨텍스트 메뉴에는 "선택한 세션 열기", "선택한 세션 바둑판 배열"(세션 2~4개), "선택 항목 이동…", "선택한 세션 보관", "선택한 N개 항목 삭제"가 표시됩니다. 선택한 항목을 드래그하면 모두 함께 이동합니다.
• 접기 상태는 앱을 다시 시작해도 유지됩니다.

3. 탭

설정 ▸ 동작 ▸ "탭"에서 세션을 여는 방식을 선택합니다.

• 단일(기본값): 트리에서 에이전트 세션을 클릭하면 브라우저에서 링크를 따라갈 때처럼 현재 세션 탭을 재사용합니다. 떠나온 탭은 모든 분할 창과 함께 백그라운드로 이동하며, 그 프로세스는 계속 실행됩니다. 터미널 세션은 각각 별도의 탭으로 열립니다.
• 다중: 세션마다 별도의 탭으로 열립니다.

"새 탭에서 열기"는 항상 새 탭을 엽니다. 두 모드 모두 다른 탭으로 전환해도 실행 중인 작업은 멈추지 않으며, 탭을 닫으면(⌘W 또는 ×) 그 탭의 프로세스가 종료됩니다. 에이전트 세션은 탭을 닫아도 문제가 없습니다. 대화가 유지되므로 노드를 다시 열면 대화가 재개됩니다.

백그라운드 탭은 상태 표시줄에 "백그라운드 N/M"으로 표시되며, 이를 클릭하여 탭을 다시 불러오거나 종료할 수 있습니다. 단일 모드에서는 "Background limit"(기본값 32)으로 백그라운드 탭 수를 제한합니다. 한도를 넘으면 가장 오래된 비활성 백그라운드 탭이 자동으로 종료됩니다. 모든 백그라운드 탭이 작업 중이거나 사용자를 기다리는 중이면 VelaTerm이 종료할 탭을 묻습니다.

탭 바의 세부 기능은 다음과 같습니다.

• ⌘1–9(Windows와 Linux에서는 Ctrl+1–9)를 누르면 해당 위치의 탭으로 전환합니다. 마우스 가운데 버튼으로 클릭하면 탭이 닫힙니다.
• 탭 목록 끝의 ＋는 임시 터미널을 엽니다. 오른쪽 끝의 버튼으로 새 터미널, 새 문서, 내장 브라우저 탭(데스크톱 앱), 게임 센터를 엽니다.
• 탭의 컨텍스트 메뉴에는 "탭 닫기", "다른 탭 닫기", "오른쪽 탭 닫기", "모든 탭 닫기", "백그라운드로 전환"(탭의 프로세스는 계속 실행)과 트리의 세션 메뉴와 같은 항목이 있습니다.

문서 탭과 브라우저 탭은 문서 및 브라우저 탭에서 설명합니다.

4. 분할 창

탭 하나에 여러 분할 창을 둘 수 있습니다.

• ⌘D는 오른쪽으로, ⌘⇧D는 아래쪽으로 분할합니다(Windows와 Linux에서는 Ctrl+Alt+D와 Ctrl+Alt+E). 분할 창 헤더에도 같은 버튼이 있습니다. 새 분할 창은 현재 분할 창의 작업 디렉터리에서 시작하는 임시 터미널입니다.
• 기존 세션을 현재 탭에 표시하려면 세션 메뉴에서 "오른쪽 분할에서 열기", "아래쪽 분할에서 열기" 또는 "활성 분할 창에서 열기"를 선택하거나, 사이드바에서 세션을 가운데 영역으로 드래그합니다.
• "선택한 세션 바둑판 배열"은 선택한 세션 2~4개를 탭 하나에 배치합니다.
• 현재 탭의 다른 분할 창에 표시된 세션은 사이드바에서 강조 표시됩니다.

구분선은 드래그하여 옮길 수 있습니다. 백그라운드 유지는 탭 전체에 적용되므로, 탭을 떠났다가 돌아와도 레이아웃이 그대로 유지됩니다. ⌘W는 현재 분할 창을 닫으며, 마지막 분할 창을 닫으면 탭이 닫힙니다.

5. 임시 터미널

"새 터미널", ⌘T, 탭 바의 ＋를 사용하면 임시 터미널이 열립니다. 임시 터미널은 탭으로만 존재하며, 트리 노드가 되지 않고 닫으면 사라집니다. 탭에는 "임시" 표시가 붙습니다. 간단한 명령은 임시 터미널에서 실행하고, 오래 걸리는 작업은 에이전트 세션에서 진행하는 것이 좋습니다. 임시 터미널의 메뉴에는 "열기", "새 탭에서 열기", 분할 항목, "이름 바꾸기", "세션 정보", "초안 닫기"만 있습니다.

6. 상태 점과 필터링

각 에이전트 세션 옆의 점은 세션 상태를 나타냅니다. 작업 중일 때는 녹색, 사용자의 응답이 필요할 때는 노란색, 에이전트가 응답했고 사용자가 확인했으면 자홍색입니다. 전체 범례는 AI 에이전트 세션 §3에 있습니다.

상태 표시줄에는 "작업 중", "처리 대기"(사용자의 응답 필요), "확인함" 상태인 세션 수가 표시되며, 해당 세션이 없는 카운터는 숨겨집니다. 카운터를 클릭하면 사이드바에 해당 세션만 표시되고, 다시 클릭하면 필터가 해제됩니다.

사이드바에는 다음 도구가 있습니다.

• 검색 상자("세션 / 그룹 검색…")는 이름으로 트리를 필터링합니다.
• 필터 버튼("상태로 필터")으로 하나 이상의 상태를 선택할 수 있으며, 이와 별도로 표시 하나를 선택할 수 있습니다.
• 상태 필터는 설정한 시점에 조건에 맞던 세션을 계속 표시하므로, 작업하는 동안 목록이 갑자기 바뀌지 않습니다. "상태 필터 동적 추가"(설정 ▸ 동작, 기본값 켬)를 사용하면 새로 조건에 맞게 된 세션이 추가됩니다. 사이드바 하단의 "상태 필터 새로 고침"은 모든 세션을 다시 확인하고, 세션 메뉴의 "상태 새로 고침"은 해당 세션만 다시 확인합니다.
• 사이드바 하단의 "트리 보기를 아래로 분할"은 검색과 필터를 따로 적용할 수 있는 두 번째 트리 보기를 추가합니다. 예를 들어 한쪽에는 사용자의 응답이 필요한 세션만, 다른 쪽에는 전체 트리를 표시할 수 있습니다. 추가한 보기는 각각 닫을 수 있습니다.

7. 오른쪽 패널

• 파일: 세션 작업 디렉터리의 파일 트리입니다. 파일을 두 번 클릭하면 문서 탭에서 열립니다.
• 정보: 세션 세부 정보, 계정 사용량, 현재 턴, 리소스 사용량을 표시합니다. AI 에이전트 세션 §8을 참조하십시오.
• Git: 브랜치, 스테이지된 변경 사항과 스테이지되지 않은 변경 사항, 추적되지 않는 파일, 커밋 작성, 커밋 기록을 표시합니다.
• 지식 베이스: 세션 지식 베이스, 보관된 세션, 로컬 지식 베이스를 표시합니다. 로컬 지식 베이스와 세션 지식 베이스를 참조하십시오.

8. 보관: 삭제하지 않고 치워 두기

끝난 작업을 삭제할 필요는 없습니다. 세션을 마우스 오른쪽 버튼으로 클릭하고 "세션 보관"을 선택하면 세션이 숨겨집니다. 세션과 하위 세션이 트리에서 사라지고 프로세스가 종료되지만, 모든 데이터는 유지됩니다. "그룹 보관"은 그룹 안의 모든 세션을 보관하고, "선택한 세션 보관"은 선택한 세션을 보관합니다.

보관된 세션은 지식 베이스에 있으며, 사이드바 상단의 "보관된 세션" 버튼으로 열 수 있습니다. 보관된 세션은 프로젝트별로 묶여 표시되고, 검색 상자("보관 내용 검색…")로 내용을 검색할 수 있습니다. 보관된 각 세션에서 다음 작업을 할 수 있습니다.

• 대화를 읽을 수 있습니다. 에이전트 세션은 메시지를 표시하며, 대화가 없으면 터미널 녹화가 있는 경우 녹화를 표시합니다. 두 번째 탭에는 이 세션에서 생성된 지식 항목이 표시됩니다.
• "일반 세션으로 복원"은 세션을 트리의 원래 위치로 되돌립니다. 대화 ID가 그대로 유지되므로 세션을 열면 원래 대화가 재개됩니다.
• "세션 지식 베이스로 정리"는 세션에서 재사용할 수 있는 지식을 추출합니다.
• "전체 컨텍스트를 Markdown으로 내보내기"(Claude 및 Codex)는 전체 대화를 파일로 저장합니다.
• "영구 삭제 (녹화 포함)"는 데이터를 삭제하는 유일한 작업입니다.

9. 전체 검색(⌘⇧F)

"모든 세션 검색"(⌘⇧F, Windows와 Linux에서는 Ctrl+Alt+G)은 이름뿐 아니라 에이전트 대화와 기록된 터미널 출력을 포함한 모든 세션의 내용을 검색합니다.

• 여러 단어를 순서에 관계없이 조합할 수 있으며, 단어의 일부와 중국어, 일본어, 한국어 텍스트도 검색됩니다. 결과는 관련성 순으로 정렬됩니다.
• 왼쪽에는 결과가 세션별로 묶여 표시되고, 오른쪽 미리 보기에서는 현재 일치 항목이 강조 표시됩니다. ↑/↓와 Enter로 여러 세션에 걸친 일치 항목을 차례로 이동합니다.
• "세션 열기"를 누르면 작업 공간에서 해당 세션이 열립니다.
• 보관된 세션은 "보관 세션 포함"을 선택하지 않으면 검색에서 제외됩니다.

터미널 출력은 세션 녹화가 켜져 있을 때만 검색할 수 있습니다(설정 ▸ 고급 ▸ "세션 로그 기록", 기본값 끔). 에이전트 대화는 항상 검색할 수 있습니다.

10. 안전하게 삭제하기

세션을 삭제하면 녹화와 함께 영구적으로 제거됩니다. 보관된 세션이 들어 있는 그룹이나 프로젝트를 삭제해도 보관된 세션은 유지되며, 그중 하나를 복원하면 해당 프로젝트와 그룹도 함께 복원됩니다. 확실하지 않다면 먼저 보관하십시오. 보관된 내용은 언제든지 복원할 수 있습니다.

11. 종료와 작업 공간 복원

앱을 종료하면 "VelaTerm을 종료할까요?"라는 확인 창이 표시되고, 실행 중인 터미널 세션과 에이전트 세션이 중지됩니다. "작업 공간 저장"을 선택하면 다음에 실행할 때 같은 탭과 분할 창이 다시 열립니다. 복원된 세션은 자동으로 시작되지 않으며, 각 분할 창에 "저장된 작업 공간에서 복원했습니다. 아직 실행 중인 프로세스가 없습니다."라는 메시지와 "시작" 버튼이 표시됩니다. 이 확인란은 마지막 선택을 기억합니다.