gimbal-runs

Gimbal を使用する

インストール済みのコマンドを使用して、プロジェクトでワークフローを実行します。インストール済みのワークフローを呼び出すために、Go を書いたり Svelte をビルドしたりする必要はありません。新しいワークフローにはワークフローを作成するを、アプリケーションのビルドにはビルドとリリースを使用してください。

ワークフローを選び、仕様を把握する

gimbal --help
gimbal run --help
gimbal run review --help

ワークフローのヘルプは、選択した実行中の中央カタログから取得されます。現在のディレクトリの外にある場合は、--instance-dir /abs/instance を使用してください。登録済みのワークフロー、入力、モデルのデフォルト設定を確認できます。df-* スキルが存在していても、それが Gimbal のコマンドになるわけではありません。

デフォルトでは、macOS アプリは ~/.gimbal/desktop をインスタンスディレクトリとして、同梱の中央サーバーを起動します。CLI の実行をそのカタログに送信するには、--instance-dir ~/.gimbal/desktop を指定するか、CLI に GIMBAL_INSTANCE_DIR を設定してください。 アプリは、外部サーバーへのプロキシとして明示的に設定されている場合にのみ、GIMBAL_SERVER_URL を使用します。

目標、対象プロジェクト、許可される変更、有用な結果を示す証拠を明確にします。提供されたチャプターやスプリントが背景情報を与えてくれる場合があります。関係する場合はそれを利用し、呼び出しのたびに計画用の成果物を作り出さないでください。プロミス、チャプター、スプリント、タスク、実行の違いについては、用語集と証拠に関するガイダンスを参照してください。

ワークフローのヘルプでは、目的、入力、出力や変更、完了の要件、制限事項を説明する必要があります。重要な点が欠けている場合は、権威ある情報を推測せず、ワークフローのソースまたはユーザーから確認してください。

調査ドキュメントを作成する場合は、gimbal run research-document --help を確認してください。目標、ローカルの調査ディレクトリ、出力パス、ドキュメントのトークン予算を指定します。--source-dir を指定すると、ローカルの原資料を固定して使用します。ウェブから収集する場合は省略してください。このワークフローはセマンティックな INDEX.md を書き込み、抽出したすべての主張と Jev のソース／ペアに関する所見を <research-dir>/.semantic-index/ に記録し、ドキュメントの受け入れ前に所見を修正または限定します。別のコマンドである gimbal run research-eval --help は、固定されたソースを使って、調査担当モデルとインデックスキュレーター担当モデルの割り当てを比較します。その勝者は、その評価スイートに対する暫定的なものです。レポートでは、事実の正確性、検索、修正、コストを区別します。

スプリントを計画する場合は、gimbal run sprint-plan --help を確認してください。ローカルの意図ファイルと、ephemeral/sprints/ 配下の新しいスプリントディレクトリを指定します。意図ファイルには、ステークホルダーが得る成果、境界、受け入れを示す証拠、役立つ参照パスを記載します。このワークフローはプロジェクト情報と過去の成果物を収集してインデックス付きの作業セットにまとめ、3 つのドラフトを作成して相互批評を行い、実装用の参照情報を含む提案版の plan.md を作成します。実行前に、未解決のステークホルダー判断事項を確認してください。計画が完了しても、成果が実現したことにはなりません。

実行を開始する

Jev の監督に WithSupervisor を使用するワークフローに限り、Gimbal には TYPESAFE_API_KEY が必要です。run-prompt、Jev を使用しないワークフロー、インスタンスの起動には、このキーは必要ありません。監督対象のワークフローは、Jev による監督に到達した時点でキーがない場合、明確なエラーを報告します。すでに起動しているインスタンスにだけ接続するヘルプやコマンドでは、ローカルの TypeSafe キーは必要ありません。

gimbal --instance-dir /abs/instance --port 8080
# In another shell:
gimbal run review --instance-dir /abs/instance --project /abs/project --input '{"goal":"Review the parser changes for correctness; report concrete findings with evidence."}'

中央サーバーとワークフローのデーモンは、起動時に --plugin-dir DIR を繰り返し指定することで、ネイティブプラグインを検出します。各環境に対応するプラグインのビルドをデプロイし、プロジェクトのプラグインを再ビルドした後は再起動してください。入力仕様の変更を受け入れるために、CLI やフロントエンドを再ビルドする必要はありません。制御コマンドと生成処理では、ローカルのプラグインファイルを読み込みません。

--input には JSON オブジェクトまたは @/abs/input.json を指定するか、カタログのパラメーター用フラグを使用してください。共通のブラウザー版「Run」フォームには同じフィールドが表示されます。空、0、false の値を任意で送信する場合は「Include」にチェックを入れてください。実行が受け付けられる前に、入力エラーの対象となったフィールド名が表示されます。 デフォルトでは、central は独立したローカルランナーを起動します。リモートに配置する場合は、central の --project ディレクトリとは独立して、--workflow-endpoint URL --workflow-project /abs/project-at-A と --work-dir /abs/workdir-at-A を指定します。B でタスクを実行するには --task-endpoint URL を指定します。--workflow-route と --task-route では、登録済みのバックエンド実装に対して、バックエンドの name、configuration、environment を含む JSON または @file を指定できます。各環境でリポジトリとワークスペースを用意してください。プラグインのパスは、各デーモンのローカルで設定します。central は実行ルートを保持するため、central を再起動すれば、再送信せずに実行中の実行を再び開けます。観測チャネルの切断は、作業が停止または失敗した証拠ではなく、観測の空白です。

絶対パスでプロジェクトを指定してください。デフォルトではロールモデルのフラグを渡さないでください。ワークフローに表示されるデフォルト値は意図されたロール構成であり、フラグを指定すると置き換わります。ユーザーが特定のモデルや処理能力を指定した場合、デフォルトでは実行できずユーザーが代替を承認した場合、またはワークフロー独自のヘルプで現在の作業が安価なモデルに適した明確に範囲の定まったケースだと示されている場合に、ロールを上書きしてください。最後のケースでは、通常の作業には、ドキュメントで案内されている Sol または Opus の選択を優先してください。ただし、ヘルプに記載された曖昧さ、リスク、難易度の基準に該当する場合は、設定済みのフロンティアモデルを維持してください。一般的なコスト削減の圧力を理由に、無関係なロールまで一律に上書きしないでください。上書きする前に、--help のロールに関する行をすべて読み、変更後の割り当てを明示してください。結果レポートには、実際に使用したモデルを記録してください。

OpenCode のモデルは明示的に指定します。opencode/<model-id> は OpenCode の opencode プロバイダーを選択し、opencode/<provider>/<model-id> は OpenCode で設定された別のプロバイダーを選択します。どちらの形式も、ワークフローのロールフラグと gimbal run-prompt --model で使用できます。共有サーバーは初回使用時に起動し、セッションを閉じた後も動作を続けます。状態の保存先はデフォルトで ~/.gimbal/opencode または GIMBAL_OPENCODE_DIR です。gimbal opencode start|stop [--state-dir DIR] で直接管理でき、停止すると進行中の作業が中断されます。生のリクエスト／結果／SSE のキャプチャは <state-dir>/captures/ に書き込まれます。

Diffusion Router と Pi を使用する場合は、現在のキーで利用可能な、チャットとツールをサポートするモデル ID を確認します。

curl -fsS https://router.diffusion.io/v1/models \
  -H "Authorization: Bearer ${DIFFUSION_API_KEY}" |
  jq -r '.data[] | select(.capabilities.openai_chat == true and .capabilities.tools == true) | .id'

選択したオープンウェイトモデルの ID の前に pi/diffusion/ を付け、ワークフローのロールフラグまたは gimbal run-prompt --model で指定します。たとえば pi/diffusion/deepseek-4.1-flash-background のように指定します。これらのモデルのルーティングに Gimbal は models.dev を必要としません。サーバー環境で DIFFUSION_API_KEY を設定してください。Pi ハーネスは Gimbal プロセス内でネイティブに実行されるため、別途 Pi、Bun、または Node をインストールする必要はありません。シェルツールは引き続き子プロセスのコマンドを起動します。

別の有用なプロファイルとして、計画にはフロンティアモデルの能力を使い、その後、リスクが低く、取り消し可能で、独立して検証できるバックグラウンド作業を Terra または Sonnet に割り当てる方法があります。壁時計時間に余裕があり、ワークフローに範囲の定まった検証フィードバックがあって、弱い完了済みの試行を却下し、より適切な割り当てで再試行できる場合に、この方法を優先してください。計画は証明ではないため、リスクに応じた独立した検証を維持してください。明示的な再試行経路がない限り、ワークフローがプロバイダー、ハーネス、実行のエラーを再試行するとは限りません。

独立した実行プロセスの起動後、コマンドは実行 ID を返します。結果を待つには --follow を使用してください。central が切断された場合、再送信せずに最大 30 秒間、選択したインスタンスを再検出して同じ実行を再開します。切断から復旧できない場合は、明示的なエラーを返します。コマンドが終了しても、デーモンが停止しても、実行は継続します。同じインスタンスディレクトリを使ってデーモンを再起動すると、デーモンが受け入れたプロジェクトの観測と制御を再開できます。デーモンの --port 0 を指定すると、利用可能なブラウザポートが選択されます。--uds を指定すると、Unix ソケット経由でサービスを提供します。

選択したスタンドアロンデーモンでエージェント、コマンド、スコープ所有のサービスを実行するには、--task-endpoint を使用してください。ワークスペースの設定、転送されるアーティファクト、スコープ付きシークレットについては、タスクデーモンを参照してください。

メッセージングタスクのルート

filesystem、river、http-sse のネイティブプラグインは、ワークフローを通常の Go のまま保ちながら、リクエストと保持されたイベントを運びます。CLI と各プラグインは、同じチェックアウトと Go ツールチェーンからビルドしてください。go build -buildmode=plugin -o /abs/plugins/filesystem.so ./plugins/messaging-filesystem で filesystem プラグインをビルドできます。River と HTTP のパッケージは ./plugins/messaging-river と ./plugins/messaging-http です。--plugin-dir /abs/plugins を指定して central を起動してください。 公開する CLI では、-trimpath を追加し、配布に記載されたソース／ツールチェーンおよびワークスペースの要件に厳密に従ってください。

ルートファイルには Name と Configuration が含まれます。次のいずれかの設定を選んでください。

Name	Configuration
filesystem	{"Directory":"/abs/private-messages"}
river	{"DSNFile":"/abs/private-postgres-dsn","Queue":"gimbal"}
http-sse	{"URL":"http://127.0.0.1:18091"}

filesystem または River の場合、呼び出し元と同じルートを指定してワーカーを 1 つ起動してください。

gimbal message-worker --plugin-dir /abs/plugins --task-route @/abs/route.json
gimbal run service-check --instance-dir /abs/instance --project /abs/project --work-dir /abs/project/work --task-route @/abs/route.json --task 'Write the required file.' --follow
gimbal message-watch --plugin-dir /abs/plugins --task-route @/abs/route.json --run RUN_ID

バックエンド依存関係が設定されていないワーカーは、スコープ付きシークレットをプロセスのプライベートメモリ内に保持します。名前付き環境では、オーケストレーションから提供される共有シークレットディレクトリを使用します。

これらのコマンドは別々のシェルで実行してください。River には、到達可能な PostgreSQL と、接続文字列を含むプライベートファイルが必要です。ワーカーがスキーマを初期化します。アクションキューのデフォルトは gimbal、別個の制御キューのデフォルトは gimbal_control、アクションワーカー数のデフォルトは 4 です。独立したデプロイメントを分離するには、異なるキューを使用してください。

HTTP では、環境ごとに 1 つの URL を使用します。ワーカールートにはさらに、Listen（127.0.0.1:18091）と絶対パスの EventsDir を指定します。エージェントのセッション、コマンド、サービスには、オーケストレーションで選択されたデーモンを使用します。

名前付き環境を自動起動するには、呼び出し元のルートに Environment と Backends を追加します。たとえば、filesystem プラグインでは次のようになります。

{
  "Name": "filesystem",
  "Configuration": {"Directory": "/abs/control"},
  "Environment": "development",
  "Backends": {
    "Orchestrator": {
      "Name": "local",
      "Configuration": {
        "Directory": "/abs/private-backends",
        "Environments": {
          "development": {
            "Command": ["/abs/gimbal", "message-worker", "--plugin-dir", "/abs/plugins", "--task-route", "@/abs/worker.json"],
            "Route": {"Name": "filesystem", "Configuration": {"Directory": "/abs/development-messages"}}
          }
        }
      }
    },
    "Secrets": {"Name": "file", "Configuration": {"Directory": "/abs/private-backends/secrets"}}
  }
}

worker.json には、その環境の Route と同じ Name と Configuration を指定します。オーケストレーションはワーカーの準備完了を管理し、選択されたシークレット設定をプライベートな標準入力経由で渡します。名前付きオーケストレーターの登録とシークレットの登録は、メッセージングプラグインとは独立しています。ローカルサブプロセスオーケストレーターには共有シークレットが必要です。file バックエンドは、呼び出し元とワーカー間でプライベートディレクトリを共有します。memory バックエンドは同じプロセス内の呼び出し元とワーカー向けであり、ローカルサブプロセスオーケストレーションでは拒否されます。これはディスパッチ前にデーモンを起動し、無関係なスコープ付き利用を維持し、最後のネイティブスコープがクリーンアップされた後にデーモンを停止します。このワーカーを手動で起動しないでください。名前付き環境ではメッセージングが必要です。直接タスクエンドポイントで配置を回避することはできません。

service-check ワークフローには、Docker、psql、Python 3、およびデーモン環境内のエージェントハーネスが必要です。このワークフローは Postgres と Web サービスを管理し、スコープ付き接続値を公開し、並列コンシューマーを介してデータベースにクエリを実行し、Gimbal シークレットコールバックを使ってエージェントに Web の応答を取得させます。新しい作業ディレクトリを使用し、gpt-5.6-luna など、明示的に低コストのモデルを指定してください。

この実装では、ワーカーと呼び出し元がローカルパスを共有します。ワーカーを再起動しても、ネイティブアクションやセッションは復元されません。メッセージングルートでは Steering と fork はサポートされていません。配信が不確実な場合でも、ネイティブ処理の失敗や終了が確定するわけではありません。message-watch は保持された履歴を独立して読み取ります。これを停止しても処理はキャンセルされません。JSONL には、プライベートなエージェントコンテンツが含まれる場合があります。イベントファイルや PostgreSQL の行は、明示的に削除されるまで残ります。

実行を見つけて作業を確認する

gimbal runs --work-dir /abs/project
gimbal watch RUN_ID --work-dir /abs/project

同じプロジェクトディレクトリを使用します。runs は、応答中のローカルランタイムから実行中の実行を含む JSON を返します。watch は、最初のスナップショットに続いて、改行区切りの JSON 変更を出力します。実行のステータス、スコープ、セッション、ターンを読み、何が起きているかを把握します。

終了時刻のないターンは、アクティブなセッションを示します。そのセッションの正確な ID をコピーします。ロール名、セッション ID、ターン ID、ループスコープ ID は、それぞれ異なるものを示します。検出結果が空でも、ランタイムが存在しない、または到達不能である可能性がありますが、保存済みの履歴について確定的なことは分かりません。

セッションまたは次の計画判断を調整する

gimbal steer RUN_ID --work-dir /abs/project --session SESSION_ID "Investigate the failing parser test before expanding the review."
gimbal steer RUN_ID --work-dir /abs/project --loop LOOP_SCOPE_ID "Prioritize the CLI work in the next assignment."

ターゲットは必ず 1 つだけ選択します。セッションへの指示は、そのセッションのアクティブなターンに送られます。landed: false は、その指示が破棄され、後のターン用に保存されなかったことを意味します。ループへの指示は、そのディスパッチを行うループの次の計画判断に向けてメッセージをキューに登録します。

実行可能な修正案と関連する根拠を伝えたうえで、エージェントの動作を確認します。landed: true は配信されたことを示し、queued: true はキューに登録されたことを示します。どちらも、指示に従ったことを示すものではありません。

結果とその証拠を評価する

目標に関連する作業または動作を調べます。レビューでの指摘は具体的な不具合を示す必要があります。実装に関する主張には、変更された動作の観察が必要です。テストやコマンドの結果は、実際に検証した内容に対する証拠です。記録された失敗を、成功したと述べる文章で覆すことはできません。

実行が終了し、プランナーがディスパッチを停止しても、要求された結果が未達成のままの場合があります。保証については、主張、スコープ、証拠、検証者、検査対象の状態を特定します。ワークフローまたは受け入れ条件で独立した検証が求められる場合は、それを実施します。検証者は結果を調べるものであり、作業者の説明を証拠として受け入れるものではありません。

保存済みの記録は /abs/project/.gimbal/runs/RUN_ID/ に残ります。ブラウザーで履歴を確認するには、プロジェクトディレクトリから gimbal --port 0 を実行します。ライブの watch には実行中のオーナーが必要ですが、保存済みの履歴を表示してもセッションは復旧しません。Codex は、1 分以内に最大 3 回試行して、失われた接続を積極的に再調整します。存続しているネイティブターンには再接続し、完了済みの結果は履歴から読み取ります。デーモンが引き続き利用できない場合、または安全に続行できるか不明な場合、オーナーインスタンスが稼働している間は、同じ呼び出し、実行、タスクが一時停止状態のままになります。接続通知には原因が記載されています。既存の作業を調べ、以前の操作が停止したことを確認したうえで、次のコマンドを使って、制限付きの再調整バッチをもう一度要求します。

gimbal steer RUN_ID --work-dir /abs/project --session SESSION_ID resume

これは、その Codex セッションが一時停止している場合のアダプター復旧制御です。ネイティブ側で配信されたことやタスクが完了したことを示すものではありません。アダプターは、再接続または同じスレッドでの続行開始の前に、再度履歴を確認します。受け入れ済みの結果を再実行することはありません。代わりに gimbal cancel RUN_ID --work-dir /abs/project でキャンセルします。このコマンドは、終端状態の実行について、保留中のリモートクリーンアップも再試行します。クリーンアップに失敗した場合、オーナーインスタンスは停止制御を保持しますが、作業者が停止したことの証明にはなりません。インスタンスを再起動すると、存続している独立したワークフロープロセスへの制御が再接続されます。終了したワークフロープロセスを復元することはできません。--task-endpoint を指定した実行では、中央側が保持しているオーナールートを使って、そのプロセスのリモートスコープをクリーンアップします。クリーンアップに失敗した場合は、再試行できます。

Gimbal には汎用の再開コマンドはありません。リポジトリの保証ヘルパーは、独自の再開可能な状態、スケジュール、バッジを定義することがあります。これらは別個の機能です。

直接調査する場合は、保存済みの実行結果とターン結果から始め、関連するセッションのトランスクリプトまたは記録されたコマンド出力を確認します。証拠の保持や共有については、利用側プロジェクトのポリシーに従ってください。

実用的なユーザーテストを実行する

gimbal run validate-product --suite-file /abs/suite.yaml --instance-dir /abs/instance --project /abs/project --follow を実行すると、Opus 5.5 で呼び出し側が割り当てたワークロードを1～3件実行し、Gemini Flash でそのスクリーンショットを確認して、調査結果をまとめます。スイートでは、テスト対象の製品に対して issue_repo が必要です。最後のエージェントは重複を確認し、補足スクリーンショットを gimbal upload-artifact でアップロードし、裏付けのある調査結果をそのリポジトリに公開します。各ワークロードの後、同じテスターセッションで追加の質問に1つ回答します。具体例を挙げながら、UX と UI について、それぞれ最も気に入った点を3つ、最も気に入らなかった点を3つ回答します。デブリーフはタスクレポートに追加されます。経過したワークロード時間には含まれません。製品、ローカルの割り当てファイル、分離されたワークスペース、起動／準備完了確認コマンドまたは既存の URL、出力ディレクトリを指定します。選択したインスタンスを起動します。起動時に /abs/project が許可されていなかった場合、ワークフローコマンドの初回起動時に許可されます。 --follow はトリアージと課題の公開が完了するまで待機します。このコマンドのヘルプでは、JSON／YAML 入力とモデルのオーバーライドについて説明しています。公開には、認証済みの gh と、設定済みの公開アーティファクト保存先が必要です。

機能を網羅するチェックリストではなく、有用なタスクを割り当ててください。テスターはテスト対象の製品のソースを決して調べてはなりません。説明文付きのスクリーンショットを撮り、タスクの成功と使いやすさを分けて報告します。動画は、人が任意で確認するためのものです。実行前に libx264 を含む FFmpeg をインストールしてください。reports.json には、それぞれの2.5倍速 H.264 video.mp4 のパスが記録されます。動画は最大1280×720で、gimbal upload-artifact ですぐにアップロードできる状態です。元の video.webm は隣に残ります。 Gimbal を使って別のプロジェクトを構築するテストでは、ライブ UI／API の監視に、委任された実行自体の Web リスナーを使用してください。単独の履歴ビューアーには、別のプロセスが所有する実行の古いスナップショットが残る場合があります。

会話から作業する

Git チェックアウトから gimbal --port 0 を実行し、Conversations を開きます。会話の作成時に Codex、Claude、または agy/Gemini を選択すると、Gimbal がワークツリーとブランチを作成します。エージェントにレビューまたは実装を開始するよう依頼し、リンクされた実行を開いて同じサーバー上で進捗を確認します。実装には、会話のワークツリー内にローカルの完了条件ファイルが必要です。会話のターンが進行中の間は、サーバーを起動したままにしてください。起動したワークフローは独立して実行されます。再起動後、保存済みの Codex 会話は、次のメッセージでネイティブのスレッドを再開します。保存済みの Claude と agy/Gemini の会話は、履歴として引き続き閲覧できますが、まだ続行できません。

起きたことを報告する

ワークフロー、プロジェクト、モデル、実行 ID、有用な結果、観察された証拠を記載してください。誘導した場合は、対象、提供結果、その後の挙動を含めてください。失敗した要件や立証できなかった要件は、完了した作業とは分けて記載してください。レポートの詳しさはタスクに見合うものにしてください。