🤖 技術調査 - Grok-Build

概要

Grok-Buildは、xAIが開発するターミナルネイティブな自律的コーディングエージェントです。開発プロジェクト内において、コードの変更や実行計画の作成を自律的に行います。

関連技術との関係

xAIが提供する関連技術とGrok-Buildの関係は以下の通りです。

類似ツールとの比較

類似の自律的コーディングツールとの比較は以下の通りです。

• モデルの補足: Grok-Build 起動時の既定（default）の coding / agent session 推奨モデルは grok-build です。背景にある LLM 系統として xAI の最新フラグシップモデル（Grok 4.5 など）が動作します。

アーキテクチャの違い

各ツールのアーキテクチャにおける技術的根拠は以下の通りです。

ユースケース別の推奨ツール

開発目的や規模に応じた推奨ツールは以下の通りです。

特徴

Grok-Buildの主な特徴は以下の通りです。

• マウス操作に対応したフルスクリーンTUI（Terminal User Interface）の提供
• 最大8つのサブエージェントを並列で起動してタスクを分担
• 実行計画を作成し、事前にユーザーへ提示
• Agent Client Protocol (ACP) をサポートし、外部IDEと双方向で通信（Stdio経由のJSON-RPCを主とする）
• AGENTS.md を用いたプロジェクト固有ルールの適用
• MCPのサポートによる外部ツールやデータの活用
• visionモデルを用いた視覚的な動作検証の実施
• ヘッドレスモードのサポートによるCI/CDなどの自動化プロセスへの対応

構造

Grok-Buildの構造について、C4 modelに基づき「システムコンテキスト」「コンテナ」「コンポーネント」の3段階で説明します。
※本構造は、公式マニュアルの機能説明と実機挙動から再構成した論理アーキテクチャモデルです。

システムコンテキスト図

Grok-Buildと、その周囲を取り囲むユーザーや外部システムとの関係性を示すシステムコンテキスト図です。

Grok Build システム境界

外部環境

コンテナ図

Grok-Build内部の主要な実行単位やインターフェースを示すコンテナ図です。

Grok Build システム

外部システム

コンポーネント図

「エージェントコア（Agent Core）」内部をドリルダウンし、具象モデルや実ツールを用いた相互作用を示すコンポーネント図です。

エージェントコアコンテナ

連携する具象システムとファイル

データ

Grok-Buildが扱う各種設定ファイルや履歴データの構造について説明します。
※本データモデルは、動作時に保存されるファイルを観測してモデル化した挙動ベースのスキーマです。

ディレクトリ構成とファイル配置

Grok-Buildが使用するローカル環境のディレクトリ構成とファイルの役割は以下の通りです。

~/.grok/
├── auth.json             # 認証資格情報キャッシュ（OAuth/APIキー情報）
├── config.toml           # グローバル設定ファイル
├── logs/
│   └── grok.log          # ログファイル
└── sessions/
    └── [session_id]/     # ユニークなセッションID
            ├── chat_history.jsonl  # 会話の往復履歴ログ
            ├── summary.json        # セッションメタデータおよび圧縮された要約
            ├── updates.jsonl       # リアルタイムな更新ログ
            └── events.jsonl        # ツール実行や各種システムイベントのストリーミングログ

概念モデル

Grok-Buildが読み書きする主要データ間の関係を示します。

情報モデル

各データが保持する主要な属性と関連関係を示すクラス図です。

構築方法

Grok-Buildのインストール、前提条件、バージョン確認、および認証ログインの手順を説明します。

前提条件

Grok-Build を利用するために、以下の前提条件を確認してください。

• 対応OS
  • macOS、Linux、Windows (WSL2 または PowerShell) でネイティブ動作。
• プラン契約
  • 利用には SuperGrok / X Premium Plus のアカウント契約、または公式プラン（無料体験枠等あり）への登録が必要。
• システム要件
  • バイナリ提供のため、Node.js や Rust などのコンパイル環境は不要。

インストール方法

• macOS / Linux / WSL でのインストール
  • 公式のインストール用シェルスクリプトを実行。

  curl -fsSL https://x.ai/cli/install.sh | bash
  

• Windows (PowerShell) でのインストール
  • PowerShell から直接インストーラーをダウンロードして実行。

  irm https://x.ai/cli/install.ps1 | iex
  

バージョン確認

• インストール状況の検証
  • grok version サブコマンドを実行してバージョン情報を出力。

  grok version
  

認証ログイン

• 対話型ログイン (推奨)
  • コマンドを実行し、ブラウザで起動する OAuth 認証画面に従ってログイン。
  • 認証資格情報は ~/.grok/auth.json にキャッシュ。

  grok auth login
  

• 非対話型・CI環境向けログイン (APIキー)
  • 環境変数 XAI_API_KEY を設定。

  export XAI_API_KEY="xai-..."
  

• ログアウト
  • キャッシュされた認証情報を削除し、セッションを破棄。

  grok auth logout
  

設定ファイルの初期配置 (config.toml)

• グローバル設定の配置場所
  • 個人設定ファイルは ~/.grok/config.toml に配置。
• 設定例
  • ツールの実行確認をスキップする設定や、Vimキーバインドの有効化などを記述。

  [ui]
  permission_mode = "always-approve" # ツール実行時の確認をスキップする設定
  vim_mode = true                   # Vimキーバインドを有効化する設定
  
  [models]
  default = "grok-build"            # デフォルトで使用するモデル名
  

設定・パラメーターの適用優先順位

Grok-Buildの実行において、設定パラメーターやモデル設定が競合した場合、以下の優先順位で適用されます。

1. コマンドライン引数 (起動時に渡す --always-approve や --model など)
2. 環境変数 (XAI_API_KEY や GROK_MODELS_BASE_URL などの変数によるオーバーライド)
3. プロジェクト固有設定 (対象プロジェクトのルートにある .grok/config.toml ※ただしプロジェクト固有設定は主に MCPサーバー、プラグイン、個別権限ルール定義に限定され、一般の [models] や [ui] 設定のオーバーライドはサポートされません)
4. グローバル個人設定 (~/.grok/config.toml)

APIプロバイダーが自動検出される際は、以下の優先順位で有効なAPIキーが探索されます。
xai (grok) > openai > anthropic > google > openrouter > groq > azure > github > custom > ollama

利用方法

Grok-Build の主要コマンド、UIモード、および各種パラメーターについて説明します。

必須パラメータ一覧

Grok-Build の実行における主要なパラメーターとオプションは以下の通りです。

主要コマンド

• ヘルプの表示
  • 利用可能なコマンドやオプション一覧を表示。

  grok --help
  

• ツールのアップデート
  • インストール済みの CLI ツールを最新バージョンに更新。

  grok update
  

TUI と Headless モードの使い分け

• TUI (Terminal User Interface) モード
  • 対象のプロジェクトディレクトリで引数なしの grok コマンドを実行。
  • リッチな全画面表示で、対話的にコーディング作業を進めるのに適する。
• Headless モード
  • -p (または --single) オプションで指示を直接渡して実行。
  • スクリプトや CI/CD パイプラインでの自動実行に適する。
  • 実行例：

  grok -p "Fix the bugs in main.rs" --always-approve --output-format streaming-json
  

TUI モードの基本操作とキーバインド

• 基本ショートカットキー
  • Ctrl+. (または Ctrl+X): キーボードショートカット一覧画面の表示
  • Enter: プロンプトの送信
  • Esc (または Ctrl+C): 実行中のターン（命令処理）の中止
  • Ctrl+Enter (または Ctrl+I): 実行中の操作への割り込み（Interject）
  • Shift+Tab: セッションモードの切り替え (Normal / Plan / Always-approve)
  • F2 (または Ctrl+,): 設定画面の起動
  • Ctrl+Q (または Ctrl+D 二回押し): TUI の終了
• 画面スクロールとナビゲーション
  • Tab: プロンプト入力欄と会話履歴表示エリアのフォーカス切り替え
  • Ctrl+R: プロンプト履歴の検索
  • Shift+H / Shift+L: ターン（指示の履歴）の切り替え（※ Vim Mode が有効な場合のみ動作）
  • Shift+K / Shift+J: 応答（AIからの返答履歴）の切り替え（※ Vim Mode が有効な場合のみ動作）

TUI モードのスラッシュコマンド

• セッション管理
  • /help: コマンドとショートカットのヘルプ表示
  • /plan [指示内容]: 実行前に手順を設計する「Plan Mode」の開始（※タスクグラフの構築や進捗は /tasks や /dashboard コマンドで確認します）
  • /new (保存して新規) または /clear (現在の対話履歴クリア): セッションの初期化
  • /resume: 過去のセッション一覧の表示および切り替え
• 設定・機能拡張
  • /always-approve: ツール実行の自動承認モードのトグル切り替え
  • /memory (または /mem): 永続記憶（cross-session memory）機能の検索と直接編集（※本機能が有効な場合にのみ表示されます）
  • /skills (または /plugins / /mcps): 拡張機能（MCP/プラグイン等）を管理するモーダルの表示

運用

起動・停止方法

• 起動
  • インタラクティブモードでエージェントを起動。

    grok
    

  • ヘッドレスモード（ワンショット実行）で起動。

    grok -p "ここに指示を入力します"
    

• 停止
  • 起動中のインタラクティブセッションを停止。
    • ターミナル上で Ctrl + C を入力。
    • チャット欄で /exit コマンドを実行。

状態確認

• 現在のアクティブな設定や自動検出されたプラグイン、フックを確認。

  grok inspect
  

• 登録されているMCP（Model Context Protocol）サーバーの状態を確認。

  grok mcp list
  

ログ確認

• エージェントの動作ログファイルを参照。
  • macOS/Linuxにおけるデフォルトのログ保存先。

    tail -f ~/.grok/logs/grok.log
    

  • Windowsにおけるデフォルトのログ保存先。

    type %USERPROFILE%\.grok\logs\grok.log
    

更新方法

• CLIツールを最新バージョンへ更新。

  grok update
  

MCPサーバーの登録・管理

• 開発用ツールの機能を拡張するためのMCPサーバーを追加。
• ローカルで実行するStdioベースのMCPサーバーを追加するコマンド。

  grok mcp add <name> -- npx -y <package-name> <args>
  

• リモートで提供されるHTTPベースのMCPサーバーを追加するコマンド。

  grok mcp add --transport http <name> <url>
  

• プロジェクト限定でMCPサーバーを追加する場合は、--scope project オプションを付与。
• 設定ファイル config.toml に直接記述して管理することも可能。
  • 記述例（~/.grok/config.toml または <project>/.grok/config.toml）：

    [mcp_servers.filesystem]
    command = "npx"
    args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    env = { API_KEY = "${MY_API_KEY}" }
    startup_timeout_sec = 30
    

プラグインの管理

• 拡張機能やカスタムスキル、MCP設定を内包したプラグインパッケージを登録。
• プロジェクトのルートに作成した .grok/plugins/ ディレクトリ配下にプラグインを配置。
• 起動時に自動検出され、利用可能になる。
• grok inspect を実行してプラグインの読み込み状況を確認。

ベストプラクティス

設定管理

• 個人環境用とプロジェクト共有用の設定を分離して管理。
  • グローバルな個人設定は ~/.grok/config.toml に保存し、[models] や [ui] 設定を定義。
  • 共有するプロジェクト設定は .grok/config.toml に保存し、Gitリポジトリにコミット。※ただしプロジェクト固有設定はMCPサーバーやプラグイン、セキュリティ承認ルールの定義のみをサポートし、モデルやUI設定のオーバーライドはグローバル設定で行う必要がある。
• 設定ファイルにAPIキーなどの機密情報を直接記述しないように徹底。
  • 環境変数参照機能（${ENV_VAR}）を利用。

フック（Hooks）の活用

• ライフサイクルイベントごとに実行する処理をJSONファイルで記述。
• 定義ファイルは ~/.grok/hooks/*.json や .grok/hooks/*.json に任意の名前で配置可能（Grok-Build起動時にすべてのJSONファイルが自動ロードされます）。
• 主要なフックのライフサイクルイベント一覧

• 遮断可能（ブロッキング）なフックである PreToolUse を活用。
  • Linterやセキュリティスキャンを実行。
  • エラーを検知した場合は終了コード 2 または拒否判定のJSONを返して、Grok-Buildによる不正なコマンド実行やファイル書き換えを防ぐ。
• フックの定義例（PreToolUse）です。

  {
    "hooks": {
      "PreToolUse": [
        {
          "matcher": "Bash",
          "hooks": [
            {
              "type": "command",
              "command": "bin/safety-check.sh",
              "timeout": 10
            }
          ]
        }
      ]
    }
  }
  

スキル（Skills）の定義方法

Grok-Buildでは、特定の複雑なタスクや手順を「スキル」として追加定義し、TUI上で /スキル名 として実行させることが可能です。

• 配置場所: ./.grok/skills/ または ~/.grok/skills/ に配置。
• 記述形式: Markdown形式（例: SKILL.md）で定義し、先頭に YAMLフロントマターを記述。
• 記述例 (.grok/skills/db-migrate/SKILL.md):

  ---
  name: db-migrate
  description: データベースのマイグレーションを実行し、最新の状態に同期します。
  arguments: "<環境名 例: development, staging>"
  ---
  
  # データベースマイグレーションの手順
  
  指定された環境に対して、スキーマのマイグレーションを安全に適用します。
  
  1. 前提条件の確認：
     - `database.yml` が存在し、環境変数がロードされていることを確認します。
  2. ドライランの実行：
     - `bundle exec rails db:migrate:status` で未適用のマイグレーションを一覧化します。
  3. マイグレーション実行：
     - `bundle exec rails db:migrate RAILS_ENV=$ARGUMENTS` を実行します。
  4. スキーマの整合性チェック：
     - `git diff db/schema.rb` で差分を確認し、エラーが無いかチェックします。
  

フックの処理フロー

チーム開発でのAGENTS.md運用と他ツール互換

• リポジトリのルート（またはサブディレクトリ）に AGENTS.md を作成して配置。プロジェクトのコーディング規約、ビルド・テスト実行ルールをドキュメント内に明記すると、エージェントが自動でこれを読み込みルールを遵守。
• 他ツールとの互換検出機能:
  • Grok-Buildは他ツールからの移行を支援するため、CLAUDE.md, Claude.md, CLAUDE.local.md や、.grok/rules/, .claude/rules/, .cursor/rules/ に置かれた任意の *.md ルールファイルも起動時に自動検出して読み込む。

CI/CD連携

ヘッドレスモード（grok -p または --single）を活用して、CIのジョブ内でコードの検証やLinterの自動実行、あるいはコードの自動修正（パッチ）を組み込むことが可能です。

例として、GitHub Actions で Grok-Build を実行するための YAML 定義例を示します。

name: CI with Grok-Build
on: [push]

jobs:
  code-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Install Grok-Build
        run: |
          curl -fsSL https://x.ai/cli/install.sh | bash
          echo "$HOME/.grok/bin" >> $GITHUB_PATH

      - name: Run Grok Agent for Code Quality Check
        env:
          XAI_API_KEY: ${{ secrets.XAI_API_KEY }}
        run: |
          grok --single "Check code style and output unified diff if there are any issues" --always-approve

自動生成されたコードが人間によるレビューを経ずに直接デプロイされることを防ぐため、プルリクエスト（PR）の自動作成にとどめる運用を推奨します。

セキュリティ制約

• プロジェクト固有の設定やフックを有効化するためには、実行ディレクトリの信頼（Trust）が必要。
  • /hooks-trust コマンドを実行するか、起動時に --trust オプションを明示的に指定。
• MCPツール呼び出しのセキュリティ境界:
  • MCPサーバーを介してローカルディレクトリ外のファイルをエージェントが操作するのを防ぐため、一部のMCPサーバー（filesystemサーバーなど）では起動オプションに allowed_paths（許可パス）を設定可能。
  • config.toml 内で対象 MCP サーバーの起動引数に明示的に許可するディレクトリ制限を指定。

    args = ["--allowed-paths", "/Users/suwa_sh/src/github.com/suwa-sh/pkm"]
    

• ログや一時ファイルに機密情報が含まれる可能性があるため、~/.grok/logs/ などのディレクトリを共有しないよう注意。

ローカルとリモートの使い分け

• ローカル環境：
  • インタラクティブな対話型開発やバグ修正には、TUIでのローカル実行を使用。
• リモート/クラウド環境：
  • 複雑な環境のディープリサーチやバッチ処理には、ヘッドレスモードをリモートの実行用インスタンスで実行。

トラブルシューティング

大規模スキャン時のタイムアウトへの対処

大規模なモノリシックリポジトリやファイル数が数万件を超えるプロジェクトでは、Grok-Buildが起動時や実行計画の立案時にすべてのディレクトリをスキャンするため、インデックス処理が非常に遅くなる、またはタイムアウト（504 等）する場合があります。

• .gitignore の徹底: Grok-BuildはGitの追跡対象ファイルを基準にするため、ビルドアセットや外部モジュール（node_modules など）は必ず .gitignore に登録。
• 除外設定の明記: 設定ファイル config.toml 内の [project] セクションの exclude フィールドに配列形式で除外パターンを記述するか、一部環境では .grokignore ファイルを作成してスキャン対象外とするディレクトリやファイルのパターンを明示。

頻出エラーと解決手順

まとめ

Grok-Buildは、並行サブエージェント実行やリッチなTUIなどの特徴を持ち、大規模リファクタリングを強力に支援する自律コーディングエージェントです。公式ドキュメントと照らし合わせたフック機能やセキュリティ設定を最適化することで、CI/CDや日常のコーディングにおいて安全かつ高速に活用できます。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ドキュメント
  • xAI Build Overview (docs.x.ai/build/overview)
  • xAI Build CLI Headless Scripting (docs.x.ai/build/cli/headless-scripting)
  • xAI Build CLI Reference (docs.x.ai/build/cli/reference)
  • xAI Build Keyboard Shortcuts (docs.x.ai/build/keyboard-shortcuts)
  • xAI Build Features Hooks (docs.x.ai/build/features/hooks)
  • xAI Build Features MCP Servers (docs.x.ai/build/features/mcp-servers)
  • xAI Build Settings (docs.x.ai/build/settings)
  • xAI CLI Install Guide (x.ai/cli)
• 関連仕様
  • Model Context Protocol Specification (MCP)