context-pack

Context Pack

コードベース、フォルダー、または ZIP アーカイブを、LLM のコンテキストウィンドウに最適な、整った単一のテキストブロックにまとめます。スマートなフィルタリング、対話形式での選択、見やすい Markdown 出力に対応しています。

使用する場面

次のような場合に、このスキルを使用します。

• コードベース全体を LLM に送って、分析や変更を行いたい
• 共同作業のために、プロジェクトを別の AI エージェントと共有したい
• コードレビューやデバッグ用のコンテキストを作成したい
• AI が利用しやすい形式で、ドキュメントとコードをまとめたい
• レガシープロジェクトを LLM 対応形式に変換したい

機能

1. スマートなファイル検出

• ディレクトリまたは ZIP 内のすべてのファイルを自動検出します
• .gitignore のパターンを尊重します
• よくある不要ファイルやフォルダー（node_modules、.git、ビルド成果物）を除外します
• 入れ子になったディレクトリ構造にも対応します

2. ファイル形式の検出

• テキストファイル：そのまま含めます（コード、ドキュメント、設定）
• バイナリファイル：任意で Base64 エンコードできます（画像、実行ファイル、バイナリ）
• 不明なファイル：スマートに判定し、バイナリとして処理します

3. 対話形式での選択

• まとめる前にファイルツリーをプレビューできます
• 特定のファイルやディレクトリを選択／選択解除できます
• ファイル形式、サイズ、パターンでフィルタリングできます
• 統計情報（合計サイズ、ファイル数、トークン推定値）を確認できます

4. スマートなフォーマット

出力形式：

# Context Pack: project-name

## Summary
- Source: /path/to/project
- Files: 42
- Size: 156 KB
- Token estimate: ~50,000

## File Tree

src/ ├── index.ts ├── utils/ │ └── helpers.ts └── components/ └── Button.tsx

## Files

### src/index.ts
```typescript
// File content here...

src/utils/helpers.ts

// File content here...

src/components/Button.tsx

// File content here...

### 5. Binary Handling
```markdown
## Binary Files (Base64 Encoded)

### assets/logo.png
```base64
iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAABhWlDQ1BJQ0MgcHJvZmlsZQAAKJF9kT1I
g1AcxV/TaqVVHuwQxCFDdwURXQQXU8QII0M9k9q0QhGzBjOjog7WFpaCujgEC/pBj6Bg56KOqI4K7gN+
...

## Examples

### Pack a folder
```bash
# Pack current directory
bash scripts/pack.sh .

# Pack specific directory
bash scripts/pack.sh /path/to/myproject

# Pack with binary files included
bash scripts/pack.sh . --include-binary

# Pack with specific file limit
bash scripts/pack.sh . --max-files 50 --max-size 1MB

ZIP アーカイブをまとめる

bash scripts/pack.sh project.zip

# Extract and pack
bash scripts/pack.sh archive.zip --extract-to ./temp

ファイルをフィルタリングする

# Only include TypeScript files
bash scripts/pack.sh . --include "*.ts" --include "*.tsx"

# Exclude tests
bash scripts/pack.sh . --exclude "*test*" --exclude "*spec*"

# Include only src directory
bash scripts/pack.sh . --include-dir "src"

対話形式で選択する

# Preview and select interactively
bash scripts/pack.sh . --interactive

# This shows a file tree where you can:
# - [x] Select files/folders with checkboxes
# - See file sizes and types
# - Toggle binary inclusion
# - Preview before generating

出力オプション

# Output to file
bash scripts/pack.sh . --output project-context.md

# Copy to clipboard (if available)
bash scripts/pack.sh . --clipboard

# JSON output for programmatic use
bash scripts/pack.sh . --format json

対応ファイル形式

テキストファイル（デフォルトで含める）

• コード：.js、.ts、.jsx、.tsx、.py、.java、.c、.cpp、.go、.rs、.php、.rb
• Web：.html、.htm、.css、.scss、.sass、.less
• 設定：.json、.xml、.yml、.yaml、.toml、.ini、.conf、.env
• ドキュメント：.md、.txt、.csv、.tsv、.log
• スクリプト：.sh、.bash、.zsh、.ps1、.bat

バイナリファイル（Base64 エンコードは任意）

• 画像：.png、.jpg、.jpeg、.gif、.svg、.ico、.webp、.bmp
• 実行ファイル：.exe、.bin、.app、.dll、.so、.dylib
• アーカイブ：.zip、.tar、.gz、.rar、.7z
• ドキュメント：.pdf、.doc、.docx、.xls、.xlsx、.ppt、.pptx
• その他：.mp3、.mp4、.wav、.avi、.mov、.ttf、.otf、.woff

スクリプト

scripts/pack.sh

フィルタリングと出力のオプションを備えたメインのパッキングスクリプトです。

bash scripts/pack.sh [OPTIONS] <path>

Options:
  -i, --include PATTERN      Include files matching pattern
  -e, --exclude PATTERN      Exclude files matching pattern
  -d, --include-dir DIR      Include only this directory
  --include-binary            Include binary files as Base64
  --max-files N              Maximum number of files
  --max-size SIZE            Maximum total size (e.g., 10MB, 1GB)
  --max-tokens N             Maximum token estimate
  -o, --output FILE          Output file (default: stdout)
  --format FORMAT            Output format: markdown, json, plain
  --clipboard                Copy output to clipboard
  --interactive              Interactive file selection
  -v, --verbose              Verbose output
  -h, --help                 Show help

scripts/pack-web.sh

ファイル選択用の Web ベースの対話型インターフェースを起動します。

# Launch web UI
bash scripts/pack-web.sh [path]

# Opens browser with:
# - File tree browser with checkboxes
# - Size statistics
# - Token count estimates
# - Preview before packing

scripts/unpack.sh

コンテキストパックをファイルに展開します。

bash scripts/unpack.sh <context-file> [output-dir]

# Extracts files from markdown format
# Reconstructs directory structure
# Decodes Base64 binary files

出力形式

Markdown（デフォルト）

# Context Pack: my-project

## Summary
- **Source**: /path/to/my-project
- **Packed**: 2024-03-08T10:30:15Z
- **Files**: 42 (38 text, 4 binary)
- **Size**: 156 KB
- **Token Estimate**: ~52,000 tokens

## File Tree

my-project/ ├── src/ │ ├── index.ts │ ├── utils/ │ │ └── helpers.ts │ └── components/ │ └── Button.tsx ├── package.json └── README.md

## Files

### package.json
```json
{
  "name": "my-project",
  "version": "1.0.0",
  "type": "module"
}

src/index.ts

import { Button } from './components/Button';

export function init() {
  const button = new Button('Click me');
  button.render();
}

src/utils/helpers.ts

export function formatDate(date: Date): string {
  return date.toISOString().split('T')[0];
}

バイナリファイル（Base64 エンコード）

assets/logo.png

iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAA...

---

Context Pack スキルでパッキング

### JSON Format
```json
{
  "pack": {
    "name": "my-project",
    "source": "/path/to/my-project",
    "packed_at": "2024-03-08T10:30:15Z",
    "stats": {
      "files": 42,
      "text_files": 38,
      "binary_files": 4,
      "size_bytes": 156432,
      "estimated_tokens": 52000
    },
    "file_tree": {
      "name": "my-project",
      "type": "directory",
      "children": [...]
    }
  },
  "files": [
    {
      "path": "package.json",
      "type": "text",
      "size": 234,
      "content": "{...}"
    },
    {
      "path": "src/index.ts",
      "type": "text",
      "size": 567,
      "content": "import..."
    },
    {
      "path": "assets/logo.png",
      "type": "binary",
      "size": 12345,
      "encoding": "base64",
      "content": "iVBORw0KGgo..."
    }
  ]
}

トークン数の推定

LLM のコンテキストウィンドウ向けのおおよそのトークン数：

ファイル形式	おおよそのトークン数
英語のテキスト	1 トークンあたり約 4 文字
コード	1 トークンあたり約 3 文字
JSON	1 トークンあたり約 2 文字
Base64 バイナリ	1 トークンあたり約 1 文字

簡易推定：

• コード 1 KB ≈ 300 トークン
• テキスト 1 KB ≈ 250 トークン
• Base64 1 KB ≈ 1000 トークン（大きなバイナリは避けてください）

コンテキストウィンドウの上限：

• GPT-4：約 8K～32K トークン
• Claude：約 100K～200K トークン
• Gemini：約 1M トークン

対話モード

--interactive を使用すると、ファイル選択用の TUI（テキストユーザーインターフェース）が表示されます。

Context Pack - Interactive Mode
================================

File Tree (use arrows to navigate, space to select)
[✓] my-project/
  [✓] src/
    [✓] index.ts                                      567 B
    [✓] utils/
      [✓] helpers.ts                                 1.2 KB
    [✓] components/
      [✓] Button.tsx                                  890 B
  [✓] package.json                                  234 B
  [ ] node_modules/                                 [skip]
  [ ] .git/                                         [skip]

Statistics:
  Selected: 5 files, 2.9 KB
  Skipped: 847 files (node_modules, .git)
  Est. tokens: ~9,500

Commands:
  [SPACE] Toggle selection  [A] Select all  [N] None
  [E] Exclude pattern       [I] Include pattern
  [B] Toggle binary files   [P] Preview
  [ENTER] Generate pack     [Q] Quit

注意事項

• プライバシー：すべての処理はローカルで行われ、ファイルはアップロードされません
• 大規模なコードベース：上限内に収まるよう、--max-files と --max-tokens を使用してください
• バイナリファイル：大きなバイナリファイルはコンテキストを肥大化させるため、除外を検討してください
• トークン数：推定値は概算であり、実際のトークン数はモデルによって異なります
• Markdown を推奨：LLM は Markdown の構造を適切に解析できます
• ファイルの順序：一貫した出力になるよう、ファイルはパス順に並べ替えられます
• 重複排除：同一のファイルは一度だけ含められます
• 循環参照：シンボリックリンクは解決され、適切に処理されます