argus

Argus が生まれた理由

AI エージェントは今やコードの大半を書いています。しかし、その成果を評価するときに基準にするのは、ブラウザーで実際に何が起きるかではなく、コンパイルできて、完成したように見えるかどうかです。3 回目のクリックで発生する未捕捉の例外。HTTP 経由で認証情報を送信するフォーム。4 秒の LCP。ダークモードで消えるボタン。無限ループで叩かれる API エンドポイント。

Argus はそのギャップを埋めます。 Chrome DevTools Protocol 経由で実際の Chrome を操作し、ローカルで実行中のアプリを監査して、構造化された重大度順のバグレポートをエージェント、またはあなたに渡します。エージェントが修正し、Argus が再チェックすることで、コードがマシンから外に出る前にループが完了します。

クイックスタート

インストール不要です。 初回実行時に npx が Argus を取得します。

1 — プロジェクトのルートにある .mcp.json に 2 行追加します：

{
  "mcpServers": {
    "chrome-devtools": { "command": "npx", "args": ["-y", "chrome-devtools-mcp@latest"] },
    "argus":           { "command": "npx", "args": ["-y", "argusqa-os"] }
  }
}

または Claude Code CLI から実行します：

claude mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest
claude mcp add argus -- npx -y argusqa-os

2 — Chrome を起動します（Chrome を自動検出し、適切なフラグを設定します）：

npx -y -p argusqa-os argus-chrome

# macOS
open -a "Google Chrome" --args --remote-debugging-port=9222 --headless=new

# Windows (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --headless=new --no-sandbox --disable-gpu --user-data-dir="$env:TEMP\chrome-argus"

# Linux
google-chrome --remote-debugging-port=9222 --headless=new --no-sandbox

3 — エージェントに依頼します：

Run argus_audit on http://localhost:3000

これで完了です。検出結果は構造化され、重大度順に並べられて、会話内、Slack、またはローカルの report.html として返されます。問題がある場合は、npx -y -p argusqa-os argus-doctor を実行すると、1 つのコマンドでセットアップを診断できます。

修正ループ

エージェント型コーディングセッション内で Argus がどのように動作するかを示します：

You:    Build me a checkout page with a card form.
Agent:  [writes the code, dev server renders it]

You:    Run argus_audit on http://localhost:3000/checkout
Argus:  ● 2 critical · 3 warnings
        ● uncaught TypeError in checkout.js (visible on submit)
        ● form posts over HTTP — security_no_https
        ▲ card inputs missing labels + autocomplete (a11y/WCAG)
        ▲ LCP 4.1s — hero image unoptimized
        ▲ duplicate POST /api/cart ×7 — likely render loop

Agent:  [fixes all five]

You:    Run argus_get_context
Argus:  ✓ resolved: 5 · persisting: 0 · new: 0

argus_get_context は前回のスナップショットとの差分を表示するため、エージェントは何を修正し、何を壊し、何が残っているのかを正確に把握できます — 出力の長い文章を読み直す必要はありません。

「でも、エージェントはすでにブラウザーを操作できます…」 — そのとおりです。しかし、操作することと評価することは別です。生のブラウザー MCP（Playwright MCP、素の chrome-devtools-mcp）はエージェントに手と目を与えますが、何をチェックすべきかはセッションごとにエージェントが改めて導き出す必要があり、コンソールログを掘り下げるためにコンテキストを消費します。Argus はその上にある評価レイヤーです。閾値、重大度ポリシー、実行間のベースライン、フレークのフィルタリング、重複排除、根本原因のヒントを備えた、コード化済みの 149 種類の検出項目を、デフォルトで秘匿化して 1 回の呼び出しで返します。

Argus が検出するもの

32 の分析エンジン、149 種類の固有の問題タイプ、テストファイルのメンテナンスは不要です。

さらに、すべての検出結果は次の後処理を受けます。

すべての検出結果は critical / warning / info に分類され、適切な Slack チャンネルに送られるか、ローカルの HTML レポートに表示されます。検出結果ごとの重大度テーブルと検出方法については、REFERENCE.md を参照してください。

お使いのスタックで動作

Argus はソースではなく、レンダリングされた出力を監査するため、設計上フレームワークに依存しません。Chrome で動作するものなら、Argus で監査できます。

正直な制限事項： Chrome/Chromium のレンダリングのみ（Safari/Firefox のエンジン差異には対応しません）、Web のみ（ネイティブのモバイル／デスクトップアプリには対応しません）。バックエンドサービスは単独の API テストスイートとしてではなく、ページが生成するトラフィックを通じてチェックします。

機密保持 — Aegis の外部送信境界

デフォルトで有効です。 Argus はアプリを監査してシークレットや脆弱性を検出するため、その検出結果は、マシンの外に出したくないデータそのものです。Aegis は、データが外部境界を越える前に、すべての境界でそれらを編集します。AI エージェントを導入するチームにとって、これは「AI QA ツールを使っています」と「安全な理由をセキュリティ責任者にはっきり説明できます」の違いになります。

外部シンクに送信される検出結果 — 呼び出し元のエージェントのコンテキストウィンドウに入り、そのエージェントのモデルプロバイダーに送られる MCP ツールのレスポンス、Slack メッセージ、GitHub の PR コメントとその ::error 注釈、ホスト型／CI HTML レポート、または CI ログ — は、必要最小限の情報に限定されます。機密な検出結果は type + route + severity と 🔒 マーカーとして送信され、元のペイロード（message、evidence、リクエスト／レスポンス本文、ヘッダー、Cookie、スタック）が送信されることはありません。URL はクエリ文字列を除いて表示します（トークンはそこに含まれるためです）。問題のない検出結果ではメッセージを保持しますが、そのメッセージに誤って埋め込まれたシークレットや PII も引き続き除去します。

これは、Argus 自身の境界において、OWASP LLM02:2025 — Sensitive Information Disclosure の緩和策（データの最小化、編集、デフォルト拒否の外部送信フィルタリング）を実装するものです。オプションのローカル専用再水和ボールト（ARGUS_REDACT_VAULT=1）を使うと、差分が安定するアーティファクト向けに復元可能な、情報を含まないトークンを生成できます。npm run report:rehydrate でローカルに再展開できます。動作の変更については CHANGELOG.md に記載されています。

MCP ツール

Claude（または任意の MCP クライアント）に依頼できます。ターミナルは不要です。

すべてのツールのレスポンスは、エージェントに届く前に Aegis の外部送信境界を通して必要最小限の情報に限定されます。機密情報が除外された場合は、オプションの redaction 情報（{ redacted, total }）が付与されます。

プロンプトの例：

Run argus_audit on http://localhost:3000/checkout
Run argus_audit_full on http://localhost:3000/dashboard
Run argus_compare
Run argus_get_context

実戦で検証済み。雰囲気ではありません

Argus 自身の正確性も、Argus が監査する対象と同じ方法で担保されています。

• 実際の Chrome を 64 のフィクスチャページに対して動かす 171 ブロックの統合ハーネスで、998/998 件の厳密なアサーションを実施しています。カテゴリごとの陰性対照（誤検出ゼロ）、9 つすべての MCP ツールのゴールデンレスポンススキーマ、バージョン更新時に chrome-devtools-mcp の API 変更を検知する上流ドリフトカナリアを含みます
• 562 件の Chrome 不要なユニットテスト（Vitest）＋プロパティベースのパーサーファジング
• npm audit：脆弱性ゼロ · すべての PR で CodeQL + Dependabot を実行 · Socket.dev：脆弱性／品質／ライセンスの評価は 100/100/100
• セッションファイルと取得したトークンは 0600 で書き込み、所有者のみがアクセスできます

セットアップの全手順

前提条件

オプション A — MCP サーバー (Claude Code ユーザーに推奨)

ローカルへのインストールは不要です。上記のクイックスタートを使用し、対象 URL を追加してください。

# .env in your project root
TARGET_DEV_URL=http://localhost:3000
TARGET_STAGING_URL=https://staging.example.com   # optional — enables argus_compare

任意 — Slack 通知：

1. api.slack.com/apps → Create New App → 名前を BugBot に設定
2. OAuth & Permissions → Bot Token Scopes：chat:write、files:write、files:read
3. ワークスペースにインストール → xoxb-... トークンをコピー
4. #bugs-critical、#bugs-warnings、#bugs-digest チャンネルを作成し、それぞれで /invite @BugBot を実行

SLACK_BOT_TOKEN=xoxb-...
SLACK_CHANNEL_CRITICAL=C0000000000
SLACK_CHANNEL_WARNINGS=C0000000001
SLACK_CHANNEL_DIGEST=C0000000002

Slack を使わない場合：Argus は reports/report.html を自動生成し、ブラウザーで開きます。追加設定は不要です。

オプション B — npm パッケージ（CI／開発依存関係）

npm install --save-dev argusqa-os
npx argus init   # interactive wizard — detects framework, discovers routes, writes .env
npm run crawl    # run after Chrome is started

オプション C — リポジトリをクローン（コントリビューター／ソース全体）

git clone https://github.com/ironclawdevs27/Argus.git
cd Argus
npm install
npm run init     # interactive setup wizard

手動セットアップ（ウィザードを省略する場合）：

cp .env.example .env
# Fill in TARGET_DEV_URL and optional Slack tokens

次に、src/config/targets.js でルートを設定します。

export const routes = [
  { path: '/',          name: 'Home',      critical: true,  waitFor: 'main' },
  { path: '/login',     name: 'Login',     critical: true,  waitFor: 'form' },
  { path: '/dashboard', name: 'Dashboard', critical: true,  waitFor: '[data-testid="dashboard"]' },
  { path: '/settings',  name: 'Settings',  critical: false, waitFor: null },
];

• critical: true — このルートのエラーは #bugs-critical に送信されます
• waitFor — Argus が取得前に待機する CSS セレクター（ページの準備完了を示します）

CLI コマンド

npm run chrome         # Launch Chrome with --remote-debugging-port=9222 (auto-detects binary)
npm run doctor         # Pre-flight check: Chrome reachable, .mcp.json valid, .env has TARGET_DEV_URL
npm run crawl          # Batch audit of all configured routes
npm run compare        # Dev vs staging diff (CSS-only if no staging URL)
npm run watch          # Passive monitor — polls open Chrome tab every 1s
npm run report:html    # Generate reports/report.html from last JSON audit
npm run report:pdf     # Export HTML report to A4 PDF (requires: npm install puppeteer)
npm run server         # Start Slack slash-command server (port 3001)
npm run init           # Interactive setup wizard
npm run test:unit          # 562 unit tests — no Chrome required
npm run test:harness       # 171-block correctness harness — requires Chrome
npm run test:harness:log   # same, but tees full output to harness-results.txt
npm run test:coverage      # merged unit + harness coverage gate (requires Chrome)

監視モード — あなた（またはエージェント）の開発中にリアルタイムで監視します。

# Terminal 1: start your app
npm run dev

# Terminal 2: start Argus watcher
npm run watch
# Ctrl+C → stops monitor and writes reports/report.html

Slack スラッシュコマンド（任意のチャンネルから必要に応じて実行）：

/argus-retest https://staging.example.com/checkout

トンネル経由でサーバーを公開するには、cloudflared tunnel --url http://localhost:3001 を実行します（無料、アカウント登録不要）。生成された URL を Slack App → Slash Commands の Request URL に設定してください。

GitHub Actions CI — PR ゲート

Argus は複合 GitHub Action として提供されます。各 PR で差分から影響を受けるルートを特定して監査し、その PR が新たに持ち込む検出結果に限ってマージをブロックします（ベースラインを考慮）。PR への冪等なコメントと Check Run も作成します。

リポジトリのシークレットに追加してください（Settings → Secrets → Actions）。

同梱の ワークフロー は、main へのプッシュ時、毎日 UTC 午前 6 時、および手動実行時に動作します。重大な問題が見つかった場合、パイプラインは失敗します。

環境変数

トラブルシューティング

問題が起きたときは、まず npx -y -p argusqa-os argus-doctor を実行してください。Chrome の到達可能性、MCP 設定の有効性、必須の環境変数キーを確認し、各失敗に対する正確な修正方法を表示します。

Chrome DevTools MCP に接続できない

claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest
# Restart Claude Code after adding

Slack にメッセージが投稿されない

• トークンが xoxb- で始まっている必要があります（xoxp-、xoxe-、xapp- ではありません）
• 各チャンネルで /invite @BugBot を実行します
• 必須スコープ：chat:write、files:write、files:read

スクリーンショットが真っ白になる

• ページの読み込みが完了していません。src/config/targets.js の pageSettleMs を大きくするか、ルートに waitFor セレクターを追加してください

/argus-retest が "dispatch_failed" を返す

• トンネル URL が変更されています。Slack App → Slash Commands の Request URL を更新し、再インストールしてください

CSS 分析で結果が空になる

• ページが認証の背後にある可能性があります。Argus が制御している Chrome インスタンスでログインしていることを確認してください

CI パイプラインがすぐに失敗する

• Chrome の起動が間に合っていない可能性があります。.github/workflows/argus.yml の sleep 3 を sleep 5 に変更してください

Argus と Playwright / Cypress の違い

Argus はユニットテストや E2E テストの代替ではなく、補完するレイヤーです。

既知の制限事項

ハーネスの 998 件のアサーションはすべて成功しています（998/998）。現在、MCP レイヤーや Chrome レイヤーの既知の制限事項はありません。Lighthouse はヘッドレスで実行されます（lighthouse_audit 引数の修正後）。残りのソフトアサーション（パフォーマンストレース、GC に依存するヒープ増加）は、週次の strict-soft レーン（harness-strict.yml）で ARGUS_HARNESS_STRICT_SOFT を介してのみ、カウント対象のハードアサーションに昇格されます。スコープの制限：Chrome／Chromium のみ、ウェブアプリのみ — お使いのスタックとの互換性をご覧ください。

ホスト型 Argus — 創設メンバー

Chrome や npm を実行せずに、履歴、トレンド、スケジュール、チームダッシュボード付きで監査を行いたいですか？Argus Cloud は創設メンバー向けの早期アクセスを提供しています。月額 $19、永久固定（通常価格は $29）です。

創設メンバーになる → argus-qa.com

このページのオープンソースエンジンは、これからも常に MIT ライセンスで、すべての機能をご利用いただけます。ホスト型プランが提供するのは利便性と履歴の保持であり、検出機能ではありません。

プロジェクト構成

src/
  argus.js              — single-page audit entry point
  mcp-server.js         — 9 MCP tools exposed to Claude / any MCP client
  orchestration/        — crawl loop, Slack/GitHub dispatch, env comparison, watch mode
  utils/                — 32 analysis engines (accessibility, security, performance, PDF, recording, etc.)
  adapters/browser.js   — CdpBrowserAdapter — wraps all chrome-devtools-mcp calls
  config/targets.js     — routes, thresholds, auth steps
  cli/
    init.js             — argus init interactive setup wizard
    chrome-launcher.js  — npm run chrome / argus-chrome — launches Chrome with correct flags
    doctor.js           — npm run doctor / argus-doctor — pre-flight checks
    pr-validate.js      — headless CI entry point for GitHub Actions
test-harness/           — 171-block correctness harness, 998 hard assertions, 64 fixture pages
test/unit/              — 562 Vitest unit tests (no Chrome required)
landing/                — Product landing page (React 19 + Vite + Tailwind)

ソース全体のマップ → CLAUDE.md · MCP／DSL リファレンス → SKILL.md

コントリビュート

コントリビュートを歓迎します — フィクスチャページ、新しい検出カテゴリ、フレームワークのルート検出、ドキュメントなど。まずは CONTRIBUTING.md をご覧ください。

1. リポジトリをフォークしてブランチを作成します
2. npm run test:unit — Chrome を使わずに検証します（562 件のテスト）
3. npm run test:harness — 統合テストをすべて実行します（Chrome がポート 9222 で必要です）
4. PR を作成します — Argus は CI ワークフローを通じて自身を監査します

ライセンス

MIT © ironclawdevs27