orstrum summarize

Generate an LLM "Purpose" summary for a file, or for the whole graph in batch mode.

$ orstrum summarize [path] [options]

With no path, summarize runs in batch mode over every indexed file. Pass a path to summarize a single file. It reads ORSTRUM_ANTHROPIC_API_KEY from the environment (or a .env in the working dir); pass --use-claude-code to invoke via your local claude CLI and Pro/Max quota instead.

How it works

For each file being summarized, summarize sends the file's full source plus a small amount of import context (first-sentence purposes of its resolved imports) to the model, and stores the resulting Purpose sentence in graph.db. Raw source is only sent to the model — it is never stored in the graph.

Whether a stored summary is still valid is decided by a content hash: sha256(inputHash + model + promptVersion). Note that the import context is deliberately excluded from this hash — otherwise a file's summary would be invalidated every time a neighbor's purpose changed, causing unbounded re-summarization. A summary is regenerated when the file's content, the model, or the prompt version changes (or when you pass --force).

Options

-c, --config <path>

string

Config file path. Defaults to the nearest orstrum.config.*.

--dry-run

flag

Print what would be sent without invoking the model.

--force

flag

Regenerate the Purpose even if the source hasn't changed since the last summary.

--use-claude-code

flag

Invoke via the local claude CLI (Pro/Max subscription quota) instead of the API. Slower and pricier for large batches.

--max-files <n>

number

Batch mode: process at most N files.

--changed-only

flag

Batch mode: only files whose summaryHash no longer matches (skips stubs with no stored hash).

--paths <glob>

string

Batch mode: filter to files matching this glob pattern.

--concurrency <n>

number

Parallel API calls. Default 2 (also ORSTRUM_CONCURRENCY or summarize.concurrency in config).

--max-retries <n>

number

Total attempts per file on 429 rate-limit errors. Default 5 (also ORSTRUM_MAX_RETRIES or summarize.maxRetries in config).

-y, --yes

flag

Auto-accept the onboarding init prompt when no config is found.

Summaries are optional but significantly improve orstrum_search and orstrum_get_summary quality. You only pay for LLM generation once per unique file version, model, and prompt version.

Cost and token usage per file are stored in the summaries table alongside the purpose text, so you can audit what was generated and at what cost.