先日、Hacker Newsで「Executable Markdown files with Unix pipes 」という投稿を見かけました。思わず「これは面白い」と唸りました。

claude-switcher を使うと、Markdownファイルの先頭に #!/usr/bin/env claude-run というshebang（先頭行で実行コマンドを指定する仕組み）を書くだけで、そのファイルが実行可能になります。さらに、普通のUnixコマンドと同じようにパイプでつなげられる。

1
2

cat data.json | ./analyze.md > results.txt
git log -10 | ./summarize.md

「LLMをパイプラインに組み込む」という発想が新鮮で、実際に動かしてみたくなりました。

claude-switcherとは？

claude-switcherは、Claude Code で動くMarkdownファイルを実行可能にするツールです。Andi Search の開発チームが作成し、MITライセンスで公開されています。

主な特徴は次の通りです:

• shebang対応: Markdownファイルが直接実行できる
• Unixパイプ対応: stdin/stdout（標準入力/標準出力）が使えるので、他のコマンドと組み合わせられる
• プロバイダー切り替え: AWS Bedrock、Vertex AI、Azureなど複数のクラウドプロバイダーを使い分け可能
• セッション分離: 個人のClaude Code環境と自動化スクリプトを完全に分離

何が面白いのか？

このツールの本質は、「決定論的な処理とLLMの組み合わせ」だと思います。

従来のシェルスクリプトでは扱いづらかったタスクも、たとえば次のようにできます:

• ログファイルの要約
• テスト結果の判定
• コミットメッセージの生成
• データの分類・整形

こういった「人間の判断が必要だった曖昧なタスク」を、LLMに任せられます。しかも、それをパイプラインの一部として扱えます。

1
2
3
4
5

# テストを実行してLLMが結果を要約
./run_tests.sh | ./summarize-results.md > report.txt

# Git履歴を元にchangelogを生成
git log --oneline -20 | ./generate-changelog.md > CHANGELOG.md

決定的な処理（シェルスクリプト、コマンドライン）と、非決定的な処理（LLM）を同じパイプラインでつなげられるのが新しい。

「再現性がない」問題への向き合い方

Hacker Newsのコメント欄では、「nondeterministic shell scripting（非決定的なシェルスクリプト）」という批判が多く見られました。LLMは同じ入力でも違う出力を返します。なので、シェルスクリプトのように「常に同じ結果」は保証されません。

でも、それは使い方の問題だと思います。

従来のシェルスクリプトで解決できる部分（ファイル操作、データ抽出、コマンド実行など）は、そのまま使えばOKです。LLMには「判断」「要約」「分類」など、シェルスクリプトでは難しい部分だけを担当させます。

例えば:

1
2
3
4
5

# 決定論的な部分: テスト実行とログ抽出
./run_tests.sh 2>&1 | tee test.log

# 非決定論的な部分: LLMがログを要約
cat test.log | ./summarize.md > summary.txt

要約の表現は毎回変わるかもしれませんが、**「失敗した3件のテストを特定して報告する」**という目的は達成できます。

インストールと基本的な使い方

前提条件

• Claude Code がインストール済みであること
• macOSまたはLinux環境

セットアップ

1
2
3

git clone https://github.com/andisearch/claude-switcher.git
cd claude-switcher
./setup.sh

/usr/local/bin にコマンドがインストールされ、~/.claude-switcher/ に設定ファイルが作成されます。

アップデートする場合は、git pull して ./setup.sh を再実行します:

1
2
3

cd claude-switcher
git pull
./setup.sh

最初のExecutable Markdown

シンプルな例から始めます:

1
2
3
4
5
6
7

cat > analyze.md << 'EOF'
#!/usr/bin/env claude-run
Analyze this codebase and summarize the architecture in 3 bullet points.
EOF

chmod +x analyze.md
./analyze.md

これで、カレントディレクトリのコードベースを分析してくれます。

パイプラインで使う

標準入力からデータを受け取る例:

1
2
3
4
5
6
7

cat > summarize-commits.md << 'EOF'
#!/usr/bin/env claude-run
Summarize the following git commits in plain Japanese, focusing on what changed and why.
EOF

chmod +x summarize-commits.md
git log --oneline -10 | ./summarize-commits.md

Git履歴を流し込むと、日本語で要約してくれます。

パーミッション管理

デフォルトでは、Executable Markdown（実行可能なMarkdown）はコード実行権限を持ちません。これは安全のための設計です。

コード実行が必要な場合は、明示的にフラグで許可します:

1
2

#!/usr/bin/env -S claude-run --permission-mode bypassPermissions
Run ./test/automation/run_tests.sh and summarize what passed and failed.

--permission-mode bypassPermissions を指定すると、LLMがシェルコマンドを実行できるようになります。shebangで複数の引数を渡す場合、macOSなどでは #!/usr/bin/env -S を使います。

重要: このフラグは信頼できるスクリプトにのみ使用してください。LLMが誤って危険なコマンド（例: rm -rf）を実行するリスクがあります。

プロバイダー切り替え

個人のClaude Code環境と自動化スクリプトを分離したい場合、クラウドプロバイダーのAPI経由で実行できます。

1
2
3
4
5
6
7
8

# AWS Bedrockを使用
claude-run --aws task.md

# Google Vertex AIを使用
claude-run --vertex task.md

# Anthropic APIを使用
claude-run --apikey task.md

設定は ~/.claude-switcher/secrets.sh で行います:

1
2
3
4
5
6
7
8

nano ~/.claude-switcher/secrets.sh

# AWS Bedrock
export AWS_PROFILE="your-profile-name"
export AWS_REGION="us-west-2"

# Anthropic API
export ANTHROPIC_API_KEY="sk-ant-..."

これにより、個人のClaude Codeサブスクリプションのレート制限を気にせず、自動化スクリプトをクラウドで実行できます。

実用例: テスト結果のSlack通知

実際に役立ちそうな例を試してみました。

1. テスト実行スクリプト（通常のbash）

1
2
3
4

#!/bin/bash
# test-runner.sh
pytest tests/ --tb=short > test-output.txt 2>&1
echo $? > test-exit-code.txt

2. 結果を要約するMarkdown

1
2
3
4

#!/usr/bin/env claude-run
Read test-output.txt and test-exit-code.txt.
If exit code is 0, output "✅ All tests passed".
Otherwise, summarize failed tests in Japanese (max 3 lines).

3. パイプラインで繋ぐ

1

./test-runner.sh && ./summarize-test.md | slack-cli post -c dev-alerts

テスト結果をLLMが要約し、Slackに投稿される仕組みです。

注意点

非決定性

同じ入力でも、LLMは毎回異なる出力を返す可能性があります。「完全に同じ結果」を期待するタスクには向いていません。

コスト

API経由で実行する場合、トークン使用料が発生します。大量のデータを処理する前に、コストを見積もることをお勧めします。

セキュリティ

--permission-mode bypassPermissions を使う場合、LLMが生成したコードが実行されます。信頼できない入力データを扱う場合は、DevContainer（開発用コンテナ）など、隔離された環境で実行するべきです。

類似ツール

Hacker Newsのコメントで紹介されていた類似ツール:

• mdflow : Markdown内の変数展開に対応
• Atuin Desktop : YAML形式の「Executable Runbook」
• Runme: Markdownドキュメント内のコードブロックを実行

それぞれ異なるアプローチで「ドキュメントを実行可能にする」試みをしています。

まとめ

claude-switcherの面白さは、「プロンプトがファイルになる」ことだと思います。

• Git管理できる（diffが取れる、履歴が残る）
• チームで共有できる（再利用可能な自動化）
• Unixパイプラインに組み込める（既存ツールと組み合わせ可能）

「curl | bash より読みやすい」という指摘もありました。確かに、Markdownで書かれた指示の方が「何をやるのか」を追いやすいです。

LLMを「コマンド」として扱う発想は、今後のワークフロー自動化で重要になりそうです。興味のある方はぜひ試してみてください。

参考リンク

• claude-switcher - GitHub
• Show HN: Executable Markdown files with Unix pipes - Hacker News
• Claude Code
• Pete Koomen (@koomen) - Executable Markdown の提案元