agent-deck

agent-deck は、AIベースのコマンドラインツール（主に Antigravity CLI (agy)）をデスクトップ上で快適に操作するための、マルチAI CLIラッパーデスクトップアプリケーションです。

Tauri、Rust、および React を使用して構築されており、軽量でセキュア、そしてプレミアムなデザインのデスクトップインターフェースを提供します。

📖 詳細ドキュメント: このREADMEは概要のみです。より詳しい手順は以下を参照してください。

• 利用ガイド — セットアップ・スキルの使い方・トラブルシューティング（エンドユーザー向け）
• 管理者ガイド — 配布・スキルカタログ運用・自己更新の仕組み・トラブルシューティング（管理者向け）

---

🌟 主な機能

• リアルタイム PTY ストリーミング
  • バックエンドで疑似ターミナル（PTY）を制御し、xterm.js を通じて高速かつスムーズにCLI出力を表示します。
  • 便利なキーボードショートカット:
    • Ctrl+Shift+C (macOS: Cmd+Shift+C): ターミナル上の選択範囲をコピー
    • Ctrl+Shift+V (macOS: Cmd+Shift+V): クリップボードのテキストをターミナルへ貼り付け
    • Ctrl+Shift+A (macOS: Cmd+Shift+A): ターミナルのテキストを全選択
    • Ctrl+C (macOS: Cmd+C): 選択範囲がある場合はコピー、ない場合は実行中のプロセスに強制終了シグナル (SIGINT) を送信
• マルチ動作エンジン対応（Claude Code / Codex）
  • デフォルトの agy に加え、ローカル環境にインストール済みの claude (Claude Code) や codex を自動検出し、動作エンジンとして選択可能にします。
  • 誤操作防止のため、セッション実行中（running）はエンジン選択 UI (アプリ内およびネイティブメニュー) が非活性（Disabled）になります。
• 対話型チャットコンソール
  • 美しく使いやすいチャット型のインターフェースにより、CLIコマンドを入力せずに直感的なやり取りが可能です。
  • 他エンジン（Claude/Codex）のセッション開始時、SKILL.md の内容を最初のメッセージ（メタプロンプト）として自動的に注入してタスクの指示を行います。
• CWD履歴（最近使ったフォルダ）のクイックアクセス
  • 作業ディレクトリ（CWD）の選択履歴を最大5件まで保存し、ボタン隣の ▼ ドロップダウンから瞬時に切り替え可能です。
• SKILL.md クイックプレビュー & システムエディタ連携
  • 作業ディレクトリ内にある SKILL.md を読み込み、アプリ内の専用モーダルでプレビュー閲覧できます。また、「エディタで編集」ボタンから VS Code などのシステム規定エディタを直接起動して指示書を編集できます。
• セッションの強制終了 (SIGKILL)
  • セッションがハングした際、メニューバーの「Session ➔ Force Kill Session」からプロセスグループごと強制終了させることができます。
• スキル（skill）フォルダの自動検出・リビルド
  • 選択した作業ディレクトリ（CWD）内に skill フォルダがある場合、セッション開始前に自動でスキルのリビルド（agy build）をバックエンドで実行します（※ agy エンジン動作時のみ）。
• 作業ディレクトリ（CWD）の切り替え
  • セッション開始前に、UIから直感的に作業ディレクトリを選択・変更できます。
• リアルタイム・テーマ切り替え
  • UI全体の配色およびターミナル背景色を瞬時に切り替え可能。
  • Light (Default), Dark, Solarized Light, Solarized Dark, Dracula, One Dark の6種類のカラースキームを内蔵。
• 自動多言語対応 (Bilingual)
  • OSのシステム言語設定を自動で判別し、日本語環境なら日本語、それ以外のロケール環境では英語表示に自動的に切り替わります。
• Windowsバックグラウンド起動の最適化
  • Windows環境において子プロセス（PowerShellやその他CLIコマンド）が起動する際、一瞬黒いコンソールウィンドウがポップアップ表示されるチラつきを抑え、完全にバックグラウンドで隠蔽された状態で実行します。
• ポータブルZIP配布
  • インストーラーによる配置ではなく、ダウンロードしたZIPを展開してすぐに実行できるポータブル設計。
• スキルカタログ（組織内共有・自動配布）
  • Google Drive 上の共有フォルダをスキルカタログとして利用し、チーム内でスキルを共有できます（下記参照）。

---

📦 スキルカタログと組織向け自動配布 / Skill Catalog & Org Auto-Distribution

config.toml の [drive] catalog_folder_id に Google Drive の共有フォルダを設定すると、そのフォルダがチームのスキルカタログになります。

前提条件（管理者が事前に1回だけ行うセットアップ）: catalog_folder_id を設定するだけでは動作しません。事前に管理者が Google Cloud Console で（1）プロジェクトを作成し Drive API を有効化、（2）OAuth 2.0 クライアント ID（種類:「デスクトップアプリ」）を発行し、config.toml の [oauth] client_id / client_secret に設定しておく必要があります（テンプレート: config/config.toml.template）。この管理者セットアップが完了していれば、一般ユーザー側は追加の設定不要で、初回起動時にブラウザでの Google ログイン・同意のみ行います。詳細な手順・注意点（OAuth同意画面のテストユーザー制限など）は 管理者ガイド §6 を参照してください。

• 共有: skill-catalog share <name> — 自分のスキルをカタログに登録（SKILL.md のみなら .md、スクリプト同梱なら .zip として自動選択）
• 取得: skill-catalog import <name> — 他のメンバーのスキルを取り込み
• 自動配布: 管理者が skill-catalog publish <name> でスキルを _default/ フォルダに置くと、カタログを設定した全端末の次回起動時に自動で導入・更新されます（_default/ から外せば自動で削除）。初回のみブラウザで Google 認可が必要です。
  • _default/ フォルダの書き込み権限は Drive 側で管理者のみに絞ることを推奨します。

組織版としての再配布 / Shipping Your Org's Own Build

agent-deck は fork せずに「自組織版」を配布できるよう設計されています:

1. アプリ本体（agent-deck.app / agent-deck.exe）は外側の名前を変えるだけでリブランドできます（例: acme-console.app）。メニューバーの「Update」から行う自己更新は、リブランド後の名前を維持したまま最新リリースへ更新します。
2. 組織固有のスキルやスクリプトは、スキルディレクトリに同梱して publish すればカタログ経由で全端末に配布されます — このリポジトリに手を入れる必要はありません。
3. 配布物は「GitHub Releases のビルド + 組織の値（[oauth] client_id/client_secret と [drive] catalog_folder_id を含む config.toml）」だけで完結します。

---

⚙️ UIカスタマイズ設定 (agent_config.json)

agent-deck は、組み込まれる親アプリケーションやプロジェクト環境に応じてUIの表示内容を柔軟にカスタマイズできます。

アプリの起動時、作業ディレクトリ（CWD） や 実行バイナリと同階層 の直下、またはそれぞれの場所に作成した config/ フォルダの内部（例：config/agent_config.json）に設定ファイルを配置しておくことで、UIが自動的にその設定を読み込んで上書きします。

設定ファイルの構成例 (agent_config.json)

{
  "app_name": "My Custom AI Console",
  "default_theme": "light",
  "font_family": "Menlo, Monaco, 'Courier New', monospace",
  "font_size": 13,
  "engines": [
    {
      "id": "agy",
      "name": "Antigravity",
      "command": "agy",
      "args": []
    }
  ]
}

📝 設定ファイルの記入例 (ユースケース別)

① テーマとフォントをカスタマイズする例

デフォルトの Antigravity エージェントを使用しつつ、テーマを Dracula（ダーク系）に変更し、フォントサイズを大きくし、フォントファミリーに Fira Code を指定する例です。

{
  "app_name": "Galaxy CLI Terminal",
  "default_theme": "dracula",
  "font_family": "'Fira Code', Consolas, monospace",
  "font_size": 15,
  "engines": [
    {
      "id": "agy",
      "name": "Antigravity",
      "command": "agy",
      "args": []
    }
  ]
}

② 独自の自作CLIエージェントを組み込む例

agent-deck を独自のPythonエージェントや他のコマンドラインアシスタント（例: my-custom-cli）のGUIフロントエンドとして着せ替える例です。

{
  "app_name": "My Project Assistant",
  "default_theme": "oneDark",
  "font_family": "SF Mono, Menlo, monospace",
  "font_size": 13,
  "engines": [
    {
      "id": "my-custom-agent",
      "name": "Project Agent",
      "command": "my-custom-cli",
      "args": ["chat", "--interactive"]
    }
  ]
}

③ セッション開始前に親プロジェクト独自の準備処理を走らせる例

組み込み先のプロジェクトが、セッション開始前に独自のセットアップ・更新チェック・認証確認などを行いたい場合、pre_launch_command / pre_launch_args で任意のコマンドを指定できます。作業ディレクトリ（CWD）でこのコマンドが実行され、成功（終了コード0）した場合のみセッションが開始されます。

{
  "app_name": "My Project Assistant",
  "engines": [
    { "id": "agy", "name": "Antigravity", "command": "agy", "args": [] }
  ],
  "pre_launch_command": "bash",
  "pre_launch_args": ["preflight.sh"],
  "pre_launch_required": true
}

pre_launch_required を false にすると、この処理が失敗してもセッションは開始されます（例: ネットワーク不通でも起動をブロックしたくないベストエフォートのバージョンチェックなど）。pre_launch_command が指定されていないプロジェクトでは、従来通り作業ディレクトリ直下の skill フォルダを自動検出してリビルドする挙動（5.7節）にフォールバックします。

OS ごとに異なるコマンドを実行したい場合は、pre_launch_macos / pre_launch_windows（install/updateと同じ{command, args}形式）で上書きできます。指定した方のOSでは pre_launch_command/pre_launch_args より優先されます。

{
  "app_name": "My Project Assistant",
  "engines": [
    { "id": "agy", "name": "Antigravity", "command": "agy", "args": [] }
  ],
  "pre_launch_macos":   { "command": "bash", "args": ["preflight.sh"] },
  "pre_launch_windows": { "command": "cmd",  "args": ["/c", "preflight.bat"] },
  "pre_launch_required": true
}

設定パラメータ項目

キー名	型	説明	デフォルト値
app_name	string	ヘッダーに表示されるアプリケーション名。	"agent-deck Chat Console"
default_theme	string	初期起動時のカラーテーマ (light, dark, solarizedLight, solarizedDark, dracula, oneDark)。	"light"
font_family	string	ターミナルで適用されるフォントファミリー。	"Menlo, Monaco, 'Courier New', monospace"
font_size	number	ターミナルの文字サイズ (px)。	13
engines	array	サイドバーに表示し、対話に使用するCLIエンジンのリスト。	(上記構成例の通り、デフォルトは agy)
pre_launch_command	string	セッション開始前に作業ディレクトリ（CWD）で実行するコマンド。未指定ならskillフォルダ自動リビルド（5.7節）にフォールバック。	(未指定)
pre_launch_args	array	pre_launch_commandに渡す引数リスト。	[]
pre_launch_required	boolean	trueならpre_launch_command失敗時にセッション開始を中断。falseなら警告のみでセッションを開始。	true
pre_launch_macos	{command, args}	macOSでのみpre_launch_command/pre_launch_argsを上書き。	(未指定)
pre_launch_windows	{command, args}	Windowsでのみpre_launch_command/pre_launch_argsを上書き。	(未指定)

---

🚀 インストールと起動方法

macOS (Apple Silicon 向け)

1. GitHubの Releases から agent-deck-mac.zip をダウンロードします。

2. ZIPを展開すると、agent-deck.app と同じ階層に Initial_setup_for_Mac.command が入っています。初回だけこれをダブルクリックして起動してください（Finderの警告が出るので「開く」を選択）。中身は xattr -cr でmacOSの隔離属性（quarantine）を解除してから agent-deck.app を開くだけの単純なスクリプトで、実行後は自動的に tmp/ フォルダへ移動します（一度実行すれば隔離属性は解除済みになるので、2回目以降は agent-deck.app を直接ダブルクリックするだけで構いません）。

   なぜこれが必要か: quarantine属性が付いたまま agent-deck.app を直接ダブルクリックすると、macOSの「App Translocation」機能により、起動のたびに /private/var/folders/.../AppTranslocation/<ランダムなID>/d/ という毎回変わる場所からアプリが実行されます。agyの「このフォルダを信頼する」確認は場所（パス）ごとに記憶されるため、パスが毎回変わると確認ダイアログが何度でも再表示されてしまいます。Initial_setup_for_Mac.command で事前に隔離属性を解除しておけば、この問題は起きません。

   Initial_setup_for_Mac.command を使わず agent-deck.app を直接開きたい場合は、事前に手動で隔離属性を解除してください。方法は以下のどちらでも構いません。

   方法A: ターミナルを使わず「システム設定」から許可する

   ターミナルの操作に慣れていない方は、こちらの手順をお使いください。

   1. Finderで agent-deck.app をダブルクリックして、一度起動を試みます。
   2. 「"agent-deck.app"は、開発元を確認できないため開けません」といった警告ダイアログが表示されるので、「完了」（または「OK」）をクリックしていったん閉じます。
   3. 画面左上の Apple メニュー（りんごのマーク）をクリックし、「システム設定...」を開きます。
      • （macOS Monterey以前をお使いの場合は「システム環境設定」→「セキュリティとプライバシー」を開いてください）
   4. 左側のメニューから「プライバシーとセキュリティ」を選択します。
   5. 右側の画面を一番下までスクロールすると、「セキュリティ」の項目に「"agent-deck.app"は使用がブロックされました」という表示と、その横に「このまま開く」というボタンがあるので、それをクリックします。
   6. Macのログインパスワードの入力や Touch ID を求められた場合は入力・認証します。
   7. 再度 agent-deck.app をダブルクリックすると、もう一度確認ダイアログが表示されます。今度は「開く」ボタンがあるので、それをクリックすればアプリが起動します。

   ※ この方法は隔離属性そのものは解除しないため、App Translocationは起きたままです（上記の「このフォルダを信頼する」再確認の問題は解決しません）。この問題も解決したい場合は Initial_setup_for_Mac.command を使うか、方法Bで隔離属性を解除してください。

   方法B: ターミナルを使う（慣れている方向け）

   xattr -cr /path/to/agent-deck.app

3. 初回起動時に Antigravity CLI (agy) が見つからない場合、自動インストールを促すオンボーディング画面が表示されます。「Install Antigravity CLI」をクリックすると、アプリケーションと同階層の ./bin/ ディレクトリ配下に自動インストールされ、すぐに利用可能になります（ポータブル構成）。

Windows

1. GitHubの Releases から agent-deck-win.zip をダウンロードします。
2. ZIPを展開し、中にある agent-deck.exe を実行します。
3. macOS と同様に、初回起動時に agy が検出されない場合は自動インストールが実行され、アプリと同階層の ./bin/ 配下にポータブルに配置されます。

---

🛠️ 開発者向けセットアップ

ローカル環境でのビルドおよび実行手順です。

前提条件

• Rust (stable)
• Node.js (v20以上推奨)

手順

1. 依存関係のインストール

   npm install

2. 開発サーバーの起動 (Live Reload)

   npm run tauri dev

3. ローカルでのプロダクションビルド

   • macOS (Apple Silicon)

     npm run tauri build -- --target aarch64-apple-darwin

   • Windows

     npm run tauri build

---

📦 自動リリースビルド (CI/CD)

本プロジェクトは GitHub Actions による自動ビルドワークフローを統合しています。

1. プロジェクトバージョン（package.json, Cargo.toml, tauri.conf.json）を更新します。
2. バージョンタグ（例: v0.0.2）を作成して GitHub にプッシュします：

   git tag -a v0.0.2 -m "Release v0.0.2"
   git push origin v0.0.2

3. GitHub Actions 上で自動的にコンパイルが走り、バイナリが ZIP にパッケージングされて自動公開されます。

先にテスト版で動作確認してから本番公開したい場合は、タグ名に v0.0.2-rc1 のようなプレリリース識別子を付けてください。GitHub 上で pre-release として公開され、既存インストールの自動アップデートには一切配信されません。詳細は 管理者ガイド「テスト→本番の昇格フロー」 を参照してください。