시작하기

이 가이드는 설치부터 첫 터미널과 첫 AI 에이전트 세션까지 안내합니다. 작업을 시작하는 데는 이 내용으로 충분하며, 각 기능은 다른 장에서 자세히 설명합니다(매뉴얼 개요 참조).

1. VelaTerm 소개

VelaTerm은 AI 코딩 에이전트와 함께 작업하도록 만든 터미널 관리자입니다. 터미널 세션과 에이전트 세션을 프로젝트 → 그룹 → 세션 트리로 정리하고, Claude Code, Codex 같은 코딩 에이전트를 전용 세션으로 실행합니다. 에이전트가 작업 중인지, 사용자의 입력이 필요한지, 작업을 마쳤는지 언제든지 확인할 수 있으며, 세션을 다시 열면 대화가 이어집니다. 에이전트는 자체 터미널 인터페이스에서 실행할 수도 있고, 메시지·도구 카드·권한 버튼으로 구성된 대화 보기에서 실행할 수도 있습니다. 브라우저 원격 접속과 SSH 원격 개발을 이용하면 다른 기기에서도 세션을 이어서 사용할 수 있습니다.

2. 설치

다운로드 페이지에서 사용 중인 플랫폼에 맞는 패키지를 내려받습니다.

플랫폼	패키지	참고
macOS	`.dmg`(Apple Silicon용과 Intel용 빌드를 따로 제공)	파일을 열고 VelaTerm을 응용 프로그램 폴더로 드래그합니다. 이 앱은 Apple의 공증을 받았습니다
Windows	`-setup.exe` 설치 프로그램(min 버전과 full 버전)	full 버전(약 360MB)에는 완전한 Git Bash가 포함되어 있고, min 버전(약 25MB)은 없는 명령을 필요할 때 내려받습니다. 두 버전은 같은 위치에 설치되므로 하나만 선택합니다
Linux	`.AppImage`(x86_64 및 aarch64)	실행 권한을 부여한 뒤 실행합니다. 별도로 설치할 필요가 없습니다

VelaTerm은 업데이트를 자동으로 확인합니다. 앱 메뉴에서 "Check for Updates…"를 선택하면 즉시 확인합니다.

3. 처음 실행하기: 프로젝트 추가

처음 실행하면 사이드바가 비어 있으며, 프로젝트를 추가하는 세 가지 방법이 표시됩니다.

"프로젝트 만들기"는 새 폴더를 만들어 프로젝트로 추가합니다.
"프로젝트 열기"(⌘O, Windows와 Linux에서는 Ctrl+Alt+O)는 기존 폴더를 프로젝트로 추가합니다.
"Git에서 클론"은 저장소를 클론하여 프로젝트로 추가합니다.

사이드바 상단의 버튼으로도 같은 작업을 할 수 있습니다. 프로젝트 안에는 그룹을 원하는 깊이까지 중첩해 만들 수 있고(예: frontend, backend, testing), 그 안에 세션을 만듭니다.

왼쪽 사이드바의 프로젝트 트리

4. 첫 터미널 열기

다음 방법 중 하나로 임시 터미널을 엽니다.

⌘T(Windows와 Linux에서는 Ctrl+Alt+T)를 누릅니다.
사이드바에서 프로젝트, 그룹 또는 세션 위에 마우스 포인터를 올리고 ＋ 버튼을 클릭한 다음 "새 터미널"을 선택합니다. 터미널은 해당 노드의 디렉터리에서 시작됩니다. 프로젝트와 그룹의 컨텍스트 메뉴에도 같은 항목이 있습니다.
가운데 영역이 비어 있으면 "터미널 만들기"를 클릭합니다.

세션이 열려 있지 않은 가운데 영역

임시 터미널은 탭으로만 존재합니다. 트리의 노드가 되지 않고 닫으면 사라지므로, 간단한 명령을 실행할 때 적합합니다.

5. 첫 AI 에이전트 세션 열기

프로젝트나 그룹을 마우스 오른쪽 버튼으로 클릭하고 "새 Claude 세션"을 선택합니다. 메뉴 최상위에는 Claude, Codex, OpenCode가 있고, "더 많은 에이전트 세션"에는 지원하는 14가지 에이전트가 모두 있습니다. ⌘N(Windows, Linux 및 일반 브라우저에서는 Ctrl+Alt+N)을 눌러 검색 가능한 에이전트 목록을 열 수도 있습니다.

VelaTerm은 프로젝트 디렉터리에서 에이전트를 시작합니다. Claude, Codex, OpenCode, Pi, OMP 세션은 대화 보기로 열리며, 아래쪽 입력란에 메시지를 입력하고 Enter를 누르면 됩니다. 다른 에이전트는 에이전트 자체의 터미널 인터페이스를 보여 주는 터미널 보기로 열립니다. 분할 창 헤더의 전환 버튼을 누르면 세션을 다른 보기로 전환할 수 있습니다. 자세한 내용은 대화 보기를 참조하십시오.

정보 패널이 표시된 실행 중인 Claude 세션

이제부터 다음 세 가지 기능을 사용할 수 있습니다.

상태 점: 사이드바에서 세션 옆에 있는 점이 에이전트의 상태를 나타냅니다. 녹색은 작업 중, 노란색은 사용자의 응답이 필요한 상태(질문 또는 권한 요청), 자홍색은 에이전트가 응답했고 사용자가 이미 확인한 상태를 뜻합니다.
시스템 알림: 에이전트가 멈추고 사용자를 기다리면 알림이 표시됩니다. 해당 세션을 이미 보고 있으면 알림이 표시되지 않습니다.
자동 재개: 탭을 닫거나 앱을 종료해도, 다음에 세션을 열면 멈춘 지점부터 대화가 이어집니다. 새 대화가 필요하면 새 세션을 만듭니다.

에이전트 CLI가 아직 설치되지 않았다면 세션에 설치 카드가 표시됩니다. 카드에는 사용 중인 시스템에 권장되는 설치 명령과 "지금 설치" 버튼이 있습니다.

6. 간단히 둘러보기

메인 창

왼쪽 사이드바: 검색 상자와 상태 필터가 있는 프로젝트 트리입니다. 상단에는 프로젝트 만들기, 프로젝트 가져오기, Git에서 클론, 모든 세션 검색, 보관된 세션 버튼이 있습니다.
가운데 영역: 탭 바와 열려 있는 세션이 표시됩니다. 기본적으로 트리에서 에이전트 세션을 클릭하면 현재 탭을 재사용하며, 이전 탭은 백그라운드에서 계속 실행됩니다. 탭을 닫으면 그 탭의 프로세스가 종료됩니다. 탭은 여러 분할 창으로 나눌 수 있습니다(⌘D는 오른쪽, ⌘⇧D는 아래쪽).
오른쪽 패널: 현재 세션에 따라 내용이 바뀌며, 파일, 정보(세션 세부 정보, 계정 사용량, 컨텍스트 및 리소스 사용량), Git(브랜치, 변경 사항, 커밋), 지식 베이스의 네 가지 탭이 있습니다.
상태 표시줄: 세션 수, 현재 세션 유형, Git 브랜치, 권한 모드, 알림 스위치, 작업 중 / 처리 대기 / 확인함 카운터가 표시됩니다. 카운터를 클릭하면 사이드바에 해당 상태의 세션만 표시됩니다.
제목 표시줄 오른쪽: 테마 전환, 원격 접속, 원격 서버에 연결, 공유, 설정, 계정, 피드백 버튼과 양쪽 패널을 표시하거나 숨기는 버튼이 있습니다.

7. 다음 단계

트리, 탭, 분할 창, 보관, 전체 검색: 인터페이스 및 세션 관리.
에이전트 기능, 재개, 포크, 권한: AI 에이전트 세션.
대화 보기에서 작업하기: 대화 보기.
에이전트가 별도의 워크트리에서 하위 세션을 시작하게 하기: 세션 생성 및 Git 협업.
터미널 기능(검색, 이미지 붙여넣기, 명령어 자동 완성): 터미널 사용법.
휴대폰이나 다른 컴퓨터에서 VelaTerm 사용하기: 원격 개발 및 관리.