{
  "markdown": "# symbols\n\nA fast, polyglot source code intelligence CLI. Extract symbols, parse imports, trace dependencies, and analyze impact — all from the command line.\n\nNo language server required. No build step for your projects. Just point it at your code.\n\n[![Go](https://img.shields.io/badge/Go-1.26-00ADD8?logo=go&logoColor=white)](https://go.dev/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCPAmpel](https://img.shields.io/endpoint?url=https://mcpampel.com/badge/Jordan-Horner/symbols.json)](https://mcpampel.com/repo/Jordan-Horner/symbols)\n\n<a href=\"https://glama.ai/mcp/servers/Jordan-Horner/symbols\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/Jordan-Horner/symbols/badge\" alt=\"symbols MCP server\" />\n</a>\n\n## Table of contents\n\n- [Why this exists](#why-this-exists)\n- [How it saves context](#how-it-saves-context)\n- [What it does](#what-it-does)\n- [Install](#install)\n- [Language support](#language-support)\n- [Usage](#usage)\n  - [Symbol extraction](#symbol-extraction)\n  - [Import parsing](#import-parsing)\n  - [Dependency queries](#dependency-queries)\n  - [Impact analysis](#impact-analysis)\n  - [Project graph summary](#project-graph-summary)\n  - [JSON output](#json-output)\n  - [Shorthand](#shorthand)\n  - [Symbol search](#symbol-search)\n- [MCP server](#mcp-server)\n- [How it works](#how-it-works)\n- [Project root detection](#project-root-detection)\n- [Limitations](#limitations)\n- [License](#license)\n\n## Why this exists\n\n`symbols` is for the moments when you need to understand a codebase quickly without opening 30 files first.\n\nCommon pain points it targets:\n\n- You are about to change a file and need to know blast radius immediately.\n- You are onboarding to an unfamiliar repo and need a map, not a scavenger hunt.\n- You are reviewing a PR and want concrete dependency and ownership signals.\n- You are using AI coding tools and need reliable, structured project context on demand.\n\nInstead of manually reconstructing context from editor tabs, grep output, and memory, `symbols` gives you the structural view in one step.\n\n## How it saves context\n\n`symbols` saves context in two practical ways:\n\n1. It externalizes code structure into fast, repeatable queries (`list`, `deps`, `dependents`, `impact`, `graph`, `search`) so you do not have to rebuild mental maps every session.\n2. It exposes the same model through MCP (`syms mcp`) so agents and tools can fetch fresh project facts directly, rather than relying on stale chat history or guessed file relationships.\n\nNet effect:\n\n- less re-reading\n- fewer \"what will this break?\" surprises\n- faster onboarding and safer refactors\n- more useful AI assistance because context is retrieved, not improvised\n- lower cost from fewer exploratory engineering cycles and reduced AI token spend on repo re-discovery\n\n## What it does\n\n```\nsyms list server.py           # functions, classes, constants, variables\nsyms imports server.py        # parsed import statements\nsyms deps server.py           # files this file imports from\nsyms dependents server.py     # files that import this file\nsyms impact server.py         # full impact analysis (direct + transitive)\nsyms graph .                  # project-wide dependency summary\nsyms search User              # find symbols by name across a project\nsyms mcp                      # run as MCP server for AI tools\n```\n\n## Install\n\n### Option 1: Build from source\n\n```sh\ngit clone https://github.com/Jordan-Horner/symbols.git\ncd symbols\ngo build -o syms .\nsudo mv syms /usr/local/bin/\n```\n\n**Requirements:** Go 1.26+\n\n### Option 2: Direct installation (Linux/macOS)\n\n```sh\n# Install directly to /usr/local/bin\ncurl -L https://github.com/Jordan-Horner/symbols/releases/latest/download/syms-$(uname -s)-$(uname -m) -o /usr/local/bin/syms\nchmod +x /usr/local/bin/syms\n```\n\n### Option 3: Homebrew (macOS)\n\n```sh\nbrew tap Jordan-Horner/tap\nbrew install syms\n```\n\n### Verify installation\n\n```sh\nsyms --version\n```\n\n## Language support\n\nSymbol extraction uses tree-sitter for full AST parsing (function signatures with parameters, classes, types, constants). Import parsing and dependency resolution use regex.\n\n| Language | Symbols | Import parsing | Dependency resolution |\n|---|---|---|---|\n| Python | tree-sitter (functions, classes, constants, variables) | regex | Relative + absolute imports |\n| TypeScript | tree-sitter | regex | `tsconfig.json` path aliases, relative paths, `index.ts` |\n| JavaScript | tree-sitter | regex | Same as TypeScript (also reads `jsconfig.json`) |\n| Svelte | tree-sitter (script block) | regex | Same as TypeScript |\n| Go | tree-sitter | regex | `go.mod` module prefix, package directories |\n| Java | tree-sitter | regex | Dot-to-slash, `src/main/java` prefix |\n| Kotlin | tree-sitter | regex | Same as Java + `.kt` |\n| Rust | tree-sitter | regex | `crate`/`self`/`super`, `mod.rs` |\n| C# | tree-sitter | regex | Namespace-to-path, class name fallback |\n| PHP | tree-sitter | regex | PSR-4 conventions, `require`/`include` |\n| C/C++ | tree-sitter | — | — |\n| Ruby | tree-sitter | — | — |\n| Scala | tree-sitter | — | — |\n| Bash | tree-sitter | — | — |\n\n## Usage\n\n### Symbol extraction\n\n```sh\n# Single file\nsyms list app.py\n\n# Multiple files\nsyms list src/main.go src/handlers.go\n\n# Recursive directory scan\nsyms list -r src/\n\n# JSON output (for piping to other tools)\nsyms list --json app.py\n\n# Pretty JSON output (human-readable)\nsyms list --json --pretty app.py\n\n# Optional: include precise symbol ranges\nsyms list --json --ranges app.py\n\n# Count symbols per file\nsyms list --count src/\n\n# Filter by symbol kind (repeatable or comma-separated)\nsyms list --filter class src/\nsyms list --filter class,function src/\nsyms list --filter class --filter function src/\n```\n\n**Output:**\n\n```\n### `app.py` — 245 lines\n\n  constant VERSION  # line 1\n  constant API_URL  # line 3\n  variable app  # line 5\n  class Application  # line 12\n  def __init__(self, config)  # line 15\n  async def start(self)  # line 34\n  def shutdown(self)  # line 78\n```\n\n### Import parsing\n\n```sh\nsyms imports server.py\n```\n\n**Output:**\n\n```\n### `server.py`\n\n  from flask import Flask, jsonify  # line 1\n  from .models import User, Post  # line 2\n  import os  # line 3\n```\n\n### Dependency queries\n\n```sh\n# Direct dependencies\nsyms deps src/handlers.go\n\n# Transitive (everything it depends on, recursively)\nsyms deps -t src/handlers.go\n\n# Who imports this file?\nsyms dependents src/models.py\n\n# Transitive dependents\nsyms dependents -t src/models.py\n```\n\n### Impact analysis\n\n```sh\nsyms impact src/core/utils.py\n```\n\n**Output:**\n\n```\n### `src/core/utils.py` — impact analysis\n\n  Direct dependents:     8\n  Transitive dependents: 23\n\n  Direct:\n    src/api/handlers.py\n    src/core/auth.py\n    src/core/db.py\n    ...\n\n  Indirect (transitive):\n    src/api/routes.py\n    src/main.py\n    tests/test_auth.py\n    ...\n```\n\n### Project graph summary\n\n```sh\nsyms graph .\n```\n\n**Output:**\n\n```\nProject dependency graph\n\n  Files:              187\n  Import edges:       562\n  Unresolved imports: 43\n\n  Most depended-on files:\n    src/utils.py  (36 dependents)\n    src/config.py  (33 dependents)\n    src/models.py  (23 dependents)\n\n  Heaviest importers:\n    src/app.py  (28 imports)\n    src/main.py  (24 imports)\n\n  Circular dependencies (1):\n    src/config.py <-> src/runner.py\n```\n\n### JSON output\n\nAll commands support `--json` for machine-readable output:\n\n```sh\nsyms impact --json src/utils.py | jq '.direct_dependents'\nsyms graph --json . | jq '.hot_spots[:5]'\n\n# Optional: pretty-print JSON for humans\nsyms graph --json --pretty .\n\n# Full edge map (file → its dependencies)\nsyms graph --json . | jq '.edges'\n\n# What does a specific file depend on?\nsyms graph --json . | jq '.edges[\"src/app.py\"]'\n```\n\n### Shorthand\n\nThe `list` subcommand is the default — you can omit it:\n\n```sh\n# These are equivalent:\nsyms list app.py\nsyms app.py\n\n# Flags work too:\nsyms -r src/ --json\n```\n\n### Symbol search\n\n```sh\n# Find symbols by name (fuzzy: exact > prefix > contains)\nsyms search User\n\n# JSON output\nsyms search --json handle\n\n# Search in a specific project\nsyms search --root /path/to/project Config\n\n# Search only specific symbol kinds\nsyms search --filter class User\n\n# Optional: include precise symbol ranges in search results\nsyms search --json --ranges User\n```\n\n**Output:**\n\n```\nFound 3 symbols matching \"User\":\n\n  class User  models.py:1\n  class UserProfile  models.py:5\n  function get_user(id)  api/handlers.py:12\n```\n\n## MCP server\n\nRun `syms` as an MCP server for AI tool integration (e.g. Claude Code):\n\n```sh\nsyms mcp\n```\n\nExposes all functionality as MCP tools over stdio (JSON-RPC 2.0):\n\n| Tool | Description |\n|---|---|\n| `syms_list` | Extract symbols from files |\n| `syms_imports` | Parse import statements |\n| `syms_deps` | File dependencies |\n| `syms_dependents` | Reverse dependencies |\n| `syms_impact` | Impact analysis |\n| `syms_search` | Search symbols by name |\n| `syms_graph` | Project dependency graph |\n\n`syms_list` and `syms_search` accept optional `kinds: string[]` arguments to filter symbol kinds.\n`syms_list` and `syms_search` also accept optional `include_ranges: boolean` for start/end line+column metadata.\nTool results are returned in `structuredContent` (not JSON text blobs in `content[].text`).\n\n### Claude Code setup\n\nAfter installing `syms`, configure it as an MCP server:\n\n**Project-level** (recommended for teams):\n\nCreate `.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"symbols\": {\n      \"command\": \"syms\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nCommit this file so your team gets the symbols server automatically.\n\n**Global (all projects)**:\n\nCreate or edit `~/.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"symbols\": {\n      \"command\": \"syms\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nAfter configuration:\n1. Restart Claude Code\n2. When prompted, approve the `symbols` MCP server\n3. Claude Code will now have access to code intelligence tools in all your projects\n\n## How it works\n\n**Symbol extraction** uses tree-sitter for full AST parsing. Each language has a compiled grammar (linked statically into the binary) that produces a syntax tree. The tool walks the tree to extract top-level declarations with names, kinds, line numbers, and function parameters. For Python, module-level assignments are also extracted as constants (UPPER_CASE) or variables.\n\n**Import parsing** uses regex patterns tuned to each language's import syntax. This is fast and reliable for standard import forms without needing AST parsing.\n\n**Dependency resolution** maps import specifiers to actual files on disk using language-specific conventions:\n- Python: module dot-path to file path, relative import resolution\n- Go: `go.mod` module name stripping, package-to-directory mapping\n- Java/Kotlin: dot-to-slash convention, standard source root prefixes (`src/main/java/`)\n- Rust: `crate`/`self`/`super` path resolution, `mod.rs` convention\n- C#: namespace-to-path with progressive prefix stripping\n- PHP: PSR-4 backslash-to-slash mapping, `require`/`include` path resolution\n\n**Directory scanning** uses early pruning of `.git`, `node_modules`, `dist`, `build`, `vendor`, `target`, and other common non-source directories.\n\n## Project root detection\n\nFor `deps`, `dependents`, `impact`, and `graph`, the tool auto-detects the project root by walking up the directory tree looking for `.git`, `package.json`, or `pyproject.toml`. Override with `--root`:\n\n```sh\nsyms deps src/app.py --root /path/to/project\n```\n\n## Limitations\n\n- **Convention-based resolution** — dependency resolution uses file path conventions, not compiler/build system integration. TypeScript/JavaScript `paths` from `tsconfig.json`/`jsconfig.json` are supported (including `extends`), but webpack/vite aliases defined outside tsconfig are not.\n- **File-level granularity** — dependencies are traced at the file level (import graph), not at the function or symbol level. There is no call graph.\n- **C/C++ includes** — `#include` parsing and header resolution are not yet implemented. Symbol extraction works, but dependency tracing does not.\n- **Ruby/Scala/Bash** — symbol extraction works via tree-sitter, but import parsing and dependency resolution are not implemented.\n- **Dynamic imports** — Python's `importlib.import_module()`, JavaScript's computed `require()`, and similar dynamic patterns are not detected.\n- **Monorepo boundaries** — the tool resolves imports within a single project root. Cross-package imports in monorepos may not resolve correctly.\n\n## License\n\n[MIT](LICENSE)\n",
  "bytes": 12564,
  "sha": "d2d659420a02e167e74fdc579571e44a8e45232c4a399b4571b90701a8df8383",
  "repo_slug": "jordan-horner/symbols",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jordan_horner_symbols_409242d7/readme"
}