Claude Codeのcwc-makersプラグインで/maker-setupからCardputerを設定する

cwc-makersは、Code-with-Claude Makers用のM5Stack Cardputer-Advを、Claude Codeから1コマンドで使える状態にするプラグインです。USB-Cで接続して/maker-setupと打てば、リポジトリの取得、UIFlow 2.0ファームウェアの書き込み、アプリ一式の導入までをClaudeが進めます。人間の手が要るのは、本体背面のボタン操作だけです。

cwc-makersプラグインは何をするものか

cwc-makersはAnthropic verifiedのプラグインで、claude-plugins-officialマーケットプレイスに入っています。マーケットプレイスの説明は「/maker-setup1コマンドで、build-with-claudeリポジトリをcloneし、UIFlowファームウェアを書き込み、Claude Buddyのアプリ一式を入れる」という内容です。

プラグインのREADMEによると、/maker-setupの後に起きることは次の4つです。

• moremas/build-with-claudeをclone(取得)する
• デバイスを検出し、UIFlow 2.0ファームウェアを書き込み、Claude Buddy・Hello・Snakeのアプリ一式を入れる
• 背面のダウンロードモード用ボタン操作だけ、ユーザーに案内する
• Claude DesktopとBLEでペアリングできる、手のひらサイズのコンピューターが完成する

その後は「Magic 8ボール」「ピクセルペット」「天気ティッカー」のようなアプリをClaudeに頼むと、MicroPythonを書いて再書き込みなしでデバイスに送れます、とREADMEは説明しています。

READMEは、/maker-setupが想定された入り口で、2つのスキルは状況に応じてClaudeが自動で呼ぶこともあると書いています。スキルの内容はアップストリームのリポジトリから取り込まれており、~/.claude/skills/へのシンボリックリンクは不要です。

始める前に用意するもの

必要なのはCardputer-Adv本体、USB-Cケーブル、Python 3.10以上のホスト環境です。READMEによると、gitは任意です。/maker-setupはgitが無い場合にcurlとtarでのダウンロードに切り替わります。esptoolは初回実行時に自動でインストールされ、pyserialはアップストリームのリポジトリに同梱されています。

注意したい点が1つあります。アップストリームのREADMEは前提としてgitを挙げていますが、プラグイン側の/maker-setupはgitなしでも進む作りです。プラグインから入る場合は、gitが無くても止まりません。

Linuxでは、シリアルポートを開くのにグループ権限が要ります。Permission deniedやCould not open portで書き込みが失敗するなら、一度だけ次を実行してログインし直します。

sudo usermod -aG dialout $USER

これはDebian系・Arch系の例で、Fedora系ではuucpグループを使うとスキルは説明しています。

プラグインを入れて/maker-setupを実行する

インストールはマーケットプレイス名を付けた形で行います。

/plugin install cwc-makers@claude-plugins-official

導入経路の選び方はclaude plugin installの導入経路を選ぶで整理しています。入れたはずのプラグインが動かないときは、「packages are not installed」と出るClaude Codeプラグインの対処が切り分けの参考になります。

デバイスをUSB-Cでつないだら、作業したいディレクトリでClaude Codeを開き、次を打ちます。

/maker-setup

コマンドの定義は短く、disable-model-invocation: trueが付いています。Claudeが勝手に起動するのではなく、ユーザーが打ったときだけ動くコマンドです。

再実行すると約500KBを再ダウンロードするだけで、更新の仕組みは別に用意していません。

背面のボタン操作でダウンロードモードに入る

CardputerやCardputer-AdvのようなネイティブUSBのESP32-S3ボードは、ファームウェアの書き込みにボタン操作が欠かせません。スキルによれば、ソフトウェアだけでダウンロードモードに入る方法はなく、DTR/RTSを使う回避策も効きません。

Claudeが止まって案内したら、本体の背面で次のとおりに操作します。

画面が暗くならずUIFlowが起動してしまうときは、G0を離すのが早すぎます。もっと長く押して、もう一度試します。スキルは、画面が暗くなったとユーザーが確認するまで、スクリプトの再実行やソフトウェアでの回避を試みないよう指示しています。

書き込みの目安時間は、README上でファームウェアが約180秒、アプリの転送が約100秒です。書き込み中にケーブルを抜かないでください。途中で抜けても、ROMのブートローダーは残るため、再度/maker-setupを実行すれば書き込みからやり直せるとスキルは説明しています。

Claude Codeから長いコマンドを流すときの注意

m5-onboardスキルは、onboard.pyをBashツールのフォアグラウンドで実行しないよう書かれています。出力は終了するまでClaudeに返らず、2〜3分の無音がハングと区別できないためです。ボタン操作の案内まで届かないうちに、Claudeが諦めてしまう恐れがあります。

そこで、バックグラウンド実行にしてteeでログを残し、Monitorなどでログの要所だけを拾う流儀が指定されています。

python3 scripts/onboard.py --apps buddy 2>&1 | tee /tmp/m5-onboard.log

2>&1は解決策ではありません。進捗はもともと標準エラーに出ているため、ストリーミングの仕方こそが要点だとスキルは述べています。ログからはEnter download modeのような行を拾い、見つけたらユーザーに物理操作を頼む流れです。

これはCardputerに限らない設計です。数分かかり途中で人の操作が必要なコマンドは、フォアグラウンドで走らせるとClaudeからは止まって見えます。Monitorの期限の仕様はMonitorのpersistentが廃止され30分で監視が切れる理由にまとまっています。この書き込み作業は数分で終わるので、期限に当たることは少ないでしょう。自分のターミナルでonboard.pyを直接走らせる場合は、出力がそのまま流れるので何も変える必要はありません。

Cardputer-Advを選ぶ理由と、無印を持っているとき

onboard.pyの既定は--variant cardputer-advです。ユーザーが機種を言わなければ、Cardputer-Advだとみなします。

Core2・CoreS3・Basic・Fireなど別のボードなら、対応する--variantを明示します。

セットアップ後の使い方

完了すると、本体の側面のスイッチで電源を入れられます。起動ログの後にランチャーのメニューが現れ、/flash/apps/の各.pyが項目として並びます。矢印キーで選び、Enterで起動し、ESCでランチャーに戻ります。USB-Cを抜いても内蔵のLiPoバッテリーで動きます。

Claude DesktopとつなぐClaude Buddyは、次の手順です。

BLEでの接続は端末同士のローカルな通信なので、Wi-Fiの状態に左右されません。

Claudeにアプリを作らせて再書き込みなしで送る

ここからはcardputer-buddyスキルの出番です。デバイス上のファイルは次のように並んでいます。

/flash/
├── main.py              ランチャーメニュー
├── buddy_*.py           共有ライブラリ(BLE・UI・状態など)
├── burst_frames.py      スプライト画像
└── apps/
    ├── claude_buddy.py
    ├── hello_cardputer.py
    └── snake.py

main.pyは起動時に/flash/apps/を走査し、見つけた.pyをメニュー項目にします。新しいアプリはbuddy/device/apps/に置いて転送すれば、次の起動で並びます。最小の見本はhello_cardputer.pyで、キーボードの読み取り・フォント・終了の流儀が入っています。

Claudeに「サイコロアプリを足して」と頼んだ場合の、現実的な進め方は次のようになります。

• hello_cardputer.pyを参考に新しい.pyを書く(Claudeが担当)
• 書き換えた分だけをUSB経由で転送する
• シリアルログを見てエラーを直す

転送、ログ監視、1行のREPL実行には、buddy/scripts/のスクリプトを使います。

# 変更したファイルだけを送る
python3 buddy/scripts/push.py --port <PORT> --files apps/snake.py
 
# デバイスのシリアルログを見る
python3 buddy/scripts/tail_serial.py --port <PORT>
 
# REPLで1行だけ実行する
python3 buddy/scripts/repl_run.py --port <PORT> \
  --script "import os; print(os.listdir('/flash'))"

<PORT>はdetect.pyが最後に報告したものを使います。macOSなら/dev/cu.usbmodem1101、Linuxなら/dev/ttyACM0、WindowsならCOM3のような値です。実行してログを取り、Claude Codeに読ませて直すループは、Claude CodeでESP32の開発とシリアルデバッグを進める手順のArduino CLI版と同じ形です。こちらはMicroPythonなので、ビルド工程を挟まず.pyを送るだけで済みます。

アプリ一式をまとめて入れ直したいときは、install_apps.pyを使います。

python3 onboard/scripts/install_apps.py --port <PORT> --src buddy

上のスクリプトのパスには食い違いがあります。cardputer-buddyスキルはonboard/scripts/install_apps.pyと書き、build-with-claudeのREADMEは.claude/skills/m5-onboard/scripts/install_apps.pyと書いています。実際にクローンしたbuild-with-claude/の中身を見て、存在するほうのパスを使ってください。

詰まったときの切り分け

READMEのトラブルシューティングを、症状から引ける形にまとめます。

古いボード(Basic・Fire・Core2・StickC)のドライバー問題はCardputer-AdvとCoreS3には当てはまりません。この2機種はWindows標準のコンポジットUSBドライバーで動きます。

BLEが通らない原因として、スキルが詳しく書いているのがUIFlowの既定の起動設定です。既定のboot_option=1ではFlow用のBLEアドバタイズが裏で走り、NimBLEコントローラーが詰まってしまいます。ユーザーのコードからgap_advertiseを呼ぶとOSError(-519)(メモリ不足)になります。そこでbuddyのバンドルは、NVSのboot_option=2にして独自のmain.pyで起動を引き取ります。install_apps.pyは、ルートにmain.pyがあるバンドルを入れるとき、この設定を自動で書き込みます。

実行する前に知っておきたい3点

ここまで便利さを見てきましたが、実行前に把握しておくと安心な点が3つあります。

1つ目は、リポジトリを取得してスクリプトを走らせる構造であることです。プラグイン本体はスキルとコマンドの定義だけで、書き込みを行うスクリプトはmoremas/build-with-claudeにあります。実行前にbuild-with-claude/onboard/scripts/の中身をClaudeに要約させるか、自分で目を通す運用が現実的です。

2つ目は、イベント用のWi-Fiです。同梱のランチャーは起動のたびに、イベント会場のAP(SSIDはcardputer)へ自動接続します。認証情報はbuddy/device/wifi_event.pyにコミットされています。会場で公開されている資料のパスワードなので漏洩ではない、とREADMEは説明しています。イベントの外で使うなら、wifi_event.pyを書き換えるか、main()の先頭近くにある_connect_wifi_with_splash()の呼び出しを外します。接続に失敗してもランチャーは続行します。

3つ目は、UIFlowに戻す方法です。buddyのバンドルは/flash/main.pyを置くだけで、boot.pyには触れません。デバイスのREPLで次を打てば、標準のUIFlowランチャーが次回の起動から使えます。

import os
os.remove('/flash/main.py')
import machine; machine.reset()

/flash/apps/のアプリも消したいなら、同じ要領で個別に削除します。ファームウェアから入れ直すなら、--appsを付けずにm5-onboardを再実行します。UIFlowの書き込みだけを行い、ファイルシステムには触れません。

まとめ

cwc-makersは、ハードウェアの初期設定という「手順書を読んで人間が打つ作業」を、Claudeに渡せる形にしたプラグインです。人間の仕事は、背面ボタンの操作と、Claude Desktopでの接続の2つに絞られます。それ以降はMicroPythonの.pyを足して転送するだけなので、Claude Codeの普段の開発ループがそのままデバイス開発に使えます。手持ちが無印Cardputerのときは、書き込み前に必ずAdvかどうかを自分で確かめてください。