メインコンテンツへ移動
AIチュートリアル

Harpチュートリアル：落ち着いたmacOSサイドバーでClaude CodeとCodexエージェントを整理する

macOSにHarpをインストールし、Claude CodeとCodexのセッションを永続グループに整理して、エージェントの状態を監視し、使用量制限リングを設定し、tmuxでセッションを接続する方法を学びます。

約11分で読了
Harpチュートリアル：macOSサイドバーでClaude CodeとCodexエージェントを整理する

Harpは、オープンソースのWarpターミナルを非公式にmacOS向けへフォークしたものです。Warpのターミナル、AI、クラウド機能を維持しながら、従来のタブバーを、長時間実行するコーディングエージェント向けに設計されたサイドバーへ置き換えています。

Harpでは、Claude CodeやCodexのセッションを複数並行して実行し、どのセッションが作業中か、あなたの操作を待っているか、完了したか、バックグラウンドで実行中か、保留中かをすばやく確認できます。Harp自体はサーバーを運用しません。Warpの上流機能は、Warpと同様に引き続きWarpのサーバーと通信します。

エージェントのセッションを整理して表示するHarpのサイドバー

Harpの追加機能

エージェントの状態を一目で確認

サイドバーの各行には、Claude CodeまたはCodexのセッション状態を表示できます。未読マーカーはセッションを確認するまで残り、ドットはバックグラウンド処理がまだ実行中であることを示し、月のアイコンは保留にしたタブを示します。Cmd+Rでタブの名前を変更できます。

永続グループ

タブを名前付きグループに入れて、プロジェクトやエージェントを整理できます。tmux連携を有効にすると、Harpはグループと並び順をtmuxセッションに保存します。これにより、再起動後もレイアウトが維持され、他のtmuxクライアントからも同じ配置を確認できます。

使用量制限リング

サイドバーのフッターには、各プロバイダーについて2つのリングを表示できます。1つは5時間の期間、もう1つは週間制限を示します。Harpは、任意のツールが管理するローカルJSONファイルからこれらの値を読み取ります。使用量データを自ら取得することはありません。想定されるファイル形式については、制限リングの形式に関するドキュメントを参照してください。

スマートフォン対応のtmuxセッション

tmuxに接続されたセッションには、名前、グループ、既読状態、非アクティブ状態を保持できます。SSH経由でスマートフォンから起動する場合など、別の場所で開始したtmuxセッションは、tmuxオプション@warp_adoptを1に設定することで、Harpのタブとして取り込めます。

Harpをインストールする

最新のmacOSビルドをインストールする

  1. GitHub Releasesページから最新のHarpリリースを開きます。
  2. Harp-<version>.dmgファイルをダウンロードします。
  3. ディスクイメージを開き、HarpをApplicationsフォルダへドラッグします。

Harpは独自のバンドル識別子com.dominikmartn.Harp、URLスキームharp://、設定ディレクトリ~/.harpを使用します。これにより、これらのリソースを共有せずにWarpと並行して実行できます。

ソースからビルドする

Harpを自分でビルドするには、macOSとrust-toolchain.tomlで指定されたRustツールチェーンを使用します。リポジトリのルートから、まずブートストラップスクリプトを1回実行します。

./script/bootstrap

次に、デバッグアプリケーションをコンパイルして起動します。

./script/run

ビルドによってtarget/debug/bundle/osx/Harp.appが生成され、起動します。macOSの実行スクリプトは、キーチェーン内の最初のApple Development IDでアプリケーションに署名し、見つからない場合はアドホック署名に切り替えます。署名済みで公証可能なリリースDMGを作成するには、script/release_macosを使用し、ヘルプ出力を確認してください。

Harpを設定する

Harpの追加連携はデフォルトで無効になっています。~/.harp/settings.tomlを作成または編集し、必要な機能を有効にしてください。Harpは変更時に設定ファイルを再読み込みします。

[integrations.limit_rings]
enabled = true
file = "~/.cache/limit-rings.json"

[integrations.tmux]
enabled = true

使用量制限リングを有効にする

integrations.limit_rings.enabledをtrueに設定し、integrations.limit_rings.fileをプロバイダーの使用量を含むローカルJSONファイルに指定します。~はホームディレクトリを表します。

tmux同期を有効にする

integrations.tmux.enabledをtrueに設定すると、tmuxとの同期、セッションの取り込み、tmux内でのエージェント検出が有効になります。Harpは10秒ごとにtmuxを確認します。

tmuxを有効にすると、名前、グループ、並び順、既読フラグ、非アクティブフラグ、取り込んだセッションを同期できます。独自の動作が必要な場合は、integrations.tmux.session_scriptに、名前変更とグループ変更を処理するスクリプトを指定できます。スクリプトには次の形式でコマンドが渡されます。

<script> rename <shell_pid> <group> <title>
<script> group <session_id> <old_group> <new_group>

サイドバーとエージェントツールバーを調整する

  • appearance.vertical_tabs.full_tab_menuのデフォルト値はtrueです。falseに設定すると、タブとグループのメニューを主要な操作だけに絞れます。同じオプションは、設定の「外観」>「タブ」からも利用できます。
  • agents.third_party.should_render_cli_agent_toolbarのデフォルト値はfalseです。trueに設定すると、CLIエージェントのセッション下に上流のツールバーを再表示できます。

サードパーティ製CLIエージェントツールバーを無効にした場合は、プロジェクトの説明に従い、Claude CodeのプラグインマーケットプレイスからWarpプラグインを更新してください。

コーディングエージェントでHarpを使う

  1. Harpを開き、Claude CodeまたはCodexのワークフロー用セッションを作成します。
  2. Cmd+Rでタブ名を変更し、目的が分かるようにします。
  3. 関連するセッションを名前付きグループに入れます。たとえば、プロジェクトごとにグループを作成します。
  4. サイドバーの状態インジケーターを確認し、対応が必要なセッション、作業中のセッション、完了したセッションを把握します。
  5. すぐに必要でないセッションを保留にします。Harpでは月のアイコンが表示されます。
  6. 準備ができたら未読セッションを開き、出力を確認します。

新しいタブは、Cmd+T、ダブルクリック、またはサイドバーの空白部分を右クリックして表示されるメニューから作成できます。このプロジェクトでは、検索フィールド、表示オプション、タブ設定ボタンなど、一部のタブバー操作項目を意図的に削除しています。

別の場所で開始したセッションを取り込む

別のデバイスやターミナルから tmux セッションを作成した場合は、Harp にタブとして取り込ませることができます。対象の tmux セッションで次を実行します。

tmux set-option @warp_adopt 1

tmux 統合を有効にすると、Harp はそのセッションを追跡し、サイドバーに名前、グループ、状態を反映できます。SSH 経由で開始した作業を続ける場合などに便利です。スマートフォンから開始した作業にも対応できます。

Claude Code のバックグラウンドタスク通知を接続する

このリポジトリには、バックグラウンドタスクを Harp に通知する Claude Code フックが含まれています。統合手順は integrations/claude-code にあります。バックグラウンドでのアクティビティをサイドバーに表示したい場合は、この手順を使用してください。

高度な開発オプション

状態変更を追跡する

エージェントのトランスクリプトに対する回帰チェックを行うには、WARPOSS_STATUS_TRACE=1 を指定してデバッグビルドを起動します。Harp は状態変更を ~/Library/Logs/harp.log に [status-check] 行として記録します。

実際のログインなしで実行する

起動時に WARPOSS_SKIP_LOGIN=1 を設定すると、テストユーザーで起動し、認証が必要なリクエストを失敗させることができます。ログインを使用しない自動実行を想定した機能です。

分離されたデバッグデータプロファイルを使用する

デバッグビルドでは、WARP_DATA_PROFILE=<name> を設定すると、設定とデータをデフォルトのプロファイル保存場所ではなく ~/.harp-<name> に保存できます。

コントリビューションを検証する

変更を提出する前に、リポジトリの提出前チェックを実行します。

./script/presubmit

これにより、フォーマット、Clippy、テストが実行されます。

まとめ

Harp は Warp ターミナルを、多数の長時間実行する Claude Code セッションや Codex セッションを管理するワークスペースに変えます。macOS アプリをインストールするかソースからビルドし、必要に応じて tmux と limit-ring の統合を有効にしてから、グループと状態インジケーターを使ってエージェント主導の開発を整理できます。Harp は非公式の Warp フォークであるため、Harp 固有の問題は Warp ではなく、このリポジトリに報告してください。