Metadata-Version: 2.4
Name: symtext
Version: 0.1.0
Summary: Lightweight code graph indexer with incremental file watching and MCP server
Project-URL: Homepage, https://github.com/ds7n/symtext
Project-URL: Documentation, https://github.com/ds7n/symtext#readme
Project-URL: Repository, https://github.com/ds7n/symtext
Project-URL: Issues, https://github.com/ds7n/symtext/issues
Project-URL: Changelog, https://github.com/ds7n/symtext/blob/main/CHANGELOG.md
Author-email: ds7n <270055197+ds7n@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: code-graph,indexer,mcp,tree-sitter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: graphdblite<0.2,>=0.1.1
Requires-Dist: loguru>=0.7
Requires-Dist: pathspec>=0.12
Requires-Dist: portalocker>=3.2.0
Requires-Dist: psutil>=5.9; sys_platform == 'win32'
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pydantic>=2.0
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: tree-sitter-language-pack<0.14,>=0.13
Requires-Dist: tree-sitter>=0.24
Requires-Dist: typer>=0.15
Requires-Dist: watchfiles>=1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Requires-Dist: types-psutil>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# symtext

A code-graph indexer for LLM agents. Parses your project with
[tree-sitter](https://tree-sitter.github.io/), stores the structure
(functions, classes, calls, imports, inheritance) in a local graph
database, and serves it to your LLM client over
[MCP](https://modelcontextprotocol.io/). Supports 24 languages and
incremental updates via file-watching.

## Quick start

Install [uv](https://docs.astral.sh/uv/) if you don't have it:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Add symtext to your MCP client config:

```json
{
  "mcpServers": {
    "symtext": {
      "command": "uvx",
      "args": ["symtext", "mcp"]
    }
  }
}
```

Where the snippet goes:

- **Claude Code** — `~/.claude.json` (user-wide), or `<project>/.mcp.json`
  (committed, project-wide). One-liner equivalent:
  `claude mcp add symtext -- uvx symtext mcp`.
- **Claude Desktop** —
  `~/Library/Application Support/Claude/claude_desktop_config.json`
  (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
- **Cursor / Cline / Windsurf / VS Code** — see
  [`docs/install.md`](https://github.com/ds7n/symtext/blob/main/docs/install.md).

Open your editor inside any project. First call indexes the repo
(seconds for small repos, ~1 min for large); subsequent calls are
instant. Everything lives under `~/.symtext/projects/<hash>/` —
nothing is written into your project tree. Diagnostics:
`uvx symtext doctor`.

Don't use `uv`? `pipx` and plain `pip install symtext` work too — see
[`docs/install.md`](https://github.com/ds7n/symtext/blob/main/docs/install.md).

## MCP tools

| Tool              | Purpose                                                                          |
|-------------------|----------------------------------------------------------------------------------|
| `shape`           | Codebase dimensions: node/edge counts, language breakdown, directory tree       |
| `summarize`       | Per-file summaries: function counts, class names, top functions by caller count  |
| `symbols`         | Full symbol listing for a file or directory                                      |
| `search_symbols`  | Fuzzy search by name or docstring content                                        |
| `get_callers`     | All functions that call a given function, with source context                    |
| `get_callees`     | All functions that a given function calls                                        |
| `get_importers`   | All files that import a given module                                             |
| `get_dependencies`| Outbound imports for a file — modules + line numbers                             |
| `get_hierarchy`   | Class inheritance — ancestors, descendants, or both                              |
| `path_between`    | Shortest call chain between two functions                                        |
| `unused_symbols`  | Functions with zero callers (dead-code finder, with entrypoint heuristics)       |
| `changed_symbols` | Git-aware blast radius: symbols changed vs a ref + their callers                 |
| `describe_symbol` | Full profile: source, callers, callees, imports — one round-trip                 |

The tools form a natural hierarchy: `shape` (counts) → `summarize`
(per-file) → `symbols` (every symbol). Start broad, drill down.

## Supported languages

24 languages: Bash, C/C++, C#, Dart, Elixir, Go, Haskell, HCL, Java,
Kotlin, Lua, Objective-C, Perl, PHP, Protobuf, Python, R, Ruby, Rust,
Scala, SQL, Swift, TypeScript/JavaScript, Zig.

## Docs

- [`docs/install.md`](https://github.com/ds7n/symtext/blob/main/docs/install.md) —
  install variants, MCP setup, troubleshooting
- [`docs/cli.md`](https://github.com/ds7n/symtext/blob/main/docs/cli.md) —
  CLI reference
- [`docs/configuration.md`](https://github.com/ds7n/symtext/blob/main/docs/configuration.md) —
  settings, env vars, monorepo override
- [`docs/storage.md`](https://github.com/ds7n/symtext/blob/main/docs/storage.md) —
  `~/.symtext/` layout
- [`docs/security.md`](https://github.com/ds7n/symtext/blob/main/docs/security.md) —
  threat model, disk-read clamp, Cypher hardening
- [`docs/architecture.md`](https://github.com/ds7n/symtext/blob/main/docs/architecture.md) —
  module layout (full spec in
  [`SPEC.md`](https://github.com/ds7n/symtext/blob/main/SPEC.md))
- [`CHANGELOG.md`](https://github.com/ds7n/symtext/blob/main/CHANGELOG.md),
  [`CONTRIBUTING.md`](https://github.com/ds7n/symtext/blob/main/CONTRIBUTING.md),
  [`SECURITY.md`](https://github.com/ds7n/symtext/blob/main/SECURITY.md)

## Credits

Built on [tree-sitter](https://tree-sitter.github.io/),
[graphdblite](https://github.com/ds7n/graphdblite), and
[watchfiles](https://github.com/samuelcolvin/watchfiles).
Inspired by [codegraphcontext](https://github.com/CodeGraphContext/CodeGraphContext).

## License

MIT — see [LICENSE](https://github.com/ds7n/symtext/blob/main/LICENSE).
