🇬🇧 English

@hayashiii/sitesnap

ウェブサイトのスクリーンショット(デスクトップ + モバイル)を一括キャプチャしてローカルに保管する、AIエージェントフレンドリーなCLIツール。ポートフォリオ用のサイト集めを目的として設計。

• 📁 データはJSON + PNGファイル(DB不要)
• 🤖 Claude Code / Codex などのAIエージェントから1コマンドで実行可能(Claude Code Skill同梱)
• 📡 --json フラグで構造化出力 → エージェントが結果をパース可能
• ⚙️ 構造化エラー(code + hint)でエージェントが自動リトライしやすい
• 🔧 TypeScript で実装、Bun 開発 / Node.js 22+ 配布のハイブリッド構成
• 🌐 別プロジェクト(Astro等)から meta.json を読み込んで公開ポートフォリオに統合可能

インストール

# グローバルインストール(推奨)
npm install -g @hayashiii/sitesnap
# または: pnpm add -g @hayashiii/sitesnap
# または: yarn global add @hayashiii/sitesnap

# Playwright の Chromium ブラウザを取得(初回のみ)
npx playwright install chromium

Node.js 22以上 が必要です。

Quick Start

# サイトマップから全ページを一気にキャプチャ
sitesnap site https://example.com/sitemap.xml

# 1ページだけ
sitesnap page https://example.com/about

# キャプチャ済みのサイト一覧
sitesnap list

# サイトのフォルダを Finder で開く(macOS)
sitesnap open example.com

コマンド一覧

グローバルフラグ

sitesnap list --json
# → [{ "domain": "...", "pages": 45, ... }]

sitesnap site https://example.com/sitemap.xml --force-visible --out ~/captures

Optional: agent-assisted diagnosis

通常のキャプチャ経路にAIやWebwrightは入りません。失敗した時だけ doctor を明示的に実行すると、最新runの result.json を読み、白紙っぽいスクリーンショットやtimeoutを集計して再取得案を出します。

sitesnap site https://example.com/sitemap.xml
sitesnap doctor sites/example.com/runs/latest

深掘りしたい場合は、任意のagentへ渡す調査票を生成します。Webwrightは同梱せず、ユーザーが使いたいagentに agent-task.md を渡す設計です。

sitesnap doctor sites/example.com/runs/latest --agent-task
# 生成: diagnosis.md, agent-task.md, suggested-sitesnap.config.json

アニメーション対策(デフォルトで有効)

Playwrightブラウザコンテキストに以下を自動適用しています:

• prefers-reduced-motion: reduce の送信(まともなサイトはこれでアニメ無効化)
• 全要素の animation/transition を 0.001s に短縮するCSS注入
• document.fonts.ready と全画像のロード完了を待ってから撮影

それでも真っ白なら --force-visible を試してください(AOS等のscroll-reveal対策)。

出力構造

sites/                              (--out で変更可)
├── index.json                      全サイトのサマリ
└── <domain>/
    ├── meta.json                   ページ一覧 + 画像パス + タイトル
    ├── runs/latest/result.json      最新runの診断用サマリ
    ├── runs/latest/options.json     最新runの実行オプション
    ├── desktop/<slug>.png          デスクトップ版スクショ
    └── mobile/<slug>.png           モバイル版スクショ

meta.json のスキーマ

{
  "domain": "example.com",
  "source": "https://example.com/sitemap.xml",
  "captured_at": "2026-05-01T12:00:00Z",
  "pages": [
    {
      "url": "https://example.com/",
      "slug": "index",
      "title": "ページタイトル",
      "desktop": "desktop/index.png",
      "mobile": "mobile/index.png",
      "captured_at": "2026-05-01T12:00:00Z",
      "desktop_error": null,
      "mobile_error": null
    }
  ]
}

AI Agent からの使い方

Claude Code

パッケージには skills/sitesnap/SKILL.md が同梱されています。npm install -g @hayashiii/sitesnap した瞬間から Claude Code が自動認識し、自然言語で呼び出せるようになります:

ユーザー: 「このサイト保存して: https://example.com/sitemap.xml」 Claude Code が自動的に sitesnap site … を実行

Codex CLI / その他のシェル実行可能なAIエージェント

Codex CLI はプロジェクト直下の AGENTS.md を自動で読み込むので、以下のスニペットをご自分の AGENTS.md に追記すれば自然言語で呼び出せるようになります:

## sitesnap でWebサイトをキャプチャする

このリポジトリでは `sitesnap` コマンドが利用可能です。

- `sitesnap site <sitemap-url> --json` で sitemap から全ページキャプチャ
- `sitesnap page <url> --json` で単一ページのみキャプチャ
- `sitesnap list --json` でキャプチャ済みサイト一覧

出力は stdout に JSON、進捗ログは stderr。失敗時は非ゼロ終了。

AGENTS.md を使わない他のエージェントでも、同じスニペットをシステムプロンプトや指示文に貼れば同様に使えます。

このリポジトリ自体に手を入れる場合(コントリビューター向け)は、ルートの AGENTS.md を参照してください。sitesnap のコードベースを AI エージェントで開発する際の指針が書いてあります。

設定変更(ソースを編集する場合)

src/config.ts でデフォルト値を調整できます:

• viewports.desktop … デスクトップのビューポートサイズ
• viewports.mobile … モバイルのデバイス名 (Playwright devices 参照)
• concurrency … 並列キャプチャ数(デフォルト3)
• navigationTimeout … ページ読み込みタイムアウト(ms)

ポートフォリオサイトへの統合

meta.json を静的サイトジェネレーター(Astro等)から読み込む想定で設計しています。Astroの例:

// src/pages/portfolio/[domain]/[slug].astro
import meta from '../../../path/to/sites/example.com/meta.json';

export function getStaticPaths() {
  return meta.pages.map(p => ({
    params: { domain: meta.domain, slug: p.slug },
    props: { page: p, domain: meta.domain }
  }));
}

画像パスは meta.json 内で desktop/<slug>.png 形式の相対パスなので、配信時のbaseURLと組み合わせて使ってください。

制限・注意

セキュリティ

• デフォルトで localhost / 127.x / 10.x / 192.168.x / 172.16-31.x / 169.254.x (リンクローカル) へのアクセスを拒否します(SSRF対策)。社内環境で使う場合は --allow-private を付けてください。
• http:// / https:// 以外のスキーム(file://, ftp://, data:)は受け付けません。
• HTTPリクエストには sitesnap/<version> (+<homepage>) を User-Agent として送信します。
• sitemapindex の循環参照や深いネスト(デフォルト最大5段)は自動で検出して中断します。

その他の注意

• スクショ画像はGit管理外推奨。meta.json だけGit管理に乗せるのが基本(画像はサイズ大、生成物として扱う)
• ログイン必須サイトは現状未対応(今後 Playwright の storageState で対応予定)
• JavaScriptを大量に使うSPAは networkidle で待機してますが、撮り逃しがあれば sitesnap retry <domain> で再取得を

ライセンス

MIT © 2026 Hayashi

リンク

• GitHubリポジトリ
• Issues
• npm