symbols

symbols

高速なマルチ言語対応のソースコードインテリジェンス CLI です。コマンドラインからシンボルの抽出、インポートの解析、依存関係の追跡、影響分析を行えます。

言語サーバーは不要です。プロジェクトのビルドも不要です。コードを指定するだけです。

目次

• これが必要な理由
• コンテキストの節約方法
• できること
• インストール
• 言語サポート
• 使い方
  • シンボルの抽出
  • インポートの解析
  • 依存関係の照会
  • 影響分析
  • プロジェクトグラフの概要
  • JSON 出力
  • 短縮形
  • シンボル検索
• MCP サーバー
• 仕組み
• プロジェクトルートの検出
• 制限事項
• ライセンス

これが必要な理由

symbols は、最初に30個ものファイルを開かずに、コードベースをすばやく把握したいときに役立ちます。

よくある課題として、次のようなものがあります。

• ファイルを変更する前に、影響範囲をすぐに把握する必要がある。
• なじみのないリポジトリへの参加時に、手探りではなく全体像を知りたい。
• PR をレビューする際に、具体的な依存関係や所有者の手がかりが欲しい。
• AI コーディングツールを使っていて、必要なときに信頼できる構造化されたプロジェクトコンテキストが欲しい。

エディターのタブや grep の出力、記憶から手作業でコンテキストを組み立てる代わりに、symbols なら構造を一度で把握できます。

コンテキストの節約方法

symbols は、実用的な方法で2つのコンテキスト節約を実現します。

1. コード構造を高速で繰り返し実行できるクエリ（list、deps、dependents、impact、graph、search）として外部化するため、セッションごとに頭の中で構造を再構築する必要がありません。
2. MCP（syms mcp）を通じて同じモデルを公開するため、エージェントやツールは古いチャット履歴や推測したファイル間の関係に頼らず、最新のプロジェクト情報を直接取得できます。

その結果、次のような効果が得られます。

• 読み返しの手間が減る
• 「これを変更すると何が壊れる？」という想定外の事態が減る
• オンボーディングが速くなり、リファクタリングも安全になる
• コンテキストを即興で作らずに取得するため、AI の支援がより有用になる
• 探索的な開発サイクルの削減と、リポジトリの再調査に費やす AI トークンの削減によりコストが下がる

できること

syms list server.py           # functions, classes, constants, variables
syms imports server.py        # parsed import statements
syms deps server.py           # files this file imports from
syms dependents server.py     # files that import this file
syms impact server.py         # full impact analysis (direct + transitive)
syms graph .                  # project-wide dependency summary
syms search User              # find symbols by name across a project
syms mcp                      # run as MCP server for AI tools

インストール

オプション 1：ソースからビルド

git clone https://github.com/Jordan-Horner/symbols.git
cd symbols
go build -o syms .
sudo mv syms /usr/local/bin/

要件： Go 1.26 以降

オプション 2：直接インストール（Linux/macOS）

# Install directly to /usr/local/bin
curl -L https://github.com/Jordan-Horner/symbols/releases/latest/download/syms-$(uname -s)-$(uname -m) -o /usr/local/bin/syms
chmod +x /usr/local/bin/syms

オプション 3：Homebrew（macOS）

brew tap Jordan-Horner/tap
brew install syms

インストールの確認

syms --version

言語サポート

シンボルの抽出には tree-sitter を使用し、完全な AST 解析を行います（パラメーター付き関数シグネチャ、クラス、型、定数）。インポートの解析と依存関係の解決には正規表現を使用します。

言語	シンボル	インポート解析	依存関係の解決
Python	tree-sitter（関数、クラス、定数、変数）	正規表現	相対インポート + 絶対インポート
TypeScript	tree-sitter	正規表現	tsconfig.json のパスエイリアス、相対パス、index.ts
JavaScript	tree-sitter	正規表現	TypeScript と同じ（jsconfig.json も読み込みます）
Svelte	tree-sitter（スクリプトブロック）	正規表現	TypeScript と同じ
Go	tree-sitter	正規表現	go.mod のモジュールプレフィックス、パッケージディレクトリ
Java	tree-sitter	正規表現	ドットをスラッシュに変換、src/main/java プレフィックス
Kotlin	tree-sitter	正規表現	Java と同じ + .kt
Rust	tree-sitter	正規表現	crate/self/super、mod.rs
C#	tree-sitter	正規表現	名前空間からパスへの変換、クラス名へのフォールバック
PHP	tree-sitter	正規表現	PSR-4 の規約、require/include
C/C++	tree-sitter	—	—
Ruby	tree-sitter	—	—
Scala	tree-sitter	—	—
Bash	tree-sitter	—	—

使い方

シンボルの抽出

# Single file
syms list app.py

# Multiple files
syms list src/main.go src/handlers.go

# Recursive directory scan
syms list -r src/

# JSON output (for piping to other tools)
syms list --json app.py

# Pretty JSON output (human-readable)
syms list --json --pretty app.py

# Optional: include precise symbol ranges
syms list --json --ranges app.py

# Count symbols per file
syms list --count src/

# Filter by symbol kind (repeatable or comma-separated)
syms list --filter class src/
syms list --filter class,function src/
syms list --filter class --filter function src/

出力：

### `app.py` — 245 lines

  constant VERSION  # line 1
  constant API_URL  # line 3
  variable app  # line 5
  class Application  # line 12
  def __init__(self, config)  # line 15
  async def start(self)  # line 34
  def shutdown(self)  # line 78

インポートの解析

syms imports server.py

出力：

### `server.py`

  from flask import Flask, jsonify  # line 1
  from .models import User, Post  # line 2
  import os  # line 3

依存関係のクエリ

# Direct dependencies
syms deps src/handlers.go

# Transitive (everything it depends on, recursively)
syms deps -t src/handlers.go

# Who imports this file?
syms dependents src/models.py

# Transitive dependents
syms dependents -t src/models.py

影響分析

syms impact src/core/utils.py

出力：

### `src/core/utils.py` — impact analysis

  Direct dependents:     8
  Transitive dependents: 23

  Direct:
    src/api/handlers.py
    src/core/auth.py
    src/core/db.py
    ...

  Indirect (transitive):
    src/api/routes.py
    src/main.py
    tests/test_auth.py
    ...

プロジェクトグラフの概要

syms graph .

出力：

Project dependency graph

  Files:              187
  Import edges:       562
  Unresolved imports: 43

  Most depended-on files:
    src/utils.py  (36 dependents)
    src/config.py  (33 dependents)
    src/models.py  (23 dependents)

  Heaviest importers:
    src/app.py  (28 imports)
    src/main.py  (24 imports)

  Circular dependencies (1):
    src/config.py <-> src/runner.py

JSON 出力

すべてのコマンドで、機械可読な出力を得るために --json を使用できます。

syms impact --json src/utils.py | jq '.direct_dependents'
syms graph --json . | jq '.hot_spots[:5]'

# Optional: pretty-print JSON for humans
syms graph --json --pretty .

# Full edge map (file → its dependencies)
syms graph --json . | jq '.edges'

# What does a specific file depend on?
syms graph --json . | jq '.edges["src/app.py"]'

省略形

list サブコマンドはデフォルトのため、省略できます。

# These are equivalent:
syms list app.py
syms app.py

# Flags work too:
syms -r src/ --json

シンボル検索

# Find symbols by name (fuzzy: exact > prefix > contains)
syms search User

# JSON output
syms search --json handle

# Search in a specific project
syms search --root /path/to/project Config

# Search only specific symbol kinds
syms search --filter class User

# Optional: include precise symbol ranges in search results
syms search --json --ranges User

出力：

Found 3 symbols matching "User":

  class User  models.py:1
  class UserProfile  models.py:5
  function get_user(id)  api/handlers.py:12

MCP サーバー

AI ツールとの連携（例：Claude Code）のために、syms を MCP サーバーとして実行します。

syms mcp

すべての機能を stdio 経由の MCP ツール（JSON-RPC 2.0）として公開します。

ツール	説明
syms_list	ファイルからシンボルを抽出します
syms_imports	インポート文を解析します
syms_deps	ファイルの依存関係
syms_dependents	逆方向の依存関係
syms_impact	影響分析
syms_search	名前でシンボルを検索します
syms_graph	プロジェクトの依存関係グラフ

syms_list と syms_search は、シンボルの種類を絞り込むための任意の kinds: string[] 引数を受け付けます。 syms_list と syms_search は、開始位置と終了位置の行・列メタデータを含めるための任意の include_ranges: boolean も受け付けます。 ツールの結果は structuredContent で返されます（content[].text 内の JSON テキストではありません）。

Claude Code のセットアップ

syms のインストール後、MCP サーバーとして設定します。

プロジェクト単位（チームに推奨）：

プロジェクトのルートに .mcp.json を作成します。

{
  "mcpServers": {
    "symbols": {
      "command": "syms",
      "args": ["mcp"]
    }
  }
}

このファイルをコミットすると、チームでシンボルサーバーを自動的に利用できるようになります。

グローバル（すべてのプロジェクト）：

~/.mcp.json を作成または編集します。

{
  "mcpServers": {
    "symbols": {
      "command": "syms",
      "args": ["mcp"]
    }
  }
}

設定後：

1. Claude Code を再起動します
2. プロンプトが表示されたら、symbols MCP サーバーを承認します
3. これで Claude Code はすべてのプロジェクトでコードインテリジェンスツールにアクセスできるようになります

仕組み

シンボルの抽出には、完全な AST 解析を行う tree-sitter を使用します。各言語にはコンパイル済みの文法があり（バイナリに静的リンクされています）、構文木を生成します。ツールは構文木をたどり、名前、種類、行番号、関数パラメーターを含むトップレベルの宣言を抽出します。Python では、モジュールレベルの代入も定数（UPPER_CASE）または変数として抽出します。

インポートの解析には、各言語のインポート構文に合わせて調整された正規表現パターンを使用します。AST 解析を必要とせず、標準的なインポート形式を高速かつ確実に処理できます。

依存関係の解決では、言語固有の規則を使ってインポート指定子をディスク上の実際のファイルに対応付けます。

• Python：モジュールのドット区切りパスからファイルパスへの変換、相対インポートの解決
• Go：go.mod のモジュール名の除去、パッケージからディレクトリへの対応付け
• Java/Kotlin：ドットからスラッシュへの変換、標準のソースルートの接頭辞（src/main/java/）
• Rust：crate／self／super のパス解決、mod.rs の規則
• C#：名前空間からパスへの変換と、接頭辞の段階的な除去
• PHP：PSR-4 によるバックスラッシュからスラッシュへの変換、require／include パスの解決

ディレクトリのスキャンでは、.git、node_modules、dist、build、vendor、target など、一般的なソース以外のディレクトリを早い段階で除外します。

プロジェクトルートの検出

deps、dependents、impact、graph では、ディレクトリツリーを上にたどり、.git、package.json、または pyproject.toml を探して、ツールがプロジェクトルートを自動検出します。--root で上書きできます。

syms deps src/app.py --root /path/to/project

制限事項

• 規則に基づく解決 — 依存関係の解決にはファイルパスの規則を使用し、コンパイラーやビルドシステムとの統合は行いません。tsconfig.json／jsconfig.json の TypeScript／JavaScript paths はサポートされています（extends を含む）が、tsconfig の外部で定義された webpack／vite のエイリアスには対応していません。
• ファイル単位の粒度 — 依存関係は関数やシンボル単位ではなく、ファイル単位（インポートグラフ）で追跡されます。呼び出しグラフはありません。
• C／C++ のインクルード — #include の解析とヘッダーの解決はまだ実装されていません。シンボルの抽出は機能しますが、依存関係の追跡には対応していません。
• Ruby／Scala／Bash — tree-sitter によるシンボルの抽出は機能しますが、インポートの解析と依存関係の解決は実装されていません。
• 動的インポート — Python の importlib.import_module()、JavaScript の計算式を使った require() など、同様の動的パターンは検出されません。
• モノレポの境界 — ツールは単一のプロジェクトルート内でインポートを解決します。モノレポ内のパッケージをまたぐインポートは、正しく解決されない場合があります。

ライセンス

MIT