시작하기
이 가이드는 설치부터 첫 번째 터미널 사용 및 첫 AI 에이전트 세션까지 안내해 줍니다. 작업을 시작하기에 충분하며, 각 기능의 상세 내용은 이 매뉴얼 시리즈의 나머지 부분에 있습니다(매뉴얼 개요 참조).
1. VelaTerm이란 무엇인가요?
한 문장으로 요약하자면, AI 에이전트 시대를 위해 만들어진 터미널 관리자입니다. 이 도구는 흩어져 있는 여러 터미널 세션을 프로젝트 → 그룹 → 세션 구조로 정리하며, Claude Code 및 Codex와 같은 코딩 에이전트들을 일등 시민처럼 다룹니다. 에이전트들이 작업 중인지, 입력을 요청하는 중인지, 아니면 작업이 완료된 상태인지 실시간으로 확인할 수 있으며, 세션을 다시 열면 대화가 자동으로 이어집니다. 브라우저 원격 접속과 SSH 원격 개발 기능까지 더해지면 어디서든 세션을 제어할 수 있습니다.
2. 설치
다운로드 페이지에서 사용 중인 플랫폼에 맞는 패키지를 다운로드하세요:
| 플랫폼 | 패키지 | 참고사항 |
|---|---|---|
| macOS | .dmg (별도의 Apple Silicon / Intel 빌드) | VelaTerm을 열어 ‘응용 프로그램’ 폴더로 드래그하세요. 이 앱은 인증이 완료되어 있어 보안 우회 없이 바로 실행됩니다. |
| Windows | -setup.exe 설치 프로그램으로, min/full 두 가지 버전이 있습니다. | full 버전(~360MB)은 완전한 Git Bash 구성을 포함해 바로 사용 가능하며, min 버전(~25MB)은 크기가 작아 필요한 명령어만 필요할 때 다운로드됩니다. 두 버전 모두 동일한 위치에 설치되므로 원하는 것을 선택하세요. |
| Linux | .AppImage (x86_64 / aarch64) | 실행 파일로 만들어 바로 실행하면 설치가 필요 없습니다. |
이 앱은 자동으로 업데이트를 확인하며(“업데이트 확인…” 메뉴 항목도 있음), 따라서 최신 릴리스 채널과 항상 동기화됩니다.
3. 처음 실행 시: 프로젝트 가져오기
처음 실행하면 창이 비어 있으며, 왼쪽 사이드바에 디렉터리를 가져오라는 안내가 표시됩니다. 사이드바 상단의 폴더 버튼을 클릭하거나 ⌘O 키를 눌러 작업 중인 디렉터리를 선택하면, 그 디렉터리가 트리의 첫 번째 “프로젝트”가 됩니다. 또는 “Git에서 복제” 기능을 사용해 리포지토리 URL에서 직접 프로젝트를 생성할 수도 있습니다.
프로젝트가 추가되면 그 아래에 그룹을 만들 수 있습니다(최대한 깊이까지 중첩 가능 — 예: frontend / backend / testing). 그룹 안에는 세션이 존재합니다. 트리 구조는 다음과 같습니다:
4. 첫 번째 터미널 열기
다음 세 가지 방법 중 하나를 사용하세요:
- ⌘T 키를 누르세요(Windows/Linux에서는 Ctrl+Alt+T). 즉시 임시 터미널 탭이 생성됩니다. 터미널은 언제나 초안입니다. 중앙 패널 탭으로만 존재하고 트리에 포함되지 않으며 닫으면 삭제되는데, 그래서 빠른 명령 실행에 잘 맞습니다.
- 사이드바에서 프로젝트·그룹·세션 행에 마우스를 올린 뒤 ＋ 버튼 → “새 터미널 세션”을 선택하세요. 만들어지는 것은 같은 초안이며, 해당 노드의 작업 디렉터리에서 열린다는 점만 다릅니다. 그룹의 마우스 오른쪽 버튼 메뉴에도 같은 항목이 있습니다.
- 중앙 패널에 아무 세션도 열려 있지 않을 때는 “터미널 생성” 버튼을 클릭하기만 하면 됩니다.
5. 첫 번째 AI 에이전트 세션 열기
프로젝트나 그룹을 마우스 오른쪽 버튼으로 클릭한 뒤 “새 Claude 세션”을 선택하세요(메뉴에는 Codex 및 “기타 에이전트 세션” 항목도 포함되어 있습니다). VelaTerm은 해당 프로젝트의 디렉터리에서 Claude Code을 실행하고 자동으로 상태 보고용 훅을 삽입합니다:
이 시점부터 세 가지 기능을 사용할 수 있습니다:
- 상태 점: 사이드바의 세션 옆에 있는 작은 점은 실시간으로 에이전트의 상태를 나타냅니다. 녹색은 작업 중임을, 노란색은 사용자의 입력이나 승인이 필요함을, 보라색은 에이전트가 응답을 보냈으며 사용자가 그 내용을 확인했음을 의미합니다. 더 이상 창을 전환해 확인할 필요가 없습니다.
- 시스템 알림: 에이전트가 작업을 멈추고 사용자의 입력이나 확인을 기다릴 때 시스템 알림이 표시됩니다. 이미 세션을 보고 있을 경우에는 알림이 표시되지 않습니다.
- 자동 재개: 탭을 닫거나 전체 앱을 종료해도 다음에 해당 세션 노드를 열면 대화가 마지막에 멈춘 지점부터 바로 이어집니다. 완전히 새로운 대화를 원한다면 새 세션 노드를 생성하세요.
이 내용은 해당 CLI가 설치되어 있다는 전제하에 작성되었습니다. CLI가 설치되어 있지 않아도 문제가 되지 않습니다. 세션 내에 설치 안내 카드가 표시되어 사용 중인 플랫폼에 맞는 설치 명령어, 원클릭 설치 기능, 재시도 버튼이 제공됩니다.
6. UI 안내
- 왼쪽 사이드바: 프로젝트 트리 + 검색 상자 + 네 개의 헤더 버튼(프로젝트 가져오기, Git에서 복제, 전체 검색, 아카이브된 세션).
- 중앙 패널: 탭 바 + 터미널 영역. 탭은 브라우저와 유사하게 동작합니다. 트리의 세션을 클릭하면 기본적으로 현재 탭이 재사용되며, 다른 탭으로 전환해도 백그라운드에서 계속 실행됩니다. 탭을 닫아야만 해당 프로세스가 실제로 종료됩니다. 탭은 패널로 분할할 수도 있습니다(오른쪽으로 ⌘D, 아래로 ⌘⇧D).
- 오른쪽 패널: 현재 세션에 따라 구성되며, 파일(파일 트리), 정보(기본 정보, 모델, 사용량, 리소스 사용량), Git(브랜치 및 변경 사항)의 세 가지 탭이 있습니다.
- 상태 표시줄: 세션 수, 현재 세션 상태, Git브랜치, 알림 켜기/끄기, 그리고 전체적인 작업 중 / 대기 중 / 확인됨 카운터가 표시됩니다. 원하는 상태를 클릭하면 사이드바가 해당 상태의 세션들만 표시하도록 필터링됩니다.
- 제목 표시줄, 오른쪽: 밝은 테마/어두운 테마 전환, 원격 접속, 원격 서버 연결, 설정.
7. 다음으로 살펴볼 내용
- 트리와 탭에 관한 자세한 내용(분할, 아카이브, 전체 검색, 다중 선택 일괄 작업): 인터페이스 및 세션 관리.
- 터미널 기능(검색, 이미지 붙여넣기, Windows 셸 선택): 터미널 사용법.
- 에이전트의 기능 차이, 재개/포크/권한 모드: AI 에이전트 세션.
- 에이전트가 하위 작업들을 분리된 작업 트리로 나누어 병렬로 작업하도록 하는 방법: 세션 생성 및 Git 협업.
- 휴대폰이나 다른 컴퓨터에서도 이 모든 기능을 사용하는 방법: 원격 개발 및 관리.