세션 생성 및 Git 협업

이 장에서는 함께 사용하는 두 가지 기능을 설명합니다. 하나는 하위 작업을 독립된 하위 세션으로 분리하는 기능(선택적으로 격리된 git 워크트리 사용)이고, 다른 하나는 병렬로 진행한 브랜치를 다시 합치는 그래픽 병합 기능입니다. 두 기능을 함께 사용하면 여러 에이전트가 같은 저장소에서 병렬로 작업할 수 있습니다.

1. 하위 세션 생성이란

어떤 세션에서든 하위 작업을 분리할 수 있습니다. VelaTerm은 현재 노드 아래에 새 하위 세션을 만들고(트리가 상위 → 하위 → 그 하위로 계층화됨), 필요하면 격리된 git 워크트리를 할당한 뒤, 작업 설명을 새 세션의 첫 메시지로 보냅니다. 새 에이전트는 시작되자마자 추가 설명 없이 작업에 착수합니다.

이렇게 만든 세션은 자체 프로세스를 가진 트리의 실제 세션이므로, 언제든지 지켜보고, 응답하고, 다시 열고, 재개할 수 있습니다. 숨겨진 백그라운드 작업이 아닙니다.

여러 에이전트가 계획, 실행, 검토를 나누어 맡아야 하는 작업이라면 계획 및 실행 워크플로를 사용하십시오. 자세한 내용은 계획 및 실행을 참조하십시오.

2. 하위 세션을 만드는 방법

진입 방법	사용 주체	워크트리
명령 `vspawn "task"`	사용자 또는 스크립트(모든 세션에서 사용 가능)	기본값은 사용 안 함. `--worktree`를 지정하면 사용
명령 `vspawn-tree "task"`	위와 같음	항상 사용
Claude Code의 `/vspawn task`, Codex의 `$vspawn task`	사용자가 에이전트에 요청하면, 에이전트가 먼저 작업 내용을 독립적인 프롬프트로 확장	기본값은 사용 안 함
Claude Code의 `/vspawn-tree task`, Codex의 `$vspawn-tree task`	위와 같음	항상 사용

두 명령은 VelaTerm이 시작한 모든 세션에서 사용할 수 있습니다. 에이전트 스킬을 사용하려면 Vela Skills가 필요합니다. 설정 ▸ 일반에서 "Install"을 선택한 다음, 에이전트가 스킬을 인식하도록 Claude Code 또는 Codex 대화를 새로 시작합니다. 에이전트는 사용자가 요청할 때만 이 스킬을 호출합니다.

새 세션은 자신을 만든 대화를 볼 수 없습니다. 스킬을 사용하면 에이전트가 목표, 관련 파일, 지금까지의 결론, 제약 조건, 검수 기준을 작업 내용에 적어 넣습니다. 명령을 직접 실행할 때는 이러한 내용을 작업 텍스트에 포함하십시오.

3. 디렉터리, 에이전트, 모델

디렉터리. 하위 세션은 명령을 실행한 디렉터리에서 시작하며, 이 디렉터리는 워크트리를 만들 때 사용하는 저장소이기도 합니다. 다른 프로젝트를 사용하려면 --cwd <path>를 지정합니다(예: vspawn-tree --cwd /work/project "fix the parser"). 자체 프로젝트 폴더가 없는 컬렉션에서는 이 옵션이 중요합니다. 대화에서 저장소 하나가 명확하게 드러나면 스킬이 --cwd를 자동으로 추가합니다.
에이전트. 하위 세션은 현재 세션과 같은 에이전트를 사용하며, 일반 터미널에서 만들면 Claude Code를 사용합니다. --claude, --codex, --copilot, --kiro로 다른 에이전트를 선택할 수 있고, 확인 카드에서는 모든 에이전트 유형 중에서 선택할 수 있습니다.
모델과 추론 강도. --model <name>과 --effort <level>로 하위 세션의 모델과 추론 강도를 지정합니다(예: vspawn --model opus --effort high "port the parser"). 모델 이름은 실행할 에이전트에 맞게 지정해야 합니다. 에이전트가 지원하지 않는 설정은 세션을 만들기 전에 거부됩니다. 이 옵션이 없으면, 에이전트 유형이 같은 하위 세션은 상위 세션의 실행 인자와 권한 설정을 이어받고, 유형이 다른 하위 세션은 설정 ▸ 에이전트에 있는 해당 에이전트의 기본값을 사용합니다.
보기. 대화 보기를 지원하는 하위 세션은 상위 세션도 대화 보기를 지원하면 상위 세션과 같은 보기로 열리고, 그렇지 않으면 에이전트의 기본 보기로 열립니다.

모든 옵션은 세션 명령 §3에 나와 있습니다.

4. 생성 전 확인

기본적으로 모든 하위 세션 생성 요청은 먼저 "하위 세션 시작"이라는 제목의 확인 카드를 표시합니다. 이 카드는 작업 중인 세션의 포커스를 가져가지 않으며, 시스템 알림("하위 세션 시작 확인 대기")으로 확인을 기다리고 있음을 알려 줍니다.

카드에는 요청한 세션과 그 디렉터리("요청한 세션"), 하위 세션의 첫 메시지가 될 "작업 지시", "실행 설정"("세션 유형", "모델", "추론 강도"), "작업 디렉터리" 선택("현재 디렉터리 사용" 또는 "독립 워크트리")이 표시됩니다.
모델 제안 목록은 선택한 에이전트에서 가져옵니다. 목록을 사용할 수 없으면 모델 식별자를 직접 입력할 수 있습니다. 필드를 "에이전트 기본값"으로 두면 에이전트 자체의 설정을 사용합니다.
일반 터미널은 작업 디렉터리에서 열리기만 하며, 작업 지시를 실행하지 않습니다.
"하위 세션 시작"(또는 ⌘Enter / Ctrl+Enter)을 누르면 하위 세션이 시작되고, "취소"를 누르면 요청이 취소됩니다. 이후의 요청은 대기열에서 기다리며, 카드에 남은 요청 수가 표시됩니다("추가 확인 대기 N건").

카드 없이 요청을 바로 시작하려면 설정 ▸ 동작에서 "Confirm before spawn"을 끄거나, 개별 명령에 --yes를 추가합니다.

5. 워크트리: 충돌 없는 병렬 작업

워크트리를 사용하면 하위 세션은 자체 디렉터리의 새 브랜치에서 작업하므로, 원래 작업 디렉터리 및 다른 하위 세션과 격리됩니다. 여러 에이전트가 같은 저장소를 동시에 변경할 때 권장하는 구성입니다. 새 워크트리는 현재 커밋에서 시작하며 커밋하지 않은 변경 사항은 포함하지 않습니다. 하위 세션의 워크트리를 만들 수 없으면 해당 세션은 원래 디렉터리를 사용합니다.

워크트리에서 작업하는 세션은 사이드바의 아이콘에 작은 배지가 표시되며, 배지에 마우스 포인터를 올리면 워크트리 이름과 경로가 표시됩니다.

워크트리를 사용하는 다른 방법은 다음과 같습니다.

프로젝트, 그룹 또는 세션 메뉴의 "새 worktree 세션…" 항목은 "Worktree" 옵션이 "새로"로 설정된 생성 대화 상자를 엽니다. 디렉터리와 브랜치 이름으로 사용할 "worktree 이름"을 입력합니다. 이 대화 상자에서 세션을 "기존" 워크트리에 연결하거나 "없음"을 선택할 수도 있습니다.
그룹 메뉴의 "Worktree로 이동…" 항목은 그룹을 새 워크트리나 기존 워크트리에 연결합니다. 이후 그룹에서 만드는 세션은 해당 워크트리를 사용하며, 이미 그룹에 있던 세션은 기존 디렉터리를 유지합니다. 워크트리가 연결된 그룹에는 "그룹 정보" 항목도 있습니다.

디렉터리가 git 저장소인 세션이나 그룹의 Git 하위 메뉴에는 다음 항목이 있습니다.

항목	기능
"변경 사항 보기…"	작업 트리의 변경 사항을 파일 목록 및 diff와 함께 표시합니다
"Merge…"	병합 대화 상자를 엽니다(§6)
"Copy worktree path", "Open worktree folder"	워크트리에 연결된 세션과 그룹에서 사용할 수 있습니다
"Delete worktree…"	이 저장소의 워크트리를 선택하여 해당 디렉터리를 디스크에서 삭제합니다. "Force delete (discard uncommitted changes)"를 선택하면 커밋하지 않은 변경 사항이 있어도 삭제합니다

연결된 워크트리가 삭제된 뒤에는 세션 또는 그룹 메뉴에 "Convert to normal session" 또는 "Convert to normal group"이 표시됩니다. 이 항목을 선택하면 연결이 해제되어 세션이 다시 프로젝트 디렉터리에서 시작됩니다.

하위 트리에 워크트리가 있는 세션을 삭제하면, 확인 창에서 해당 워크트리도 함께 제거할 수 있습니다.

6. 병합: 그래픽 Git 병합

작업이 끝나면 병합합니다. 워크트리 사용 여부와 관계없이 디렉터리가 git 저장소인 세션이나 그룹에서 "Git ▸ Merge…"를 선택하면 "Merge branches" 대화 상자가 열립니다.

두 브랜치 선택. "Source branch"와 "Target branch"를 선택합니다. "Swap direction"을 누르면 두 브랜치가 서로 바뀝니다. 같은 대화 상자에서 하위 세션의 브랜치를 메인 브랜치로 병합할 수도 있고, 메인 브랜치를 하위 세션으로 병합하여 최신 상태로 만들 수도 있습니다.
확정하기 전에 병합으로 대상 브랜치에 들어올 변경 사항이 표시됩니다.
병합은 대상 브랜치가 체크아웃된 작업 트리에서 실행됩니다. 대상 브랜치가 어디에도 체크아웃되어 있지 않으면 병합을 실행할 수 없으므로, 먼저 체크아웃해야 합니다.
소스 브랜치의 작업 트리에 커밋하지 않은 변경 사항이 있으면, 입력한 메시지로 먼저 커밋합니다("Commit & merge").
병합 중 충돌이 발생하면 VelaTerm은 충돌을 그대로 두고 해결할 위치를 알려 줍니다. 해당 워크트리의 터미널에서 충돌을 해결한 다음(에이전트에게 맡길 수도 있음) 커밋합니다.

병합해도 워크트리는 삭제되지 않습니다. 워크트리가 더 이상 필요 없으면 "Git ▸ Delete worktree…"로 제거합니다.

7. 일반적인 작업 흐름

메인 세션에서 Claude Code와 작업 내용을 논의한 다음 /vspawn-tree refactor the checkout module을 실행합니다(Vela Skills 필요).
확인 카드에서 작업 내용을 검토하고 "하위 세션 시작"을 선택합니다. 하위 세션이 자체 워크트리에서 시작되어 사이드바의 상위 세션 아래에 표시되며, 작업하는 동안 상태 점이 녹색으로 표시됩니다.
메인 세션에서 작업을 계속합니다. 하위 세션이 질문하거나 작업을 마치면 상태 점이 바뀌고 알림이 표시됩니다.
하위 세션의 작업을 검토한 다음 "Git ▸ Merge…"를 선택하여 하위 세션의 브랜치를 메인 브랜치로 병합합니다.
"Git ▸ Delete worktree…"로 워크트리를 제거한 다음, 기록을 남기기 위해 하위 세션을 보관합니다.