Claude Code ガイド

Appearance

原文（日本語に翻訳） ​

claude agents に --add-dir、--settings、--mcp-config、--plugin-dir、--permission-mode、--model、--effort、--dangerously-skip-permissions フラグを追加し、ディスパッチされるバックグラウンドセッションを設定できるようにしました

原文（英語） ​

Added --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort, and --dangerously-skip-permissions flags to claude agents to configure dispatched background sessions

概要 ​

Claude Code v2.1.142では、claude agentsコマンドに複数の設定フラグが追加されました。これらのフラグにより、Agent View（エージェントビュー）を開く際に、そこからディスパッチするすべてのバックグラウンドセッションのデフォルト設定を一括で指定できるようになります。たとえば、使用モデルや権限モード、追加ディレクトリ、MCPサーバーなどをAgent Viewの起動時にまとめて設定でき、個々のセッションごとに設定し直す手間を省けます。なお、これらのフラグはClaude Code v2.1.142以降でのみ有効で、旧バージョンではエラーになります。

基本的な使い方 ​

claude agents に続けてフラグを指定するだけで、Agent Viewとそこからディスパッチされるバックグラウンドセッションの設定を変更できます。

bash
# モデルと権限モードを指定してAgent Viewを開く
claude agents --model opus --permission-mode auto

# 努力レベルを高めに設定して開く
claude agents --effort high

# 複数のフラグを組み合わせた例
claude agents --permission-mode plan --model opus --effort high

指定したデフォルト設定は、Agent ViewのDispatch入力欄の下のフッターに表示されます。

実践例 ​

### 特定のモデルと努力レベルを使ってCI/CD向けセッションを一括設定する ​

品質重視の作業（コードレビューや複雑なリファクタリング）では、より高性能なモデルと高い努力レベルで複数のエージェントを並列実行したいケースがあります。

bash
# Opusモデル・高努力レベルで全セッションを起動
claude agents --model opus --effort high

# Agent ViewのDispatch入力で順にタスクを入力すると、
# すべてのセッションが同じモデルと努力レベルで実行される

各バックグラウンドセッションごとに claude --bg --model opus --effort high を実行する代わりに、Agent View起動時に一度だけ指定すれば済みます。

### 追加ディレクトリを含めてプロジェクトをまたいだ作業をする ​

複数のリポジトリやディレクトリにまたがる作業（モノレポや共有ライブラリの参照など）では、--add-dir でファイルアクセスを追加ディレクトリに拡張できます。

bash
# 共有ライブラリと別リポジトリへのアクセスを付与してAgent Viewを開く
claude agents --add-dir ../shared-lib --add-dir ../api-specs

# 複数パスを指定する場合は --add-dir を繰り返す
# （スペース区切りでの複数指定は claude agents では非対応）
claude agents --add-dir ../frontend --add-dir ../backend --add-dir ../infra

注意：--add-dir はファイルへのアクセス権を付与しますが、.claude/ 内のサブエージェント定義や設定ファイルの自動探索は行いません。

### カスタム設定ファイルで本番環境向けの権限を制限する ​

本番環境に近い厳格な設定でエージェントを動作させたい場合、専用の設定ファイルを用意して --settings で適用できます。

bash
# カスタム設定ファイルを作成
cat > ci-settings.json <<'EOF'
{
  "permissions": {
    "allow": ["Read", "Bash(git log *)", "Bash(git diff *)"],
    "deny": ["Bash(rm *)", "Bash(git push *)"]
  },
  "defaultMode": "plan"
}
EOF

# 設定ファイルを適用してAgent Viewを開く
claude agents --settings ./ci-settings.json

# インラインJSONでの指定も可能
claude agents --settings '{"defaultMode": "acceptEdits"}'

--settings で指定した値は、既存の settings.json の同キーを上書きします。指定しないキーはファイルベースの設定値を引き継ぎます。

### MCPサーバーをバックグラウンドセッションに提供する ​

ツールの実行やデータ取得にMCP（Model Context Protocol）サーバーを使っている場合、--mcp-config で設定ファイルを読み込み、ディスパッチされる全セッションにMCPツールを提供できます。

bash
# MCPサーバー設定ファイルを作成
cat > mcp-config.json <<'EOF'
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}
EOF

# MCPサーバーを読み込んでAgent Viewを開く
claude agents --mcp-config ./mcp-config.json

# MCPサーバーのみ使用し、他のMCP設定を無視する場合
claude agents --mcp-config ./mcp-config.json --strict-mcp-config

### ローカルプラグインを全セッションで有効にする ​

独自のプラグインや実験中のプラグインを全バックグラウンドセッションで使いたい場合、--plugin-dir でプラグインのディレクトリを指定します。

bash
# ローカルプラグインを読み込んでAgent Viewを開く
claude agents --plugin-dir ./my-custom-plugin

# 複数プラグインを読み込む場合は --plugin-dir を繰り返す
claude agents --plugin-dir ./plugin-a --plugin-dir ./plugin-b.zip

# 設定ファイルやMCPサーバーと組み合わせた例
claude agents \
  --plugin-dir ./my-plugin \
  --mcp-config ./mcp-config.json \
  --settings ./agent-settings.json \
  --add-dir ../shared-lib

### 権限プロンプトをスキップして完全自動化パイプラインを構築する ​

CI環境やスクリプトから完全自動でエージェントを動かす場合、--dangerously-skip-permissions で権限プロンプトをすべてスキップできます。

bash
# 全権限プロンプトをスキップ（十分に検討した上で使用）
claude agents --dangerously-skip-permissions

# 自動化スクリプトからバックグラウンドセッションを起動する例
claude --bg --dangerously-skip-permissions "テストスイートを実行して失敗を修正する"

### プランモードで安全にコード変更を事前確認する ​

エージェントに変更を加えさせる前に計画だけ立てさせたい場合、--permission-mode plan を使うと読み取り専用のリサーチフェーズのみが実行されます。

bash
# 全セッションをプランモードで開始する
claude agents --permission-mode plan --model sonnet

# セッションをアタッチして計画を確認後、/acceptEdits 等で許可する

注意点 ​

  • バージョン要件：--permission-mode、--model、--effort フラグは Claude Code v2.1.142 以降でのみ使用可能です。旧バージョンでは unknown option エラーになります。
  • フラグの適用範囲：指定したフラグはAgent View自体と、そこからディスパッチされた全セッションに適用されます。既存のバックグラウンドセッションには影響しません。
  • --add-dir の複数指定：スペース区切りでの複数パス指定（例：--add-dir a b c）は claude agents では非対応です。複数指定する場合はフラグを繰り返してください。
  • bypassPermissions / auto モードの制限：--permission-mode bypassPermissions または --permission-mode auto を使用するには、事前に claude をインタラクティブモードで実行してそのモードに一度同意している必要があります。未承認の状態では拒否されます。
  • --dangerously-skip-permissions の危険性：このフラグを使うと、.git、.claude、.vscode などへの書き込みを含む全操作の権限確認がスキップされます。信頼できる環境・タスクでのみ使用してください。
  • セッション固有のオーバーライド：claude agents で設定したデフォルト値は、個々のセッションをアタッチして /model を実行したり、サブエージェントのフロントマターに model を設定したりすることで上書きできます。
  • 設定の優先順位：--settings で指定した値はファイルベースの settings.json より優先されますが、セッション内のコマンド（/model など）はそれより更に優先されます。

関連情報 ​