RaycastとClaude Code — サブスク接続と拡張開発の2通り

RaycastでClaudeを使う2通り

「Raycast Claude」で探す人の目的は、大きく2つに分かれます。

RaycastのAIでClaudeを使う

Raycastには「Bring Your Own Subscription」があり、Claudeのサブスクリプションをそのまま使えます。サブスク接続は、Raycastの有料プラン(Pro Exclusive)の機能です。

接続するには、Claude Codeをインストールしてclaudeを起動し、/loginでサインインします。プランに含まれるモデルが、Raycastのモデル選択に並びます。設定の場所は「Settings → AI → Models & Providers」の「Local AI Subscriptions」です。

APIだけのアカウントはサブスク接続の対象外なので、下記のAPIキー接続を使います。

使った分はClaudeサブスクの利用枠に数えられ、RaycastのAIクレジットは、画像生成など一部のツールを除いて減りません。プロンプトはお使いのマシンからAnthropicへ直接送られ、RaycastのサーバーはClaudeの認証情報を保存しません。

利用上限はAnthropic側の仕様に従います。5時間枠と週間上限があり、Claude Codeなど他の用途と共有です。Raycastで上限に達すると、どの上限か、いつ戻るかが表示されます。

サブスクではなくAPIキーで使う場合は「Bring Your Own Key」です。Anthropic、Google、OpenAI、OpenRouterのキーを登録でき、料金はプロバイダー側に請求されます。

Raycast拡張とClaude Codeの組み合わせ

ここからは、Claude Codeで拡張を作る方法です。Raycastはランチャーアプリで、拡張機能はReactとTypeScriptで書き、@raycast/apiが提供するコンポーネントでUIを組み立てます。Raycastは単一の子Node.jsプロセスを立ち上げ、その中で拡張をv8 isolate(ワーカースレッド)として読み込みます。

この構成はClaude Codeとの相性が良好です。ファイル編集・ビルド・lintの実行・ターミナル出力の読み取りを、Claude Codeが一括で担当できます。React/TypeScriptの経験が浅くても、実装をClaude Codeに任せつつ、仕様と動作確認を自分が担当する進め方ができます。ただしRaycastの画面そのものはClaude Codeから見えないので、画面の見え方はスクリーンショットや言葉で伝える必要があります。

前提条件を揃える

拡張を作り始める前に、次の環境を用意します。

• Raycast 1.26.0以上(macOS版)
• Node.js 22.14以上(fnmやnvmでのバージョン管理を推奨)
• npm 7以上
• Raycastアカウントへのサインイン(開発用コマンドの利用に必要)

サインインすると、Raycast内で「Store」「Create Extension」「Import Extension」「Manage Extensions」の4つのコマンドが使えるようになります。今回使うのは「Create Extension」です。

ひな形を作って開発モードで動かす

ひな形はRaycast側で作ります。ここはClaude Codeの出番ではありません。

cd my-extension
npm install && npm run dev

npm run devはホットリロード付きの開発モードで、ビルドエラーがターミナルに出ます。リロードはRaycast設定の「Extensions」→「Developer」にある「Auto-reload on save」で切り替えられます。

ビルドに失敗した場合、Raycastのコマンドアイコンが失敗を示し、直前に成功したコマンドは動き続けます。「直したのに表示が変わらない」と感じたら、まずターミナルのビルドエラーを疑います。そのエラーをそのままClaude Codeに貼れば、原因の切り分けから任せられます。

Claude Codeに任せる範囲を決める

実装はClaude Codeに任せられますが、公開に関わる操作は自分で実行するほうが安全です。npm run publishは実行するとraycast/extensionsへのプルリクエストを自動で作るため、確認なしで走らせたくないコマンドの代表です。

Claude Codeの権限設定は、Bash(npm run *)と書くとnpm runで始まる全コマンドに一致します。公式の権限ドキュメントでも、このルールがnpm run buildやnpm run test --watchに一致し、npm installには一致しない例が載っています。つまりnpm run publishも許可に含まれてしまいます。そこで、拡張のディレクトリの.claude/settings.jsonには許可を個別に書き、publishは拒否に置きます。

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run lint)"
    ],
    "deny": [
      "Bash(npm run publish)"
    ]
  }
}

Claude Code v2.1.287のclaude --helpにも、同じ形式の例があります。--allowedToolsと--disallowedToolsはどちらも"Bash(git *) Edit"のようにツール名とパターンを並べます。npm run devは常駐するコマンドなので、許可に入れず自分のターミナルで動かします。

コマンドの入出力を先に短い仕様として書き出してからClaude Codeに渡すと、生成されるコードと意図のズレが減ります。この進め方はcc-sddを使った仕様駆動開発とも共通する考え方です。

コマンドの種類と設定をマニフェストで決める

拡張の挙動はpackage.jsonのcommands配列で定義します。各コマンドにはmodeプロパティが必須で、値によって動作が大きく変わります。

no-viewとmenu-barのコマンドにはintervalを指定でき、90s・1m・12h・1dのような間隔でバックグラウンド実行させられます。最小値は1分(1m)です。

API連携やログイン情報を扱う拡張では、preferencesで設定値をユーザーに入力させます。typeにはtextfield・password・checkbox・dropdown・appPicker・file・directoryが選べます。required: trueにすると、値が入力されるまでコマンドを使えません。

APIキーの取得手順のような説明は、package.jsonと同じ階層のhelp.mdに書けます。未設定時の設定フォームの横にそのMarkdownが表示されます。ファイル名の大文字小文字は区別されず、Help.mdやHELP.mdでも動きます。

プリファレンスの型はRaycastがraycast-env.d.tsとして自動生成するので、Claude Codeに型を手書きさせる必要はありません。型の定義がずれて見えたときは、このファイルを読ませます。

状態を保存する場合はLocalStorageを使います。

import { LocalStorage } from "@raycast/api";
 
export default async function Command() {
  await LocalStorage.setItem("favorite-fruit", "apple");
  const item = await LocalStorage.getItem<string>("favorite-fruit");
}

LocalStorageは大量データの保存を想定していません。大きなデータはNode.js標準のfsで、拡張のサポートディレクトリに書き込む方式が案内されています。

一覧の各項目に操作を追加するときはActionPanelを使います。最初と2番目のアクションは主アクション・副アクションとして扱われ、ショートカットが既定で割り当たります。List・Grid・Detailでは↵と⌘ ↵、Formでは⌘ ↵と⌘ ⇧ ↵です。

import { ActionPanel, Action, List } from "@raycast/api";
 
export default function Command() {
  return (
    <List>
      <List.Item
        title="Docs: Update API Reference"
        subtitle="#1"
        actions={
          <ActionPanel>
            <Action.OpenInBrowser url="https://github.com/raycast/extensions/pull/1" />
            <Action.CopyToClipboard content="https://github.com/raycast/extensions/pull/1" />
          </ActionPanel>
        }
      />
    </List>
  );
}

アクションの並び順が割り当てを決めるため、Claude Codeにアクションを追加させるときは「どれを主アクションにしたいか」を先頭の順序で明示します。

動作確認とデバッグ

npm run devを動かしたままsrc/index.tsxを保存すると、Raycast側の表示が更新されます。console.logやconsole.debugの出力は開発モード中のターミナルに出るので、Claude Codeにログを仕込ませて出力を読ませる使い方ができます。ストアで配布された拡張ではコンソールログが無効になります。

実行時の例外やPromiseの拒否はRaycast上にエラー画面として出ます。開発中はスタックトレースが付きますが、ストア版ではエラーメッセージだけです。ネットワーク失敗のように起こりうるエラーは、showToastで利用者に伝える実装をClaude Codeに指定します。

ストアに出す前提がなくても、npm run buildは一度実行しておくと、開発モードでは気づきにくいエラーを早期に見つけられます。npx ray lintはESLintをsrcディレクトリ内の全ファイルに対して実行します。package.jsonのlintスクリプトにray lintを割り当てておけば、npm run lintで呼び出せます。この2つはコミット前の確認手順として、上の権限設定のとおりClaude Codeに実行させられます。

npm run build
npm run lint

ストア公開に向けて整える

Raycast Storeへの公開を考えている場合、package.jsonのメタデータをレビュー基準に合わせます。authorにはRaycastアカウントのユーザー名、licenseはMITを指定し、platformsは拡張が対応するOS(macOSまたはWindows)に絞ります。

名前の付け方にも規則があります。拡張名・コマンド名はタイトルケースで、拡張タイトルは動詞より名詞を優先します(Emoji SearchがSearch Emojiより良い例です)。コマンドタイトルは<動詞> <名詞>か名詞のみの形が一般的で、冠詞は避けます(Search an Emojiは避ける対象)。アクションパネルの項目名もタイトルケースで、サブメニューを持つ項目には末尾に…を付けます。

アイコンはPNG形式・512×512ピクセルで、ライトとダークの両方のテーマで見栄えがすることが求められます。ダーク用にはicon@dark.pngのような@darkサフィックス付きの画像を追加できます。カテゴリはApplications・Communication・Data・Developer Tools・Productivity・Systemなど15種類から最低1つ選びます。指定先はpackage.jsonのcategories配列か、拡張作成時のダイアログです。

追加の設定手順が要る拡張にはリポジトリ直下にREADME.mdを置きます。READMEがあると、プリファレンスの初回設定画面に「About This Extension」ボタンが出ます。更新履歴を見せたいときは、同じく直下にCHANGELOG.mdを置きます。

UIでは、画面遷移にNavigation APIを使い、独自のナビゲーションスタックを作らないことが求められます。画面の中身を差し替えて遷移に見せる拡張は却下の対象です。空配列を先に描画すると「No results」が一瞬チラつくので、データが届くまではローディング表示を出します。ルートコマンドのnavigationTitleは変えず、下位の画面でだけ文脈を補うために使います。ローカライズはUS Englishのみで、独自の多言語対応は入れない方針です。

必須プリファレンスは、required: trueにすればRaycastが入力を促します。そのため、設定用の独立したコマンドは作らない方針です。初回起動で設定画面が出ることは、公開前に自分でも一度確認しておきます。

公開コマンドの流れと詰まりどころ

検証が済んだら、拡張ディレクトリで公開コマンドを実行します。

npm run publish

他の人がGitHub上で直接コードを編集した場合、次回のnpm run publishが失敗します。その際は次のコマンドで変更を取り込んでから再実行します。

npx @raycast/api@latest pull-contributions

テンプレートの更新前に作った拡張では、publishスクリプトがpackage.jsonに無いことがあります。その場合はscriptsに"publish": "npx @raycast/api@latest publish"を足します。npm run publishを使わず、フォークしたリポジトリへ直接プルリクエストを送る手動フローもあります。プライベートに使うだけなら、公開ステップ自体が不要です。

publishで詰まった報告として、次の2件のGitHub issueがあります。

• #21412: npm run publish(中身はray publish)が止まった報告です。エラーは「please commit or discard your uncommited changes first」でした。報告者はクリーンなCI環境でも出たと書いており、原因は未確定です。ローカルでは、publishの前にgit statusで未コミットの変更を見ておくと、このメッセージの原因を切り分けやすくなります。
• #15218: npm run publishでプルリクエストが作れたのに、そのあとGitHub Actionsのlintで落ちた報告です。publishの前にnpm run lintを回しておく理由になります。

よくあるつまずき

Claude Codeは@raycast/apiに存在しないメソッド名やプロパティを提案することがあります。npm run buildを通すと配布用ビルドと同じ型チェックが走るので、コード生成のたびにビルドを一度通す習慣が事故を防ぎます。

npm run devを止めたまま編集して「変更が反映されない」と感じたら、開発モードが動いているかを先に見ます。公式の手順にも、拡張を変更したいときはnpm run devをもう一度起動する旨の注記があります。

CIやリモートの開発マシンでも同じチェックを回したいときは、Claude apps gatewayをCIやリモート開発機から使う設定が参考になります。

まとめ

ストアに出さない拡張なら、publishを拒否する設定を入れておくと、Claude Codeからpublishが実行されることはなく、プルリクエストも作られません。ストアに出すなら、メタデータと命名規則のレビュー基準を、公開前にClaude Codeへ照合させる使い方があります。UIをランチャーの中に置くか、チャットに埋め込むかという設計判断は、MCP Appsでも出てくる論点です。