agent-cli入門 — 音声・テキスト補正・git worktree並列開発を1つのCLIで動かす

はじめに

Claude Codeで複数の機能を並列に進めたいとき、git worktree add -b feature-x ../repo-worktrees/feature-x origin/main のようなコマンドを毎回手打ちしていないだろうか。ブランチ作成・作業ディレクトリの命名・.env のコピー・コーディングエージェントの起動までを1コマンドでまとめてくれるCLIがあれば、この手間はまるごと消える。

pipで導入できる agent-cli は、この git worktree 並列開発ワークフローに加えて、音声認識・音声合成・テキスト補正・RAG・長期記憶までを1つのCLIにまとめたPython製ツール群だと謳っている。実際にインストールし、並列開発サブコマンド dev とテキスト補正サブコマンド autocorrect を動かしてみたところ、便利な自動検出機能と、ヘルプの説明と食い違う実装の穴の両方に行き当たった。

この記事で学べること

• pip install agent-cli でのセットアップ手順
• dev（git worktree並列開発）サブコマンドの実際の挙動
• autocorrect（LLMテキスト補正）を Gemini API 経由で動かした結果
• 実機で踏んだ落とし穴とその回避策

対象読者

• Claude Code / Codex などのコーディングエージェントを git worktree で並列運用したい人
• ローカル完結のAIツール群を1つのCLIにまとめたい人

前提環境

• OS: Linux（クラウドの Claude Code on the web セッション内サンドボックス）
• Python: 3.11.15
• agent-cli: 0.102.0（pip install agent-cli で導入）
• LLMバックエンド: Gemini API（GEMINI_API_KEY 環境変数を自動参照）

TL;DR

• agent-cliは音声認識/TTS/テキスト補正/RAG/長期記憶/git worktree並列開発を1つのCLIにまとめたPythonツール（MITライセンス・223 stars）
• dev doctor / dev agents は実行中のコーディングエージェントを自動検出でき、このセッションでも claude (current) として正しく検出された
• dev new は origin リモートが無く、ローカルブランチが master のみのリポジトリ で fatal: invalid reference: main エラーになる。ヘルプの「origin/main または origin/master にフォールバックする」という説明と、実際の挙動が食い違っていた
• 回避策は --from master を明示するか、ブランチを main にリネームすること
• autocorrect は Gemini API 経由で実際に文法・スペルミスを修正できた

agent-cliとは

GitHubリポジトリ（MITライセンス・223 stars・2026年7月時点）によると、agent-cliは以下のサブコマンド群を1バイナリに束ねている。

カテゴリ	サブコマンド	内容
音声	transcribe / transcribe-live / assistant	マイク入力の文字起こし・ウェイクワード検出
テキスト	autocorrect / speak	LLMによる文法補正・テキスト読み上げ
サーバー	rag-proxy / memory / server	ドキュメント対話・長期記憶・ASR/TTSサーバー
開発	dev	git worktreeを使った並列開発環境の管理

LLM / ASR / TTS のバックエンドはそれぞれ Ollama（ローカル）・OpenAI・Gemini から選べる設計で、ローカル完結を基本にしつつクラウドAPIにも切り替えられる。

インストール

pip install agent-cli

依存関係の解決だけで完了し、追加のシステムライブラリ導入なしにCLIが使えるようになった（音声系機能を使う場合はLinuxで PortAudio が別途必要になる）。

agent-cli --version

┌────────────────────┬────────────────────────────────────────────────────┐
│ agent-cli version  │ 0.102.0                                            │
│ agent-cli location │ /usr/local/lib/python3.11/dist-packages/agent_cli  │
│ Python version     │ 3.11.15 (main, Mar  3 2026, 09:26:23) [GCC 13.3.0] │
│ Python executable  │ /usr/bin/python3                                   │
└────────────────────┴────────────────────────────────────────────────────┘

dev doctor / dev agents — 実行中のエージェントを自動検出する

dev サブコマンドは git worktree の作成・一覧・削除に加えて、対応するコーディングエージェント（Claude / Codex / Gemini CLI / Aider / GitHub Copilot CLI / Continue / OpenCode / Cursor）とエディタ・ターミナルマルチプレクサの導入状況を検出する。隔離した検証用リポジトリで実行したところ、次のように出力された。

$ agent-cli dev doctor

AI Coding Agents:
✓ claude (current)
  ○ codex (not installed)
  ○ gemini (not installed)
  ○ aider (not installed)
  ○ copilot (not installed)
  ○ continue (not installed)
  ○ opencode (not installed)
  ○ cursor-agent (not installed)

このセッション自体が Claude Code 上で動いているため、claude (current) として実際に検出された。単に環境変数を見ているのではなく、実行中のプロセスからエージェントを判定している設計だとわかる。

dev new でworktreeを作る（成功パターン）

ローカルにブランチ main があるリポジトリでは、以下のように1コマンドでworktreeが作成できた。

$ agent-cli dev new feature-z
→ Creating worktree for branch 'feature-z'...
→ Running: git worktree add -b feature-z ../demo-repo-worktrees/feature-z main
✓ Created worktree at .../demo-repo-worktrees/feature-z

╭────────────────────────────────── Success ───────────────────────────────────╮
│ Dev environment created: .../demo-repo-worktrees/feature-z                   │
│ Branch: feature-z                                                            │
╰────────────────────────────────────────────────────────────────────────────╯

dev list / dev status を叩けば、作成済みworktreeの一覧とブランチごとの差分・コミット状況を一目で確認できる。

ハマりポイント: originが無くmasterだけのリポジトリで失敗する

agent-cli dev new --help には次の説明がある。

--from ... Defaults to origin/main or origin/master

「originにmainが無ければmasterにフォールバックする」という記述だが、originリモート自体が存在せず、ローカルブランチが master だけ という構成（git init 直後にコミットしただけのリポジトリでよくある状態）で試すと、次のように失敗した。

$ agent-cli dev new feature-x
→ Creating worktree for branch 'feature-x'...
→ Running: git worktree add -b feature-x ../demo-repo-worktrees/feature-x main
Error: fatal: invalid reference: main

実行されたコマンドを見ると、origin/main でも origin/master でもなく、リテラルの main がそのまま渡っている。ローカルの master ブランチへのフォールバックは行われず、存在しない main を指定してgitがエラーになっていた。

同じリポジトリでブランチ名を main にリネームするだけで成功することは確認済みで（前節の成功パターンがまさにこの状態）、問題は「origin無し・ローカルmasterのみ」という特定の組み合わせに限られる。

回避策

--from でベースブランチを明示すれば、この問題は避けられる。

$ agent-cli dev new feature-w --from master
→ Creating worktree for branch 'feature-w'...
→ Running: git worktree add -b feature-w ../demo-repo2-worktrees/feature-w 534de07...
✓ Created worktree at .../demo-repo2-worktrees/feature-w

--from master を渡すと master の実コミットハッシュに解決され、正しくworktreeが作成された。origin無しのローカルリポジトリで dev new を使う場合は、ブランチ名を main に揃えるか、--from でベースブランチを明示するのが安全になる。

autocorrect を実際に動かす

autocorrect はクリップボードまたは引数のテキストをLLMに渡し、文法・スペル・句読点だけを直して返す。今回は GEMINI_API_KEY を使い、--llm-provider gemini で実行した。

$ agent-cli autocorrect "this is a incorect sentance with mispelled wrods" --llm-provider gemini --json
Auto-installing missing extras: llm
Installation complete!
Re-running with installed extras...
{"corrected_text": "This is an incorrect sentence with misspelled words."}

初回実行時に llm エクストラが自動インストールされ、再実行された。誤字だらけの入力文が、意味やトーンを変えずに正しい英文へ修正されている。クリップボード連携をオフにする --json を付ければ、スクリプトからの呼び出しにもそのまま使える。

著者視点の発見ポイント

ヘルプの説明だけを読んで「origin/main か origin/master に自動フォールバックしてくれる」と信じていたら、originを持たないローカル専用リポジトリでこのエラーに気づけなかったはずだ。実際に空のリポジトリを2パターン（ブランチ名 main／master）用意して試したことで、フォールバックが効くのは「origin経由でmain/masterを解決できる場合」に限られ、ローカル限定のリポジトリでは効かないという境界線がはっきりした。

もう一つ印象的だったのは dev doctor のエージェント検出だ。単純な環境変数チェックではなく、実行中のプロセス環境からエージェントの種類を割り出しており、claude / codex / gemini などマルチエージェントの共存を前提に設計されていることが伝わってきた。

まとめ

• agent-cliは音声・テキスト補正・git worktree並列開発を1つのCLIにまとめたツールで、dev サブコマンドはClaude Codeを含む複数のコーディングエージェントを自動検出する
• dev new はorigin無し・ローカルmasterのみのリポジトリで fatal: invalid reference: main になる。--from master の明示、またはブランチを main に揃えることで回避できる
• autocorrect はGemini APIバックエンドで実際に文法修正が機能した

git worktreeでの並列エージェント運用を検討しているなら、まずは自分のリポジトリのデフォルトブランチ名を確認してから dev new を試すのがよさそうだ。

参考リンク

• agent-cli (GitHub) — ソースコード・スター数・ライセンス
• agent-cli (PyPI) — インストール方法・機能一覧