画像を説明文とタグ付きで保存し、あとからテキスト検索で取り出せる画像ストレージ。Claude Code や Codex の Agent Skills から呼び出せるので、エージェントとの会話の中で画像の保存・検索ができる。Cloudflare R2 + D1 + FTS5 で動作。

Why imgsearch?

画像はどんどん増えるのに、探すのは大変。フォルダを掘ったり、ファイル名を思い出したり。

imgsearch があると：

• テキストで画像検索 — 「猫の写真」「ログイン画面」など、説明文で全文検索して即取得
• タグで整理 — 自由にタグを付けて分類、タグで絞り込み
• 日付で絞り込み — --from 2026-03-01 --to 2026-03-31 で期間指定
• どこからでもアクセス — Cloudflareに保存されるので、端末やメンバーを跨いで共有
• エージェントから直接操作 — Claude Code / Codex の会話中に保存・検索

Architecture

Workflow

Screenshots

Features

• 全文検索 — 説明文をFTS5で検索、タグ・日付での絞り込み
• CLI + ダッシュボード — ターミナルでもブラウザでも操作可能
• Agent Skills対応 — --json フラグでClaude Code / Codex から直接操作
• Cloudflare完結 — R2（画像）+ D1（メタデータ）、セルフホストなし

Prerequisites

• Node.js 20+
• pnpm
• Cloudflare アカウント

Cloudflare リソースの作成

# D1 データベース
npx wrangler d1 create imgsearch

# R2 バケット
npx wrangler r2 bucket create imgsearch

API Token — Cloudflare Dashboard → My Profile → API Tokens → 権限: D1 Edit + Workers R2 Storage Edit

R2 S3互換APIキー — Cloudflare Dashboard → R2 → Manage R2 API Tokens → Read & Write

Installation

git clone https://github.com/your-username/imgsearch.git
cd imgsearch
pnpm install
pnpm build
npm link

Configuration

imgsearch init

| 項目 | 取得場所 | |------|---------| | Account ID | Cloudflare Dashboard 右サイドバー | | API Token | 上記で作成したトークン | | D1 Database ID | wrangler d1 create の出力 | | R2 Bucket Name | imgsearch | | R2 Access Key ID | R2 S3 APIトークン | | R2 Secret Access Key | R2 S3 APIトークン |

設定は ~/.config/imgsearch/config.toml に保存されます。

Usage

全コマンド --json フラグ対応。

画像を追加

# ローカルファイル
imgsearch add screenshot.png -d "ログイン画面のエラー" --tags error,login

# URL指定
imgsearch add https://example.com/image.png -d "トップページ" --tags ui

検索

# 全文検索 (FTS5)
imgsearch search "ログイン エラー"

# タグフィルタ
imgsearch search --tag error

# 組み合わせ
imgsearch search "バナー" --tag ui

取得・更新・削除

imgsearch get <id>                                          # 詳細取得
imgsearch update <id> -d "更新後の説明" --tags error,fixed  # メタデータ更新
imgsearch delete <id>                                       # 削除
imgsearch list --tag error --limit 50                       # 一覧

Dashboard

imgsearch preview
# → http://localhost:8080

ブラウザで画像の閲覧・検索・タグフィルタ・編集・削除・アップロードができます。

Agent Skills

AIエージェント（Claude Code 等）から --json フラグで呼び出す：

# スクリーンショットを保存
imgsearch add /tmp/screenshot.png -d "Login page error banner" --tags error,login --json

# 検索
imgsearch search "login error" --json

# 取得
imgsearch get 01KMW749KJ9P2B5X3QY60WFWYB --json

{
  "id": "01KMW749KJ9P2B5X3QY60WFWYB",
  "description": "Claude Codeのロゴ・サムネイル画像",
  "tags": ["claude-code", "logo"],
  "url": "https://...r2.cloudflarestorage.com/images/01KMW749KJ9P2B5X3QY60WFWYB.png?...",
  "contentType": "image/png",
  "fileSize": 73925,
  "createdAt": "2026-03-29T07:14:58.646Z"
}

Tech Stack

| Category | Technology | |----------|-----------| | Language | TypeScript (ESM) | | Runtime | Node.js 20+ | | Image Storage | Cloudflare R2 (S3-compatible) | | Metadata DB | Cloudflare D1 (SQLite) | | Search | FTS5 full-text search | | CLI | commander | | Dashboard | hono + vanilla JS | | Validation | zod | | Build | tsup | | Test | vitest |

Limitations

• 対応画像形式: PNG, JPEG, GIF, WebP
• 最大ファイルサイズ: 50MB
• ダッシュボード: localhost のみにバインド（外部からアクセス不可）

License

MIT