CLIエージェント

すでにClaude CodeやCodexを使っているなら、それらをPerchの中で実行できます。モデルピッカーでどちらかを選んでフォルダを指定すると、そのエージェントは自分のツールを使い、あなた自身のログインで、そのフォルダで作業します。Perchのチャットとエージェントは一つのサイドバーに並ぶので、すべてを一か所で追えます。

各エージェントはリポジトリの専用のコピーで、専用のブランチの上で作業するため、手元のチェックアウトに触れることなく、複数のエージェントが同時に作業できます。作業が終わったら、何が変わったかを確認し、ワンクリックであなたのフォルダにマージするか、プルリクエストを開きます。

始める前に

• Perch Desktop 2.5.4以降で、ProまたはUltraのアカウントにサインインしていること。ウェブ版のPerchでは、CLIエージェントは使えません。
• このコンピューターにClaude CodeまたはCodexがインストールされ、サインイン済みであること。 ターミナルでclaudeまたはcodexが動くなら、Perchから起動できます。Perchはあなたがインストールしたものとあなたのログインを使い、どちらも同梱していません。
• Git。 Windowsでは、Git for Windowsをインストールしてください。マージにはgit 2.40以降が必要です。
• Perchに追加したフォルダで、コミットが一つ以上あるgitリポジトリの中にあること。エージェントが専用のコピーを持てるようにするためです。

エージェントを開始する

チャットのバーには、エージェントが何をしているか、その名前、フォルダ、ブランチ（agent/add-a-dark-mode-toggle-t-7q2mなど）が表示されます。

チャットは、開始したときのエージェントのまま変わりません。Perch自身のモデルに戻るには、新しいチャットを開始してください。

作業している間

• 承認はあなたに届きます。 エージェントが何かの許可を求めると、Claude asks to go aheadと書かれたカードが、エージェントが示す選択肢とともに表示されます。
• Modeでは、エージェント自身のモードを設定します。そのCLIにあるのと同じモードで、たとえばClaudeならAccept editsです。
• フォローアップはいつでも送れます。 作業中に送ったものは待機し、ターンが終わったときに送られます。PNG、JPEG、GIF、WebPの画像を添付でき、サイズは各画像5 MBまでです。
• Diffを選ぶとChangesパネルが開き、エージェントがそのコピーで変更したすべてのファイルが表示されます。
• Open terminalを選ぶと、エージェントのリポジトリのコピーを作業場所とするターミナルが、チャットの横に開きます。
• 複数を同時に実行できます。 最大四つのエージェントを、それぞれ専用のコピーで同時に実行できます。どれが作業中かはサイドバーに表示されます。

リポジトリの専用コピー

既定では、各エージェントはgit worktreeで作業します。git worktreeとは、リポジトリの二つ目のチェックアウトで、専用のフォルダに置かれ、専用のブランチ上にあります。エージェントが作業している間も、あなたのフォルダ、そのブランチ、まだコミットしていない内容はそのまま保たれ、二つのエージェントが同じファイルを編集することはありません。

worktreeには、gitが追跡しているファイルしかありません。Perchは、ほとんどのプロジェクトの実行に必要な次のものも持ち込みます。

• ローカルの設定ファイル。 .envと.env.*のファイルは、どの階層にあっても、gitが無視している場合にコピーされます。ローカルの設定や証明書など、gitが無視しているほかのファイルもコピーするには、リポジトリのルートにある.worktreeincludeファイルに、.gitignoreの構文で列挙します。ファイルがコピーされるのは、コピーの中でもgitがそのファイルを無視する場合だけなので、コミットに含まれてしまうことはありません。対象は最大200ファイルで、各ファイル10 MB、合計50 MBまでです。シンボリックリンクはスキップされます。
• macOSのOptionsにあるCopy node_modulesは、あなたのnode_modulesをコピーにクローンします。コピーオンライトによるクローンなので、ほぼ一瞬で終わり、追加のディスク容量は使いません。
• OptionsにあるSetup commandは、エージェントが開始する前に、npm installなどのコマンドをコピーの中で、あなたのシェル（WindowsではPowerShell）で実行します。Perchはこのコマンドをそのリポジトリ用に記憶します。コマンドが失敗した場合や15分を超えた場合でも、エージェントはそのまま開始し、チャットにその旨が表示されます。出力は、チャットのバーにあるSetup logで確認できます。

Optionsには、コピーが作られる場所であるWorktree folderと、Account folderもあります。後者では、Claude CodeやCodexのログインが複数ある場合に、使うログインのフォルダを選びます。どちらもホームフォルダの中にある必要があります。

エージェントにあなたのフォルダそのもので作業させるには、Worktreeをオフにします。その場合、変更は行われたそばからあなたのフォルダに反映され、差分の確認やマージのステップはありません。

作業を取り込む

ターンでファイルが変更されると、会話の下にあるカードがそれを知らせます。たとえば「Claude changed 4 files in its own copy of perch-app. They're not in your folder yet.」のように表示されます。変更を取り込むまで、チャットのバーに件数が表示され続けます。Review changesで差分が開きます。

あなたのブランチにマージする

Merge into mainは、あなたのフォルダが現在いるブランチの名前が付いたボタンで、エージェントの変更をすべて一つのコミットとしてあなたのブランチに加えます。コミットメッセージは最初はチャットのタイトルになっていて、編集できます。そのあと、Remove the copyを選ぶと、エージェントのworktreeとブランチが削除されます。

Perchは、マージのためにあなたのフォルダ内のものをスタッシュ、リセット、上書きすることは決してありません。代わりに、次の場合は止まってその旨を伝えます。

• フォルダにコミットされていない変更がある。 先にコミットしてから、マージしてください。
• 同じファイルが、あなたのブランチとエージェントのコピーの両方で変更されている。 Ask Claude to fixを選ぶと、コピーの中で解決するよう、エージェントにメッセージが送られます。解決したら、もう一度マージしてください。
• フォルダがブランチ上にない、またはgitが2.40より古い。

ほかの終え方

マージボタンの横のメニューには、ほかに二つの選択肢があります。

• Commit onlyは、エージェント自身のブランチに変更をコミットします。あなたのフォルダは変わりません。
• Open pull requestは、エージェントのブランチをoriginにプッシュし、プルリクエストを開きます。GitHub CLI（gh）がインストールされていれば、Perchが代わりにプルリクエストを開きます。インストールされていない場合は、PerchがGitHubの新しいプルリクエストのページを開きます。ほかのgitホストでは、Perchはブランチをプッシュし、プルリクエストはあなたがそのホストで開きます。

チャットを閉じる

あなたのフォルダにまだ入っていない変更がコピーに残っているチャットを閉じようとすると、Perchは先に確認します。選択肢は、Merge first、Keep the copy（worktreeとブランチはそのまま残ります）、Discard（変更も含めて、コピーとそのブランチを削除します）です。

あなた自身のプラン

CLIエージェントはあなた自身のClaude CodeまたはCodexのログインで動くため、その使用量はPerchの使用量ではなく、そちらのプランにカウントされます。エージェントへのメッセージは、Perchのプランに含まれる使用量を使いません。

Perchは、各エージェント自身の上限を、エージェントが報告するとおりに表示します。5-hour limitとWeekly limitで、それぞれがいつリセットされるかも示されます。これらは、モデルピッカーのエージェントのカードと、Settings › UsageのOn this computerの下で確認できます。また、エージェントが上限に近づくと、メッセージ欄の上の表示で知らせます。上限は、このコンピューターでエージェントが初めて返答したあとに表示されます。

プライバシー

• チャットはこのコンピューターにとどまります。 CLIエージェントのチャットはPerchのアカウントに保存されないため、ウェブ版やスマートフォンのPerchには表示されません。
• エージェントは自分のサービスと通信します。 あなたのメッセージは、自分でCLIを使うときと同じように、Claude CodeからAnthropicへ、またはCodexからOpenAIへ送られます。Perchのサーバーは経由しません。
• 各エージェントには必要なものだけが渡されます。 Perchは、あなたの環境変数のうち限られた一部だけを渡してエージェントを起動します。ほかのエージェントのキーも、Perchのものも含まれません。

サブセッションで使う

Perchは、仕事の一部をClaude CodeやCodexに任せることができます。たとえば「Codexに、専用のセッションで不安定なテストを直させて」のように頼むと、Perchは、そのエージェントで、チャットのフォルダの新しいworktreeの中で動くサブセッションを提案します。ほかのサブセッションと同じく、Startを選択したときにだけ開始し、それを始めたチャットに報告を返します。エージェントの承認は、引き続きあなたに届きます。

トラブルシューティング

モデルピッカーにOn this computerが表示されない。Perch Desktop 2.5.4以降で、ProまたはUltraのアカウントにサインインしていることを確認してください。

エージェントにNot installedと表示される。claudeまたはcodexがPATHに含まれるようにインストールし、Perchを終了してから開き直してください。

Needs sign-inと表示される。Sign in in a terminalを選択すると、claudeまたはcodex loginが実行されます。サインインを完了してから、Try againを選択してください。

CLIがPerchに必要なバージョンより古いと表示される。CLIを更新してください。Claude Codeの場合はclaude updateを実行します。Codexは、インストールしたときと同じ方法（npmまたはHomebrew）で更新してください。

Node 22が必要と表示される。このメッセージは、2.5.4より前のデスクトップビルドで表示されるものです。Perch Desktopを更新してください。更新後のPerch Desktopは、Nodeなしでエージェントを実行します。

フォルダでworktreeを使えない。フォルダは、コミットが一つ以上あるgitリポジトリの中にある必要があります。Worktreeをオフにすることもできます。

Windowsでコピーを削除できない。コピー内のファイルが別のプログラムで開かれています。そのファイルを閉じてから、もう一度試してください。