miku-indexgen

miku-indexgen is a CLI tool that scans a directory and generates index.json. When Markdown output is enabled, it also generates index.md.

It is intended for AI agents and programs that need a compact overview of available files before reading them in full.

Install

Run with npx:

npx miku-indexgen --input-directory <dir>

Or install globally:

npm install -g miku-indexgen
miku-indexgen --input-directory <dir>

Quick Start

Generate an index from one directory:

npx miku-indexgen --input-directory docs

This generates:

• docs/index.json

Generate both JSON and Markdown:

npx miku-indexgen --input-directory docs --markdown

This generates:

• docs/index.json
• docs/index.md

Write outputs to a separate directory:

npx miku-indexgen --input-directory docs --output-directory out --markdown

This generates:

• out/index.json
• out/index.md

When --output-directory is omitted, outputs are written under inputDirectory.

CLI Options

Option	Description
--input-directory <dir>	Directory to scan.
--output-directory <dir>	Directory to write index.json and optional index.md. When omitted, outputs are written under the input directory.
--title <text>	Add a root-level title to generated JSON.
--markdown	Also generate index.md.
--no-generator	Omit root-level generator metadata from generated JSON.
--json-summary-path <paths>	Comma-separated JSON Pointer list used to extract JSON summaries, for example /title,/name.
--no-recursive	Disable recursive scanning under the input directory.
--no-overwrite	Skip writing when an output file already exists.
--include-ext <exts>	Comma-separated list of file extensions to include, for example md,json.
--input-encoding <encoding>	Input text encoding. Supported values are utf8 and shift_jis.
--output-encoding <encoding>	Output text encoding. Supported values are utf8 and shift_jis.
--verbose	Emit progress diagnostics and timing details.

Output

Generated JSON uses a flat files array as the canonical structure.

Root-level fields:

• title optional
• generator optional, omitted when --no-generator is specified
• basePath
• files

Each file entry includes:

• name
• path
• ext
• dir
• size
• summary optional

For Markdown files, summary is extracted from the first heading or from the leading body text.

For JSON files, summary is omitted by default. When --json-summary-path is specified, each path is treated as a JSON Pointer and the first matching string value is used.

Examples

Add a title:

npx miku-indexgen --input-directory docs --title "Docs Index"

Prefer JSON package names over descriptions:

npx miku-indexgen --input-directory docs --json-summary-path /name,/description

Prefer nested metadata first:

npx miku-indexgen --input-directory references --json-summary-path /frontmatter/title,/metadata/title,/title

Read and write Shift_JIS:

npx miku-indexgen --input-directory docs --input-encoding shift_jis --output-encoding shift_jis --markdown

More Information

• Development notes: docs/development.md
• Architecture memo: docs/architecture.md
• Software style memo: docs/software-style.md

---

miku-indexgen

miku-indexgen は、ディレクトリを走査して index.json を生成する CLI ツールです。 Markdown 出力を有効にした場合は、index.md も生成します。

全文を読む前に、利用可能なファイルの全体像を把握したい生成AI やプログラム向けのツールです。

インストール

npx で実行:

npx miku-indexgen --input-directory <dir>

またはグローバルインストール:

npm install -g miku-indexgen
miku-indexgen --input-directory <dir>

クイックスタート

1つのディレクトリをインデックス化:

npx miku-indexgen --input-directory docs

生成物:

• docs/index.json

JSON と Markdown の両方を生成:

npx miku-indexgen --input-directory docs --markdown

生成物:

• docs/index.json
• docs/index.md

出力先を別ディレクトリに分離:

npx miku-indexgen --input-directory docs --output-directory out --markdown

生成物:

• out/index.json
• out/index.md

--output-directory を省略した場合は、入力ディレクトリ配下に出力します。

CLI オプション

Option	Description
--input-directory <dir>	走査対象のディレクトリ。
--output-directory <dir>	index.json と任意の index.md の出力先ディレクトリ。省略時は入力ディレクトリに出力。
--title <text>	生成する JSON のルートに title を追加。
--markdown	index.md も生成。
--no-generator	生成する JSON のルートから generator メタデータを省略。
--json-summary-path <paths>	JSON summary を抽出するための JSON Pointer をカンマ区切りで指定。例: /title,/name
--no-recursive	入力ディレクトリ配下の再帰走査を無効化。
--no-overwrite	出力ファイルが既に存在する場合は書き込みをスキップ。
--include-ext <exts>	対象拡張子のカンマ区切り一覧。例: md,json
--input-encoding <encoding>	入力テキストの文字コード。対応値: utf8, shift_jis
--output-encoding <encoding>	出力テキストの文字コード。対応値: utf8, shift_jis
--verbose	進行状況や処理時間の詳細を出力。

出力

生成される JSON は、フラットな files 配列を正本とする構造です。

ルート要素:

• title 任意
• generator 任意。--no-generator 指定時は省略
• basePath
• files

各ファイル要素:

• name
• path
• ext
• dir
• size
• summary 任意

Markdown ファイルの summary は、最初の見出しか先頭本文から抽出します。

JSON ファイルの summary はデフォルトでは省略されます。--json-summary-path を指定した場合は、JSON Pointer を左から順に評価し、最初に見つかった文字列値を使います。

例

タイトルを付ける:

npx miku-indexgen --input-directory docs --title "Docs Index"

package.json のような JSON で名前を優先:

npx miku-indexgen --input-directory docs --json-summary-path /name,/description

ネストしたメタデータを優先:

npx miku-indexgen --input-directory references --json-summary-path /frontmatter/title,/metadata/title,/title

Shift_JIS で読み書き:

npx miku-indexgen --input-directory docs --input-encoding shift_jis --output-encoding shift_jis --markdown

追加情報

• 開発メモ: docs/development.md
• アーキテクチャメモ: docs/architecture.md
• ソフトウェアスタイルメモ: docs/software-style.md