Claude CodeでArduinoを制御する — Arduino IDEなしでスケッチ作成から書き込みまで

Claude CodeにArduino専用の機能はありません。使うのは「ファイル編集」と「コマンド実行」という2つの一般的な能力だけです。実体はArduinoの公式CLIツールであるarduino-cliをBashツールから呼び出す構成で、スケッチの作成からコンパイル、ボードへの書き込み、シリアル通信の確認までを一通りこなせます。特別な連携機能の追加を待つ必要はありません。Arduino IDEも必須ではなく、IDEを開かずにターミナルだけで完結します。

詰まりやすいのは、arduino-cliの使い方よりも「終わらないコマンド」と「許可プロンプト」の扱いです。この記事は、その2点を軸に手順を組み立てます。

Arduino開発に必要な前提環境

Claude Code側で必要なのはターミナルからclaudeコマンドを実行できる環境です。CLI・IDE統合・デスクトップアプリのいずれでも、ローカルのシェルコマンドを実行できる形であれば同じ手順が動きます。Claude Codeの組み込みツールは「ファイル操作」「検索」「実行」「Web」「コードインテリジェンス」の5カテゴリです。Arduino開発で使うのは主にファイル操作と実行の2つです。

Arduino側で必要なのは、USBケーブルで接続したArduinoボードと、コンパイル・書き込みを担うarduino-cliです。Arduino IDEのGUIは不要です。リモート環境やCI上でこのワークフローを動かしたい場合の構成は、Claude apps gatewayをCIやリモート開発機から使う記事が参考になります。

uploadとmonitorは、ボードが物理的に接続されたUSBポートを開きます。ブラウザから操作する場合も、Bashツールが動くマシンにボードが挿さっている必要があります。Remote Controlのように「ブラウザのUIから操作しつつ、実行とファイルはローカルに残す」形態なら、手元のボードをそのまま使えます。

arduino-cliをセットアップする

arduino-cliはHomebrew経由か、公式のインストールスクリプトで導入します。

brew update
brew install arduino-cli

Homebrewを使わない場合は、公式スクリプトを$PWD/binに展開できます。

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

バージョンはピン留めできます。sh -s 0.9.0のようにバージョン番号を渡せば、CIやチーム内で同じarduino-cliを再現できます。nightly-latestも指定できますが、毎日master(開発の主軸ブランチ)から作られる不安定版なので、通常は使いません。配置先を変えたいときは、BINDIR=~/local/bin shのようにBINDIRを指定します。指定先のフォルダは事前に作っておく必要があり、無いとinstall.shが止まります。

arduino-cliは設定ファイルが無くても全機能を使えます。arduino-cli config initで作成しておくと、ボードマネージャーの追加URLなど、サードパーティ製ボードの項目をまとめて持てます。

導入後は、コアのインデックス更新と接続したボードの認識確認をClaude CodeにBashツールで実行させます。

arduino-cli core update-index
arduino-cli board list

board listはポート名・ボード名・FQBN(Fully Qualified Board Name)・コアを表で返します。公式の例ではポートが/dev/ttyACM1、FQBNがarduino:avr:unoのような形です。WindowsのポートはCOM3のような表記になります。FQBNのプラットフォームコア(arduino:avrやarduino:samdなど)が未インストールなら、arduino-cli core install <プラットフォーム名>で導入します。

Arduino IDEは必要か、併用できるか

結論は、Claude Codeで進めるだけならArduino IDEは要りません。arduino-cliは、ボードとライブラリの管理、スケッチのビルド、ボードの検出、書き込みを1本のコマンドで担うツールで、Arduino IDEの中核にも使われています。コンパイルもアップロードもシリアル確認も、この記事のコマンドで足ります。

IDEを併用することもできます。スケッチの構成は仕様が共通で、同じフォルダをIDEでもarduino-cliでも扱えます。Claude Codeにコードを書かせてコンパイルまで任せ、出力の確認だけIDEのシリアルモニタ(値をグラフで見るならシリアルプロッタ)で行う、という分担ができます。

ただし、IDEのシリアルモニタとarduino-cli monitorで同じポートを同時に開くと、通常は後から開いた側がエラーになります。uploadやmonitorの前に、もう一方を閉じておきます。

ポートとFQBNをスケッチに固定する

FQBNとポートは、コンパイル・書き込み・シリアル通信のほぼ全コマンドに要ります。毎回フラグで渡すと、Claude Codeが書くコマンドが長くなり、許可ルールも書きにくくなります。

スケッチフォルダにsketch.yamlを置くと、これらの既定値を1か所にまとめられます。公式のスケッチプロジェクトファイルの仕様では、default_fqbnが--fqbn、default_portが--portの既定値になります。default_port_configはmonitorの--configの既定値です。default_port_configはArduino CLI 1.1.0以降の機能です。

default_fqbn: arduino:avr:uno
default_port: /dev/ttyACM0
default_port_config:
  baudrate: 9600

board attachでも、ポートとボードをスケッチに結び付けられます。例はarduino-cli board attach -p /dev/ttyACM0 -b arduino:avr:uno BlinkAndReportで、-bがボードです。以降の例は、フラグを明示した形で書きます。

Claude Codeにスケッチを書かせる

Arduinoのプログラムは「スケッチ」と呼ばれ、実体はフォルダです。フォルダ名と同名の.inoファイルを必ず1つ含む必要があります。名前は英数字かアンダースコアで始まり、英数字・アンダースコア・ドット・ダッシュが使えて、最大63文字です。ドットで終わる名前や予約名も使えません。.inoのほかに.cpp・.c・.S・.hなどの補助ファイルも同じフォルダに置けます。

雛形はarduino-cli sketch newで作成できます。

arduino-cli sketch new BlinkAndReport

これでBlinkAndReport/BlinkAndReport.inoが生成され、中身はsetup()とloop()だけの空の骨格です。ここから先はClaude Codeの通常のファイル編集で進められます。LEDの点滅にシリアル出力を組み合わせたコードを書かせる場合、次のような指示が具体的です。

BlinkAndReport.inoを編集してください。setup()でSerial.begin(9600)とpinMode(LED_BUILTIN, OUTPUT)を呼びます。loop()ではLEDを1秒間隔で点滅させながら、Serial.println()で点滅回数をシリアルに出力してください。

.inoの読み書きはClaude CodeのEdit・Writeツールが担い、arduino-cliはコンパイルと書き込みだけを担当する分担です。ライブラリが必要な場合はarduino-cli lib search <キーワード>で検索し、arduino-cli lib install <ライブラリ名>で追加できます。

外部ライブラリをスケッチに同梱して配布したいときは、srcサブフォルダにコードを置く方法があります。src配下は再帰的にコンパイルされますが、IDEのタブには表示されません。ただしこの下に置けるのは.cppや.hなどで、Arduino言語のファイル(.ino)は対象外です。

コンパイルからシリアル確認までの1周

1周の流れは次の3段階です。

終わらないmonitorをどう扱うか

3段階のうち、Claude Codeで事故になりやすいのはmonitorです。monitorはポートを開いたまま終了しないので、Ctrl+Cのような中断が無い限りプロセスが残ります。

ここで「Bashツールがずっと止まる」と考えるのは正確ではありません。Bashツールのコマンドには時間制限があり、既定は2分です。制限に達した前景コマンドは、止められずにバックグラウンドへ移ります(sleepで始まるコマンドは例外)。移った後の制限時間は、移った時点から30分です。Claude Codeはその間も会話を進められますが、monitorは裏でポートを開いたまま動き続けます。

問題になりやすいのは、monitorがポートを開いたまま背景に残り、次のuploadと競合しうることです。/tasksでバックグラウンドのコマンドを一覧し、不要なら止められます。CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1を設定すると自動のバックグラウンド化が無効になり、制限に達したコマンドは移らずに止まります。

対策は大きく2つあります。

timeoutは、Bashの許可ルールを判定するときに外側の包みとして取り除かれる仕組みの1つです。Bash(arduino-cli monitor *)を許可していれば、timeout 5を前に付けたコマンドも同じルールで判定されます。Monitorツールも、Bashと同じ許可ルールで判定されます。

コンパイルとアップロードの許可をどう設計するか

compileとuploadは何度も繰り返すので、毎回許可を求められると開発のテンポが落ちます。.claude/settings.jsonのpermissions.allowに、*を使ったルールを登録しておくと、同じ形のコマンドは確認なしで実行できます。

{
  "permissions": {
    "allow": [
      "Bash(arduino-cli compile *)",
      "Bash(arduino-cli upload *)",
      "Bash(arduino-cli monitor *)"
    ]
  }
}

Bashのルールは、コマンド文字列全体に対して照合されます。&&や;でつないだ複合コマンドは、各部分が独立に照合されます。arduino-cli compile ... && arduino-cli upload ...と1行に書けば、2つのルールが両方必要です。

どこまで自動化するかは、開発の段階で変えるのが現実的です。

auto modeの分類器がコマンドを拒否した場合の制御は、PermissionDenied hookの記事にまとまっています。拒否のログ化とモデルへの再試行許可を、フックで細かく扱えます。対話セッションではなく、書き込みまで任せる自律エージェントを組みたい場合は選択肢が変わります。Agent SDKのパーミッション制御なら、モードとallow/denyルールを個別に設計できます。

よくあるつまずき

• uploadしたのに動作が変わらない: uploadはcompileを含みません。.inoを編集したらcompileを先に実行します
• 出力が読めない: スケッチのSerial.begin()とmonitorのbaudrateを同じ値に揃えます
• ポート名がコマンドごとに食い違う: ポート名はOSやボードで形式が変わります(/dev/ttyACM0、COM3など)。都度arduino-cli board listで確認するか、sketch.yamlのdefault_portに固定します

まとめ

Claude CodeでArduinoを動かすときの要は、sketch.yamlでFQBNとポートを固定し、monitorだけは時間を区切るかMonitorツールに任せる、という2点です。この2つを押さえれば、compile・uploadの許可ルールは短く書けて、ポートが塞がる事態も減らせます。