vtai-agent

VT-AIAgent

あなたのマシンを自動化するエージェントです。MCP サーバーとして opencode / Claude Code / pi に公開でき、vtai CLI から直接操作することもできます。

ツール

安全モデル

• デフォルトでドライラン（guardrails.dry_run_default）— プレビューではディスクに一切触れません。
• パスの封じ込め：paths.writable_roots 内でのみ書き込みます。解決済みパスにより .. やシンボリックリンクによる抜け道を防ぎ、guardrails.deny_globs でシークレットを保護します。
• フェイルクローズのシェルサンドボックス：バイナリは許可リストに登録された名前のみを指定し、 読み取り／書き込みポリシーを明示する必要があります。また、trusted_bin_dirs 内に解決され、 実行を有効にするフラグを含まず、すべてのパス引数が同じチェックに合格する必要があります。
• キルスイッチ：data_dir に KILL ファイルを置くと、実行中のツールを中断します。
• エコーループブレーカー：一定時間内に同じ拒否が N 回発生すると、ループ中のモデルが見落とせない CIRCUIT BREAKER 指示へと拒否をエスカレートします。
• 予算上限：発生したトークンコストが budget_usd_per_run を超えると、オーケストレーション実行を中断します。支出は実行ごとに記録されます。
• 監査：すべての許可と拒否を data_dir 内の SQLite に記録し、各呼び出し（オーケストレーション、MCP、CLI）を実行レコードに紐付けます。

クイックスタート

前提条件

1. インストール

git clone https://github.com/velsrocky/vtai-agent.git
cd vtai-agent
uv sync --dev

uv sync には uv >= 0.13.1 が必要です（ロックファイルは revision = 5 です。最低バージョンは [tool.uv] required-version で宣言されているため、古い uv ではロックファイルの解析に失敗する代わりに、 その旨が明確に表示されます）。

2. 設定

エージェントは 1 つの TOML ファイルを読み込みます。どのファイルを使うかは、次の順に解決されます。

1. $VT_CONFIG — 明示的な上書き
2. パッケージと同じ場所にある config/settings.toml（つまり、今クローンしたディレクトリ）
3. ~/.vtaiagent/settings.toml — ユーザーごとのファイル

新しくクローンしたディレクトリには、メンテナーの設定（メンテナーのプロバイダーと書き込み可能なルート）が含まれています。そのため、追跡対象のファイルを編集するのではなく、エージェントに自分のファイルを指定してください。

export VT_CONFIG="$HOME/.vtaiagent/settings.toml"
uv run vtai init          # writes a starter config there + creates the dirs

その export をシェルのプロファイルに記述すると、以降のコマンドと MCP サーバーで読み込まれます。

vtai init は ~/.vtaiagent（監査 DB とデータディレクトリ）、~/Downloads、~/Documents/vt-data を作成し、安全なデフォルト値を設定した初期設定ファイルを書き込みます。設定内容は、dry_run_default = true、~/.ssh、~/.gnupg、~/.aws、**/.env を対象とする deny_globs、および ~/Downloads、~/Documents/vt-data、~/.vtaiagent/tmp に限定された書き込み可能なルートです。何度実行しても安全です。

最終的にどの設定ファイルが使われるかを確認します。vtai info にはファイル名とその読み込み元が表示されます。

uv run vtai info
#   config file     : /Users/you/.vtaiagent/settings.toml (user-level)

VT_LOCAL__BASE_URL=http://localhost:13305/api/v1
VT_LOCAL__MODEL=<a pulled chat model>
VT_ACTIVE_PROVIDER=local

モデルの選択

プランナー／ジャッジモデルは active_provider で指定します。

• local — OpenAI 互換エンドポイントなら何でも使用できます：Ollama（http://localhost:11434/v1）、llama.cpp、vLLM、LM Studio、Lemonade。API キーは不要です。
• anthropic / openai — クラウドモデルです。.env に ANTHROPIC_API_KEY または OPENAI_API_KEY を設定してください。

budget_usd_per_run を有効にするには、プロバイダーブロックで cost_per_1k_input / cost_per_1k_output を設定します。設定しない場合、エージェントはモデルの標準価格表を使用します。

3. 確認

まず、事前チェックを実行します。uv、設定、書き込み可能なルート、保護対象、オプションのツール、モデルのエンドポイント、MCP の登録、レビュー待ちの委任先を確認します。

uv run vtai doctor

VT-AIAgent doctor — v0.6.2
  ✓  agent version      0.6.2
  ✓  uv                 0.13.1
  ✓  config file        /Users/you/.vtaiagent/settings.toml (user-level)
  ✓  config valid       no issues
  ✓  writable roots     3 present
  ✓  protected paths    4 deny globs
  ✓  shell allowlist    22 binaries
  ✓  model endpoint     http://localhost:11434/v1
  !  optional tools     not installed: ffmpeg (for transcode_media, voice helpers)
  ✓  mcp registration   opencode (global)
  ✓  pending approvals  none

修正が必要な項目がある場合は、ゼロ以外の終了コードを返します。続いて、各機能を試すには次のようにします。

uv run vtai info                         # config, provider, guardrails
uv run vtai tools                        # the registered tools
uv run vtai run system_info              # a read-only call, no LLM involved
uv run vtai goal --dry-run "list my Downloads"   # full loop with the model

4. エージェント CLI から使用する

scripts/register-mcp.sh                  # opencode (global), claude (user), pi (CLI)

opencode の登録情報は ~/.config/opencode/opencode.jsonc に保存され、既存のプロバイダーと統合されます。このスクリプトでは、意図的に uv の絶対パスを登録します。クライアントが最小限の PATH で動作するデーモンからサーバーを起動するとき、単なる uv の指定では NotFound: ChildProcess.spawn (uv ...) が発生するためです。

使用方法

uv sync                                  # install
uv run vtai init                         # create/validate config, dirs, writable roots
uv run vtai info                         # show config
uv run vtai tools                        # list tools
uv run vtai run system_info              # invoke a tool
uv run vtai run run_shell --params '{"command":"ls ~/Downloads","dry_run":true}'
scripts/register-mcp.sh                  # register with opencode / claude

チェックアウトしたディレクトリの外でも vtai CLI を使うには、作業コピーを追跡するように編集可能なツールとしてインストールします。

uv tool install --editable /path/to/vtai-agent   # -> ~/.local/bin/vtai

別のプロジェクトに依存関係としてインストールするには、uv add git+https://github.com/velsrocky/[email protected] を実行します。または、docker build -t vtai-agent . でイメージをビルドします。

レジストリと配布

PyPI：uv tool install vtai-agent（または pipx install vtai-agent）。Trusted Publishing とビルドアテステーションを使用して、v* タグで公開されます（.github/workflows/publish.yml を参照）。上記の `` コメントは、公式 MCP レジストリが求める PyPI パッケージの証明です。server.json にはレジストリマニフェスト（io.github.velsrocky/vtai-agent、stdio）が含まれ、公開ワークフローにはメタデータ整合性チェックも組み込まれています。これらの配布元からのみインストールしてください。似た名前のリポジトリであっても、正規の配布元である証明にはなりません。

PyPI でリリースした後、公式 MCP レジストリに登録します。

mcp-publisher auth --oauth2-github
mcp-publisher publish server.json

認証（vtai-cert）

安全性に関する主張は、文章ではなくプローブで検証します。vtai certify は、実行可能なガードレール準拠テストスイート（deny-glob の封じ込め、dotdot／シンボリックリンクによるエスケープ、フェイルクローズするシェル、注入された argv への耐性、dry-run 優先、キルスイッチ、監査の厳密性、エコーループブレーカー、スクリプト化された偽のロールバックと承認ゲートのプローブを用いた、委任先の検証してから信頼するループ）を実行し、ダイジェストを付与した証明書を生成します。 終了コード 0 が CI でのリリースを許可します。docs/certification.md を参照してください。

HTTP トランスポート

vtai serve --transport http --port 8765 --token $VT_HTTP_TOKEN は、MCP StreamableHTTP を通じて /mcp で同じガード対象ツールを公開します。localhost 以外にバインドする場合はベアラートークンが必須です。トークンがない場合、サーバーは外部へのバインドを拒否します。

開発

uv sync --dev
uv run pytest tests/ -v
uv run ruff check src/ tests/
uv run python scripts/generate_tool_catalog.py --check   # tool-catalog doc drift

設定ファイルは設定の説明に従って解決されます。$VT_CONFIG → チェックアウト内の config/settings.toml → ~/.vtaiagent/settings.toml の順です。環境変数によるオーバーライドには、__ によるネストと VT_ 接頭辞を使用します（例： VT_GUARDRAILS__DRY_RUN_DEFAULT=false）。設定は起動時に検証されます （validate_settings）。不正な deny_globs パターンや書き込み可能なルートの欠落がある場合、実行中ではなく即座に失敗します。

Windows： シェルサンドボックスで許可リストに登録されたバイナリを解決するには、PATH が通っている必要があります。また、新しい Windows ランナーでは Git for Windows の coreutils が PATH に含まれていません。Git for Windows をインストールし、その usr\bin を PATH の先頭に追加してください（CI ではこの方法を使用しています）。

Add-Content $env:GITHUB_PATH "C:\Program Files\Git\usr\bin"   # CI
# locally: add "C:\Program Files\Git\usr\bin" to your PATH

それ以外（インストール、設定、MCP 登録）は、3 つのプラットフォームすべてで同じです。

オーケストレーター

vtai goal は、制限付きの ReAct スタイルのエージェントループを実行します。各ステップでモデルは、フェンス付き JSON のツール呼び出しを 1 つ出力するか（解析、ガード処理、実行を行い、結果をフィードバックします）、自然言語で最終回答を返します。各ステップで適用される制限は、max_steps、キルスイッチ、budget_usd_per_run です。解析に失敗する、または tool キーがない単独の dry_run: true テキストブロブは、実行を「成功」として終了するのではなく、修正を促すメモとともに再試行されます。実行モードが正として扱われ、モデルがこれを上書きすることはできません。また、すべてのツール呼び出しは Step 行と監査エントリーとして永続化されます。有料プロバイダーの支出額を特定できない場合（cost_per_1k_* の設定がなく、ネイティブのコスト情報もない場合）、無料として報告するのではなく、フェイルクローズで実行が失敗します。システムプロンプトには、マシンの実際の OS が記載されます。

意図的にネイティブの関数呼び出しではなくテキストプロトコルを使用しています。このマシン上のローカル Ollama モデルは、ネイティブのツールスキーマが提供されていても、ツール呼び出しを未加工の JSON テキストとして出力するためです（2026-10-03 に qwen2.5-coder:7b で確認）。そのため、テキストプロトコルはローカルプロバイダーとクラウドプロバイダーの両方で同じように動作します。

自動モード

auto_mode は、指定したループを実行します。目標をコーディング CLI（デフォルトでは opencode）に送信し、設定されたモデルで回答を目標に照らしてレビューします。回答が不十分な場合は、批評を引用したフォローアッププロンプトを送信します。これを max_iterations まで繰り返します。判定役が達成とみなすのは、余計な文言のない OK だけです（曖昧さを含む回答は不合格です）。支出額は guardrails.budget_usd_per_run に対して計測され、実行の spend 詳細に割り当てられます。判定役自身の LLM 呼び出しは常に計測されます。委任先 CLI の支出額は、報告可能な場合に計測されます。claude -p --output-format json は total_cost_usd を公開し、コストを報告できる CLI から読み取り可能なレポートが得られない場合は、フェイルクローズで失敗します。opencode／pi はヘッドレス実行の支出額を報告しません（これはベンダーが文書化している動作であり、イベントストリームを推測解析することはありません）。そのため、これらの実行では "cli_usd": "unmeasured" が記録され、max_iterations／timeout のみで制限されます。opencode または Claude Code の内部から、プロンプトの先頭に @vt-ai_automode_on を付けてください。MCP サーバーの指示によって、この記述がツールにルーティングされます。

uv run vtai run auto_mode --params '{"goal":"add a unit test for parser.py","working_dir":".","max_iterations":3}'

コーディングの委任

delegate_coding は対象リポジトリのスナップショットを作成し、選択した CLI をヘッドレスで実行して差分を取得します。verify_command が失敗した場合（またはタイムアウト／終了コードが 0 以外の場合）はロールバックします。知っておくべきガードは 3 つあります。

• 人間による承認ゲート：require_approval のデフォルトは true です。対話型の場合は git diff --stat を表示し、変更を保持するか確認します。非対話型の実行（MCP、スクリプト、オーケストレーション）では、変更はワークツリー内に承認待ちとして保持されます。自動ループを停止させるため、実行結果は失敗として報告されます。vtai approve <id>（保持）または vtai approve <id> --rollback で処理します。リポジトリに承認待ちがある間は、require_approval: false であっても delegate_coding はそのリポジトリでの新たな作業を拒否します。require_approval: false を指定するのは、人間がすでに確認したタスクに限ってください。
• pi には認証情報が必要です：認証済みのプロバイダーがない状態では、pi -p はツール呼び出しの JSON ブロックを出力するだけで、何も適用せずに終了コード 0 を返します。このツールは現在、明確なメッセージを表示してフェイルクローズします。pi に委任する前に pi auth check を実行するか、opencode ／ claude の使用をおすすめします。

Claude への委任は --output-format json を指定して実行されるため、返信テキストは result から取得され、呼び出しの total_cost_usd はツールの詳細情報に cli_cost_usd として記録されます（監査対象にもなります）。opencode／pi への委任では "cli_cost_usd": "unmeasured" と報告されます。

uv run vtai approve          # list pending delegate approvals
uv run vtai approve 7        # keep the pending diff
uv run vtai approve 7 --rollback

vtai info には承認待ちの件数が表示されるため、確認のために保持された委任結果を見失うことはありません。

アプリケーションの検査（REA 機能）

inspect_application は REA と連携し、ソースコードがなくてもエージェントがローカルアプリの仕組みを静的に説明できるようにします。REA の検査機能は強力なため、vtai-agent のガード内でのみ実行され、デフォルトでは無効です。

[capabilities.rea]
enabled        = true             # enable only after install vetting
binary         = "rea"
command_prefix = ["analyze-javascript-application"]
timeout        = 1800.0
keep_copy      = false

安全性に関する契約は次のとおりです。対象は deny_globs を通過する必要があります。その後、data_dir 配下の隔離ディレクトリにコピーされます（コピー時に拒否対象のエントリーとポリシーに反するシンボリックリンクはスキップされるため、REA がアクセスできないパスを読み取ることはありません）。REA は最小限の子プロセス環境（API キーを継承しない環境）でコピーに対して実行され、timeout 経過後に強制終了されます。出力 JSON が解析され、sha256 の証拠ダイジェストと REA の証拠 ID が監査ログに記録されます。オプションの判定パス（auto_mode と同じモデルおよびフェイルクローズポリシー）では、結果が成功と報告される前に、証拠が目的に答えていることを検証します。元の対象には一切変更を加えず、keep_copy が true でない限り隔離コピーは削除されます。実際の JS アプリに対し、実際の rea 6.7.0 CLI を使用して 2026-10-21 に実環境で検証済みです。spawn、--json のエンベロープ、証拠の数字をすべて確認しています。詳細は docs/showcases/rea-live-validation.md を参照してください。

uv run vtai run inspect_application \
  --params '{"goal":"explain how Notes builds its CSV export header",
             "target":"~/quarantine/Notes-app","dry_run":true}'

REA は公式ソース（github.com/morluto/rea または npm の rea-agents パッケージ。出所を確認してください）からのみインストールし、ミラーサイトからはインストールしないでください。

監査ログ

すべての許可／拒否は ~/.vtaiagent/vtai.db に保存されます。SQL クライアントなしで検索できます。

uv run vtai audit --limit 20
uv run vtai audit --denied --grep ssh
uv run vtai audit --action delegate --run-id 193

1 回の実行について、目的、すべてのツール呼び出し、許可または拒否された内容、費用を最初から最後まで確認するには、次のようにします。

uv run vtai runs            # list runs
uv run vtai runs --summary  # aggregate: spend percentiles, tool counts, denial codes (JSON with --json)
uv run vtai show 193        # one run in full

音声コントロール（agent-listen / agent-speak）

どちらのヘルパーも、ローカルの Lemonade Server（Linux/macOS では TTS が kokoro-v1、STT が Whisper-Tiny。Windows では whisper.cpp のレシピが一部の AMD GPU で正常に動作しないため、デフォルトで Moonshine-Tiny-Streaming）と通信します。接続先は http://localhost:13305 です。どのプラットフォームでも、LEMONADE_STT_MODEL で STT モデルを上書きできます。録音時間を変更するには --seconds N、無音に基づいて早期に停止するには --vad を使用し、接続先を変更するには LEMONADE_BASE_URL を設定します。

スクリプトは scripts/ でバージョン管理されています。次のコマンドでインストールします。

uv run vtai voice-sync

voice-sync は両方のヘルパーを ~/.local/bin にコピーし（--dest で変更可能）、実行可能にしたうえで、ファイルごとに installed / updated / unchanged を報告します。vtai voice-sync --check は差分のみを報告し（同期されていない場合は終了コード 1）、スクリプトの更新を pull した後は --check を付けずに再実行してください。別のチェックアウトから同期するには、VTAI_SCRIPTS_DIR を設定します。

クロスプラットフォームに関する注意事項（macOS 27/ARM、2026-10-12 で検証済み）：

対応環境：Linux + macOS + Windows — 3 つすべてで CI を実行しています（Linux と macOS は push 時の実行をブロック。Windows は、スイートが移植可能になった 0.6.0 で再導入されました。許可リスト方式のサンドボックスが実際のバイナリを解決できるよう、Git Bash の coreutils を PATH の先頭に追加しています）。rsync に依存するテストは、rsync がないランナーではスキップされ、フェイルクローズを検証するカウンターテストで補完されます。

• Linux では録音に arecord を使用します。それ以外では、ヘルパーは ffmpeg（-f pulse / avfoundation）にフォールバックするため、macOS と Windows でも動作します。
• --vad は現在、Linux の arecord が必要です。他のプラットフォームでは --seconds N を使用してください。
• macOS のマイク選択：avfoundation のデバイスインデックスはマシンごとに異なります。ffmpeg -f avfoundation -list_devices true -i "" で一覧を表示し、AGENT_LISTEN_FF_INPUT で上書きしてください（デフォルトは音声のみの -f avfoundation -i ":0"）。内蔵マイクのないマシン（多くのミニ PC など）では、外部デバイスまたは USB デバイスを接続する必要があります。接続しない場合、録音は無音になります（終了コード 6、音声なし）。
• 再生には ffplay → afplay（macOS）→ mpg123 → aplay の順に試します。
• ALSA のマイクレベル修正と、以下の vtai-audio-fix systemd ユニットは Linux 専用です。Windows と macOS ではシステム設定で処理します。
• guardrails.trusted_bin_dirs のデフォルト値は OS ごとに異なります（C:\Windows\System32、/usr/bin, /bin, /usr/local/bin, /opt/homebrew/bin、および Linux 用のパス）。現在のマシンに存在しない項目は無視されます（検証が失敗するのは、存在するパスが 1 つもない場合のみです）。そのため、1 つの設定に Linux と macOS の両方のパスを記載できます。
• system_info は移植可能です。メモリ情報は sysctl / vm_stat から、ディスク情報は macOS の /、$HOME、/Volumes/* から取得します（Metal GPU に関する注意事項。macOS には rocm-smi はありません）。
• Linux 以外では transcode_media のデフォルトは libx264 です（VAAPI は Linux 専用）。明示的な "codec" の指定があれば、引き続きその指定が優先されます。
• disk_audit は macOS では ~/Library/Caches、~/Library/Logs、/Library/Caches、~/.Trash も測定します。新規にインストールした macOS では、スターター許可リストに vm_stat（Linux 専用の free / nproc の代わり）が含まれます。

トラブルシューティング

セットアップと MCP

• opencode mcp list に ✗ vtai-agent failed: NotFound: ChildProcess.spawn (uv ...) と表示される場合： クライアントが最小限の PATH（デーモンでは PATH=/usr/bin:/bin:...）でサーバーを起動したため、単独の uv を解決できませんでした。scripts/register-mcp.sh を再実行してください。絶対パスの uv が登録されます。または、opencode の設定にある mcp.servers.vtai-agent.command 配列を uv のフルパス（command -v uv）に編集してください。
• opencode mcp list に No MCP servers configured と表示される場合：登録はプロジェクトごとに行われます。チェックアウトしたディレクトリから実行するか、scripts/register-mcp.sh が ~/.config/opencode/opencode.jsonc に書き込むグローバル登録を使用してください。
• "config exists: …/config/settings.toml" と表示され、設定が無視される場合：チェックアウト内の設定は ~/.vtaiagent/settings.toml より優先されます。VT_CONFIG="$HOME/.vtaiagent/settings.toml" を設定して vtai init を再実行してください。vtai info には使用中のファイルと、その取得元が表示されます。
• uv sync が Required uv version ... does not match で失敗する場合：uv >= 0.13.1 をインストールしてください（ロックファイルのリビジョンは 5 です）。

音声（Linux / PipeWire / ALSA）

• マイクから音声が聞こえない、または文字起こし結果がクリッピングしたノイズになる場合：内蔵マイクのブーストが高すぎる値に固定され、入力がクリッピングしています。以下の方法で修正してください（~/.config/systemd/user/vtai-audio-fix.service により、毎回のログイン時にも適用されます）。

  amixer -c 2 sset 'Internal Mic Boost' 0
  amixer -c 2 sset 'Capture' 75%
  

• ヘッドホンジャックが検出されない場合：カーネルがコンボポートのジャックを認識していないため、ヘッドホンアンプがオフのままになります。pw-cli enum-params 53 EnumRoute を確認してください。ヘッドセットがしっかり差し込まれるまで、analog-output-headphones ルートは available: no と表示されます。検出が不安定な場合は、wpctl set-route 38 1 で手動でルートを設定してください。

• デフォルトの入力ソースが違うマイクになっている場合：pw-cli enum-params 53 Route でルートを一覧表示し、wpctl set-route 47 <index> で選択してください（0 = 内蔵マイク、1 = ヘッドセットのマイク）。

• STT が [BLANK_AUDIO] またはノイズの文字起こしを返す場合：arecord -d 3 -f cd /tmp/t.wav でレベルを確認し、ピークを調べてください。0 付近なら選択中のルートから信号が届いていません。フルスケールならクリッピングしているため、ブーストを下げてください。

コーディングの委任

• delegate_coding で変更したファイルがリポジトリに残っている場合：承認待ちの状態です。vtai approve <id> を実行して変更を保持するか、--rollback を実行して破棄するまで、変更は確認用に保持されます。人間がすでに確認したタスクに限り、require_approval: false を渡してください。

貢献

セットアップ、変更時に遵守すべきガードレールのルール、テスト／lint コマンドについては、CONTRIBUTING.md を参照してください。

セキュリティ

ガードレール、脆弱性に該当するもの、非公開での報告方法については、SECURITY.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。自由に使い、フォークし、ご自身のマシンで実行してください。