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

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

# 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

brew tap Jordan-Horner/tap
brew install syms

syms --version

# 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

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"]'

# 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

syms mcp

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

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