AI 에이전트 세션

이 장에서는 VelaTerm의 핵심 차별점인 AI 코딩 에이전트를 타입화된 세션 형태로 호스팅하는 기능을 다룹니다. 실시간 상태 표시, 자동 대화 재개, 포크, 권한 제어가 그 예입니다.

1. 지원되는 에이전트

새 세션 메뉴에는 9가지 로컬 에이전트 유형이 제공됩니다: Claude Code, Codex, OpenCode, Copilot CLI, Cursor CLI, Antigravity, Cline, Pi, Crush입니다. 각 에이전트의 기능은 약간씩 다릅니다:

“권한 기반”이란 VelaTerm 에이전트가 시작될 때 공식 콜백 메커니즘(훅/플러그인/확장 프로그램)을 주입하여, 상태 변화가 터미널 출력에서 추측되는 것이 아니라 에이전트 측에서 능동적으로 보고되는 것을 의미합니다. 모든 정보를 보고하지 않는 에이전트(codex, crush)의 경우 화면 감지 기능이 그 공백을 채웁니다. 일반 터미널에서 직접 실행하는 에이전트는 영향을 받지 않으며, 주입은 VelaTerm세션 시작 시에만 적용됩니다.

2. 상태 점: 누가 작업 중이고 누가 나를 기다리고 있는가

각 에이전트 세션 옆의 점은 실시간으로 업데이트됩니다. 녹색 = 작업 중, 노란색 = 사용자의 조치 필요(질문, 권한 요청, 읽지 않은 알림), 보라색 = 답변 완료 및 확인됨. 상태 표시줄의 세 개 카운터는 클릭 가능한 필터로, 여러 에이전트가 동시에 작동할 때 이를 통해 자신을 기다리는 에이전트를 찾을 수 있습니다.

시스템 알림과 함께 사용됩니다. 에이전트가 사용자를 위해 일시 중지될 때(질문이나 턴 종료 시) 알림이 표시되고, 해당 세션에는 읽지 않은 표시가 생기며 도크의 표시도 그 수를 반영합니다. 이미 해당 세션을 보고 있을 경우에는 아무런 알림도 발생하지 않습니다. 서명된 macOS 빌드에서는 알림을 클릭하면 바로 해당 세션으로 이동합니다. 상태 표시줄의 “알림” 항목이 전체적인 전환 기능입니다.

3. 자동 재개: 닫았다가 다시 열어도 대화는 그대로

한 줄로 요약하자면: 트리의 각 에이전트 세션 노드는 하나의 진행 중인 대화에 해당합니다.

• 처음 실행할 때 VelaTerm은 에이전트의 세션 ID를 자동으로 기억합니다.
• 그 이후에는 탭을 닫았든 앱을 종료했든, 해당 노드를 다시 열면 에이전트가 재시작되면서 재개 플래그(claude --resume <id> 등)와 함께 이전 상황이 그대로 복원됩니다. 재개하기 전에 VelaTerm는 대화가 여전히 존재하는지 확인하며, 삭제된 경우에는 멈추는 대신 조용히 새로 시작됩니다.
• 새로운 대화가 필요하신가요? 새 노드를 생성하면 됩니다. 이 전체 메커니즘은 자동으로 이루어지므로 별도의 스위치나 정리 작업이 필요 없습니다.

수동 재개: 다른 곳에서 에이전트 세션 ID를 얻은 경우(예: 일반 터미널에서 진행한 대화), 새 세션 메뉴 하단의 “세션 재개…”를 사용하여 유형을 선택하고 ID를 붙여넣으면 해당 대화가 정상적인 세션 노드로 트리에 추가됩니다.

4. 포크: 현재 대화에서 분기하기

대화가 있는 claude/Codex/Pi 세션을 마우스 오른쪽 버튼으로 클릭한 다음 “세션 포크”를 선택하면, 원본 대화의 현재 이력에서 분기된 자매 노드가 생성되어 원본은 그대로 유지됩니다. 이는 git 브랜치와 유사합니다. “동일한 상황에서 두 가지 접근법을 시도”할 때 매우 유용합니다.

5. 권한 모드 및 시작 인자

두 단계 권한: 지원되는 각 세션은 “기본” 모드(단계별 확인) 또는 “모든 권한 확인 생략” 모드로 실행될 수 있습니다. 후자는 YOLO 모드라고도 하며, 해당 플래그(--dangerously-skip-permissions 등)와 함께 에이전트가 시작됩니다. 세션 편집 양식의 “모든 권한 확인 생략”을 통해 각 세션별로 전환할 수 있으며, 설정 ▸ 에이전트에서는 유형별 기본값을 지정할 수 있습니다.

맞춤형 시작 인자: 세션 편집 양식의 “시작 인자” 항목에 해당 세션용 추가 명령줄 인자를 입력할 수 있습니다. 설정 ▸ 에이전트에는 유형별 기본 템플릿이 저장되어 있으며, 새 세션 메뉴의 “인자 포함으로 새로 만들기…”를 통해 한 번에 매개변수가 지정된 세션을 생성할 수 있습니다.

실행 파일 경로: 에이전트가 PATH 외부에 설치된 경우, 설정 ▸ 에이전트에서 유형별로 “실행 파일 경로”를 지정해 주세요. 비워두면 PATH에서 해당 명령을 찾습니다.

6. 설치되지 않았나요? 설치 안내

설치되지 않은 에이전트를 실행해도 command not found에서 막히지 않습니다. 세션에는 사용 중인 운영체제에 맞는 설치 명령이 포함된 안내 카드가 표시되며, 이를 복사하거나 한 번의 클릭으로 바로 실행할 수 있습니다. 설치가 완료되면 바이너리의 위치가 자동으로 감지되어 경로 설정에 채워지고, 재시도 버튼을 클릭하면 세션이 다시 시작됩니다. 각 에이전트는 여전히 자체 로그인/API 키 설정이 필요하며, 해당 카드에는 문서 링크가 제공됩니다.

7. 정보 패널: 모델, 사용량, 리소스

에이전트 세션이 열려 있을 때 오른쪽 패널의 정보 탭에는 실행 중인 세부 정보가 표시됩니다:

• AGENT: 세션 이름, 유형, 실행 상태, 작업 디렉터리, Git 브랜치, 시작 시간, 실행 시간.
• MODEL / This turn (claude): 현재 모델, 컨텍스트 사용량, 현재 실행 중인 도구.
• USAGE (claude / codex): 공식 할당량 사용 현황(5시간 및 7일 기간 기준); 갱신 간격은 설정 가능함(Usage refresh).
• RESOURCES: 세션의 프로세스 트리에서 측정된 CPU/메모리 사용량.

8. 트랜스크립트, 내보내기, 아카이빙

• 마우스 오른쪽 버튼 → “Session 내보내기…”(claude / codex, 대화가 녹화된 후 한 번 표시됨)를 클릭하면 어시스턴트의 사고 과정과 모든 도구 호출에 포함된 입력값 및 결과까지 포함된 전체 컨텍스트가 Markdown에 저장됨.
• 아카이브된 에이전트 세션은 아카이브 패널에서 파싱된 트랜스크립트 형태로 읽을 수 있으며(터미널 재생 필요 없음), 복원하면 평소와 같이 계속 사용할 수 있음. Interface & Session Management §7을 참조할 것.

9. 기타 사항

• 자동 명명: 이름이 지정되지 않은 세션은 첫 메시지의 내용을 기반으로 이름이 부여됨(claudie 및 기타).
• 실시간 테마 적용: 밝은 테마/어두운 테마 전환 시 claude 세션의 스킨이 즉시 변경되며 재시작이 필요 없음.
• Vela Skills: Settings ▸ General에 있는 “Vela Skills” 옵션을 활성화하면 /vspawn, /vspawn-tree, /vopen 스킬들이 ~/.claude/skills/에 설치되어, claude가 대화 중에 서브 세션을 생성하거나 문서를 열 수 있음(Session Spawning & Git Collaboration 참조).
• 윈도우: claude / codex는 PowerShell를 통해 완전히 지원됨; 다른 유형의 경우 최선을 다해 지원됨.