Get up and running with Graph-sitter programs in IDEs like VSCode, Cursor and PyCharm.

Make sure to install and initialize Graph-sitter with gs init

​
Configuring your IDE Interpreter

gs creates a custom Python environment in .codegen/.venv. Configure your IDE to use this environment for the best development experience.

​
MCP Server Setup

This is an optional step but highly recommended if your IDE supports MCP support and you use AI Agents. The MCP server is a local server that allows your AI Agent to interact with the Graph-sitter specific tools, it will allow an agent to:

  • ask an expert to create a codemod
  • improve a codemod
  • get setup instructions

​
IDE Configuration

​
Cline

Add this to your cline_mcp_settings.json:

{
  "mcpServers": {
    "graph_sitter.cli": {
        "command": "uv",
        "args": [
            "--directory",
            "<path to codegen installation>/codegen-sdk/src/graph_sitter.cli/mcp",
            "run",
            "server.py"
        ]
    }
  }
}

​
Cursor:

Under the Settings > Feature > MCP Servers section, click “Add New MCP Server” and add the following:

Name: codegen-mcp
Type: Command
Command: uv --directory <path to codegen installation>/codegen-sdk/src/graph_sitter.cli/mcp run server.py

​
Index Graph-sitter Docs

​
Cursor:

If you use Cursor you’ll be able to configure the IDE to index the Graph-sitter docs. To do so go to Settings > Features > Docs and then click on Add new docs. We recommend using this url to index the API reference:

https://graph-sitter.com/api-reference/index

​
Create a New Codemod

Generate the boilerplate for a new code manipulation program using gs create:

gs create organize-types \
  -d "Move all TypeScript types to \
      into a centralized types.ts file"

Passing in -d --description will get an LLM expert to compose an initial version for you. This requires a Github account registered on codegen.sh

This will:

  1. Create a new codemod in .codegen/codemods/organize_types/
  2. Generate a custom system-prompt.txt based on your task
  3. Set up the basic structure for your program

The generated codemod includes type hints and docstrings, making it easy to get IDE autocompletion and documentation.

​
Iterating with Chat Assistants

When you do gs init, you will receive a system prompt optimized for AI consumption at .codegen/codegen-system-prompt.txt.

If you reference this file in “chat” sessions with Copilot, Cursor, Cody, etc., the assistant will become fluent in Codegen.

Collaborating with Cursor’s assistant and the Graph-sitter system prompt

In addition, when you create a codemod with “-d”, Graph-sitter generates an optimized system prompt in .codegen/codemods/{name}/{name}-system-prompt.txt. This prompt contains:

  • Relevant Codegen API documentation
  • Examples of relevant transformations
  • Context about your specific task

You can also drag and drop the system prompt (available here)file directly into chat windows like ChatGPT or Claude for standalone help.

​
Running and Testing Codemods

# Run => write changes to disk
gs run organize-types

# Reset changes on disk
gs reset
You can also run the program directly via .codegen/.venv/bin/python path/to/codemod.py or via your editor’s debugger

​
Viewing Changes

We recommend viewing changes in your IDE’s native diff editor.

​
What’s Next

Explore Tutorials

See real-world examples of codemods in action.

Graph-sitter Guides

Learn about Codegen’s core concepts and features