scree

scree

リポジトリやメモの Markdown をローカルでセマンティック検索し、MCP 経由で Claude Code に提供します。

Scree は Markdown を見出しごとに分割し、API 経由で各部分をベクトル化して、フォルダーごとに 1 つのインデックスをディスク上の SQLite ファイルに保存します。Claude Code はファイル全体を読み込む代わりに、質問に一致する少数のチャンクをリクエストします。一致した箇所には元の行番号が示されるため、Claude は該当箇所だけを読めます。正本は Markdown のままなので、インデックスはいつでも削除して再構築できます。

設計については docs/SPEC.md を参照してください。

クイックスタート

Go 1.26 と https://openrouter.ai/settings/keys で取得できる OpenRouter API キーが必要です。手順に特に記載がない限り、コマンドはこのリポジトリのルートから実行します。

1. ビルド：CGO を使わない静的バイナリを作成します。

   CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/scree ./cmd/scree
   

2. キーを保存：設定ファイルに保存します。scree key は入力内容を画面に表示せずにキーの入力を求めるため、シェルの履歴にも画面にも残りません。~/.config/scree/env をモード 600 で書き込み、API へのテスト呼び出しを 1 回行います。

   bin/scree key
   

   ファイル内のほかの行は保持し、以前のキーがあれば置き換えます。scree key < file を使うと、ファイルの先頭行からキーを読み込みます。この場合、保存済みのキーを置き換えるには -replace が必要です。-offline を指定するとテスト呼び出しを省略し、-check を指定するとテスト呼び出しだけを行います。プロンプトで Ctrl-C を押すと、何も保存されません。自分の検索とは別に Claude Code の OpenRouter 利用料を確認するには、bin/scree key -mcp で 2 つ目のキーを保存します。すると scree mcp はそのキーを使い、それ以外は最初のキーを使います（設定ファイル）。

3. インストール：バイナリをインストールします。

   mkdir -p ~/.local/bin
   install -m 755 bin/scree ~/.local/bin/
   

   Claude Code が scree を PATH 上で見つけられる必要があります。~/.local/bin が PATH に含まれていない場合は、シェルのプロファイルに追加してください。

4. インデックス作成前にリポジトリを確認：scree run は設定ファイルを読み込み、scree コマンドを実行します。リポジトリ内から次を実行します。

   cd ~/code/myrepo
   scree run doctor -v
   

   doctor -v は無視されるすべてのファイルを一覧表示し、残りをインデックス化するコストを見積もります。インデックス化可能なファイルに非公開の情報が含まれていた場合は、インデックスを作成する前に.screeignore または .gitignore に追加してください。

5. リポジトリで scree を有効化：リポジトリのルートから次を実行します。

   claude mcp add scree --scope project -- scree mcp
   

   キーやパスを含まない "command": "scree", "args": ["mcp"] を設定した .mcp.json が書き込まれるため、これをコミットしてください。Claude Code は各ユーザーにプロジェクトサーバーの承認を一度求めます。その後、リポジトリ内のすべてのセッションでインデックスが最新の状態に保たれ、最初のセッションではバックグラウンドでインデックスが作成されます。serve は、リポジトリ自身の .mcp.json に scree mcp が指定されていない場合、そのリポジトリを拒否します。そのため、ほかの場所にも scree が登録されていても、この設定がないリポジトリがインデックス化されることはありません。scree をユーザースコープに登録することも避けてください。

   プロジェクトサーバーを承認することは、そのリポジトリを信頼することを意味します。 Claude Code はサーバーを起動する前に、PATH を含むリポジトリの .mcp.json の env を適用します。つまり、承認したリポジトリが scree として実行されるプログラムを決め、そのプログラムが設定ファイルにアクセスできるということです。ほかのプロジェクトサーバーと同様に、信頼できる .mcp.json を持つリポジトリでのみ scree を承認してください。この設定を自分で変更する方法については、絶対パスを参照してください。

6. 任意：リポジトリ外のメモフォルダー：メモ用フォルダーを参照してください。

ビルド

Go 1.26 が必要です。CGO は不要です。タグ付きリリースでは、GitHub のリリースページで Linux、macOS、Windows 用（amd64 および arm64）のビルド済みバイナリ、ghcr.io/jrapakko/scree イメージ、およびClaude Desktop バンドルも公開されます。バンドルは scripts/mcpb.sh がリリースのバイナリから zip 形式で作成します。

CGO_ENABLED=0 go build -trimpath -ldflags='-s -w' -o bin/scree ./cmd/scree

設定

設定は環境変数から読み込まれます。設定ファイルは、API キーも含め、設定を一元管理するファイルです。シェルのプロファイルでキーを export しないでください。OPENROUTER_API_KEY が設定されていない場合でも、コマンドを直接実行（scree search、doctor、reindex、watch）すれば、scree run と同様に設定ファイル内のキーが使われます。詳しくは以下をご覧ください。

変数	デフォルト
SCREE_DB	$XDG_DATA_HOME/scree/indexes/<folder>-<hash>/index.db。フォルダーごとに 1 つ（または -db）
SCREE_MODEL	openai/text-embedding-3-small
SCREE_DIMENSIONS	512。0 を指定するとモデルのデフォルトサイズを使います
SCREE_EMBED_URL	https://openrouter.ai/api/v1/embeddings
SCREE_MAX_FILE_BYTES	1048576。これより大きいファイルはスキップされます
SCREE_FIRST_SYNC_MB	50。フォルダー内の Markdown がこのサイズを超える場合、Claude Code セッションまたは watch は最初のインデックス作成を開始しません（0 = 制限なし）。scree reindex は常に実行します
SCREE_ZDR	1。OpenRouter 以外のエンドポイントでは 0 を設定します
SCREE_HTTP_TOKEN	なし。serve -allow-remote では必須です。設定されている場合はループバックでも適用されます
SCREE_PAGER	/usr/local/bin、/usr/bin、または /bin にある less -FRX。ターミナルでの scree search のテキスト表示に使うページャーです。シェルを介さずに実行されます。絶対パス、またはこれらのフォルダー内の名前を指定し（PATH からは検索されません）、その後に引数を指定します。空にするとページャーを使いません
SCREE_COLORS	word=1:match=1;33:link=36:lineno=2。テキスト表示で、見出し語、一致した語、場所、行番号に使う SGR コードの色です（数字と ; のみ）。match= を指定すると、一致した語の色を無効にします
OPENROUTER_API_KEY	なし。設定ファイルにキーがある場合（scree key で書き込みます）、未設定でも search、reindex、doctor、watch は scree run と同様に実行されます。キーがない場合（未設定または空）、ノートはキーワード検索専用でインデックス化され、auto 検索は keyword を実行します
SCREE_MCP_API_KEY	なし。設定ファイルからのみ読み込まれ（scree key -mcp で書き込みます）、scree mcp のみが使用します。scree mcp はこのキーを、設定ファイル内のキーの代わりに OPENROUTER_API_KEY として serve に渡します。コマンドを直接実行した場合も scree run も、このキーは使用しません

$XDG_DATA_HOME のデフォルトは ~/.local/share です。相対パスは無視されます。これも絶対パスのホームディレクトリもない場合、-db で指定されていない限り、scree はインデックスを開きません。

対象フォルダー。 -notes <dir> でコマンドラインから指定します。指定がない場合、CLI コマンドは現在のディレクトリの git ルートを使い、git 管理下にない場合は現在のディレクトリを使います。Claude Code の実行環境では、serve は Claude Code の起動時の作業ディレクトリ（プロジェクトまたはアクティブなワークツリー）の git ルートをインデックス化します。-notes、-db、SCREE_DB は指定できず、CLAUDE_PROJECT_DIR が同じリポジトリ内にある必要があります。.mcp.json では環境変数を設定できますが、作業ディレクトリは設定できません。また、ルートの .mcp.json に scree mcp サーバーが指定されていないフォルダーも拒否します。Claude Code の外では、serve にデフォルトの対象フォルダーはありません。-notes を指定してください。自動検出されたフォルダーがホームディレクトリ（パスワードデータベースから取得し、その参照に失敗した場合のみ $HOME を使用）、その親フォルダー、またはファイルシステムのルートにあたる場合は拒否されます。コマンドラインでは -notes を指定すれば、そのようなフォルダーもインデックス化できます。serve では、-allow-home を指定しない限り、-notes で指定した場合もそのようなフォルダーを拒否します（Claude Desktop などのクライアントは、ユーザーが選んだフォルダーを渡します）。このチェックではパスだけでなくフォルダー自体を比較するため、ホームフォルダーへの別のパス（バインドマウント、macOS での大文字・小文字の違い、/System/Volumes/Data/Users/…）も拒否されます。比較対象は選択したフォルダーとホームフォルダーおよびその親フォルダーのみです。そのため、ホームフォルダーを内部にマウントしたフォルダー（コンテナーや開発用コンテナーで設定されることがあります）は検出されません。各インデックスには対象フォルダーが記録され、別のフォルダーでの使用は拒否されます。

モデルや次元を変更するには、scree reindex -all が必要です。インデックスには作成に使ったモデルが記録され、異なるモデルを混在させることはできません。

プライバシー

すべての埋め込みリクエストでは、OpenRouter に対して、データを保持せず、data_collection: deny に設定されたエンドポイントだけにルーティングするよう求めます。そのようなエンドポイントがないモデルの場合、データを保持するエンドポイントにフォールバックせず、モデル名を明示したわかりやすいエラーが発生します。SCREE_ZDR=0 を設定すると、この機能は無効になります。他の OpenAI 互換エンドポイントでは、無効にする必要がある場合があります。API に送信されるのは、パスと見出しを添えたチャンクテキストだけです。キーワード検索はローカルで実行されます。

ファイルの除外

除外されたファイルは、インデックス作成のために読み込まれることも、埋め込み API に送信されることも、検索結果として返されることもありません。また、read_doc と reindex からも拒否されます。判定には次の 4 つのレイヤーが使われます。

• 組み込みルール： 隠しファイルと隠しフォルダー。ただし、ルートの .claude/（.claude/worktrees/ を除く）、.github/、.gitlab/、.gitea/、.forgejo/、.cursor/、.codex/、.gemini/、.windsurf/、.circleci/、.buildkite/ は除きます。また、.md、.markdown、.mdc 以外のファイル、フォルダーの外部を指すシンボリックリンク、SCREE_MAX_FILE_BYTES を超えるファイル、FIFO などの通常ファイルではないファイル（開かれることはなく、doctor が読み取り不能として報告します）、制御文字を含む名前も除外されます。
• .gitignore： Git リポジトリでは、Git が除外するすべての項目（ネストされた .gitignore ファイル、.git/info/exclude、グローバル除外ファイル）が対象です。node_modules/ のような除外フォルダーは読み込まれず、ネストされたリポジトリもスキップされます。パターンに一致する追跡対象ファイルも除外されます。-gitignore=false を指定すると、このレイヤーは無効になります。
• インデックス作成対象フォルダーのルートにある .screeignore。gitignore 構文を使用します。
• フロントマター： ファイルのフロントマターに scree: ignore を指定します。

# .screeignore
journal/
**/private-*.md
/inbox/scratch.md
!journal/public.md

.screeignore に include-hidden .name/ を指定すると、別のルート隠しフォルダーがインデックスされます。また、/.cursor/ のようなパターンを指定すると、既定の除外対象の 1 つを解除できます。! ルールは除外フォルダー内のファイルを再度含めますが、名前で一致したファイルは再度含めません。そのため、*.private.md は !archive/2024/ の下にあっても除外されたままです。doctor -v では、! によって再度含められた項目が表示されます。.screeignore を読み取れない場合、シンボリックリンクである場合、または scree が解析できない行がある場合は、修正されるまで何もインデックスされません。doctor は問題のある行を行番号で示します。

---
scree: ignore
---

パターンを信頼して使う前に、scree doctor -v を実行して、各レイヤーで何が除外されるかを確認してください。ルールの詳細は docs/SPEC.md を参照してください。

使用方法

scree key                # save the API key in the settings file
scree key -mcp           # optional: a separate key for scree mcp (Claude Code)
scree doctor             # check config, index, and the API
scree doctor -v          # also list every ignored file, and check the keyword index
scree reindex            # index new and changed files
scree reindex docs/a.md  # re-index one file
scree reindex -all       # rebuild from scratch
scree search "how do I rotate the backup keys"
scree search -mode keyword PURGE_OLD_RECORDS   # exact words, no API call
scree search -format text "ci seed"              # hits grouped by query word (the default on a terminal)
scree search -no-pager "ci seed"                 # the same, printed without the pager
scree search -format json "…"                    # one JSON object per hit
scree search -format grep "…"                    # path:line:text, for fzf or vim -q
scree watch              # keep the index current (run as a service)
scree serve -notes .     # MCP over stdio, from a terminal
scree serve -notes . -http 127.0.0.1:7077   # MCP over HTTP, loopback only
scree indexes            # list per-folder indexes; -prune deletes ones whose folder is gone

indexes と key を除くすべてのコマンドは、-notes <dir>、-db <file>、-gitignore=false を受け取ります。Claude Code の外部で serve を使うには -notes が必要です。ターミナルから実行する場合、OPENROUTER_API_KEY が未設定で、設定ファイルにキーが保存されていれば、search、reindex、doctor、watch は scree run <command> と同じように動作します。scree run はいずれの場合も設定ファイルを読み込みます。たとえば、scree run search "…" のように実行します。

検索モード

scree search -mode と search_docs ツールの mode で指定できるのは、次のとおりです。

• auto（既定値）：通常は semantic です。ただし、クエリに識別子のような単語、文字と _ または数字を含む単語（PURGE_OLD_RECORDS、psycopg_pool、R7-Q2、v2 など）、またはフォルダーのコード語彙（下記参照）に含まれる単語がある場合は、hybrid になります。ID、API、2026、well-known は該当しません。
• hybrid：チャンクテキスト、見出し、パスを対象とするベクトル検索と SQLite FTS5 キーワード検索を組み合わせ、相互順位融合で結果を統合します。そのため、完全一致する名前が上位に表示されます。
• semantic：ベクトル検索のみです。
• keyword：FTS5 のみです。API を呼び出さないため、キーがない場合や API が停止している場合でも動作します。埋め込み呼び出しに失敗した場合は、その旨が表示されます。

API キーがない場合、auto は keyword を実行し、出力の末尾に [mode: auto → keyword: no API key; run scree key, or set OPENROUTER_API_KEY] が表示されます。-mode semantic または hybrid はエラーになります。serve は設定ファイルを直接読み込みません。Claude Code では同じメッセージが表示されます（scree mcp がファイル内のキーを渡します）。それ以外の環境（Claude Desktop など）では、add an OpenRouter API key in the extension's settings, set OPENROUTER_API_KEY, or start through scree mcp と表示されます。Windows では、scree key と scree mcp の部分は省略されます。 キーがなくても、インデックス作成は引き続き機能します。各ノートはチャンク化され、API を呼び出さずにキーワード検索用として保存されます。また、reindex はそれらのファイルを indexed (N keyword only: no API key) と報告します。キーを設定すると、次回の同期（scree reindex、またはライターの起動時）に、そのファイルだけが埋め込み処理されます。それまでは、semantic と hybrid では見つからず、その旨が表示されます（[N files indexed for keyword search only; scree reindex embeds them]）。また、scree doctor はインデックスの行でそれらを数えます。キーがある状態での API エラーや停止は、キーなしとして扱われません。ファイルはこれまでどおり失敗するか、API の応答を待ちます。API に拒否されたキー（401）の場合、そのプロセスでは以降、API に再度問い合わせずにキーワード検索用としてのみインデックスを作成します。auto は keyword を実行し、the embedding API rejected the API key; replace it: <hint> と表示します。動作するキーを使った次のプロセスでは、そのファイルが埋め込み処理されます。OpenRouter がモデレーションでフラグを立てた入力に対して返す 403 は、ほかの API エラーと同様に、そのファイルだけを失敗させます。キーが拒否されたとは見なされません。

Scree は OPENROUTER_API_KEY の前後にある空白と改行を取り除きます。値が未入力の ${...} プレースホルダーである場合、または scree key が拒否する値（内部の空白、制御文字、引用符を含む値）である場合は、キーなしとして扱われます。値を表示しないログが 1 行出力されます。

実際のノートを対象とした、平易な自然言語のクエリ 16 件と識別子のクエリ 7 件による非公開の評価では、auto は平易な質問のファイル MRR を 0.89 に保ちながら、識別子の MRR を 0.46 から 0.80 に引き上げました。常時 hybrid を使うと、識別子の検索精度は同程度に向上しますが、平易な質問の精度が下がるため、デフォルトにはなっていません。

コード用語の語彙は、psycopg や PageFetcher のように _ も数字も含まない名前を検出します。各同期では、Markdown と同じ除外ルールを適用しつつ、隠しフォルダー内は決して対象にせず（.claude/ 形式の許可リストは Markdown 用です）、requirements*.txt、pyproject.toml、package.json、go.mod、Cargo.toml に含まれる依存関係の名前と、Python、JavaScript、TypeScript、Go のファイルにあるインポート文や宣言内の大文字小文字が混在する名前（PageFetcher、useState）を読み取ります。ベンダー提供のフォルダーと変更されていないファイルはスキップされ、1 回の同期で開くファイルは最大 20,000 件です。パッケージ名であっても、一般的な単語は除外されます。golang.org/x/sync から追加されるのはその完全なパスだけです。また、約 350 語のストップリストで、機能語（how、the）、一般語と同じパッケージ名（sync、requests、next、config）、大文字小文字が混在する通常の単語（setUp、fileName）を除外します。除外されなかった単語があると、平易な質問でも hybrid に振り分けられる場合があります。クエリ内の PageFetcher's は PageFetcher として扱われます。小文字に変換した名前だけがローカルインデックスに保存されます。コードがチャンク化、埋め込み処理、API への送信をされることはありません。コードとドキュメントがある 2 つのリポジトリでは、コード名を含む質問の検索結果が少し向上し、平易な質問が hybrid に振り分けられることはありませんでした。

ルーティングには語彙のみが使われ、ノートにその名前が含まれているかどうかは関係ありません。hybrid のキーワード側はクエリの全単語に一致するため、ドキュメントにその名前がほとんど登場しなくても、コード名を含む質問の検索結果は向上します。抽出処理はパーサーではなく、行単位のヒューリスティックです。そのため、たとえば文字列内のテキストを名前として誤認することがあります。このような誤認が起こっても、質問が hybrid に振り分けられる可能性があるだけで、その名前が出力されたり埋め込み処理されたりすることはありません。scree doctor は、読み取った名前の数と、そのうちノートにも含まれる名前の数を報告します（pagefetcher は PageFetcher に一致します。golang.org/x/sync のようなドットやスラッシュを含む名前は、フレーズとして一致する必要があります）。-v では後者のサンプルのみが表示されます。コードにしか見つからない名前は決して表示されません。

クエリが構文として FTS5 に渡されることはありません。各単語は引用符で囲まれた語句になります。単語内の _ と - は保持されるため、psycopg_pool は 1 つの語句として扱われます。pool だけでは、ベクトル側でのみ検索されます。

結果

ターミナルで scree search を実行すると、クエリの単語ごとにまとめられたテキストビューが表示されます。各ヒットは、キーワード検索でテキスト、パス、または見出しに最初に含まれるクエリの単語の下に1回だけ表示されます。見出しと、その単語を含む行（最大10行、各行160文字で切り詰め）が続き、その後に場所、さらに現在のファイルにあるその範囲の全行が行番号付きで表示されます（同じ無視ルールを適用して読み込み、3,500バイトで切り詰めます）。クエリの単語を含まないヒット（通常はセマンティック検索のみのヒット）と古いヒットは最後に表示されます。古いヒットには行番号付きの行がありません。

seed:
  ### 5.1 Files
  - `.forgejo/workflows/ci.yml`: build, test, and the seed from the run number
	>docs/plan.md:189-191
		>>189  ### 5.1 Files
		>>190
		>>191  - `.forgejo/workflows/ci.yml`: build, test, and the seed from the run number

other hits:
  ## Keys
	>docs/keys.md:3-4
		>>3  ## Keys
		>>4  Rotate them yearly.

  # Old notes
	>docs/old.md (stale)
[mode: auto → hybrid]

単語はキーワード検索と同様にトークン全体に一致し、ノートに書かれたパス内（ci は .forgejo/workflows/ci.yml に一致します）や改行をまたいだ場合も一致します。OSC 8 リンクに対応しているターミナルでは、各場所がファイルへのリンクになります。抜粋と行番号付きの行では、一致した箇所のクエリの単語に色が付きます。また、単語の見出し、場所、行番号にもそれぞれ色が付きます（SCREE_COLORS）。リンクと色を無効にするには、NO_COLOR または TERM=dumb を設定します（scree run search もこれに従います）。セマンティック検索のヒットを含まない grep のようなビューには、-mode keyword を使用します。

ターミナルではテキストビューがページャーを通して表示されるため、先頭から始まります。ページャーは less -FRX（ビューが1画面に収まる場合はすぐに終了し、色とリンクをそのまま表示し、終了後もテキストを画面に残します）または SCREE_PAGER で指定できます。less 566以降は -R で OSC 8 リンクをそのまま表示しますが、それより古いバージョンではリンクがエスケープシーケンスとして表示されるため、その場合は -no-pager または SCREE_PAGER= を使用してください。-no-pager、SCREE_PAGER=（設定済みだが空）、パイプ、または起動できないページャーを指定した場合は、直接出力されます。ページャーを途中で終了してもエラーにはなりません。LESSCHARSET を設定しない場合、ページャーは LESSCHARSET=utf-8 で実行されるため、LANG がなくても less は → などの文字を表示します。scree run search と、設定ファイルのキーを使う直接の scree search は、SCREE_PAGER と SCREE_COLORS を設定ファイルからのみ取得します。TERM は xterm-256color のようなプレーンなターミナル名の場合に限り引き継がれます。また、TERMINFO、TERMINFO_DIRS、TERMCAP は決して引き継がれません。使用可能な TERM がない場合、less には TERM が必要なため、デフォルトの less は使用されません。

パイプに出力する場合、または -format xml を指定する場合、各ヒットは <hit> 要素になります。

<hit n="1" path="docs/setup.md" lines="12-19" heading="Setup > Keys" score="0.912" match="both">
chunk text
</hit>

• lines はチャンクの取得元となったソース行の範囲です。Claude はこの範囲を指定して正確に読み取れます（read_doc(path, start, end)）。インデックス作成後にファイルが変更されている場合、検索は現在のファイル内からチャンクを正確に、または空白の変更を無視して探し、現在の範囲を報告します。テキストがなくなっている場合、ヒットには stale="true" が付き、lines はありません。変更されたファイルは再インデックス作成のためにキューに追加されます。
• match は、どの検索でヒットしたかを示します。値は semantic、keyword、または both です。score はコサイン類似度で、キーワード検索のみのヒットにはありません。
• 複数のファイルに同一のチャンクがある場合（コミット済みのビルドコピーなど）、1つのヒットとして返されます。表示されるコピーには最短のパスが使われ、also="docs/print/x.md:12-18, …" に最大3つのコピーが一覧表示され、残りがある場合は also_more="N" が付きます。一覧に含まれるコピーのファイルが変更されている場合、そのコピーはヒットと同様に移動先が特定されるか、path:stale と表示されます。.screeignore でビルドフォルダーを除外する方法を引き続きおすすめします。埋め込みコストを節約できます。
• auto モードでは、出力の末尾に [mode: auto → hybrid] のような行が表示されます。

-format json は、スクリプトや評価で使う安定した形式として、1行につき1つのオブジェクトを出力します。形式は {"n","mode","path","start","end","heading","score","match","stale","also","also_more"} です。mode は実行されたモードを表し、値がない場合、start、end、score は null になります。also は {"path","start","end"} のリストです（テキストがなくなっているコピーには "stale":true が付きます）。コピーがさらにある場合にのみ also_more が表示されます。

-format grep は grep -n のような path:line:text の行を出力します。各ヒットでクエリの単語を含む行、またはセマンティック検索のヒットでは最初の行が、順位順にそれぞれ1回ずつ表示され、制御文字は削除されます。fzf でヒットを選択して vim で開くか、すべてのヒットを vim の quickfix リストに読み込めます。

sg() { scree search -format grep "$*" | fzf --delimiter : \
  --preview 'n={2}; case $n in ""|*[!0-9]*) exit;; esac; sed -n "$(( n>5 ? n-5 : 1 )),+30p" -- {1}' \
  --bind 'enter:become(n={2}; case $n in ""|*[!0-9]*) exit 1;; esac; vim "+$n" -- {1})'; }
vim --cmd 'set efm=%f:%l:%m' -q <(scree search -format grep "ci seed")

パスはフォルダーからの相対パスなので、以下のコマンドはその最上位で実行してください。自分で作成していないフォルダーは、ファイル名やテキストを自由に選べるため、各フィールドは信頼できない入力として扱ってください。上記のように、その行が数値であることを確認して、パスの前に -- を付けてください。{1} や {2} をシェルの算術式やコマンドラインにそのまま貼り付けないでください。また、vim -q には %f:%l:%m のエラー形式を指定してください。デフォルトの形式では、ノート本文中の "file" line N: も拾ってしまうためです。scree は、パスに : または制御文字が含まれるヒットを（件数を stderr に表示して）除外し、- または + で始まるパスには ./ を付けます。

設定ファイル

（Claude Code 用の）scree mcp、（ターミナルから実行する）scree run、および systemd ユニットは、すべて同じファイル ~/.config/scree/env を読み込むため、API キーをモード 600 のこのファイル 1 か所に保存できます。クイックスタートの手順 2 にある scree key で、このファイルを作成するか、ファイル内のキーを更新できます。このファイルにはキーと任意の設定を保存します。フォルダーは保存しません。

scree run を使わずにコマンドを直接実行した場合は、環境変数が使われます。OPENROUTER_API_KEY が未設定（または上記のように空欄、プレースホルダー、無効な値）で、このファイルにキーがある場合、search、reindex、doctor、watch は scree run と同じように自分自身を再実行します。つまり、このファイルだけから構築した環境で実行するため、キーが送られるのはファイル内の SCREE_EMBED_URL（またはデフォルトのエンドポイント）だけであり、プロキシがファイルに設定されていればそれを経由します。シェルの SCREE_*、プロキシ、SSL_CERT_FILE、GODEBUG の各変数は適用されません。その場合、doctor はキーの取得元がこのファイルであると表示します。ファイルがない場合、またはキーが含まれていない場合は、キーなしとして扱われます。ファイルが以下のチェックに通らない場合、問題の内容を示す警告を 1 つ表示し、コマンドはキーなしで実行されます（auto 検索は keyword を実行します）。serve 自体はファイルを読み込みません。Claude Code の場合は、すでに scree mcp がファイルの内容を適用しています。

このファイルには 2 つ目のキー SCREE_MCP_API_KEY も保存できます。scree key -mcp で書き込みます（scree key と同じフラグおよびルールが適用されます。-check -mcp で確認できます）。その場合、scree mcp と scree mcp -docker は、ファイル内のキーの代わりにこのキーを OPENROUTER_API_KEY として serve に渡します。これにより、OpenRouter のキーごとの使用状況で Claude Code を scree search などと分けて確認できます。後者では引き続き OPENROUTER_API_KEY が使われます。SCREE_MCP_API_KEY が同じ名前のままプロセスに渡されることはありません。このキーが使用できない場合（空、プレースホルダー、内部に空白がある、引用符を含む）、scree mcp は理由を stderr に表示しますが、値は表示せず、OPENROUTER_API_KEY を使います。doctor もこのキーについて警告し、問題がなければ scree mcp が別のキーを使うことを知らせます。他の設定と同様に、最後に記述された SCREE_MCP_API_KEY の行が使われます。

~ は $HOME や $XDG_CONFIG_HOME ではなく、パスワードデータベース（ログインユーザーのホームディレクトリ）を参照します。scree mcp と scree run は、ファイルが存在しない場合、シンボリックリンクである場合、自分が所有していない場合、またはグループや他のユーザーが読み取れる場合、起動を拒否します。最後のケースは chmod 600 で修正できます。scree key もこのようなファイルを拒否します（ファイルがない場合は問題ありません）。また、~/.config/scree フォルダーがシンボリックリンクである場合、自分が所有していない場合、グループや他のユーザーが書き込み可能な場合、~/.config がシンボリックリンクである場合、またはキーによってファイルが 64 KB を超える場合も拒否します。Linux では、ホームディレクトリは /etc/passwd から取得します。LDAP または sssd のログインの場合は getent passwd から取得します。いずれからもユーザー情報を取得できない場合、$HOME を信頼せず、起動を拒否します。Windows では実行できません。環境変数を設定して、scree serve -notes … などのコマンドを直接実行してください。

1 行につき NAME=value を 1 つ記述し、scree key と同様に値を一重引用符で囲んでください。これにより、空白を含むパスも 1 つの値として扱われます。export プレフィックスも使用できます。このファイルはデータとして読み込まれ、シェルとして実行されることはないため、値の中身は展開されません。受け付けられるのは、scree 独自の変数（SCREE_*、OPENROUTER_API_KEY）、プロキシ変数、および scree mcp -docker から docker にのみ渡される DOCKER_HOST と DOCKER_CONTEXT です。それ以外の名前はエラーになり、該当する行が示されます。「設定」表にある他の変数も同じファイルに記述できます。値には、その値を囲む引用符と同じ引用符を含められません。

Claude Code

scree mcp は設定ファイルを読み込み、scree serve を実行します。Claude Code に保存されるのはコマンドだけなので、キーが ~/.claude.json に残ることはありません。scree をインストールし（クイックスタートの手順 3）、各リポジトリのルートから登録します。

claude mcp add scree --scope project -- scree mcp

生成された .mcp.json をコミットします。serve は、Claude Code が起動された作業ディレクトリの git ルートをインデックス化し、CLAUDE_PROJECT_DIR が同じリポジトリ内にあることを確認します。また、リポジトリの .mcp.json で scree mcp が指定されていることも確認します（command が scree または /scree で終わるパスであり、最初の引数が mcp であること）。ワークツリーでは、ワークツリーがインデックス化されます。同じリポジトリ内の複数のセッションは、1 つのインデックスを共有します。1 つのセッションが書き込み、ほかのセッションは読み込み、書き込み側が終了すると別のセッションが引き継ぎます。リポジトリが SCREE_FIRST_SYNC_MB より大きい場合は、その中で scree run reindex を一度実行するまでインデックス化されません。検索時にその旨が表示されます。

ツールは search_docs(query, k, mode?)、read_doc(path, start?, end?)、reindex(path?) です。各検索結果には行範囲が含まれるため、Claude はその行だけを読み取れます。また、コピーされたフォルダー間の重複は 1 件の検索結果にまとめられます（also=）。それでも、ビルド出力は .screeignore で除外してください。

scree mcp が使用する設定は、設定ファイルだけです。リポジトリにコミットされた .mcp.json は、起動時の環境を指定するため、scree mcp はその環境を無視します。-docker 以外の引数はすべて拒否し、パスワードデータベースから設定ファイルを見つけて、自身を置き換え（exec）、独自のバイナリで scree serve を実行します。その環境に含まれるのは、HOME（passwd に登録されたホームディレクトリ）、PATH=/usr/local/bin:/usr/bin:/bin、CLAUDE_PROJECT_DIR、およびファイル内の設定だけです。それ以外は何も引き継がれません。継承された SCREE_*、キーやプロキシの変数、XDG_DATA_HOME、XDG_CONFIG_HOME、DOCKER_HOST、Go ランタイムの GODEBUG や GOMAXPROCS も引き継がれません。scree はシェルを使わない静的バイナリなので、最初の行より前に古いシェルラッパーに作用し得る LD_PRELOAD、bash の SHELLOPTS や PS4、エクスポートされた BASH_FUNC_* 関数も作用しません。実際の scree が起動した後は、リポジトリの環境からキーを別のエンドポイントに送ったり、別の設定ファイルに差し替えたり、インデックスを移動したり、scree の対象フォルダーを別の場所に指定したりすることはできません。ただし、最初に PATH を通じて scree としてどのプログラムを実行するかは選べます。クイックスタートの信頼に関する注意事項を参照してください。（macOS では、Go バイナリはシステムライブラリに動的リンクされるため、DYLD_* 変数が最初のプロセスに作用する可能性があります。docs/SPEC.mdの未解決項目を参照してください。）

通常の scree または絶対パス

コミットされた .mcp.json では通常の scree を指定するため、インストール先に関係なく誰でも使え、各ユーザーの PATH（またはリポジトリの env）でバイナリが見つかります。自分だけが使う設定では、代わりに絶対パスを登録すれば、どのプログラムが設定を使用するかを PATH で決められることはありません。このプロジェクト用に ~/.claude.json に保存するローカルスコープのエントリーは、env も含め、プロジェクト側の同名エントリーより優先されます。

claude mcp add scree --scope local -- "$HOME/.local/bin/scree" mcp

これを実行すると、シェルが $HOME を展開するため、保存されるコマンドは /home/you/.local/bin/scree のような絶対パスになります。リポジトリにコミットされた .mcp.json では、引き続き scree mcp を指定する必要があります。これにより、リポジトリでオプトインします。

推奨される構成は、scree mcp を介した stdio です。serve -http はループバックだけでリッスンします。ループバック以外のアドレスでは -allow-remote と 16 文字以上の SCREE_HTTP_TOKEN が必要で、その場合、すべてのリクエストで Authorization: Bearer <token> を送信する必要があります。トークンはコマンドラインではなく、設定ファイルに保存してください。

printf 'SCREE_HTTP_TOKEN=%s\n' "$(openssl rand -hex 32)" >> ~/.config/scree/env
scree run serve -notes ~/notes -http 0.0.0.0:7077 -allow-remote

これを実行する際は、Claude Code セッション内ではなくターミナルから実行してください。セッション内では CLAUDE_PROJECT_DIR が設定されており、serve は -notes を拒否します。

クライアントには、その後ヘッダーが必要になります。claude mcp add --transport http ... --header "Authorization: Bearer $SCREE_HTTP_TOKEN" で追加した場合、シェルで変数を展開することでトークンをシェル履歴に残さずに済みますが、Claude Code は展開後のヘッダーを引き続き ~/.claude.json に保存します。

ノートフォルダー

~/notes のように、どのリポジトリにも属さないフォルダーをコマンドラインから使用します。

scree run reindex -notes ~/notes
scree run search -notes ~/notes "backup password"

systemd ユニットは scree run watch -notes ~/notes を実行して、最新の状態を保ちます。Claude Code から検索するには、~/notes で claude mcp add scree --scope project -- scree mcp を実行し、その場所で Claude Code を起動します。ここは git リポジトリではないため、フォルダーは ~/notes 自体です。別の場所で起動した Claude Code のセッションからはアクセスできません。Claude Code の serve は、セッションを実行しているフォルダーのみをインデックス化するためです。

Claude Desktop（ワンクリックバンドル）

未テストです。 このバンドルは、どのプラットフォームの MCP クライアントでもテストされていません。Claude Desktop でも、macOS や Windows でもテストされていません。また、Linux を対象としていません。実際に動作確認したのは、Linux 上で Linux ビルドを使用して実行したサーバーコマンドのみです。問題がある可能性がありますので、見つけた点をご報告ください。

0.3.6 以降のリリースには、macOS および Windows 用の Claude Desktop 向け MCPB バンドルである scree_<version>.mcpb が含まれます。バンドルには macOS 用ユニバーサルバイナリと Windows 用 amd64 バイナリが含まれます（Windows on ARM ではエミュレーションを使用して実行されます）。Claude Desktop でファイルを開くとインストールされ、2 つの設定を求められます。

• ノートフォルダー（必須）：scree がインデックス化して検索するフォルダーです。フォルダーを選択することが明示的なオプトインとなるため、.mcp.json の確認は適用されません。ノートフォルダーまたはリポジトリを選択してください。ホームフォルダー、その上位のフォルダー、またはドライブルートを選択すると、サーバーは起動しません。
• OpenRouter API key（任意）：設定しない場合、scree はキーワードのみでインデックス化と検索を行います。設定すると、意味による検索も可能になり、ノートと各クエリが埋め込み処理のために OpenRouter に送信されます。前後のスペースや貼り付けられた改行は削除されます。OpenRouter がキーを拒否した場合、scree はキーワードのみで動作を続け、検索結果にキーが拒否されたことを示します。

Claude Desktop はその後、バンドルから server/scree serve -notes <folder> を実行し、OPENROUTER_API_KEY にはキーまたは空の値を設定します。このバンドルは設定ファイルを読み込まないため、そこにある SCREE_MODEL、SCREE_DIMENSIONS、SCREE_EMBED_URL は適用されません。別のモデルで既にインデックス化されたフォルダーは拒否されます。Markdown ファイルが 50 MB を超えるフォルダーは自動ではインデックス化されません。検索結果にその旨が示され、Claude はパスを指定せずに reindex ツールを実行する前に、確認するよう指示されます。これにより、フォルダーはインデックス化されます。インデックスは CLI と同じ場所に保存されるため、CLI でも同じフォルダーを検索できます。一方が他方の読み込める範囲を超えてインデックスをアップグレードする場合があるため、両者は同じバージョンにしてください。

バイナリには署名も公証もありません。macOS では、ダウンロードしたバンドル内の server/scree の実行を Gatekeeper が拒否する場合があります。その場合は、「システム設定」→「プライバシーとセキュリティ」で許可してください。また、未署名のバイナリには docs/SPEC.md に記載されている DYLD_* に関する注意点もあります。Windows SmartScreen でも同様の警告が表示される場合があります。各リリースには scree_<version>.mcpb.sha256（sha256sum 形式。sha256sum -c、または macOS では shasum -a 256 -c で確認できます）も含まれており、レジストリエントリー io.github.jrapakko/scree にも同じ sha256 が記録されています。インストール時にクライアントがこれを確認するかどうかは未テストです。

バックグラウンドサービス（systemd）

# needs ~/.config/scree/env from "Settings file" above
mkdir -p ~/.local/bin ~/.config/systemd/user
cp bin/scree ~/.local/bin/
cp contrib/scree-watch.service ~/.config/systemd/user/
systemctl --user daemon-reload && systemctl --user enable --now scree-watch
journalctl --user -u scree-watch -f

このユニットは scree run watch -notes ~/notes を実行するため、scree mcp と同じ方法で設定ファイルを読み込みます（systemd の EnvironmentFile は使用しません）。別のフォルダーを使う場合は、ExecStart の -notes を編集してください。そのフォルダー内の Claude Code セッションが既に書き込みロックを保持している場合は、ロックが解放されるまで待機します。

Docker または Podman

イメージのサイズは約 18 MB です。静的バイナリのみを含み、特権のないユーザーとして実行されます。フォルダーは読み取り専用でマウントされ、インデックスは /data のボリュームに保存されます。Linux では、ファイル変更イベントがバインドマウント経由でコンテナーに届きます。macOS では、Docker Desktop がイベントを転送しないため、watch は変更を検知できません。日常的な利用には、ネイティブバイナリまたは systemd ユニットを使用してください。 SELinux を使用するホスト（Fedora、RHEL、CentOS Stream）では、各バインドマウントに :z が必要です。 これがないと、コンテナはマウントされたフォルダーを読み取れず、scree は open /notes: permission denied で失敗します。以下の例には :z が含まれています。また、scree mcp -docker では、設定ファイルに SCREE_MOUNT_OPTS=ro,z が必要です。:z は、マウントが読み取り専用の場合でも、ホスト上のフォルダー内のすべてのファイルに（container_file_t への）ラベルを永続的に付与し直します。マウントするのはノート用フォルダーかリポジトリにし、ホームディレクトリはマウントしないでください。SELinux を使用していないシステムでは、:z を省略してください。ラベルを付け直したくない場合は、代わりにネイティブバイナリを使用してください。

docker build -t scree .            # or: podman build -t scree .

docker run を使用する場合：

# background indexer
docker run -d --name scree-watch --restart unless-stopped \
  -e OPENROUTER_API_KEY \
  -v "$HOME/notes:/notes:ro,z" -v scree-data:/data \
  scree watch -notes /notes

# one-off commands against the same index
docker run --rm -e OPENROUTER_API_KEY -v "$HOME/notes:/notes:ro,z" -v scree-data:/data scree doctor -notes /notes
docker run --rm -e OPENROUTER_API_KEY -v "$HOME/notes:/notes:ro,z" -v scree-data:/data scree search -notes /notes "backup password"

値を指定せずに -e OPENROUTER_API_KEY を指定すると、シェルから変数が引き継がれるため、キーがコマンドラインに表示されることはありません。

シェル、または compose.yaml と同じ場所にある .env から OPENROUTER_API_KEY を読み込む compose を使用する場合：

SCREE_NOTES_DIR=$HOME/notes docker compose up -d     # starts watch
docker compose logs -f watch

SCREE_NOTES_DIR は、/notes にマウントされるホスト側フォルダーを compose で指定するための名前にすぎません。compose.yaml は SCREE_MODEL、SCREE_DIMENSIONS、SCREE_MAX_FILE_BYTES、SCREE_FIRST_SYNC_MB、SCREE_ZDR、SCREE_EMBED_URL も引き継ぎます。また、serve に対して SCREE_HTTP_TOKEN も引き継ぎます。serve サービスは mcp プロファイルの背後にあるため、up では起動しません。

Claude Code では、MCP サーバーを stdio 経由でセッションごとに 1 つのコンテナで実行できます。scree mcp -docker は設定ファイルを読み込み、docker run -i --rm --pull=never を実行します（コンテナにはキーが渡されるため、イメージがない場合もレジストリから取得されることはありません）。プロジェクトフォルダーはそのフォルダー自身のパスに読み取り専用でマウントされ（各リポジトリに scree-data ボリューム内の独自のインデックスが作成されます）、scree-data ボリュームもマウントされます。設定されている設定項目だけが名前で渡され（-e NAME）、キーがコマンドラインに表示されることはありません。作業ディレクトリの git ルートを serve と同じルール（所有している .git を経由する場合のみ。シンボリックリンクは不可。また、/tmp などのスティッキーフォルダー内またはその上位では不可）でマウントするため、.gitignore が適用されます。また、CLAUDE_PROJECT_DIR が別の作業ツリーにある場合は起動を拒否します。serve はマウントされたフォルダー内で実行され（-w）、そこで同じフォルダールールと .mcp.json のオプトイン確認を適用します。グローバル git 除外ファイルはコンテナ内から参照できません。また、git ディレクトリがマウントされたフォルダーの外にある作業ツリーは、コンテナ内で読み取れません。

リポジトリにコミットされている .mcp.json では、全員が共有する scree mcp が指定されています。Docker を自分で使うには、ローカルスコープのエントリを追加してください。これは、自分に対してプロジェクトのエントリより優先されます。

claude mcp add scree --scope local -- "$HOME/.local/bin/scree" mcp -docker

docker CLI に渡される環境は、HOME、/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin の PATH、設定項目、および設定ファイルで指定されている場合は DOCKER_HOST または DOCKER_CONTEXT です。Claude Code やリポジトリの環境からは何も引き継がれないため、エンジンでこれら 2 つの変数が必要な場合は、設定ファイルで指定してください。設定ファイル内の SCREE_DOCKER（docker または podman のみ。指定されたフォルダー内から検索され、PATH 経由では検索されません）、SCREE_IMAGE（デフォルトは scree:latest。自分で取得した ghcr.io/jrapakko/scree:<version> のような完全修飾名も使用できます）、SCREE_DATA_VOLUME（パスではなくボリューム名）を指定すると、エンジン、イメージ、ボリュームを変更できます。SCREE_MOUNT_OPTS（デフォルトは ro）ではマウントオプションを設定でき、ro、ro,z、ro,Z のみ指定できます。SELinux を使用するホストでは、上記のとおり ro,z を設定してください。パスワードデータベースに登録されたホームディレクトリ、その上位のフォルダー、または / は決してマウントされず、: を含むパスは拒否されます。scree mcp と同様に、引き継がれた設定は無視され、その他の引数は受け付けません。

コンテナ内では、公開ポート経由で到達できるようにするには、serve -http がループバック以外のアドレスにバインドする必要があるため、-allow-remote と SCREE_HTTP_TOKEN が必要です。ホスト上では、たとえば -p 127.0.0.1:7077:7077 のように、ループバックにのみポートを公開してください。

watch と serve のコンテナは scree-data ボリュームを共有します。ネイティブプロセスの場合と同様に、SQLite の WAL モードにより、watch が書き込んでいる間も serve は読み取りを行えます。

動作の仕組み

• 各フォルダーには、$XDG_DATA_HOME/scree/indexes/ の下に独自のインデックスがあります。scree serve（Claude Code セッションごとに 1 つ）または scree watch のうち、インデックスのロックファイルを保持しているプロセスが唯一の書き込みプロセスです。起動時にコンテンツハッシュで同期し、その後 fsnotify で監視します。パスに対する最後のイベントから 1.5 秒待ち、ハッシュが変わったファイルだけを再度埋め込みます。同じインデックスを使うほかのプロセスは読み取り専用で、5 秒ごとにロックを再試行するため、書き込みプロセスの終了後に別のプロセスが引き継ぎます。
• 最初の同期はバックグラウンドで実行されるため、Claude Code はすぐに接続できます。同期が完了するまでは、検索結果にインデックスが未完成であることが示されます。SQLite の WAL モードにより、書き込み中も読み取り側は検索できます。
• 検索結果は、パス、行範囲、見出し、照合タイプを含む <hit> 要素です。チャンクは最大 3500 文字、各ヒットのテキストは最大 4000 文字、1 回の応答は最大 64 KB です。クエリに識別子が含まれる場合、検索ではベクトルと SQLite の FTS5 キーワードインデックスを組み合わせ、完全一致する名前が上位に表示されます。read_doc はファイル全体、または指定した行範囲を <doc> 要素で返し、最大サイズは 256 KB です。サーバーは、どちらも指示ではなくデータとして扱うようクライアントに伝えます。
• 結果を返す前に、すべてのヒットについて現在の除外ルールを再確認します。そのため、新たに除外対象になったファイルや削除されたファイルは、直ちに結果から除外されます。
• 検索は API を最大 10 秒（2 回試行）待ちます。インデックス作成では、1 回の試行につき最大 30 秒、最大 3 回試行します。API の停止後は、インデックス作成を 30 秒間一時停止し、最大 5 分まで間隔を倍増させてから再同期します。これにより、停止中に変更されたファイルも、再編集なしで取り込まれます。
• シャットダウン時、serve と watch は書き込みプロセスを最大 5 秒間待ちます。2 回目の Ctrl-C または SIGTERM を受け取ると、直ちに終了します。
• インデックスファイルまたはフォルダーが消失、あるいは置き換えられた場合、scree watch はエラーで終了するため、systemd または Docker が再起動します。serve では書き込みプロセスが停止し、検索結果にその旨が報告されます。フォルダー名が変更された場合や除外ファイルが変更された場合は、監視対象を再登録します。インデックスディレクトリは 0700 で作成され、ファイルは 0600 で作成されます。
• ベクトルは SQLite のベクトル拡張機能である vec1 に保存され、フラット（正確）なコサインインデックスが使われます。キーワードには SQLite の FTS5 が使われます。どちらも ncruces/go-sqlite3 によって WebAssembly にコンパイルされており、これによりバイナリは CGO に依存しません。
• scree が信頼するのは、自分が所有するシンボリックリンクではない .git のみです。/tmp のようなスティッキービットが設定されたフォルダー内やその上位には .git を探しません。また、git の除外ファイル（.gitignore、.git/info/exclude、.git ファイル）や .screeignore のシンボリックリンクをたどらず、リポジトリの .git/config を読み取らず、それらの内容を出力することもありません。メッセージにはファイル名と行番号のみが表示されます。他人が所有する .git がある場合はエラーになります。その下にあるフォルダーをそれでもインデックス化するには、-notes <folder> -gitignore=false を渡してください。
• インデックスファイル、その -wal ファイルと -shm ファイル、および writer.lock は、シンボリックリンク経由では決して開かれません。インデックスフォルダー、またはその上位にある scree/indexes フォルダーがシンボリックリンクの場合も拒否されます。
• 読み取り可能な対象を決めるポリシーは 1 つだけで、インデックス作成、検索、read_doc、reindex はすべてこのポリシーに従います。シンボリックリンクをたどるのはインデックス対象フォルダー内に限られ、リンク先にもルールが適用されます。シンボリックリンクされたフォルダーは再帰的に探索しません。

小規模なインデックスの場合、アイドル時のメモリ使用量はプロセスあたり約 13～15 MB、1000 ファイル（4000 チャンク）のインデックスでは約 20 MB です。デフォルトモデルでのインデックス作成コストは Markdown 1 MB あたり約 $0.0025 です。doctor の見積もりは上限値です。

scree-mcp ラッパーからの移行

シェルラッパーの scree-mcp、scree-run、scree-mcp-docker は廃止されました。scree mcp、scree run、scree mcp -docker がバイナリ内で処理を実行します。設定ファイルに変更はありませんが、シンボリックリンクであってはならず、新たに DOCKER_HOST と DOCKER_CONTEXT を保持できるようになりました。

1. 各リポジトリで、新しい .mcp.json を再登録してコミットします。

   claude mcp remove scree --scope project
   claude mcp add scree --scope project -- scree mcp
   

   serve は引き続き scree-mcp を指定した古いエントリを受け付けますが、そのエントリが機能するのは scree-mcp プログラムが存在する間だけです。現在はインストールされていません。

2. 古いラッパーを削除します：rm -f ~/.local/bin/scree-mcp ~/.local/bin/scree-run。scree-mcp-docker を scree-mcp としてインストールした場合は、それも削除して、ローカル Docker エントリを追加します。

3. scree-run <command> を使用していた箇所では、scree run <command> を使用します。

4. EnvironmentFile でファイルを読み込む代わりに scree run watch を実行するようになったため、systemd ユニットを更新します：cp contrib/scree-watch.service ~/.config/systemd/user/ && systemctl --user daemon-reload && systemctl --user restart scree-watch。

単一フォルダー版からの移行

単一フォルダー版は SCREE_NOTES を読み込み、~/.local/share/scree/index.db に単一のインデックスを保持していました。現在は各フォルダーに専用のインデックスがあり、フォルダーはリポジトリまたは -notes から取得されます。

1. ~/.config/scree/env から SCREE_NOTES= の行を削除します。この設定は無視され、残っていると doctor が警告します。
2. ユーザースコープの登録を削除します：claude mcp remove scree --scope user。これを登録したままにすると、開いたすべてのプロジェクトで scree が起動します。その場合、.mcp.json で scree mcp が指定されていない各プロジェクトで serve が処理を拒否します。代わりにリポジトリごとに scree を登録し（クイックスタートの手順 5）、コマンドラインからノートフォルダーを指定します。
3. scree run reindex -notes ~/notes を実行して、新しい場所にノートのインデックスを再構築し、その後 ~/.local/share/scree/index.db を削除します。または、-db ~/.local/share/scree/index.db を指定して残すこともできます。指定すると、そのフォルダー用にインデックスが引き継がれます。scree indexes で古いファイルを確認できます。
4. systemd ユニットを更新します：cp contrib/scree-watch.service ~/.config/systemd/user/ && systemctl --user daemon-reload && systemctl --user restart scree-watch。
5. Docker：イメージは SCREE_NOTES または SCREE_DB を設定しなくなりました。-notes /notes を渡してください。scree-data ボリューム内の古い /data/index.db は使用されません。インデックスを再構築してください。

以前のフォルダーごとのビルドで作成されたインデックスは、開くとその場でアップグレードされます。次回の同期時に行範囲が補完され、変更されていないファイルは再埋め込みされません。また、重複ハッシュとキーワードインデックスは保存済みのチャンクから構築されます。現在のチャンクサイズ上限より前に作成されたインデックスでは、一度 scree reindex -all を実行する必要があります。

ライセンス

MIT。詳細は LICENSE を参照してください。リリースアーカイブとコンテナーイメージには、バンドルされた依存関係のライセンスが含まれています（THIRD_PARTY_LICENSES/、またはイメージ内の /usr/share/doc/scree）。