sem

Ataraxy Labs スタックの一部: ソフトウェア開発のためのエージェントネイティブなインフラストラクチャ。関連項目: weave (エンティティレベルの git マージドライバー) · inspect (セマンティックコードレビュー) · opensessions (コーディングエージェント向けの tmux サイドバー)。

マニフェストを読む: https://ataraxy-labs.com/#thesis · エッセイ: https://ataraxy-labs.com/blogs · LLM: https://ataraxy-labs.com/llms.txt

Git 上に構築されたセマンティックバージョン管理。
変更された行ではなく、sem は変更されたエンティティ (関数、メソッド、クラス) を教えてくれます。

なぜ sem なのか? · エージェントと sem を使う · インストール · コマンド · エージェント (MCP) · クラウドの同意 · リリース

sem は Git 上で動作するセマンティックバージョン管理ツールです。tree-sitter でコードを解析し、すべての関数、クラス、メソッドをエンティティとして抽出し、行単位ではなくエンティティレベルで差分を取ります。つまり、「x-y 行が変更された」ではなく「関数 blahh が変更された」と表示されます。

セットアップ不要で、あらゆる Git リポジトリで動作します。

クラウドを利用したクエリはリポジトリごとにオプトインです。ログインしても、リポジトリがアップロードされたりクエリが送信されたりすることはありません。公開/非公開リポジトリの状態、プレビュー画面、ローカル監査ログ、忘れるコントロールについては、クラウドの同意フローを参照してください。

エージェントと sem を使う

4 つの問い、4 つの動詞。すべての動詞が --json を受け付けます。

問い	動詞
どこにあるのか?	sem find、sem grep
自分の変更は何に触れるのか?	sem impact
正しいのか?	sem check
人間は何をレビューすべきか?	sem certify

どこにあるのか? 名前で関数、クラス、メソッドを探します:

sem find parse_config

function parse_config src/config.py:1

誰がそれを呼び出すか (--callers)、それが何を使うか (--refs)、または呼び出し元と呼び出し先を含むそのコード (--context):

sem find parse_config --callers

function parse_config src/config.py:1
  function load src/config.py:6
  function test_parse_config tests/test_config.py:4

rg のようにテキストを検索します:

sem grep splitlines

src/config.py:2:    pairs = [line.split("=", 1) for line in text.splitlines() if line]

自分の変更は何に触れるのか? エンティティに依存するすべてのものと、実行すべきテスト:

sem impact parse_config --tests

⚡ 1 tests affected:
    tests/test_config.py
      function test_parse_config (L4–5)

sem impact --diff HEAD --tests は、コミットされていない変更全体に対して同じことを答えます。

正しいのか? プロジェクト自身のコンパイラ、型チェッカー、リンター、テストを実行し、同じ結果が得られる場合は変更が影響しうるものだけを再チェックします。終了コード 0 は成功、1 は失敗、2 は判断できなかったことを意味します:

sem check

cmd    FAIL      full        sh (0 rechecked, 279 ms)
  `python3 -m pytest -q tests` exited 1:
  E       AssertionError: assert {'a': '1'} == {'a': '2'}

人間は何をレビューすべきか? コミット範囲のレビュー証明書: 何が変更されたか、その変更が取り残す呼び出し元、それに到達するテスト:

sem certify main..HEAD

# sem certificate 94f4bd74e26e..d73d4d092b43
1 files, 2 entities changed (1 added, 1 modified, 0 deleted, 0 renamed, 0 moved).
- modified `parse_config` (src/config.py:1): 2 static caller(s) in 2 file(s) that this change does not modify

MCP を話すエージェント向けに、sem mcp は同じ動詞をツールとして提供します (AI エージェントと使うを参照)。

インストール

curl -fsSL https://raw.githubusercontent.com/Ataraxy-Labs/sem/main/install.sh | sh

または Homebrew を使用します。

brew install sem-cli

または Windows で winget を使用します。

winget install AtaraxyLabs.sem

または Windows で Scoop を使用します。

scoop install sem

または npm ラッパーを node_modules にインストールします。

npm install --save-dev @ataraxy-labs/sem

Bun を使用する場合は、パッケージを信頼済みに設定して、postinstall スクリプトがバイナリをダウンロードできるようにします。

bun add -d @ataraxy-labs/sem
bun pm trust @ataraxy-labs/sem

インストール後は、いつでも最新リリースに更新できます。

sem config update

または、crates.io から cargo を使用します。

cargo install sem-cli

または、ソースから最新の main をビルドします（Rust が必要です）。

cargo install --git https://github.com/Ataraxy-Labs/sem sem-cli

または、GitHub Releases からバイナリを入手します。

または、Docker 経由で実行します。

docker build -t sem .
docker run --rm -it -u "$(id -u):$(id -g)" -v "$(pwd):/repo" sem diff

GNU Parallel との名前の競合

GNU Parallel は sem バイナリ（/usr/bin/sem）を parallel へのシンボリックリンクとして提供します。両方をインストールしている場合、競合します。sem --version を実行して、どちらを使用しているか確認してください。(#77)

簡単な対処法：

# Option 1: alias in your shell profile (~/.bashrc, ~/.zshrc)
alias sem="$HOME/.cargo/bin/sem"

# Option 2: make sure cargo bin comes first in PATH
export PATH="$HOME/.cargo/bin:$PATH"

# Option 3: if installed via Homebrew
export PATH="$(brew --prefix)/bin:$PATH"

npm／bun 経由でインストールした場合、バイナリは node_modules/.bin/sem にあり、npx sem または bunx sem 経由で呼び出すため、競合を完全に回避できます。

コマンド

あらゆる Git リポジトリで動作します。セットアップは不要です。Git の外でも、任意のファイル比較に使用できます。

動詞	答えられる質問
sem find	どこで定義されていますか？何が呼び出し、何を使用し、その周辺には何がありますか？
sem grep	このテキストはどこにありますか？
sem impact	このエンティティまたはこの差分を変更すると、何に影響しますか？
sem check	自分の変更は正しいですか？
sem certify	このコミット範囲で人間が確認すべき内容は何ですか？
sem diff	どの関数とクラスが変更されましたか？
sem graph	コードはどのようにつながっていますか？
sem history	このエンティティは時間とともにどのように変化しましたか？最後に変更したのは誰ですか？
sem cloud	アカウント、クラウドレビュー、リポジトリ横断クエリ
sem config	git diff の統合、テレメトリ、補完、更新、統計
sem mcp	エージェント向けの MCP ツールとしての同じ動詞

sem <verb> --help を実行すると、すべてのフラグと使用例が表示されます。

sem は SQLite のエンティティキャッシュをデフォルトで OS のキャッシュディレクトリ内に、リポジトリの外部に保存します。キャッシュのルートを変更するには SEM_CACHE_DIR=/path/to/cache を設定します。リポジトリ内での上書きは無視されるため、キャッシュファイルによって作業ツリーが変更されることはありません。

sem find

名前でエンティティの定義を見つけ、次にそのエンティティについて、何が呼び出すのか、何を使用するのか、または周辺コードとともにコードを確認します。回答はディスク上のクエリインデックス（index.sem。エンティティキャッシュの隣に保存）から取得します。リポジトリでの初回呼び出し時にインデックスが作成され、以降の呼び出しではデーモンを使わず直接読み取ります。

sem find "function diff_command"        # where it is defined ("type name" narrows by kind)
sem find diff_command load_config       # several names in one call
sem find diff_command --callers         # who calls it; says when the caller set may be incomplete
sem find diff_command --refs            # what it calls and references
sem find diff_command --context         # its code plus callers and callees, within a token budget
sem find diff_command --context --budget 4000 --hops 1
sem find --in src/auth.ts               # every entity in a file or directory
sem find diff_command --in src/         # only definitions under src/
sem find --text "retry budget"          # entity bodies containing a string, named by entity
sem find diff_command --json            # JSON on any of the above

--context を指定した場合、対象のシグネチャ自体が収まらないと、JSON 出力に target_omitted: true が表示されます。

sem grep

ソースファイル全体を対象とするテキスト検索です。rg 互換の file:line:text 形式で出力し、インデックスが存在する場合はインデックスのトライグラム転置リストから結果を返します。

sem grep "TODO"
sem grep -i todo src/                   # case-insensitive, under src/
sem grep -e foo -e bar --json           # several patterns, hits kept apart

sem impact

エンティティを変更すると何が壊れるかを確認します。依存先、（推移的な）依存元、およびそのエンティティに到達するテストを表示します。

sem impact authenticateUser             # full impact
sem impact authenticateUser --deps      # direct dependencies only
sem impact authenticateUser --dependents
sem impact authenticateUser --tests     # the tests to run
sem impact authenticateUser --file src/auth.ts   # disambiguate by file
sem impact --diff HEAD --tests          # tests for the uncommitted change
sem impact --diff main..HEAD --json     # one impact report per changed entity

JS／TS ワークスペースで --diff と --tests を指定すると、変更ファイルに対するモジュールグラフの影響を受けるテストの選択結果（sem graph --modules affected-tests）が回答になります。それ以外の場合は、エンティティグラフの結果が回答になります。--no-default-excludes を指定すると、生成物、フィクスチャ、ベンダー、ベンチマーク、ビルドの各ツリーも対象に含まれます。

sem check

作業ツリーに対してプロジェクトのコンパイラー、型チェッカー、リンター、テストを実行し、判定を1つ出力します。終了コードは、合格が0、不合格が1、判定不能が2です。各チェッカーは、プロジェクト全体に対して実際のツールが出す判定を返します。その回答が同じだと確実に証明できる場合は変更の影響範囲だけを再チェックし、それ以外の場合はツールをすべて実行して理由を説明します。チェック対象がない場合は2であり、合格にはなりません。

sem check                               # every checker the project has
sem check --checkers ts,lint,tests      # only these
sem check --base origin/main            # against origin/main instead of HEAD
sem check --promises                    # also prove every promise in .sem/promises can fail
sem check --json                        # one JSON object with a verification certificate

チェッカーはプロジェクトから検出されます。TypeScript、lint、JavaScript のテスト（vitest、jest）はモジュールグラフに従い、Go は影響を受けるパッケージを再チェックします。Python の型チェック（インポートに基づいて範囲を絞る pyright、または mypy）と pytest は、変更の影響が及ぶファイルのみを再実行します。C と C++ は、変更したファイルをインクルードする compile_commands.json 内の翻訳単位のみを再コンパイルします。Cargo、Gradle または Maven、dotnet、SwiftPM はそれぞれ独自のビルドを実行し、変更箇所のみをすでに再ビルドするため、ベースが合格してから入力に変更がない場合は実行自体を省略します（TypeScript の編集によって Rust のビルドが再実行されることはありません）。

戻り値の型を宣言している Python 関数の本体内での編集は、他のファイルから見える内容を変更しないため、そのファイルのみを再チェックします。

独自のコマンドは .sem/check.json に記述します。例：{"commands": [{"run": "make lint", "inputs": ["src/**"]}]}。inputs を指定したコマンドは、最後に合格してから該当する入力に変更がなければスキップされます。inputs の指定がないコマンドは毎回実行されます。

sem certify

コミット範囲のレビュー証明書です。変更されたエンティティ、シグネチャの変更とそれに取り残された呼び出し元、呼び出し先の差分、維持または破られた契約（根拠付き）、モジュール到達可能性の差分（JS/TS）、影響を受けるテスト、静的参照の範囲を示します。--arch を指定すると、代わりにアーキテクチャの観点を表示します。新規または削除されたデータ経路、副作用、依存関係、循環、変更されなかった点を順位付けして示します。

sem certify main..HEAD                  # markdown certificate
sem certify main..HEAD --json           # the full certificate
sem certify main..HEAD --arch           # architecture delta
sem certify main..HEAD --arch --view    # at most 10 ranked items
sem certify main..HEAD --html > view.html   # one self-contained page

<base>...<head> はマージベースを使用します。1つの ref を指定した場合は <ref>..HEAD になります。

sem diff

名前変更の検出、構造ハッシュ、単語単位のインライン強調表示に対応した、エンティティ単位の差分です。

# Semantic diff of working changes
sem diff

# Staged changes only
sem diff --staged

# Specific commit
sem diff --commit abc1234

# Commit range
sem diff --from HEAD~5 --to HEAD

# Verbose mode (word-level inline diffs for each entity)
sem diff -v

# Plain text output (git status style)
sem diff --format plain

# JSON output (for AI agents, CI pipelines)
sem diff --format json

# Markdown output (for PRs, reports)
sem diff --format markdown

# Compare any two files (no git repo needed)
sem diff file1.ts file2.ts

# Read file changes from stdin (no git repo needed)
echo '[{"filePath":"src/main.rs","status":"modified","beforeContent":"...","afterContent":"..."}]' \
  | sem diff --stdin --format json

# Only specific file types
sem diff --file-exts .py .rs

sem graph

コードのつながりを示します。フラグを指定しない場合は、エンティティ依存関係グラフ（sem impact と sem find --context の基盤となるグラフ）を表示します。フラグを指定すると、別のレイヤーを選択できます。

sem graph --json                        # entities and the calls/references between them
sem graph --modules metrics             # JS/TS module graph: density, cycles, depth, centrality
sem graph --modules blast-radius pkg-a  # who breaks if pkg-a changes
sem graph --modules path src/a.ts src/b.ts
sem graph --dataflow                    # reads, writes and source -> sink paths
sem graph --dataflow --witness          # experimental: witness tasks per static flow
sem graph --system                      # exact dependency versions from every lockfile
sem graph --system build --out sys/     # the layered whole-system graph

sem history

Git の履歴を通じたエンティティの変更を示し、ロジックの変更と見た目だけの変更を区別します。

sem history authenticateUser
sem history authenticateUser -v         # with the content diff of each version
sem history authenticateUser --limit 20
sem history                             # repo hotspots and co-change pairs
sem history --blame src/auth.ts         # who last changed each entity in the file

エンティティを指定しない場合、sem history は最近のリポジトリ履歴をエンティティ単位で分析します。ホットスポット（最も変更の多い関数／クラスと、作成者数）と同時変更ペア（同じコミットで繰り返し変更されるエンティティ。「一方を変更するなら、もう一方も忘れずに」）を表示します。

sem cloud、sem config

sem cloud login                         # API key, or GitHub when omitted
sem cloud enable                        # cloud queries for this public repo (shows what is sent, asks first)
sem cloud disable                       # stop cloud for this repo
sem cloud review listen <diff-id>       # attach an agent to a cloud code review
sem cloud xref --json                   # cross-repo dependencies
sem cloud repos                         # where your code is stored

sem config setup                        # make `git diff` show sem's entity diff
sem config telemetry off
sem config completions zsh              # shell completions
sem config update
sem config stats                        # local diff counters; nothing leaves your machine

旧コマンド名

以前のすべてのコマンド名とフラグは、同じ出力のまま引き続き使用できます。ターミナルでは、sem は新しい表記を示す1行の注記を stderr に出力します。--json モードまたは出力がパイプに渡される場合は、余分な内容を出力しません。

旧	新
sem callers X	sem find X --callers
sem refs X	sem find X --refs
sem context X	sem find X --context
sem entities PATH	sem find --in PATH
sem log X	sem history X
sem blame FILE	sem history --blame FILE
sem arch-diff RANGE	sem certify RANGE --arch
sem topology OP	sem graph --modules OP
sem dataflow	sem graph --dataflow
sem system OP	sem graph --system OP
sem promises verify	sem check --promises
sem login, logout, whoami, review, xref, repos	sem cloud ...
sem cloud never	sem cloud disable
sem setup, unsetup, telemetry, completions, update, stats	sem config ...

プロミス

プロミスとは、エージェント（または人）がコードベースについて主張し、合格または不合格となるチェックとして記録したものです。「完了」とは、チェックに合格することを意味します。プロミスは .sem/promises/*.json に保存されます。各ルールには、人が読める "promise" を含めることができます。コード構造のルールは、sem が解析できるあらゆる言語で動作する tree-sitter クエリです。名前が _ で始まらないキャプチャはすべて違反とみなされ、入れ子になったキャプチャは最も外側のノードで一度だけ報告されます。たとえば、.sem/promises/jsx-no-logic.json は次のとおりです。

{ "laws": [
  { "id": "jsx-no-logic/conditionals",
    "promise": "JSX contains no conditional rendering",
    "forbidPattern": { "from": ["**/*.tsx", "**/*.jsx"], "within": ["jsx_expression"],
                       "query": "(ternary_expression) @conditional" } },
  { "id": "jsx-no-logic/inline-handler-bodies",
    "promise": "JSX event handlers are references, not block bodies",
    "forbidPattern": { "from": ["**/*.tsx", "**/*.jsx"], "within": ["jsx_attribute"],
                       "query": "(arrow_function body: (statement_block (_))) @handler_body" } }
] }

sem promises check                        # KEPT / BROKEN n per promise, then file:line:col  capture  snippet; exit 1 if any broken
sem promises check --changed src/App.tsx  # only violations in these files (what an edit hook runs)
sem promises check --since main           # only files changed since a ref, uncommitted and untracked included
sem promises status --json                # id, kept, violation count per promise
sem check --promises                      # prove every promise can fail (each needs a mutation)

sem promises は sem --help に一覧表示されません。sem certify を使うと、指定した範囲でプロミスが守られているか、破られているかを報告します。同じファイルは sem graph --modules check --laws <file> でも使えます。このコマンドでは、JS/TS ワークスペース向けにグラフとインポートのルール（forbid、only、acyclic、layers、forbidImport、allowImports）が追加されます。--changed または --since を指定した場合も、これらのルールはグラフ全体に対して実行されますが、変更されたファイル（またはそれを含むパッケージ）に関係する違反のみが報告されます。

編集の直後にエージェントが破られたプロミスを確認できるようにするには、編集のたびに scripts/promises-hook.sh を実行します。プロミスが破られた場合、スクリプトは終了コード 2 で終了し、違反を標準エラーに出力します。それ以外の場合は何も出力しません。Claude Code では、設定に PostToolUse フックとして追加します。

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit",
    "hooks": [ { "type": "command", "command": "sh /path/to/sem/scripts/promises-hook.sh" } ] } ] } }

このスクリプトは、フックの標準入力から tool_input.file_path を読み取ります。ほかのハーネスでは、編集したパスを引数として渡すこともできます。たとえば pi では、拡張機能の編集ツールと書き込みツールの tool_result ハンドラーから、sh promises-hook.sh <path> を実行できます。スクリプトが終了コード 2 を返した場合は、その標準エラー出力をツールの結果に追加します。

Git のデフォルトの差分として使用する

git diff の出力をエンティティ単位の差分に置き換えます。コマンドを変更しなくても、エージェントと人の両方に sem の出力が自動的に表示されます。

sem config setup

これで git diff は、行単位ではなくエンティティ単位の変更を表示します。プロンプトもエージェントの設定も必要ありません。git diff を呼び出すすべての処理で、sem の出力が自動的に使われます。また、ステージされた変更のエンティティ単位の影響範囲を表示する pre-commit フックもインストールされます。

macOS と Linux では、sem config setup によって、プロンプト送信時にコンテキストを注入する Claude Code の UserPromptSubmit フック（sem hook prompt-submit）と、Edit、Write、MultiEdit ツールを監視する sem hook tool も登録されます。編集のたびにこのフックは、変更したメソッドの兄弟実装のうち手を加えていないもの、変更したシグネチャをまだ使用している呼び出し元、および変更箇所に到達するテストとその実行コマンドをエージェントに伝えます。伝えることがない場合は何も出力しません。~/.claude/settings.json を冪等に編集し、事前にバックアップを作成します。また、すでに設定されているフックには手を加えません。

無効にして通常の git diff に戻すには（セッションフックも削除されます）。

sem config unsetup

すべてのプルリクエストでエンティティ単位の差分を表示する

GitHub Action を追加すると、すべての PR に、変更された関数、クラス、メソッドを示す固定コメントが投稿されます。プッシュのたびに同じコメントが更新され、見た目だけの PR（フォーマットやコメントの変更）も明示されます。

# .github/workflows/entity-diff.yml
name: Entity diff
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  entity-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Ataraxy-Labs/sem/[email protected]

設定不要、API キー不要で、ビルドが失敗することもありません。詳細は action/ をご覧ください。

クラウドによる高速化（規模拡大とチーム向け）

ローカルでの利用は常に無料で、高速です。ディスク上のインデックスが日常的なクエリに、プロセスを起動した直後でも数ミリ秒で応答するため、常にウォームな状態に保つ必要も、ログインする必要もありません。ノート PC の高速化に料金はかかりません。

クラウドは、ノート PC では対応できない処理に利用します。非常に大きなモノレポでは、ローカルで最初にグラフを構築するのに数秒かかることがあります。共有のチームグラフは開発者ごとに再構築すべきではありません。また、CI では何もチェックアウトせずにグラフを利用したい場合があります。sem cloud login を使うと、これらのケースを sem cloud に接続できます。sem cloud は登録済みのリポジトリのグラフを事前に構築してウォームな状態に保ち、ローカルで再構築する代わりに、負荷の高いクエリをそのグラフから処理します。

sem cloud login                        # GitHub device flow, one time
sem impact myFunc --file src/foo.rs    # served from the cloud's warm graph

完全にオプションで、透過的に動作します。

• ログインしていない、またはクラウドに接続できない場合は、sem がローカルで計算し、まったく同じ出力を表示します。失敗せず、結果にも違いはありません。
• SEM_LOCAL=1 を指定すると、ログイン中でもローカルでの計算が強制されます。
• 小規模なリポジトリでは変化はありません。ローカルですでに高速です。グラフの再構築がボトルネックになる大規模なコードベースで効果を発揮します。

以下はすべて、クラウドアカウントの範囲内で実行される関連コマンドです。

sem cloud logout          # log out
sem cloud whoami          # show current cloud identity
sem cloud enable          # turn on cloud queries for a public repo (shows what's sent first)
sem cloud disable         # stop cloud for this repo
sem cloud xref --json     # cross-repo dependencies across your indexed repos
sem cloud repos           # where your code is stored: cloud-indexed repos + local caches
sem cloud status          # cloud + telemetry state for this repo (offline; sends nothing)
sem cloud share           # cloud queries for a private repo, with extra confirmation
sem cloud forget          # delete this repo's cloud index and unregister it

status、share、forget、list、preview、log は sem cloud --help には表示されませんが、記載どおりに動作します。いずれも読み取り専用か、送信前に明示的な確認が必要です。

チームでコードレビューに sem cloud を使用している場合、sem cloud review listen <diff-id-or-url> を実行すると、レビューにライブリスナーとして参加するよう事前設定されたコーディングエージェントが起動します。このエージェントは、差分の特定の行に基づいてレビュー担当者からの質問に回答します。

解析対象

tree-sitter によるエンティティ抽出に対応した、32 のプログラミング言語：

言語	拡張子	エンティティ
TypeScript	.ts .tsx .mts .cts	関数、クラス、インターフェース、型、列挙型、エクスポート
JavaScript	.js .jsx .mjs .cjs .es6	関数、クラス、変数、エクスポート
Python	.py .pyi	関数、クラス、デコレーター付き定義
Starlark（Bazel、Buck2）	BUILD BUCK WORKSPACE PACKAGE .bzl .bazel .bxl .star	ビルドターゲット、関数
Go	.go	関数、メソッド、型、変数、定数
Rust	.rs	関数、構造体、列挙型、実装、トレイト、モジュール、定数
Java	.java	クラス、メソッド、インターフェース、列挙型、フィールド、コンストラクター
C	.c .h	関数、構造体、列挙型、共用体、typedef
C++	.cpp .cc .cxx .hpp .hh .hxx	関数、クラス、構造体、列挙型、名前空間、テンプレート
C#	.cs	クラス、メソッド、インターフェース、列挙型、構造体、プロパティ
Ruby	.rb	メソッド、クラス、モジュール
PHP	.php .inc .phtml .module	関数、クラス、メソッド、インターフェース、トレイト、列挙型
Swift	.swift	関数、クラス、プロトコル、構造体、列挙型、プロパティ
Elixir	.ex .exs	モジュール、関数、マクロ、ガード、プロトコル
Bash	.sh	関数
Fish	.fish	関数
Lua	.lua	関数（グローバル、ローカル、テーブル形式、メソッド形式）
HCL/Terraform	.hcl .tf .tfvars	ブロック、属性（ネストされたブロックの修飾名を含む）
Kotlin	.kt .kts	クラス、インターフェース、オブジェクト、関数、プロパティ、コンパニオンオブジェクト
Fortran	.f90 .f95 .f03 .f08 .f .for	関数、サブルーチン、モジュール、プログラム
Vue	.vue	template/script/style ブロックと内部の TS/JS エンティティ
XML	.xml .plist .svg .csproj および 9 種類以上の MSBuild/リソース拡張子	要素（ネスト対応、タグ名を識別子として使用）
ERB	.erb .html.erb	ブロック、式、コードタグ
Svelte	.svelte .svelte.js .svelte.ts（.test/.spec バリアントを含む）	コンポーネントブロックと rune JS/TS モジュール
Perl	.pl .pm .t	サブルーチン、パッケージ
Dart	.dart	クラス、mixin、拡張、列挙型、型エイリアス、関数
OCaml	.ml .mli	値、モジュール、型、クラス、外部宣言
Scala	.scala .sc .sbt .kojo .mill	クラス、オブジェクト、トレイト、列挙型、関数、val、拡張
Nix	.nix	バインディング、inherit 宣言
Haskell	.hs	関数、シグネチャ、データ型、newtype、クラス、インスタンス、型シノニム
Elm	.elm	値宣言、型エイリアス、型宣言、port アノテーション、infix 宣言
Clojure	.clj .cljs .cljc	var、関数、マクロ、マルチメソッド、プロトコル、レコード、型
D	.d .di	モジュール、関数、クラス、構造体、インターフェース、共用体、列挙型、テンプレート、エイリアス、ユニットテスト
Zig	.zig	関数、テスト、変数
SQL	.sql .psql .pgsql .ddl	テーブル、ビュー、関数、インデックス、型、スキーマ、トリガー、シーケンス

構造化データ形式にも対応しています：

形式	拡張子	エンティティ
JSON	.json	プロパティ、オブジェクト（RFC 6901 パス）
YAML	.yml .yaml	セクション、プロパティ（ドット区切りパス）
TOML	.toml	セクション、プロパティ
EDN	.edn	最上位のマップエントリ（キーワードキー）
CSV	.csv .tsv	行（最初の列を識別子として使用）
Markdown	.md .mdx	見出しベースのセクション
LaTeX	.tex .latex .cls .sty	セクション（part/chapter/section/…）、および theorem/lemma/proof/figure/table/algorithm などの追跡対象環境

それ以外はすべて、チャンクベースの差分検出にフォールバックします。

カスタム拡張子と拡張子のないファイル

標準外の拡張子のファイルについては、プロジェクトのルートに .semrc を作成します。

.xyz = cpp
.j = json
.mypy = python

すでに設定している場合、sem は .gitattributes のパターン（diff= と linguist-language=）も読み取ります。同じ拡張子が両方で定義されている場合は、.semrc が優先されます。

拡張子のないファイルの場合、sem は内容（shebang 行、vim の modeline、package／import／use 文などの構造的なヒューリスティック）から言語を自動検出します。これにより、設定なしで 30 以上の言語に対応します。

マッチングの仕組み

エンティティのマッチングは、次の 3 段階で行われます。

1. ID の完全一致：変更前と変更後で同じエンティティなら、変更済みまたは変更なしと判定します
2. 構造ハッシュの一致：AST 構造が同じで名前が異なる場合、名前変更または移動と判定します（空白やコメントは無視します）
3. ファジー類似度：トークンの重複率が 80％を超える場合、名前変更の可能性が高いと判定します

これにより、sem は追加や削除だけでなく、名前変更や移動も検出します。また、構造ハッシュによって、見た目だけの変更（空白、フォーマット）と実際のロジック変更を区別できます。

AI エージェントでの利用（MCP）

URL ベースのクライアントが必要ですか？ Streamable HTTP のプレビューでは、認証付きのローカル読み取り専用アクセスを利用できます。デフォルトは引き続き stdio です。

macOS と Linux では、同じチェックアウト内のクライアントがウォーム状態のリポジトリデーモンを共有します。 sem mcp --status を実行して確認してください。セッションの分離、フォールバック動作、現在のプラットフォーム制限については、共有ランタイムの仕様と再現可能なベンチマークを参照してください。

sem mcp は、標準入力／標準出力を介して Model Context Protocol サーバーを起動します。自分で実行して結果を読むコマンドではありません。コーディングエージェントがバックグラウンドで起動し、作業中に sem に質問できるようにするサーバーです。そのため、mcp は通常のコマンドと並んでいます。エージェントは、次の基本操作をツールとして利用できます。

ツール	回答する内容
sem_find	定義されている場所はどこですか？ mode：callers、refs、context。in にはファイルまたはディレクトリを指定します
sem_grep	このテキストはどこにありますか？
sem_impact	このエンティティを変更すると、何に影響しますか？ 依存元、依存先、テスト
sem_check	変更内容は正しいですか？ 判定結果は、合格、不合格、判定不能です
sem_certify	このコミット範囲で、人間が確認すべき点は何ですか？
sem_diff	2 つの参照の間で変更されたエンティティはどれですか？
sem_graph	エンティティ、モジュール、データフロー、またはシステムのグラフ
sem_history	エンティティはどのように変更されましたか？ ファイルには blame を使用します

以前のツール名（sem_entities、sem_context、sem_callers、sem_log、sem_blame）を呼び出すクライアントも、引き続き回答を得られます。ただし、これらの名前は一覧には表示されません。レビューリスナーセッション（sem cloud review listen が設定する sem mcp --review）では、join_review、wait_for_branch、reply_to_branch、list_open_branches も一覧に表示されます。

エージェントがこれらを利用する理由は、ファイル全体を読んでトークンを消費する代わりに、「submitOrder を変更すると何が壊れますか」（sem_impact）や「この関数をリファクタリングするためのコンテキストだけをください」（context モードの sem_find。関数のソースと呼び出し元、呼び出し先を返します）と質問でき、呼び出し元を見落とす可能性のある grep の結果ではなく、依存関係グラフから正確で決定的な回答を得られることです。

一度追加すれば、あとはいつもどおりエージェントに話しかけるだけです。エージェントが自動でツールを呼び出します。

Claude Code：

claude mcp add sem -- sem mcp

エージェントが sem をいつ使うべきか分かるように、スキルもインストールするコマンドを 1 つ実行する方法もあります。

npx @ataraxy-labs/sem-skill

Cursor、Claude Desktop、または mcpServers の設定を使う任意のクライアント：

{
  "mcpServers": {
    "sem": {
      "command": "sem",
      "args": ["mcp"]
    }
  }
}

sem がエージェントの PATH にない場合は、バイナリの絶対パスを使用してください。別途インストールする必要はありません。sem mcp は、ほかのすべてのコマンドと同じバイナリに含まれています。

JSON 出力

sem diff --format json

1 行のロジック変更から Python 関数まで、実際の出力は次のとおりです。

{
  "summary": {
    "fileCount": 1,
    "added": 0,
    "modified": 1,
    "deleted": 0,
    "moved": 0,
    "renamed": 0,
    "reordered": 0,
    "binary": 0,
    "orphan": 0,
    "total": 1
  },
  "changes": [
    {
      "entityId": "auth.py::function::authenticate_user",
      "changeType": "modified",
      "entityType": "function",
      "entityName": "authenticate_user",
      "startLine": 1,
      "endLine": 6,
      "oldStartLine": 1,
      "oldEndLine": 4,
      "oldEntityName": null,
      "filePath": "auth.py",
      "oldFilePath": null,
      "oldParentId": null,
      "beforeContent": "def authenticate_user(username, password):\n    if not username or not password:\n        return False\n    return check_credentials(username, password)",
      "afterContent": "def authenticate_user(username, password):\n    if not username or not password:\n        return False\n    if not check_credentials(username, password):\n        return False\n    return True",
      "commitSha": null,
      "author": null,
      "structuralChange": true
    }
  ],
  "binaryChanges": []
}

名前付きの変更タイプの分類（added、modified、deleted、moved、renamed、reordered）の合計は、常に total と一致します。orphan はモジュールレベルの変更を横断的に数えるメタデータで、これらの変更はすでに名前付きの変更タイプの分類に含まれています。beforeContent／afterContent には、変更前後それぞれのエンティティのソース全体が格納されます。structuralChange は、差分が見た目だけの変更（空白、コメント）の場合に false になります。

ライブラリとして

sem-core は、crates.io から Rust ライブラリの依存関係として使用できます。

[dependencies]
sem-core = "0.23"

weave（セマンティックマージドライバー）と inspect（エンティティレベルのコードレビュー）で使用されています。

アーキテクチャ

• コード解析には tree-sitter を使用（WASM ではなくネイティブ Rust）
• Git 操作には git2 を使用
• ファイルの並列処理には rayon を使用
• 構造ハッシュには xxhash を使用
• リポジトリごとのキャッシュディレクトリ（SQLite エンティティキャッシュと mmap 可能なクエリインデックス）により、バックグラウンドデーモンを使わず、プロセス起動直後から find／callers／refs／grep で検索できます
• 新しい言語や形式を追加するためのプラグインシステム（CONTRIBUTING.md を参照）

テレメトリ

デフォルトではローカルで動作します。sem はコマンド名（例：diff、impact）を自分のマシン上でのみカウントし、このモードでは情報がアップロードされることはありません。コード、ファイルパス、リポジトリ名、ユーザー ID は記録されず、ネットワーク呼び出しも行われません。

sem config telemetry preview   # see current mode and exactly what would be sent
sem config telemetry on        # opt in: also upload counts to help improve sem
sem config telemetry off       # record nothing at all

SEM_NO_TELEMETRY=1 または DO_NOT_TRACK=1 を設定すると、モードにかかわらず何も記録しない動作が強制されます。開発ビルド（cargo build の target/ ディレクトリから実行されるもの）は記録を行わないため、sem 自体の開発によって集計データが汚染されることはありません。

コントリビューション

新しい言語を追加する場合は、手順を順に説明したガイド CONTRIBUTING.md をご覧ください。

スター履歴

ライセンス

MIT OR Apache-2.0