Scriptable interface to a powerful, multi-lingual language server.

Graph-sitter is a python library for manipulating codebases.

from codegen import Codebase

# Graph-sitter builds a complete graph connecting
# functions, classes, imports and their relationships
codebase = Codebase("./")

# Work with code without dealing with syntax trees or parsing
for function in codebase.functions:
    # Comprehensive static analysis for references, dependencies, etc.
    if not function.usages:
        # Auto-handles references and imports to maintain correctness
        function.move_to_file("deprecated.py")

Write code that transforms code. Graph-sitter combines the parsing power of Tree-sitter with the graph algorithms of rustworkx to enable scriptable, multi-language code manipulation at scale.

Installation and Usage

We support

• Running Graph-sitter in Python 3.12 - 3.13 (recommended: Python 3.13+)
• macOS and Linux
  • macOS is supported
  • Linux is supported on x86_64 and aarch64 with glibc 2.34+
  • Windows is supported via WSL. See here for more details.
• Python, Typescript, Javascript and React codebases

# Install inside existing project
uv pip install graph-sitter

# Install global CLI
uv tool install graph-sitter --python 3.13

# Create a codemod for a given repo
cd path/to/repo
gs init
gs create test-function

# Run the codemod
gs run test-function

# Create an isolated venv with codegen => open jupyter
gs notebook

Usage

See Getting Started for a full tutorial.

from graph_sitter import Codebase

Troubleshooting

Having issues? Here are some common problems and their solutions:

• I'm hitting an UV error related to [[ packages ]]: This means you're likely using an outdated version of UV. Try updating to the latest version with: uv self update.
• I'm hitting an error about No module named 'codegen.sdk.extensions.utils': The compiled cython extensions are out of sync. Update them with uv sync --reinstall-package codegen.
• I'm hitting a RecursionError: maximum recursion depth exceeded error while parsing my codebase: If you are using python 3.12, try upgrading to 3.13. If you are already on 3.13, try upping the recursion limit with sys.setrecursionlimit(10000).

If you run into additional issues not listed here, please join our slack community and we'll help you out!

Resources

• Docs
• Getting Started
• Contributing
• Contact Us

Why Graph-sitter?

Software development is fundamentally programmatic. Refactoring a codebase, enforcing patterns, or analyzing control flow - these are all operations that can (and should) be expressed as programs themselves.

We built Graph-sitter backwards from real-world refactors performed on enterprise codebases. Instead of starting with theoretical abstractions, we focused on creating APIs that match how developers actually think about code changes:

• Natural mental model: Write transforms that read like your thought process - "move this function", "rename this variable", "add this parameter". No more wrestling with ASTs or manual import management.

• Battle-tested on complex codebases: Handle Python, TypeScript, and React codebases with millions of lines of code.

• Built for advanced intelligences: As AI developers become more sophisticated, they need expressive yet precise tools to manipulate code. Graph-sitter provides a programmatic interface that both humans and AI can use to express complex transformations through code itself.

Contributing

Please see our Contributing Guide for instructions on how to set up the development environment and submit contributions.

Enterprise

For more information on enterprise engagements, please contact us or request a demo.