CLIコマンド¶

pyfltrのサブコマンド・主要オプション・出力形式・コーディングエージェント連携を扱うリファレンス。導入手順ははじめにを参照。

サブコマンド¶

pyfltrはサブコマンドで動作モードを指定する。

pyfltr <subcommand> [files and/or directories ...]

サブコマンド: ci¶

pyfltr ci [files and/or directories ...]

全チェック実行。CI環境やコミット前の検証に適する。

終了コード:

0: Formattersによるファイル変更が無く、かつLinters/Testersでのエラーも無い場合
1: 上記以外の場合

サブコマンド: run¶

pyfltr run [files and/or directories ...]

全チェック実行。 Formattersによるファイル変更があってもLinters/Testersでのエラー無しなら終了コードは0になる。ローカルでの全チェック実行に適する。

サブコマンド: run-for-agent¶

pyfltr run-for-agent [files and/or directories ...]

runと同じ動作で出力形式の既定値をjsonlに切り替えたサブコマンド。コーディングエージェントから呼び出す際に用いる。 pyfltr run --output-format=jsonlと多くの場合は等価だが、サブコマンド既定値であるため PYFLTR_OUTPUT_FORMAT=textでtextへ戻すことができる点が異なる。

出力形式の詳細はjsonl形式の使い方を参照。

サブコマンド: fast¶

pyfltr fast [files and/or directories ...]

pre-commitフックなどで実行しても作業に支障が出にくい高速なコマンドだけを実行する軽量チェック。 mypy / pylint / pytestなど起動やファイルあたりの処理に時間がかかるコマンドは除外される。 Formattersによるファイル変更があっても終了コードは0になる。

既定で含まれるコマンドは以下。

Formatters: ruff-format prettier uv-sort shfmt cargo-fmt dotnet-format
Linters: ec shellcheck typos actionlint ruff-check ty markdownlint textlint biome oxlint cargo-clippy
その他: pre-commit（.pre-commit-config.yamlのhookを統合実行）

含まれるコマンドは各コマンドの{command}-fast設定で制御できる（設定を参照）。

サブコマンド: config¶

pyfltr config <action> [options]

設定ファイルをCLIから操作する（pnpm/npm config互換の体系）。 --globalなしはカレントディレクトリのpyproject.toml、--global付きはグローバル設定ファイル（~/.config/pyfltr/config.tomlなど）が対象となる。

config get¶

pyfltr config get <key> [--global]

指定キーの現在値を1行出力する。ファイルに書かれていなければデフォルト値を返す。未知のキーはエラー終了（終了コード1）。

pyfltr config get archive-max-age-days
pyfltr config get archive-max-age-days --global

config set¶

pyfltr config set <key> <value> [--global]

指定キーに値を書き込む。値の文字列はキーのデフォルト値の型に応じて変換される。

bool: true / false / 1 / 0
int: 整数表記
str: そのまま文字列として設定する
list[str]: カンマ区切りで分割してリスト化する（例: "foo,bar" → ["foo", "bar"]）
dict: CLI非対応（エラー終了）

pyfltr config set archive-max-age-days 30 --global
pyfltr config set preset latest

--global指定時、グローバル設定ファイルが存在しなければディレクトリを含めて自動作成する。 project側（--globalなし）でpyproject.tomlが存在しない場合はエラー終了する。未知のキーはエラー終了（終了コード1）。

set時の警告条件:

archive/cache系のキー（archive / archive-max-runs等）をproject側にsetした場合: globalで集約することを推奨する旨の警告を出力する。
archive/cache以外のキーをglobal側にsetした場合: 通常はproject側が優先されるため、globalで設定しても上書きされる旨の警告を出力する。

config delete¶

pyfltr config delete <key> [--global]

設定ファイルから指定キーを削除する。該当キーがなければ正常終了（何もしない）。対象ファイルが存在しない場合は「削除対象がありません」と表示して正常終了する。未知のキーはエラー終了（終了コード1）。

config list¶

pyfltr config list [--global] [--all] [--output-format text|json|jsonl]

設定ファイルに書かれているキーと値の一覧を表示する。 --all未指定時は明示された値のみを挿入順で表示する。 --all指定時はデフォルト値のままのキーも含めて全件をキー昇順で表示し、既定値か明示値かを区別する。

--all未指定時の出力形式は次の通り。

text（既定）: key = value形式の行出力
json: {"values": {...}}の単発出力
jsonl: 1件1行の{"key": ..., "value": ...}ストリーム

--all指定時は各出力形式に既定値か明示値かの区別を追加する。

text: 既定値の行末に(default)を付加する（明示値には何も付かない）
json: {"values": {key: {"value": ..., "default": bool}, ...}}の二段構造
jsonl: {"key": ..., "value": ..., "default": bool}の1行1レコード

設定項目の一覧とデフォルト値を確認したい場合は、pyfltr config list --allで全件を確認できる。設定項目名の詳細は設定項目一覧を参照。

サブコマンド: list-runs¶

pyfltr list-runs [--limit N] [--output-format text|json|jsonl]

実行アーカイブに保存されたrun一覧を新しい順で表示する。

既定で直近20件（--limitで変更可能）
text: 固定幅テーブル。列はRUN_ID / STARTED_AT / EXIT / FILES / COMMANDS
json: {"runs":[{...}, ...]}の単発出力
jsonl: 1件1行ストリーム（kind: "run"）

アーカイブ未作成の環境では(no runs)を出力し、終了コードは0。

サブコマンド: show-run¶

pyfltr show-run <run_id> [--commands NAME[,NAME...]] [--output] [--output-format text|json|jsonl]

指定runの詳細を表示する。

<run_id>: ULID完全一致のほか、先頭一意な前方一致とlatestエイリアスを受け付ける。前方一致で複数該当した場合は曖昧エラー（終了コード1）
既定: meta（run_id・started_at・finished_at・exit_code・files・commands）とツール別サマリ（status / has_error / diagnostics）を表示
--commands NAME[,NAME...]: 指定ツールのtool.jsonとdiagnostics.jsonl全件を表示。カンマ区切りで複数指定可（入力順で並ぶ）
--commands NAME --output: 指定ツールの生出力（output.log）全文を表示（単一指定のみ）
--output-format: text（行形式 key: value）・json（単発dict）・jsonl （kind: "meta" / "command" / "diagnostic" / "output" 種別の1行1レコード）

存在しないrun_id・--commands指定時は終了コード1で標準エラーにメッセージを出力する。

同じツールがfixステージと通常ステージの両方で実行された場合、アーカイブの保存キーはツール名固定のため通常ステージ側の結果で上書きされる（show-runで参照できるのは各ツールの最終保存結果のみ）。

サブコマンド: grep¶

pyfltr grep <pattern> [paths...]

正規表現でファイルを横断検索する。 pyfltr設定のexclude/extend-exclude/respect-gitignoreを尊重するため、 node_modulesやbuild配下のノイズが混入しない。

例:

pyfltr grep "TODO" src/
pyfltr grep -i "deprecated" .
pyfltr grep -F "exact_string" --output-format=jsonl docs/

詳細は検索と置換を参照。

サブコマンド: replace¶

pyfltr replace <pattern> <replacement> [paths...]

正規表現で横断置換する。書き込みが既定動作で、--dry-runで試行できる。実行アーカイブに履歴を保存し、--undoで取り消せる。

例:

# 試行（書き込みなし）
pyfltr replace --dry-run "old_name" "new_name" src/
# 実書き込み（履歴に保存される）
pyfltr replace "old_name" "new_name" src/
# 直前のreplaceを取り消す
pyfltr replace --undo <replace_id>

詳細は検索と置換を参照。

サブコマンド: mcp¶

pyfltr mcp

stdioトランスポートでMCPサーバーを起動する。追加オプションはなく、起動後はstdin/stdoutをJSON-RPCフレームが専有する。 MCPクライアントがstdinを閉じた時点でサーバーが終了する。

提供するMCPツール（8件）:

ツール名	対応CLI	説明
`list_runs`	`pyfltr list-runs`	run一覧を新しい順で返す。`limit`で件数制御（既定20件）
`show_run`	`pyfltr show-run <run_id>`	指定runのmetaとツール別サマリを返す。前方一致・`latest`エイリアス可
`show_run_diagnostics`	`pyfltr show-run <run_id> --commands=<name>`	指定runのtool.jsonとdiagnostics全件を返す（複数指定可）
`show_run_output`	`pyfltr show-run <run_id> --commands=<name> --output`	指定runのoutput.log全文を返す（単一指定のみ）
`run_for_agent`	`pyfltr run-for-agent`	lint/format/testを実行しrun_id・失敗ツール名・retry_commands等を返す
`grep`	`pyfltr grep`	ファイル横断の正規表現検索（pyfltr exclude/.gitignore尊重）
`replace`	`pyfltr replace`	横断置換。`dry_run`の既定値は`True`（CLI既定の`False`と異なりLLM暴発防止）
`replace_undo`	`pyfltr replace --undo`	過去のreplaceを取り消す

コーディングエージェント側へのMCPサーバー登録例（JSON形式で設定ファイルに記載する場合）:

{
  "mcpServers": {
    "pyfltr": {
      "command": "uvx",
      "args": ["pyfltr", "mcp"]
    }
  }
}

エージェント常駐起動では、独立venvで動くuvxの方がプロジェクトのpyproject.toml解釈やcwd依存の影響を受けない。

Claude Codeから登録する場合はclaude mcp addコマンドを利用できる:

claude mcp add pyfltr -- uvx pyfltr mcp

サブコマンド: command-info¶

pyfltr command-info <tool> [--output-format text|json|jsonl] [--check]

対象ツールの起動方式（runner種別・実行ファイルパス・最終コマンドライン）の解決結果を副作用無しで表示する。 pyproject.tomlの{command}-runner設定やpython-runner / js-runner / bin-runnerの影響を実環境で確認する場合に使う。

出力はセクション見出し（## 実行コマンド / ## ランナー解決 / ## mise診断 / ## 設定 / ## 環境変数）で関連項目をまとめる。情報が無いセクションは省略される。

mise設定（プロジェクトmise.tomlまたはグローバル設定）にrust記述がある場合の出力例:

$ pyfltr command-info cargo-fmt
# cargo-fmt

## 実行コマンド

commandline: mise exec -- cargo fmt
executable: mise
executable_resolved: /home/user/.local/bin/mise

## ランナー解決

runner: bin-runner (default)
effective_runner: mise
mise_tool_spec_omitted: True

## mise診断

mise_active_tool_key: rust
mise_active_tools.status: ok
mise_active_tools.active_keys: rust

## 設定

enabled: True
configured_args: fmt
version: latest

tool specを省略したmise exec -- cargo fmt形になり、mise設定の解決済み内容（バージョン固定・components等）が反映される。 mise設定にrust記述が無い場合はmise exec rust@latest -- cargo fmt形になる。

{command}-fix-argsが定義されているコマンド（textlint・markdownlintなど）では、 commandline (fix step):とcommandline (check step):を併記する。 fix段とcheck段の二度実行が異なる引数を必要とするためである。

$ pyfltr command-info textlint
# textlint

## 実行コマンド

commandline (fix step): pnpx --package textlint --package ... textlint --fix
commandline (check step): pnpx --package textlint --package ... textlint --format json
...

textlintの場合、fix段では@textlint/fixer-formatterがcompactをサポートしない。このためユーザーが指定した--formatペアを除去した形が表示される。 check段ではtextlint-json設定（既定true）により出力フォーマット指定--format=jsonが注入される。

主要なオプション。

--output-format=text|json|jsonl: 出力形式を切り替える（既定text）。未指定時は環境変数PYFLTR_OUTPUT_FORMATを、AI_AGENT / CODEX_CI / CLAUDECODE / CURSOR_AGENTのいずれかが設定されていればjsonlを採用する
--check: mise経由ツールに対してmise exec --versionでの事前チェックを行う（mise install / mise trustが発生する場合があるため、既定では行わない）

未知のコマンド名や{command}-runner = "mise"を未登録ツールに指定した場合などは終了コード1で失敗する。

サブコマンド: generate-shell-completion¶

pyfltr generate-shell-completion bash
pyfltr generate-shell-completion powershell

シェル補完スクリプトを標準出力に出力する。引数にシェル種別（bashまたはpowershell）を指定する。

bashでの設定例:

eval "$(pyfltr generate-shell-completion bash)"

PowerShellでの設定例:

pyfltr generate-shell-completion powershell | Out-String | Invoke-Expression

永続化する場合はプロファイルに上記を追記。

`[files and/or directories ...]`¶

対象を指定しなかった場合は、カレントディレクトリ(.)を指定した場合と同じ扱いとなる。

指定したファイルやディレクトリの配下のうち、各コマンドのtargetsパターンに一致するファイルのみ処理される。一例を以下に示す。

Python系ツール: *.py
textlint / markdownlint: *.md
pytest: *_test.py

外部パス指定時の挙動¶

起点cwd（--work-dir適用後の作業ディレクトリ）配下にない絶対パスを「外部パス」と呼ぶ。ツールの性質に応じて以下の3分類で扱う。

--config明示注入: markdownlint ・ textlint
外部パス除外＋警告: pre-commit ・ pytest ・ vitest ・ cargo-test ・ dotnet-test ・ gitleaks ・ semgrep
既定（素通し）: 上記以外。各ツールの設定探索仕様に委ねる

注入対象では起点cwd直下の設定ファイル（.textlintrc.yaml ・ .markdownlint-cli2.yaml 等）を --config <絶対パス> 形式で明示注入する。内部パスのみの実行でも一律で注入経路を通すため、外部パス指定時に暗黙のcwd探索仕様（markdownlint-cli2が対象ファイルとCWDの共通親から設定探索する仕様等）には依存しない。起点cwd直下に設定ファイルが見つからないときは注入をスキップし、ツールの既定動作で処理する。利用者が {command}-args ・ {command}-extend-args ・ CLI --{command}-args のいずれかで --config を指定している場合は注入をスキップする。

除外対象では対象ファイル展開後の最終リストから外部パスのみを除いて内部パスは対象として実行し、除外時は1ファイルにつき1件の警告を発行する。

pyfltrプロジェクト外にある計画ファイルを検査する場合に、 pyfltrプロジェクトの .textlintrc.yaml ・ .markdownlint-cli2.yaml 設定を適用するには次のように起動する。

pyfltr run-for-agent --work-dir=/path/to/pyfltr ~/.claude/plans/example.md

上記の分類に従い、markdownlint ・ textlint には --config 経由で設定が注入され、 pre-commit などの除外対象ツールでは外部パスがスキップされて警告が発行される。

`fast` / `run` / `run-for-agent` / `ci`の動作の違いと自動修正（fixステージ）¶

各サブコマンドの主な違いを以下に示す（軽い順）。

項目	`fast`	`run`	`run-for-agent`	`ci`
対象コマンド	`{command}-fast = true`のツールのみ	有効な全ツール	有効な全ツール	有効な全ツール
fixステージ（自動修正）	有効	有効	有効	無効
Formatterによる変更時の終了コード	`0`（成功扱い）	`0`（成功扱い）	`0`（成功扱い）	`1`（失敗扱い）
Linters / Testersのエラー時の終了コード	`1`	`1`	`1`	`1`
既定の出力形式	`text`	`text`	`jsonl`	`text`
主な用途	pre-commitフック等	ローカルで全チェック	コーディングエージェント呼び出し	CI・コミット前

fast / run / run-for-agent サブコマンドは、formatter段の前にfixステージを内蔵する。

fixステージでは{command}-fix-argsが定義された有効なlinterを--fix付きで順次実行する。対象ツールはruff-check / textlint / markdownlint / eslint / biome / cargo-clippyなど。 ruff check --fix → ruff format → ruff checkのような2段階処理をpyfltrのパイプライン全体で実現する位置づけ。

カスタムコマンドでもpyproject.tomlの[tool.pyfltr.custom-commands.<name>]にfix-args = [...]を定義すれば fixステージの対象になる。

特定のツールのみ実行¶

pyfltr ci --commands=ruff-check,markdownlint [files and/or directories ...]

カンマ区切りで実行するツールだけ指定する。全サブコマンドで使用可能。 --commandsは複数回指定も可能で、カンマ区切りと併用できる。例えば--commands=mypy --commands=pyright,ruff-checkは--commands=mypy,pyright,ruff-checkと同じになる。

以下のエイリアスも使用可能。(例: --commands=format)

format: pre-commit ruff-format prettier uv-sort shfmt cargo-fmt dotnet-format
lint:
- Python系: ruff-check mypy pylint pyright ty
- Markdown系: markdownlint textlint
- JS/TS系: eslint biome oxlint tsc
- Rust系: cargo-clippy cargo-check cargo-deny
- .NET系: dotnet-build
- 監査系: uv-audit pnpm-audit npm-audit yarn-audit
- その他: ec shellcheck typos actionlint
test: pytest vitest cargo-test dotnet-test
audit: uv-audit pnpm-audit npm-audit yarn-audit
fast: per-commandの{cmd}-fastフラグがtrueのコマンド

※ pyproject.tomlの[tool.pyfltr]で無効になっているコマンドは無視される。

一時的に有効・無効を切り替えたい場合は--enable・--disableを使う。

# 通常無効化しているsemgrepを1回だけ実行する
pyfltr run --enable=semgrep --commands=semgrep

# 通常有効なmypyを1回だけ抑止する
pyfltr run --disable=mypy

--enable・--disableは--commandsと同じくカンマ区切り・複数回指定を併用できる。同一コマンドを両方に指定した場合は--enableが優先される。永続的に有効・無効を切り替える場合はpyfltr config setを使う。

UI¶

ターミナル上で実行すると、TextualベースのTUIが自動的に有効になる。

Summaryタブ: 各コマンドのステータス・エラー数・経過時間をリアルタイム表示
Errorsタブ: エラー発生時のみ出現し、全コマンドのエラー箇所をファイル:行番号形式で一覧表示
各コマンドタブ: コマンドの出力をリアルタイム表示

Errorsタブのエラー一覧はファイル:行番号: [コマンド名] メッセージ形式で、 VSCodeのターミナルからクリックして該当箇所にジャンプできる。

--ui: UIを強制的に有効化する（非対話端末など自動的にUIが無効になる環境でも起動する）
--no-ui: UIを無効化し、出力を直接ターミナルに表示（エラー一覧の後にサマリーを表示）
--stream: 非TUIモード時に各コマンドの完了時点で即時出力する（既定は全コマンド完了後にまとめて出力）
--no-exclude: exclude/extend-excludeパターンによるファイル除外を無効化する
--no-gitignore: .gitignoreによるファイル除外を無効化する
--no-archive: 実行アーカイブ（ユーザーキャッシュ配下への全実行の保存）を無効化する
--no-cache: ファイルhashキャッシュ（対象ファイル未変更時の再実行スキップ）を無効化する
--fail-fast: 1ツールでもエラーが発生した時点で残りのジョブを打ち切る（起動済みサブプロセスにはterminate()を送り、未開始ジョブはskippedとして扱われる）
--changed-since <REF>: gitの任意のref（ブランチ・タグ・コミットハッシュ・HEADなど）からの変更ファイルのみを対象とする。 git diff --name-only <REF>で取得したコミット差分・trackedファイルの作業ツリー差分・staged差分の和集合と展開済みファイル一覧の交差が対象となり、untrackedの新規ファイルは対象外。 gitが不在またはrefが存在しない場合は警告を出力して全体実行へフォールバックする。 --only-failedと併用した場合は--changed-sinceフィルタを先に適用してから--only-failedフィルタを適用する
--only-failed: 直前runの実行アーカイブから失敗ツール・失敗ファイルを抽出し、ツール別にその組み合わせだけを再実行する。直前runが無い・失敗ツールが無い・指定targetsとの交差が空の場合はメッセージを出力してrc=0で成功終了する。診断ファイルが取得できないツール（pytest等のpass-filenames=False系）は既定ファイル展開にフォールバックして全体再実行する。--no-archiveとは独立に働く（参照するのは過去runのアーカイブ）
--from-run <RUN_ID>: --only-failedの参照対象runを明示指定する（前方一致・latest対応）。未指定時は直前runを自動選択。--only-failedとの併用が前提で、単独指定はargparseエラーで拒否する。指定した<RUN_ID>が存在しない場合は警告を出力してrc=0で早期終了する
--ci: CI環境向け（--no-shuffle --no-ui 相当）
-j N / --jobs N: linters/testersの最大並列数を指定（既定: 4、pyproject.tomlでも設定可能）
--verbose: デバッグレベルのログを出力する
--keep-ui: TUI終了後にTextual画面を保持する（ログ確認用）
--work-dir DIR: pyfltrの作業ディレクトリを指定する（既定はカレントディレクトリ）

TUI実行中にCtrl+Cを1秒以内に2回続けて押すと協調中断モードへ移行する。実行中のサブプロセスを終了させ、完了済みツールの結果と中断された残りツール一覧をsummaryへ反映したうえで終了コード130（128 + SIGINT）を返す。中断時はwarnings欄に次の形式の1行が追加される。

[pyfltr] Ctrl+C により中断しました。中断されたツール: <ツール名の一覧>

協調中断モードでさらにCtrl+Cを2回続けて押すと、後始末を待たず強制終了（終了コード130）となる。

その他のオプションは pyfltr --help を参照。

出力形式¶

--output-formatで出力形式を切り替えられる。

値	用途	動作
`text`	既定。人間向け・従来互換	stdoutに進捗・詳細・summaryをまとめて表示
`jsonl`	LLMエージェント向け	stdoutにJSON Lines形式で診断・ツール結果・全体集計を出力。text整形はstderrのWARN以上に抑止
`sarif`	CIツール連携向け	stdoutにSARIF 2.1.0形式のJSONを1件出力。text整形はstderrのINFO
`github-annotations`	GitHub Actions向け	`text`と同じレイアウトをstdoutに出力し、エラー箇所のみGAワークフローコマンド記法で補強
`code-quality`	GitLab CI向け	stdoutにCode Climate JSON issue形式の配列を1件出力。text整形はstderrのINFO

jsonlはツール完了順にストリーミング出力し、最後にwarning/summary行を追加する。 sarifとcode-qualityは全結果集約後に1回だけ出力する。いずれも--output-file未指定時はstdoutを占有し、text整形出力はstderrへ振り分けられる（jsonlのみWARN以上に抑止）。 github-annotationsはstdoutをtext整形が占有するため、stdout占有は起きない。

--output-fileを指定した場合は、構造化データはファイルへ、stdoutには常にtext整形出力が並行して出る。 jsonlはファイル出力時もストリーミング（ツール完了順）で出力する。

text出力サマリー行でstatus=formattedのコマンドは末尾に; no rerun neededを付与する。 formatterによる書き換えはそれ自体が成功扱いで、再実行を要しないことを示す。

jsonl形式の使い方¶

pyfltr run --output-format=jsonl
# 以下はサブコマンド既定値で出力形式を jsonl にする略形（PYFLTR_OUTPUT_FORMAT で text へ戻すことが可能）
pyfltr run-for-agent

--output-format=jsonlかつ--output-file未指定時、stdoutにはJSONLのみを書き、 text整形出力（進捗・詳細・summary）はstderrのWARN以上に抑止される。 TUIや--stream、--uiも暗黙に無効化される。

--output-file=pathを指定するとJSONLはファイルへ出力され、stdoutには従来どおりのtext出力が並行して出力される（ローカル実行時も開発者が進捗を把握できる）。

環境変数PYFLTR_OUTPUT_FORMATでも出力形式の既定値を指定できる（値はサブコマンドが受理する出力形式のいずれか）。 CLIオプション--output-formatが指定されている場合は環境変数より優先される。エージェント起動スクリプトなどにPYFLTR_OUTPUT_FORMAT=jsonlを設定しておけば、毎回オプションを明示しなくてもciなど任意のサブコマンドでJSONL出力に切り替えられる。

環境変数AI_AGENT / CODEX_CI / CLAUDECODE / CURSOR_AGENTのいずれかが設定されていれば、 --output-format未指定時の既定値がjsonlになる。コーディングエージェント環境下での自動切り替え用とする。 JSONLヘッダーのformat_sourceには検出した変数名（例: env.CODEX_CI）が記録される。

PYFLTR_OUTPUT_FORMATを明示すれば、エージェント検出環境下やrun-for-agent配下でもtext等へ変更できる（例: PYFLTR_OUTPUT_FORMAT=text pyfltr run-for-agent）。

コーディングエージェント連携¶

コーディングエージェントからpyfltrを呼び出す方法は2種類ある。

直接呼び出し（推奨）¶

エージェントがシェルコマンドを実行できる環境では、pyfltr run-for-agentを直接呼ぶ。 JSONL出力をそのまま読み込むことができる。

MCP経由¶

pyfltr mcpでMCPサーバーを起動すると、コーディングエージェントがrun_for_agentツールとして呼び出せる。 CLIのrun-for-agentとは異なりJSONL出力がstdoutに流れないため、エージェントのMCPクライアントが結果を構造化データとして受け取れる。ただしpyfltr mcp起動後は同一プロセスのstdin/stdoutがJSON-RPCに専有されるため、他のコマンドと組み合わせた場合に出力が混ざる事故に注意する（詳細はトラブルシューティングを参照）。

コーディングエージェントがpyfltr run-for-agentを活用する基本的な流れ:

全体実行でsummaryを確認する
```
pyfltr run-for-agent
```
末尾のsummary行（"kind":"summary"）のcommands_summary.needs_action配下を参照して対応要件数の有無を確認し、問題がなければ完了する。 commands_summary.needs_action配下のfailed / resolution_failedがいずれも0であれば残作業は無く、 commands_summary.no_issues配下の内訳は確認不要。 applied_fixesが非空でもsummary.guidanceに注記が出るが、formatter/fix-stageによる書き換えのみで再実行は不要なため、そのまま完了してよい。
失敗したツール/ファイルだけ再実行する
```
# 失敗ツールを --commands で限定する
pyfltr run-for-agent --commands=mypy path/to/file.py

# または直前runの失敗ツール・失敗ファイルをまとめて再実行
pyfltr run-for-agent --only-failed
```
--commandsで特定ツールに限定することで出力量を抑えつつ、 diagnostic行から修正対象のファイル・行番号・メッセージを取得する。 command.retry_commandフィールドには当該ツールだけを失敗ファイルに限定した再実行コマンドが既に生成されているため、そのまま貼り付けて実行できる。 --only-failedは直前runのアーカイブから失敗ツール・失敗ファイルを自動抽出して再実行する。直前runが無い・失敗ツールが無い・対象との交差が空の場合は終了コード0で成功終了する。

個別ツールを限定して実行したい場合¶

特定のツール1件だけを実行したいときは--commands=<tool>オプションを使う。

pyfltr run --commands=textlint docs/
pyfltr run-for-agent --commands=mypy src/

サブコマンドはrunまたはrun-for-agentを利用する。 pyfltr textlint docs/のようにツール名をそのままサブコマンドへ書くことはできない（誤入力を検知した場合は実行例付きのエラーメッセージが表示される）。

run-for-agentサブコマンドのJSONL出力に含まれるcommand.retry_commandも同じ--commands=<tool>書式で生成される。失敗ツールだけを再実行したい場合は、該当commandレコードのretry_commandをそのまま貼り付けて実行できる。

pre-commitとの統合¶

pyfltrは.pre-commit-hooks.yamlを同梱していない。 pre-commitから呼び出したい場合は.pre-commit-config.yamlのrepo: localでlocal hookとして登録する。 entryにはuvx pyfltrを指定する（uvxでキャッシュされるため2回目以降は実用速度）。

repos:
  - repo: local
    hooks:
      - id: pyfltr-fast
        name: pyfltr fast
        language: system
        entry: uvx pyfltr fast
        require_serial: true
        types: [file]

dev依存にpyfltrを固定する運用ではentry: uv run --frozen pyfltr fastに置き換えることもできる。

共通の注意点¶

pyfltr fast はfixステージを内蔵する。pre-commit hookから{command}-fix-args定義済みlinter （cargo-clippy / ruff-check / textlint等）の自動修正が実行されるため、別hookを並べる必要は無い
formatter（ruff-format / prettier / cargo-fmt / dotnet-format等）は通常実行で常時書き込みモードで動作するため、 fixステージでは扱わない
pass-filenames = Falseのツール（cargo-* / dotnet-* / tsc等）はcrate / solution全体を対象とするため、コミット時に未変更ファイルまで書き換わる可能性がある。 cargo系・dotnet系はserial_groupで自動直列化されるので、利用者が--jobs=1などを指定する必要は無い

モノレポでの動作¶

起点cwd配下に複数の pyproject.toml を検出した場合、サブプロジェクト単位でツールを分割実行する（モノレポモード）。

検出: 起点cwd配下を再帰探索して pyproject.toml を持つディレクトリをサブプロジェクトとして扱う。 [tool.pyfltr] の有無は問わない。[tool.uv.workspace] members glob展開結果も含める。 .gitignore を尊重しつつ .venv ・ node_modules ・ target ・ build ・ dist ・ .git 配下は走査しない
適用範囲: プロジェクトローカル設定・モジュール解決・lockfileをcwd起点で読むツール（mypy・pylint・pyright・pytest・textlint・eslint・cargo-*・dotnet-*・ruff-* 等）はサブプロジェクト別に起動する。リポジトリ単位のツール（typos・shellcheck・shfmt・pre-commit）は1回だけ起動する
フォールバック: 検出結果が0件または1件の場合は単一プロジェクトとして従来通り動作する
出力スキーマ: モノレポ実行でもJSONL・SARIF・show-run・MCP読み取り系APIの公開スキーマは変更しない。サブプロジェクト境界をまたぐ実行結果は1件にマージし、人間向けoutputには # subproject: <相対パス> の区切り行を挿入する
個別設定: 各サブプロジェクトの [tool.pyfltr] 設定（ツールのON/OFF・除外・targets等）を当該ディレクトリで個別に解決して尊重する。 CLIオプション（--jobs・--no-exclude・--no-gitignore・--human-readable）は起点と同一に再適用する
ツールON/OFFの両方向: 親（起点）で無効・子で有効なら子でのみ実行し、親で有効・子で無効なら子サブプロジェクトはスキップする。起点ディレクトリ自体は1つのサブプロジェクトとして扱い、その設定が有効なら起点自身のファイルは実行する
起点cwdでの一括実行はしない: あるツールが起点で有効でも、対象ファイルを持つサブプロジェクトが全て無効化している場合、起点cwdで全ファイルをまとめて実行することはない（サブプロジェクト境界をまたいだ誤実行を避ける）
リポジトリ単位のツール（typos・shellcheck・shfmt・pre-commit）のON/OFFは、起点 pyproject.toml の設定で固定し、子の設定では切り替えない