セッションコマンド
VelaTerm は、起動するすべてのセッションに短いコマンドのセットを追加します。ユーザーとエージェントは、これらのコマンドを使って、他のセッションの起動、ファイルを開く操作、他の会話の読み取りと検索、作業中のセッションの確認、セッション間のメッセージ送信、時間のかかるコマンドの完了待ちを行えます。この章は、各コマンドと、それに対応するエージェント用スキルのリファレンスです。
1. コマンドを使える場所
これらのコマンドは、VelaTerm が起動するすべてのセッションの PATH に含まれています。対象は通常のターミナルとエージェントセッションで、ターミナルビューと会話ビューのどちらでも使え、リモートの VelaTerm サーバー上のセッションも含まれます。インストールは不要です。こうしたセッションの外で実行すると、「not inside a VelaTerm session」と表示されて終了します。
コマンドに --help を付けて実行すると、使い方が表示されます。
| コマンド | 用途 |
|---|---|
vspawn、vspawn-tree | タスクを指定して子セッションを起動する |
vopen | ファイルをドキュメントタブで、Web アドレスをブラウザタブで開く |
vrefer | 他のセッションの会話を読む、またはその会話について質問する |
vsearch | すべてのセッションの会話を検索する |
vstat | 作業中、確認待ち、待機中のセッションを表示する |
vtell | 他のセッションにメッセージを送信する |
vrun | 時間のかかるコマンドを実行し、完了を待つ |
vkb | ナレッジベースとコードグラフを照会する |
vflow | 計画・実行ワークフローを制御する |
いくつかのコマンドは、引数としてセッション参照を受け付けます。セッション参照には、完全なセッション ID、8文字以上の ID の先頭部分、セッション名の完全一致、または名前の一部で一意に特定できる文字列を指定できます。空白を含む名前は引用符で囲んでください。参照が複数のセッションに一致した場合、コマンドは候補を一覧表示します。
2. エージェント用スキル（Vela Skills）
「設定」▸「一般」▸「Vela Skills」で、対応するスキルを Claude Code と Codex にインストールできます。「Reinstall」でスキルを更新します。その後、Claude または Codex の新しい会話を始めると、エージェントがスキルを読み込みます。スキルは、Claude Code では /name、Codex では $name の形式で呼び出します。
| スキル | 呼び出す主体 | 機能 |
|---|---|---|
vspawn、vspawn-tree | ユーザー | 現在の会話から自己完結したタスクを作成し、子セッションまたは計画・実行ワークフローを開始する |
vopen | ユーザー | ファイルや Web アドレスを開く |
vkb | ユーザー | ナレッジベースとコードグラフを照会する |
vrefer、vsearch、vask | ユーザーまたはエージェント | 他の会話を読む、検索する、または質問する |
vstat | ユーザーまたはエージェント | 作業中のセッションを報告する |
vtell | ユーザーまたはエージェント | 他のセッションにメッセージを送信する |
「ユーザー」と記載したスキルは、ユーザーが呼び出したときにのみ実行されます。その他のスキルは、ユーザーが他のセッションや以前の作業に言及したときに、エージェントが自ら使うこともあります。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 の独立したワークツリーを使う点を除いて同じコマンドです。
| オプション | 意味 |
|---|---|
--worktree | 子セッションに専用のワークツリーとブランチを割り当てる |
--cwd <path> | 子セッションの作業ディレクトリとリポジトリ |
--yes | 確認カードを表示せずに起動する |
--claude、--codex、--copilot、--kiro | 子セッションのエージェント。デフォルトは現在のセッションのエージェント（通常のターミナルでは Claude Code） |
--model <name>、--effort <level> | 子セッションのモデルと思考の深さ |
--plan-execute と関連オプション | 計画・実行ワークフローを開始する |
詳しくは、セッションの生成とGitによるコラボレーションと計画と実行を参照してください。
4. vopen
vopen <file|url>...
各引数を中央ペインで開きます。Markdown ファイルは Markdown エディター、画像は画像ビューアー、その他のファイルはコードエディターで開きます。Web アドレス（http または https）はブラウザタブで開きます。ブラウザタブはデスクトップアプリでのみ使えます。相対パスは、現在のディレクトリを基準に解決されます。ドキュメントとブラウザタブを参照してください。
5. vrefer と vask
vrefer <session> [--last N] [--range A:B] [--json]
vrefer <session> --ask "<question>" [--with <agent>] [--timeout N]
vrefer --list [--json]
他のセッションの会話を出力します。対象のセッションが実行中である必要はなく、対象のセッションには何も送信されません。
| オプション | 意味 |
|---|---|
--last N | 最後の N 件のメッセージのみ |
--range A:B | A 番目から B 番目の手前までのメッセージ（0 から数える） |
--ask "<question>" | 会話を出力する代わりに、エージェントに会話を読ませて質問に回答させる |
--with <agent> | 回答するエージェント：claude、codex、opencode、pi、omp、cursor、copilot、grok のいずれか。省略すると自動的に選ばれる |
--timeout N | 回答に許容する秒数（デフォルトは 120） |
--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 にあるすべてのセッションの会話を検索します。すべての語が、順序を問わず一致する必要があります。
| オプション | 意味 |
|---|---|
--session <session> | このセッションだけを検索する |
--all | アーカイブ済みセッションも含める（デフォルトでは、アーカイブされていないセッションのみ） |
--archived | アーカイブ済みセッションだけを検索する |
--limit N | 一致するセッションの最大数（デフォルトは 10） |
--json | 機械可読な形式で出力する |
各結果には、セッション名、ID の先頭部分、一致した件数、メッセージ番号付きのいくつかの抜粋、会話全体を読むための vrefer コマンドが表示されます。メッセージ番号は vrefer --range で使えます。結果はエージェントの会話からのみ取得され、ターミナルの録画にしかない一致は返されません。「no matches」は通常の結果です。
7. vstat
vstat [--wait] [--follow] [--timeout N] [--json]
各セッションの状態を表示します。状態は working、asking（権限の承認または回答を待っている）、waiting（ターンを終えた）、unknown のいずれかです。状態が示すのは活動の有無であり、タスクが完了したかどうかではありません。
| オプション | 意味 |
|---|---|
--wait | すぐに応答せず、次の変化を待つ |
--follow | すべてのエージェントが待機状態になるまで、変化を出力し続ける |
--timeout N | 1回の待機に許容する秒数（デフォルトは 60、最大 300） |
--json | 機械可読な形式で出力する |
省略可能な最初の引数を指定すると、以前のバージョンの 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を付けると、代わりに実行中のターンにメッセージを追加します。 - 1つのメッセージに含められるテキストは、最大 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 は、計画セッションがワークフローの一部として使います。ユーザーが主に使う操作は次の2つです。
vflow status <workflow-id>は、ワークフローの状態、タスク、セッション、現在のやり取りの回数を表示します。vflow stop <workflow-id>は、以降のやり取りを停止し、実行中のセッションに停止を求めます。
12. vela コマンド
macOS では、「設定」▸「一般」▸「シェルコマンド」に「‘vela’ コマンドをインストール」があります。これを使うと、VS Code の code コマンドと同じように、シェルで vela <project-path> を使えるようになります。任意のターミナルで実行すると、プロジェクトが VelaTerm で開きます。すでに開いている場合は、そのプロジェクトに切り替わります。VelaTerm がインストールしたものではない既存の vela コマンドは、上書きされません。