Ferret の使い方

エージェントに送る

内蔵のターミナルでコーディングエージェントを動かし、ワンクリックでレビューを渡します。よく使われるのは Claude Code と Codex ですが、下の一覧にあるエージェントならどれでも使え、自分で足した CLI も使えます。ほかの場所で動くエージェント向けに指示をコピーすることもできます。

#指摘を確かめる

指摘 タブの各カードでできること:

  • 題名と依頼をその場で直す
  • 送信する / 送信しない の切り替え
  • 録画を見る(その時刻へ移動)と 画像を差し替え(別のフレームを選ぶ)
  • 確定する、削除

進み具合で絞り込む で、状態ごとに指摘を表示したり隠したりできます(たとえば、あなたの確認待ちのものだけ表示する)。すべて表示 で絞り込みを解除します。

指摘を並べ替えるには、カードの題名の左にあるつまみをドラッグするか、つまみを選んで ↑ / ↓ を押します。番号、feedback.md、エージェントへ送る内容は新しい順番に従います。絞り込んでいる間は見えている指摘の中で順番が変わり、隠れている指摘はその位置のままです。1つのレビューが複数のページやファイルにまたがるときは、指摘は同じまとまりの中で動きます。上部の 指摘の並び順 で 手動(ドラッグの順)・録画の時刻順・進み具合の順(未対応が先、完了が最後)を切り替えられます。進み具合の順に並べると、その並びが手動の順として保存されます。

上部には 元に戻す、保存先を開く、Agent向けにコピー、整理、Agentへ送信 があります。指摘にならなかった発話は 除外した発話 に並び、発話を指摘に戻す で戻せます。意味の通じない発話も指摘にならず、ここに並びます。無音から音声認識が作ってしまう「Shh.」「ご視聴ありがとうございました」のような文、「えー」のようなつなぎ言葉だけの発話、ペンの書き込みの無い「はい」「OK」だけの発話です。

指摘タブ
指摘タブ

#内蔵のターミナルでエージェントを動かす

プロジェクトを開くと、Ferret は 設定 → Agent → プロジェクトを開いたら起動 で選んだエージェントごとにターミナルのタブを1つ、プロジェクトのフォルダで開きます。最初の設定は Claude Code と Codex で、権限の確認を省き、Claude in Chrome を有効にして起動します。

claude --dangerously-skip-permissions --chrome
codex --dangerously-bypass-approvals-and-sandbox

代わりに対応している一覧から好きなエージェントを選べます(選んだ順に起動します)。何も選ばないこともできます。

自分で開くエージェントも同じように起動します。また Ferret は、Claude Code と Codex に対してプロジェクトのフォルダを信頼済みにするので、フォルダについて尋ねられません。フォルダを信頼する前、ファイルを編集する前、コマンドを実行する前に確認する普通のモードで起動するには、設定 → Agent → 権限確認を省いて起動する をオフにします。エージェントごとのコマンドと引数は 設定 → Agent(コマンド)と settings.json(agents.launch)にあり、書いたとおりに使われます。Claude in Chrome なしで Claude Code を起動するには、そこから --chrome を消します。引数ですでに権限のモードを選んでいるとき(たとえば --permission-mode plan、Codex なら --sandbox workspace-write)は、確認を省く引数を付けません。

エージェントを1つも選んでいなければ、普通のシェルが開きます。+ メニューからは 新しいターミナル を開いたり、自分のエージェントを新しいタブで起動したり、Agent設定… に移ったりできます。メニューの検索欄では、タブ、登録した URL、ファイルも探せます。

ターミナルにファイルをドロップする。 Finder(Windows ではエクスプローラー、Linux ではファイルマネージャー)からファイル、フォルダ、画像をターミナルのペインにドラッグすると、それらのパスがスペース区切りでそのペインに入力されます。Enter は押されません。エージェントの実行中も同じで、Claude Code はドロップした画像のパスを画像として読みます。ファイル からドラッグした行(選択すれば複数まとめて)も同じように扱います。パスは、ターミナルがプロジェクトのフォルダにいる間はそこからの相対パス、cd でほかの場所へ移った後は絶対パスになります。空白などの特殊な文字を含むパスは、シェルに合わせて引用符で囲みます。zsh と bash では '…'、コマンドプロンプトでは "…"、PowerShell では '…' です。

タブにはエージェントの状態が出ます: 実行中、入力待ち、完了(未確認)、待機中。完了(未確認) は、ほかのタブを見ている間にエージェントが終わったことを表し、そのタブを開くと 待機中 に変わります。サイドバーでも各プロジェクトに同じように印が付くので、プロジェクトを切り替えなくても分かります。エージェントが動いている間は動くバー、エージェントがこちらを待っている間は疑問符、そこのエージェントが終わってまだタブを開いていないときはチェックマークです。

通知。 設定 → Agent → Agent の作業が終わったときと、確認が必要なときに通知する をオンにすると、プロジェクトのエージェントがすべて終わったとき、またはエージェントが許可や回答を待っているときに、システムの通知が出ます。見ているタブについては何も出ません。通知を押すと、そのプロジェクトに切り替わってタブが開きます。

ターミナルのタブやペインをドラッグして、分割し、動かし、タブに戻す。

ドラッグで分割する。 タブか、ペインのつまみ(タブを分割すると出ます)をドラッグして、次の場所で離します。

  • ペインの端の外側4分の1: 左に分割 / 右に分割 / 上に分割 / 下に分割
  • ペインの中央: タブとして開く(ペインは分割から外れて、独立したタブになります)
  • ターミナル全体を囲む細い帯: 全体の左に分割 など(ペインが2つ以上あるとき)
  • タブバー: ここにタブとして置く

動かしている間もプロセスは動き続け、空になったタブは閉じます。キーボードでの分割:

操作macOSWindows / Linux
新しいターミナル⌘TCtrlT
右に分割⌘DCtrlShiftD
下に分割⌘⇧DAltShiftD
閉じる(ペイン/タブ)⌘WCtrlW

#再起動したあとにターミナルを戻す

Ferret を終了するとき、すべてのプロジェクトのターミナルのタブを覚えておきます。並びと分割、それぞれを開いたフォルダ、動かしていた Agent とアカウント、各画面の文字を 2,000 行までです。次に Ferret を起動すると、タブが同じ並びで戻ります。前の文字が先に出て、— 前回の続き(2026-10-05 14:30)— のような薄い色の行のあとに、同じフォルダで新しいシェルが始まります。

Agent のタブは会話を続けて起動します。Claude Code は --continue、Codex は resume --last で、そのフォルダの最後の会話を続けます。同じフォルダ・同じアカウントで同じ Agent のタブが複数あれば、続けるのは最初の1つだけで、ほかは新しく始めます(2つのタブが同じ会話を続けることはありません)。そのフォルダに Claude Code の会話が無いとき、またはプロジェクトが SSH のホストにあるときは、普通に起動します。

閉じたターミナルを開き直す。ターミナル → 閉じたターミナルを開き直す(ターミナルにフォーカスがあるときは ⌘⇧T / CtrlShiftT)で、このプロジェクトで最後に閉じたタブまたはペインを文字ごと戻し、Agent も同じように会話を続けて起動します。閉じたターミナルは最後の 10 個まで、再起動をまたいでも覚えています。

履歴は色の無い文字だけで、Ferret のデータフォルダ(terminal-restore.json、本人だけが読める)に保存し、プロジェクトには書きません。アカウントを追加 から開いたログインのタブと、1回きりのコマンドは覚えません。保存をやめるには 設定 → Agent → ターミナルの履歴を保存して復元する を切にします。保存したものも消えます。隣の 保存した履歴を消す でいつでも消せます。

#対応しているエージェント

Ferret は特定のエージェントに縛られません。下のコーディングエージェントを認識し、起動したり、Agentへ送信 のためにターミナルの中から見つけたり、インストール済みかどうかを表示したりできます。設定 → Agent には、インストール済み / 見つかりません、提供元が1行のインストーラーを公開している場合の インストール ボタン、各エージェントのコマンドと引数が並びます。

一覧に無いときは、設定 → Agent → カスタムエージェントを追加 で、どんな CLI やラッパースクリプトでも登録できます(名前、コマンド、必要なら見分けるためのプロセス名)。settings.json の agents.customAgents に足すこともできます。Ferret の外で動くエージェントには Agent向けにコピー を使えます。

いくつかの機能はエージェントによって違い、今のところ Claude Code と Codex だけで使えます。

  • アカウントと使用量: 複数のログインの切り替えと、フッターのレート制限のメーター。
  • 整理: Claude Code か Codex のログイン、または自分で設定した LLM API で動きます。

#Agentへ送信 / Agent向けにコピー

指摘タブから「Agentへ送信」で、内蔵のターミナルのエージェントへ送る。
  1. Agentへ送信 を押します。既定(自動(今のタブか、動いている Agent))では、いま開いているターミナルのタブのエージェントか、動いているエージェントに届きます。ボタンの横の矢印(送り先の Agent を選ぶ)で、送り先のエージェントやタブを選べます。
  2. Ferret はエージェントの入力欄に指示を書き込んで送信します。進み具合はターミナルで追います。

エージェントが動いていなければ、Ferret が先に起動し、準備ができしだい送ります。エージェントが作業中でも送り、エージェントは今の作業のあとに読みます。エージェントが権限の確認や質問への答えを待っている間は何も送りません。先にターミナルで答えてください。

Agent向けにコピー は、ほかの場所(別のターミナル、IDE、アプリ)で動くエージェントのために、同じ指示をクリップボードに入れます。対象になるのは 送信する にした指摘だけです。動画は決して含めません。

#判定モデルでの受け入れ確認

エージェントが指摘を直し、あなたが見る前に判定モデルで1件ずつ確かめる。

これを入にすると、コーディングエージェントはあなたが見る前に、自分の作業を指摘ごとに1回確かめます。Ferret 自身は何も判定しません。エージェントに判定モデル(System One 互換の API ならどれでも)を渡し、その使い方を feedback.md で指示します。判定モデルはエージェント自身の確認で、あなたへの質問にはなりません。エージェントはあなたに何も質問しません。あなたは BEFORE と AFTER を見比べて OK か NG を押すだけです。

  1. エージェントが指摘を実装します。
  2. 指摘ごとに AFTER のスクリーンショットを撮り(BEFORE の静止画と同じビューポートとページの状態で)、指摘の文、その「完了の条件」の行、BEFORE / AFTER の画像を1つのリクエストで判定モデルに送ります。
  3. 判定モデルを呼ぶのは、エージェントへ指摘を送るたびに指摘1件につき1回までです。2回目の判定もループもないので、「done」を出さないモデルのせいでエージェントが回り続けることはありません。
  4. エージェントはその1回の結果を読みます。P(done) がしきい値(既定 0.7)以上で、選ばれた答えが done なら、その指摘は合格で、そのままあなたに渡ります。そうでなく、結果がエージェントに直せる差をはっきり示していれば、もう1回だけ直して AFTER を撮り直してよく、そのとき判定はし直しません。
  5. どちらの場合も、エージェントはその指摘を AFTER、その1回の点数、長くても1行のメモと一緒に 確認待ち にします。対象外の指摘や、判定 API につながらないときも作業は止まらず、その指摘は点数なしで 確認待ち になります。
  6. 指摘 では、あなたの確認を待つ指摘ごとに BEFORE・AFTER・点数が材料として並びます。OK で完了、コメントつきの NG で新しい依頼としてエージェントへ差し戻し、そこでもう1回判定されます。ターミナルに出るエージェントの最後の「完了/未完了」の一覧には、指摘ごとの点数と、もう1回直したかが入ります。

設定 → 判定モデル で設定し、Agent への指示に判定モデルでの確認を入れる を入にします。プリセットは欄を埋めるだけで、どの欄も後から直せます。任意の接続先 は互換の API ならどれでも使えます。

プリセットリクエスト URLモデルキー
Ollama(既定)http://localhost:11434/v1/systemoneclef-flash、clef(画像を読める)、nimble、tev1(テキストのみ)不要、無料
Cloudflare Workers AIhttps://api.cloudflare.com/client/v4/accounts/{account_id}/ai/run/@cf/cloudflare/{model}clef-flash、clef(画像を読める)CLOUDFLARE_API_TOKEN(Workers AI の権限)。アカウント ID は欄か CLOUDFLARE_ACCOUNT_ID から
Vercel AI Gatewayhttps://ai-gateway.vercel.sh/typesafe/v1/systemonetypesafe-ai/jev、convaiinnovations/laya(テキストのみ)AI_GATEWAY_API_KEY
TypeSafehttps://api.typesafe.ai/v1/systemonejev-latest、jev-preview(テキストのみ)TYPESAFE_API_KEY
OpenAIhttps://api.openai.com/v1/decisionsgpt-6-luna(画像を読める)OPENAI_API_KEY
任意の接続先任意の完全な URL任意Bearer、任意のヘッダー、またはなし。追加のヘッダーも使える

OpenAI のプリセットは OpenAI の Decisions API を使います。リクエストの形が独自です(input、questions の配列、answers)。エージェントは今までどおり System One の形で中継へ送り、このプリセットのときだけ中継がリクエストを写し替え(BEFORE/AFTER の画像は input_image の data URL になります)、答えを元の形に戻します。そのためエージェントへの指示は変わりません。キーは OpenAI の API キー(文字起こしと同じもの)を使います。OpenAI の料金は入力トークンだけです(100 万トークンあたり $0.10)。

Ollama を使うときは、Ollama を入れ(Clef / Clef Flash には 0.35.1 以降が必要)、ターミナルでモデルを取得します。Ferret はインストーラーを実行しません。

ollama pull clef-flash

キーは、キーの欄(ほかの API キーと一緒に保存)、名前を指定した環境変数(アプリの環境、プロジェクトの .env、または ~/.ferret/.env)、または settings.json の apiKey から読みます。追加のヘッダーでは ${VAR} で環境変数の値を使えます。

キーが指示に入らないしくみ

エージェントがキーを見ることはありません。Ferret は 127.0.0.1 でローカルの中継を動かし、各ターミナルに FERRET_DECISION_URL(中継の URL。ターミナルごとのトークン付き)、FERRET_DECISION_MODEL、FERRET_DECISION_IMAGES を渡します(1リリースの間は、古い MOVIE_ADE_DECISION_* という名前も設定します)。中継がキーとヘッダーを付けてリクエストをそのまま転送するので、指示、feedback.md、エージェントのやり取りの記録には秘密の情報が入りません。ターミナルごとのトークンで使えるのは 500 回・1分に 30 回・2,000 万トークン・5 ドル(費用が分かるとき)まで、プロジェクトごとには1日 2,000 回・20 ドルまでです。上限に届くと中継は理由を付けて 429 を返し、新しいターミナルのタブには新しいトークンが渡ります。判定モデルの設定を変えると、開いているターミナルのトークンは使えなくなり、その後に開いたターミナルから新しい設定が使われます。

Cloudflare は System One のドキュメントと2点違います(実際の API で確認済み)。画像はデータ URI(data:image/jpeg;base64,…)でなければならず、そうでないと 422 "image must be an embedded base64 data URI" になります。また、答えは { "result": { … }, "success": true } で包まれて返ります(エラーは { "success": false, "errors": [ … ] })。Cloudflare のプリセットは 画像の渡し方 をデータ URI にし、エージェントはそれを FERRET_DECISION_IMAGE_FORMAT として受け取り、指示では .result があればそれを読むよう伝えます。中継は行きも帰りもそのまま通します。API トークンの代わりに Global API Key を使うときは、認証 を キーなし にし、ヘッダー X-Auth-Email: ${CLOUDFLARE_EMAIL} と X-Auth-Key: ${CLOUDFLARE_API_KEY} を足します。

画像を読めるのは Clef と Clef Flash だけです。テキストのみのモデルでは BEFORE / AFTER の画像を送る を切にします。その場合エージェントはテキストだけで判定するので、確かさは下がります。

Ollama と大きな画像

Ollama 0.35.0 は /v1/systemone へのリクエストを 64 KiB までに制限しているため、スクリーンショット付きのリクエストは HTTP 413 で失敗します。指示では、両方の画像を幅 1024px 以下の JPEG(品質 70 ほど)に縮めるようエージェントに伝えます。それでも 413 になるときは、Ollama を 0.35.1 以降に上げるか、Cloudflare Workers AI に切り替えてください。

#フッターの API 使用量

判定の呼び出しは中継を通るので、Ferret が数えられます。フッターで、エージェントの使用量メーターの横にある項目に、判定モデルと、今日の呼び出し回数・トークン数・費用が出ます(たとえば clef-flash · 42 calls · 18.3k tok)。押すと、今日、今月、プロジェクト別、モデル別、種類別(判定 / 文字起こし / 整理)の集計と、直近50回の呼び出しが見られます。

費用が出るのは、API が費用を返すとき(Vercel AI Gateway は返します)か、設定 → 判定モデル で 1M トークンあたりの価格を設定したときだけです。それ以外は「—」と出ます。記録するのはメタデータ(時刻、プロジェクト、モデル、状態、待ち時間、サイズ、画像の数、トークン数、費用)だけで、画像・テキスト・キーは記録しません。記録先は ~/.ferret/usage/decision-YYYY-MM.jsonl で、月ごとに1ファイルです。

#指示を変える

設定 → Agent → Agentへの指示 を編集します。展開される変数は2つです。

変数展開される内容
{{path}}feedback.md の絶対パス
{{relpath}}プロジェクトからの相対パス: .ferret/reviews/<id>/feedback.md

空にすると既定の指示を使います。最大 2000 文字で、指示を既定に戻す で既定に戻せます。例:

Read {{relpath}} and the PNGs next to it. Fix only findings marked to send, one commit per finding, then run the tests.

この設定は settings.json の agentPrompt に保存されます。

#GitHub で Ferret に star

最初に Agentへ送信 した後と、終えたレビューが 3、10、30 件になったときに、Ferret が GitHub で star を付けてほしいと尋ねることがあります。尋ねるのは最大3回で、間は3日以上空け、録画中には尋ねません。GitHub で star は自分の gh のログインで star を付けます(gh が使えなければ GitHub を開きます)。今後表示しない を押すと、もう尋ねません。ヘルプ → GitHub で Ferret に star… からも star を付けられます。

#よく使うサービスの CLI

設定 → よく使うサービスの CLI には、よく使うサービスのコマンドラインツールが並びます。入れておくとエージェントがそのサービスを扱えます。入れるのは任意なので、必要なものだけ入れてください。どれも入れなくても Ferret は使えます。各行には、インストール済みかどうかとバージョン、サービスのサイトへのリンク、OS に合った公式のインストールやログインのコマンドを新しいターミナルのタブで実行するボタンがあります。

  • Git のホスティング: GitHub(gh)、GitLab(glab)
  • ホスティング・デプロイ: Vercel、Netlify、Cloudflare(wrangler)、Firebase、Fly.io、Railway、Heroku
  • クラウド: AWS、Google Cloud(gcloud)、Azure(az)
  • データベース・バックエンド: Supabase、Neon、PlanetScale、Turso
  • エラー・監視: Sentry(sentry-cli)、Datadog(datadog-ci)
  • 決済: Stripe
  • コンテナ: Docker、kubectl
  • モバイル: Xcode Command Line Tools(macOS のみ)、Android Platform Tools(adb)、Expo EAS、fastlane
  • 仮想マシン: UTM(macOS のみ)、Lima、Multipass
  • AI・モデル: Ollama

その OS 向けの1行の公式インストーラーが無いツールでは、ドキュメント がそのインストール方法のページを開きます。インストールが終わると、一覧は自動でもう一度確かめます。

GitHub でこのページの翻訳を手伝う (新しいタブで開きます)