세션 명령

VelaTerm은 자신이 시작하는 모든 세션에 짧은 명령 모음을 추가합니다. 사용자와 에이전트는 이 명령으로 다른 세션을 시작하고, 파일을 열고, 다른 대화를 읽거나 검색하고, 어떤 세션이 작업 중인지 확인하고, 세션 간에 메시지를 보내고, 오래 걸리는 명령이 끝나기를 기다립니다. 이 장은 각 명령과 이에 대응하는 에이전트 스킬에 대한 참고 자료입니다.

1. 명령을 사용할 수 있는 곳

이 명령들은 VelaTerm이 시작한 모든 세션의 PATH에 있습니다. 일반 터미널과 에이전트 세션, 터미널 보기와 대화 보기, 원격 VelaTerm 서버의 세션이 모두 포함되며, 별도로 설치할 필요가 없습니다. 이러한 세션 밖에서 실행하면 "not inside a VelaTerm session"이라는 메시지를 출력하고 중지됩니다.

명령에 --help를 붙여 실행하면 사용법이 출력됩니다.

여러 명령이 세션 참조를 인자로 받습니다. 세션 참조는 전체 세션 ID, 8자 이상의 ID 접두사, 정확한 세션 이름, 이름의 고유한 일부 중 하나입니다. 공백이 포함된 이름은 따옴표로 묶습니다. 참조가 여러 세션과 일치하면 명령이 후보 목록을 표시합니다.

2. 에이전트 스킬(Vela Skills)

설정 ▸ 일반 ▸ "Vela Skills"에서 Claude Code와 Codex에 이 명령에 대응하는 스킬을 설치하며, "Reinstall"을 누르면 스킬을 새로 고칩니다. 설치한 뒤에는 에이전트가 스킬을 인식하도록 Claude 또는 Codex 대화를 새로 시작합니다. Claude Code에서는 /name으로, Codex에서는 $name으로 스킬을 호출합니다.

호출 주체가 "사용자"인 스킬은 사용자가 호출할 때만 실행됩니다. 나머지 스킬은 사용자가 다른 세션이나 이전 작업을 언급하면 에이전트가 스스로 사용할 수도 있습니다. vask는 스킬로만 제공되며, vrefer <session> --ask "<question>"을 실행합니다.

3. vspawn 및 vspawn-tree

vspawn [--worktree] [--cwd <path>] [--yes] [--claude|--codex|--copilot|--kiro] [--model <name>] [--effort <level>] <task description...>

현재 세션 아래에 새 세션을 시작하고 작업 내용을 첫 메시지로 보냅니다. vspawn-tree는 별도의 git 워크트리를 사용하는 같은 명령입니다.

자세한 내용은 세션 생성 및 Git 협업과 계획 및 실행을 참조하십시오.

4. vopen

vopen <file|url>...

각 인자를 가운데 영역에서 엽니다. Markdown 파일은 Markdown 편집기에서, 이미지는 이미지 뷰어에서, 그 밖의 파일은 코드 편집기에서 열립니다. 웹 주소(http 또는 https)는 브라우저 탭에서 열리며, 브라우저 탭은 데스크톱 앱에서만 사용할 수 있습니다. 상대 경로는 현재 디렉터리를 기준으로 해석됩니다. 문서 및 브라우저 탭을 참조하십시오.

5. vrefer 및 vask

vrefer <session> [--last N] [--range A:B] [--json]
vrefer <session> --ask "<question>" [--with <agent>] [--timeout N]
vrefer --list [--json]

다른 세션의 대화를 출력합니다. 다른 세션이 실행 중일 필요는 없으며, 그 세션에는 아무것도 전송되지 않습니다.

--ask는 답변을 위해 별도의 에이전트 프로세스를 시작하고 답변만 가져오므로, 긴 대화가 현재 컨텍스트를 차지하지 않습니다. 설정 ▸ 동작 ▸ "세션 참조 컨텍스트"에서 답변하는 에이전트에 대화를 전달하는 방식을 선택합니다. "전체 기록 사용"(기본값)을 선택하거나, "먼저 요약"을 선택하여 같은 곳에서 지정한 "요약 에이전트", 모델, 추론 강도로 대화를 먼저 압축할 수 있습니다. 답변을 생성할 수 없으면 vrefer가 그 이유를 설명하고 대신 대화를 출력합니다.

Claude Code, Codex, OpenCode, Pi, OMP, Grok Build, Kiro(텍스트 기록만)의 대화를 읽을 수 있습니다. 그 밖의 세션 유형과 에이전트 대화가 아직 기록되지 않은 세션은 읽을 수 없습니다.

6. vsearch

vsearch <words...> [--session <session>] [--all|--archived] [--limit N] [--json]

연결된 VelaTerm에 있는 모든 세션의 대화를 검색합니다. 모든 단어가 순서에 관계없이 일치해야 합니다.

각 결과에는 세션 이름, ID 접두사, 일치 항목 수, 메시지 번호가 붙은 몇 개의 발췌문, 전체 대화를 읽는 vrefer 명령이 표시됩니다. 메시지 번호는 vrefer --range에 사용할 수 있습니다. 결과는 에이전트 대화에서만 가져오며, 터미널 녹화에만 있는 일치 항목은 반환되지 않습니다. "no matches"도 정상적인 결과입니다.

7. vstat

vstat [--wait] [--follow] [--timeout N] [--json]

각 세션의 상태를 working, asking(권한 또는 답변 대기), waiting(턴 완료), unknown 중 하나로 표시합니다. 이 상태는 활동 여부를 나타낼 뿐, 작업이 완료되었는지를 나타내지는 않습니다.

선택적으로 첫 번째 인자에 이전 VelaTerm 버전의 오케스트레이션 ID를 지정하여 결과를 필터링할 수 있습니다. 계획 및 실행 워크플로에는 vflow status를 사용합니다.

8. vtell

vtell <session> [--steer] [--message-id msg-UUID] [message...]
vtell [planner-session] --report --round N [--message-id msg-UUID] [message...]

다른 세션에 메시지를 보냅니다. 메시지 인자가 없으면 표준 입력에서 텍스트를 읽습니다. 받는 세션의 대화에는 보낸 세션의 에이전트 아이콘과 세션 이름이 표시되며, 대화를 다시 열어도 그대로 표시됩니다.

• 받는 세션은 대화 보기를 사용하는 Claude Code, Codex, OpenCode, Pi 또는 OMP 세션이어야 합니다. 보관된 세션과 보내는 세션 자신은 받는 세션으로 지정할 수 없습니다.
• 받는 세션이 유휴 상태이면 새 턴이 시작됩니다. 받는 세션이 작업 중이면 턴이 끝날 때까지 메시지가 대기열에서 기다리며, --steer를 사용하면 진행 중인 턴에 바로 추가됩니다.
• 메시지 텍스트는 최대 65,536바이트까지 보낼 수 있습니다.
• 명령은 sent, queued, steered 중 하나의 수신 확인을 출력합니다. blocked는 받는 세션이 권한이나 답변을 기다리고 있다는 뜻입니다. 수신 확인은 메시지가 전달되었음을 나타낼 뿐, 받는 세션이 작업을 마쳤다는 뜻은 아닙니다.
• 명령은 메시지 ID도 출력합니다. 전달 결과가 불확실한 메시지를 다시 보내려면 --message-id와 같은 텍스트로 명령을 반복합니다. 이렇게 하면 메시지가 두 번 전달되지 않습니다.
• --report --round N은 계획 및 실행 워크플로에서 실행 세션이 결과를 검토받기 위해 제출할 때 사용하며, 보고는 해당 실행 세션의 계획 세션으로 전달됩니다. 계획 및 실행을 참조하십시오.

9. vrun

vrun [-t <seconds>] <label> <command> [arguments...]
vrun --status <label>

명령을 시작하고 완료될 때까지 기다린 다음, 종료 코드, 경과 시간, 로그의 끝부분을 출력합니다. 명령의 종료 코드는 그대로 전달됩니다. vrun은 오래 걸리는 빌드와 테스트를 위한 명령으로, 에이전트가 이러한 작업을 vrun으로 실행하면 결과가 나오는 즉시 알 수 있습니다.

• -t <seconds>는 vrun이 기다리는 시간을 지정합니다(기본값 1800). 시간이 다 되면 vrun은 코드 124로 종료되며, 명령은 계속 실행됩니다.
• --status <label>은 해당 레이블로 이전에 시작한 명령의 상태를 보고합니다.
• 명령이 실행되는 동안 세션은 "작업 중" 상태를 유지합니다. 터미널 보기에서는 터미널 위의 "백그라운드 명령" 행에 실행 중인 명령이 "로그" 및 "중지" 버튼과 함께 나열됩니다. 터미널 사용법 §6.1을 참조하십시오.

10. vkb

vkb explore <query> | search <query> | node <symbol-id> | callers <id> [depth] | callees <id> [depth]
    | impact <id> [depth] | path <from-id> <to-id> | files [path]
    | memories <query> | memory <entry-id> | notes <query> | note <vault-id> <path> | status

현재 체크아웃의 코드 그래프와 연결된 VelaTerm의 지식 베이스를 조회합니다. 코드를 조회하려면 프로젝트의 코드 그래프 페이지에서 인덱싱을 활성화해야 합니다. vkb는 읽기만 하며, 지식 항목을 변경하지 않습니다. 코드 그래프 및 지식 베이스, 세션 지식 베이스, 로컬 지식 베이스를 참조하십시오.

11. vflow

vflow status|stop|propose|dispatch|accept|block <workflow-id> [--round N --message-id msg-UUID] < message.txt

계획 및 실행 워크플로를 제어합니다. propose, dispatch, accept, block은 계획 세션이 워크플로를 진행하면서 사용합니다. 사용자에게는 주로 다음 두 가지 동작이 필요합니다.

• vflow status <workflow-id>는 워크플로의 상태, 작업, 세션, 현재 라운드를 표시합니다.
• vflow stop <workflow-id>는 이후 라운드를 중지하고 실행 중인 세션에 중지를 요청합니다.

12. vela 명령

macOS에서는 설정 ▸ 일반 ▸ "셸 명령"에 "‘vela’ 명령 설치"가 있습니다. 이 기능은 VS Code의 code 명령과 비슷한 vela <project-path> 명령을 셸에 추가합니다. 아무 터미널에서나 이 명령을 실행하면 VelaTerm에서 해당 프로젝트가 열리며, 이미 열려 있으면 그 프로젝트로 전환됩니다. VelaTerm은 자신이 설치하지 않은 기존 vela 명령을 덮어쓰지 않습니다.