Desktop インストール

このページでは、Hagicode Desktop のインストールと使い方を説明します。Hagicode Desktop は公式のデスクトップクライアントで、既定のローカルインストールの流れと日常の管理操作を 1 か所にまとめています。

おすすめの方法

macOS、Linux、およびストアを使わない Windows のユーザーが個人のローカル環境で使う場合は、Desktop をおすすめします。

• 初回起動ガイドが、ダウンロードから起動までの流れをひとつにつなげます
• Hagicode Server の起動・停止やバージョンをアプリが一括で管理します
• グラフィカルな画面で、状態の確認や操作がしやすくなります
• バージョン管理機能を内蔵しており、バージョンを簡単に切り替えられます
• データは既定でローカルに保存されるため、自分で管理しやすくなります

Windows をお使いの場合は、まず Microsoft Store インストール を検討してください。サーバーやチームへのデプロイには Docker Compose を使用します。

Hagicode Desktop とは

Hagicode Desktop は Hagicode の公式デスクトップアプリケーションで、Windows、macOS、Linux をサポートしています。お使いのマシン上の Hagicode Server のダウンロード、起動、管理を担当し、バージョン管理と日常の操作の入口も提供します。

主な利点

• .NET ランタイムを内蔵: Hagicode Server の実行に必要な .NET は Desktop に同梱されているため、別途インストールする必要はありません
• サービス管理: Hagicode Server の管理機能を内蔵しており、サービスを簡単に起動・停止できます
• バージョンの切り替え: 複数バージョンの管理に対応し、バージョン間を自由に切り替えられます
• ローカル実行: すべてのデータがローカルに保存されるため、プライバシーが守られます
• バージョン検出: 利用可能な新しいバージョンを自動的に検出します

該当するシナリオ

次のような場合は、まず Desktop をおすすめします。

• ローカルで Hagicode を使いたい個人開発者
• データやプロジェクトを自分のマシンの中に置いておきたいユーザー
• グラフィカルな画面を好み、デプロイ設定を手で書きたくないユーザー
• 異なるバージョンを頻繁に切り替える必要がある開発者

インストール前の準備

Desktop は Node.js を同梱しておらず、内部用の Node 実行環境も提供しません。システムの PATH にある node と npm を使用し、Agent CLI などの管理対象パッケージをお使いのマシンの npm のグローバルディレクトリにインストールします。始める前に、次のものを準備してください。

依存関係	要件	説明
Node.js	24 以上	npm も同時に提供されます。Node.js のインストール を参照してください
Git	現行の安定版であればどのバージョンでも可	起動時に検出されます。「新しいプロジェクト」ダイアログの「デモプロジェクト」で、サンプルリポジトリのクローンに使われます。Git のインストール を参照してください
Agent CLI	1 つ以上をインストールし、ログイン済みであること	ウィザードにはこのマシンで検出された CLI だけが表示されます。AI Agent CLI のインストール を参照してください

まず、ターミナルでバージョンを確認します。

node --version   # v24.0.0 以上が必要
npm --version
git --version

インストールしてから起動する、または Desktop を再起動する

Desktop は起動時にシステムの PATH を読み取ります。Desktop をすでに開いた状態で Node.js や Git をインストールした場合は、Desktop を完全に終了してから起動し直し、依存関係のページを更新してください。

Desktop のダウンロード

クイックダウンロード

Windows をお使いの場合は、まず Microsoft Store からのインストールをおすすめします。インストールパッケージを手動で入手したい場合、特定のバージョンのファイルを指定したい場合、または Store を利用できない場合にのみ、下の手動ダウンロードの入口を使用してください。

お使いのオペレーティングシステムに合ったバージョンを選び、インストーラーを直接ダウンロードします。

GitHubChina

ダウンロード一覧の読み込みに失敗した場合

ここで Desktop のインストールパッケージ一覧を読み込めない場合、インストールの入口は無効なダウンロードリンクを表示せず、公式のバージョン履歴ページ index.hagicode.com/desktop/history に案内します。そこでバージョンを選んでインストールパッケージをダウンロードできます。下記の GitHub Releases を直接利用することもできます。

その他の入手方法

次のチャネルからも Hagicode Desktop のインストーラーを入手できます。

1. Windows の標準的な推奨: Microsoft Store インストール にアクセスして、公式ストアの配布チャネルを利用します
2. 公式リリースページ: Hagicode GitHub Releases にアクセスして、手動インストール用のパッケージをダウンロードします
3. 公式ウェブサイト: Hagicode 公式サイト にアクセスして、ダウンロードリンクとインストール手順を入手します

正しいバージョンの選択

お使いのオペレーティングシステムに対応するインストーラーを選択してください。

• Windows: まず Microsoft Store を利用してください。手動でインストールするファイルが必要な場合は、.exe インストーラーまたは .msix パッケージをダウンロードします
• macOS: .dmg インストーラーをダウンロードします
• Linux: .AppImage または .tar.gz パッケージをダウンロードします

動作環境

• Windows: Windows 10 以降 (64 ビット)
• macOS: macOS 10.15 以降
• Linux: 主要な Linux ディストリビューション (Ubuntu 20.04 以降、Fedora 33 以降など)

ご自身で準備が必要な依存関係

Desktop には Hagicode Server の実行に必要な .NET ランタイムが同梱されており、現在サポートされているローカルの SQLite パスで既定の初期化も行われるため、.NET を別途インストールする必要はありません。ただし、Node.js 24 以上と Git はご自身でインストールする必要があります。詳しくは前述の インストール前の準備 を参照してください。

インストールと起動に関する注意事項

macOS Gatekeeper の注意事項

アプリを既定のパス /Applications/Hagicode.app にインストール済みでも、初回起動時に「アプリが壊れています」「開けません」といった Gatekeeper の警告が表示されることがあります。これは通常、macOS がインターネットからダウンロードしたアプリに com.apple.quarantine という隔離属性を付けるためで、Hagicode Desktop のインストーラー自体の不具合ではありません。

ターミナルで次のコマンドを実行してください。このコマンドには管理者権限が必要で、既定のインストールパスにあるアプリから quarantine 属性を再帰的に削除します。

sudo xattr -dr com.apple.quarantine /Applications/Hagicode.app

実行が終わったら、Hagicode Desktop を起動し直してください。

Desktop の実行

ダウンロードが完了したら、インストーラーまたはアプリケーションパッケージを開いてインストールを済ませ、Hagicode Desktop を起動します。

ネットワーク要件

ネットワーク接続が利用できることを確認してください。Desktop は、バージョン情報と Hagicode Server のインストールパッケージをインターネットから取得する必要があります。ダウンロードに失敗した場合は、ネットワーク、プロキシ、ファイアウォールの設定を確認してから、もう一度お試しください。

初回起動ガイド

Desktop を初めて開くと、まず Desktop 独自の「初回セットアップ」が表示されます。これは Hagicode Server のインストールと起動だけを担当し、次の順に進みます。

1. 言語を選択: Desktop で使用する言語を選びます。内蔵バックエンドの初回起動時にも、対応する既定の言語が使われます。
2. ようこそ: このガイドで行う準備の内容を確認します。
3. 法的文書の確認: 現在のバージョンの EULA とプライバシーポリシーを確認します。正式な文書はブラウザで開いて読めます。
4. Hagicode Server のダウンロード: 最新の Server インストールパッケージをダウンロードし、そのダイジェストを検証します。

ダウンロードが完了したら Desktop のホームに戻り、「サービスを開始する」をクリックして Hagicode Server を起動します。その後、ホームの案内に従って Web インターフェースを開いてください。

表示されるステップが一部のみの場合があります

一部の配布チャネル (たとえば Server がインストールパッケージにすでに同梱されているバージョン) や、バージョン更新後に法的文書の再確認だけが必要な場合は、ガイドにはステップの一部だけが表示されます。

Web インターフェースの初回利用

Web インターフェースに初めて入ると、初期化ウィザード が表示されます (上の Desktop の初回セットアップとは別のものです)。ここでは、インターフェースの言語とテーマの選択、デフォルトの Hagicoder の設定、最初のプロジェクトの作成を行います。詳しい手順は次のページを参照してください。

初期化ウィザードのセットアップ言語、テーマ、デフォルトの Hagicoder、最初のプロジェクトの設定を完了します。

バージョン管理

Hagicode Desktop は複数バージョンの管理に対応しており、バージョン間を自由に切り替えられます。

バージョンの切り替え

1. Hagicode Desktop を開きます
2. 「バージョン管理」ページに移動します
3. 切り替えたいバージョンを選択します
4. 「バージョンを切り替える」ボタンをクリックします
5. 切り替えが完了するまで待ちます

バージョン切り替えの注意事項

• バージョンを切り替えると、Hagicode Server が自動的に再起動されます
• 切り替える前に、すべての作業を保存してください
• プロジェクトの設定はバージョンごとに異なる場合があります

サービスの起動と停止

Hagicode Desktop では、Hagicode Server サービスを簡単に管理できます。

サービスの起動

Desktop アプリケーションのホームで「サービスを開始する」ボタンをクリックすると、Hagicode Server が起動します。

サービスの停止

Hagicode Server を停止するには、ホームの「サービスの停止」ボタンをクリックします。

サービスの状態

Desktop アプリケーションには、Hagicode Server の実行状態がリアルタイムで表示されます。表示される内容は次のとおりです。

• サービスの状態 (実行中 / 停止中)
• サービスのポート番号
• 現在のバージョン情報

次のステップ

インストールが完了したら、次の手順に進めます。

初期化ウィザードのセットアップ初回起動後はここでプロジェクトの作成を済ませ、標準のクイックスタートの流れに進みます。

会話セッションの作成既定の読み取り専用モードでプロジェクトを把握し、必要に応じて編集モードに切り替えます。

提案セッションの作成提案駆動の開発ワークフローを知り、漠然としたアイデアを構造化された実装計画に変えます。

トラブルシューティング

インストールの失敗

インストール中に問題が発生した場合は、次を確認してください。

1. ネットワーク接続を確認する: インターネットにアクセスできることを確認します
2. ディスク容量を確認する: 十分な空き容量があることを確認します
3. 管理者として実行する: Windows では、インストーラーを右クリックして「管理者として実行」を選択します
4. インストーラーの表示内容を確認する: インストーラーが表示したエラーメッセージを控えておき、問題を報告するときに添えてください

Node.js、npm、Git が見つからない

Desktop が node、npm、git が見つからないと表示した場合、または Node.js のバージョンが古すぎると表示した場合は、次の手順を試してください。

1. インストール済みか確認する: ターミナルで node --version、npm --version、git --version を実行します。Node.js は 24 以上が必要です。インストール方法は Node.js のインストール と Git のインストール を参照してください。
2. Desktop を再起動する: Desktop は起動時にシステムの PATH を読み取ります。インストール後は Desktop を完全に終了してから起動し直し、依存関係のページを更新してください。
3. PATH を確認する: ターミナルでは実行できるのに Desktop が見つけられない場合は、多くの場合、PATH が特定のシェル設定の中でしか有効になっていません (たとえば nvm や fnm を介して .bashrc / .zshrc で設定している場合)。システム全体へのインストールに切り替えるか、その PATH を読み取れる環境から Desktop を起動してください。
4. CLI パッケージを手動でインストールする: Desktop が CLI パッケージの手動インストールを求めたときは、Desktop の外のターミナルで、表示されたコマンドを実行し、完了したら Desktop に戻って更新してください。外部の Node / npm 環境と PATH の動作については、Desktop が Node 環境を使用する方法 を参照してください。

サービスの起動失敗

Hagicode Server を起動できない場合は、次を確認してください。

1. ポートの使用状況を確認する: Desktop は既定でポート 36556 を使用します (実際に使用中のポートはホームに表示されます)。他のプログラムに使われていないことを確認してください
2. ファイアウォールの設定を確認する: ファイアウォールが Hagicode Server のネットワークアクセスを許可していることを確認します
3. アプリケーションを再起動する: Hagicode Desktop を再起動してみてください
4. ログを確認する: Desktop アプリケーションで詳細なエラーログを確認します

さらにサポートが必要ですか?

ここで説明されていない問題が発生した場合は、次の手順を試してください。

1. Desktop の GitHub Issues で、同様の問題がないか確認する
2. コミュニティフォーラム で助けを求める
3. 新しい Issue を作成し、問題を詳しく説明したうえで、システムのバージョン、node --version の出力、Desktop のログを添付する