メンバー特典・買い切り版共通ガイド — voice-agent v0.1.0

声で Claude Code を動かす — 導入ガイド

受け取った zip を展開して、話しかけて開発できるようになるまで。つまずきやすいところと、実際にかかるお金も、実測値で書いてあります。

WHAT — これは何をする道具か

画面を見ないで開発が進む

ターミナルのコーディングエージェント（Claude Code）に声で作業を頼み、進み具合を声で聞くためのローカルアプリです。実行してよいかの確認にも「はい / いいえ」で答えます。

話している最中から相手は聞いていて、言い終わる前に返事が組み立ち始めます。読み上げの途中で話しかければ割り込めます。

雑談や進捗確認は窓口役の会話係がその場で答え、実作業が要るときだけ Claude Code に渡します。全部を Claude Code に流すと雑談でも数秒待たされるため、ここを分けてあります。

REQUIREMENTS — 動作環境

動く組み合わせ

環境	状態
macOS 14 以降	全機能（想定している環境）
Windows 11 / Linux（x64・arm64）	会話と開発は動く。PC 操作と権限診断の一部が使えない
Windows on ARM / Alpine	非対応。資料検索に使う sqlite-vec のバイナリが無く、サーバが起動しない

ほかに Node.js 22 以上・pnpm 10（corepack enable で入ります）・ Chrome か Edge（マイクと WebRTC を使うため。Safari は未確認）が要ります。

依存パッケージはすべてビルド済みのものが配られるので、ネイティブのコンパイルは走りません。

KEYS — 用意するもの

必要なのは2つだけ

① Claude Code にログインしたターミナル

このアプリに Anthropic の API キーは要りません。ターミナルで claude が動く状態（＝ログイン済み）であれば、その資格情報をそのまま使います。まだなら Claude Code を入れてログインしておいてください。

② OpenAI の API キー（音声に使う）

platform.openai.com/api-keys で「Create new secret key」
作った直後の1回しか全体を見られないので、その場でコピーする
支払い方法の登録が必要です
gpt-realtime が使えないと言われたら、組織の本人確認（Verify Organization）をします

キーが無くても動きます。テキスト入力での対話・テストはそのまま通り、音声だけが無効になります。

SETUP — 入れて動かす

展開して、4つ打つだけ

corepack enable              # pnpm を使えるようにする
pnpm install
cp .env.example .env         # OPENAI_API_KEY を書く
pnpm run doctor              # 足りないものを日本語で教えてくれる
pnpm dev                     # → http://localhost:5173

pnpm doctor ではなく pnpm run doctor と打ってください。 run を省くと pnpm 内蔵のコマンドに取られて何も出ません。

初回は macOS の許可（アクセシビリティ・オートメーション・画面収録）を聞かれます。 許可は起動したアプリごとに付くので、ターミナルから起動する場合と常駐させる場合で別に必要です。

USE — 使い方

開いたら、あとは話しかけるだけ

ブラウザを開くとマイクが開いて、会話係が挨拶を返します。

ファイルの読み書き・コマンド実行は1つずつ声で確認してから実行されます（画面のボタンでも可）
途中でやめたくなったら「中断」
「作業画面を見せて」で 3D の作業画面へ、「英語表示にして」で表記が英語に
「軽いモデルにして」で会話係を切り替えられます

自動で許可するのは読み取り系の道具（Read / Glob / Grep / TodoWrite）だけです。

SAFETY — 勝手に動かない仕組み

雑談では作業が始まりません

声で開発をさせる以上、聞き間違いでコマンドが走るのがいちばん怖いところです。実際に、スピーカーから出た自分の読み上げをマイクが拾って、こちらが一言も話していないのに作業が始まったことがありました（3分30秒動いて約 $0.48）。

そのため、作業を始める前に「人が実際にそう言ったか」を機械的に確かめています。次の場合は作業を始めません。

直前の発話が確認できない
聞き取れた言葉が短すぎる／相槌だけ
こちらの読み上げを拾ったように見える
同じ依頼が続いた

見送ったときは画面に理由が出ます。「頼んだのに動かない」と思ったら、まずそこを見てください。

COST — 実際にかかるお金

財布は2つあります

ひとつは音声の会話係（OpenAI）、もうひとつが実作業（Claude Code）です。雑談や進捗確認だけなら、会話係のぶんしかかかりません。

何に	実測	母数
会話係 1応答	$0.02	30 応答の平均（標準モデル）
実作業起動して1回目	$0.19	7 セッションの中央値（$0.15〜$0.38）
実作業 2回目以降	$0.07	17 回の中央値（$0.02〜$0.20）

1回目だけ高いのはプロンプトキャッシュが効いていないためです。起動したまま使い続けるほど安くなるので、こまめに再起動しないほうが得です。

※ すべて作者の環境での実測値です。あなたの請求額を保証するものではありません。 作業の内容と対象リポジトリの大きさで変わります。

高いと感じたら

会話係を軽量モデルに切り替える（画面のヘッダーから。単価が約3分の1になります）
起動したまま使う（再起動するたびに1回目の値段に戻ります）
長引いていると感じたら「中断」と言う

かかった額は画面の上にその場で出ます。単価を確かめていないモデルでは金額を空欄にします（推測の数字を出さないため）。

TROUBLE — 困ったとき

まず doctor を打つ

pnpm run doctor

症状	見るところ
声が出ない・つながらない	`.env` の `OPENAI_API_KEY`。`gpt-realtime` が使えるアカウントか
マイクが使えない	ブラウザのマイク許可。再読み込み直後は一度画面に触れる必要があります
作業が始まらない	「作業は始めていません」の表示が出ていないか（上の SAFETY）
ポートが使われている	8787（サーバ）と 5173（画面）を使います
`pnpm doctor` が何も出さない	`pnpm run doctor` と打つ

OPTIONAL — 慣れてきたら

できることを広げる

手元の資料を引かせる

docs/ に .md .txt .pdf を置いて索引を作ると、会話の中で引けるようになります。

pnpm rag:index

資料に無いことは「資料には見つかりませんでした」と返り、それらしい答えを作りません。鍵や資格情報らしい名前（.env* id_rsa* *.pem credentials*）は、 中身を読む前に索引から外れます。

別のリポジトリで使う

# .env
VOICE_AGENT_WORKSPACE=/path/to/your/repo

複数を同時に開くこともできます（「packages/web も開いて」）。画面に半透明のターミナルが並び、話しかけている相手だけ縁が光ります。

アバターを出す

既定は計器表示です。VRM モデルを使いたい場合は packages/web/public/avatar.vrm に置いて、 voiceagent.config.json の avatar.kind を "vrm" にしてください。 置いただけでは切り替わりません（「置く」と「使う」を分けてあります）。

TERMS — このソフトの扱い

再配布はできません

メンバーシップ特典（メンバー版）または note / Brain での単体購入（買い切り版）として受け取る配布物です。受け取った本人が使う・改変するのは自由ですが、再配布・転載・販売はできません（改変したものも同じ）。

	メンバー版	買い切り版
受け取れる版	在籍中は常に最新版（Discord の配布チャンネルへ）	購入時点の版のみ（以後の更新は含みません）
使える期間	解約後も、受け取った版はそのまま使えます	期限なし（買い切り）
質問への対応	メンバー Discord の質問チャンネル	なし（このガイドと同梱文書の範囲でご利用ください）

買い切り版のご購入後にメンバーシップへ参加された場合は、その時点からメンバー版の扱いになります。

同梱の LICENSE に条項があります。とくに免責には目を通してください —— このソフトは声での指示にもとづいて、Claude Code にファイルの読み書きとコマンドの実行をさせるものです。 重要なデータはバックアップを取り、バージョン管理された作業フォルダで使ってください。