graph-sitter
Documentation menu

The .codegen Directory

The .codegen directory contains your project's Graph-sitter configuration, codemods, and supporting files. It's automatically created when you run gs init.

Directory Structure

.codegen/
├── .venv/            # Python virtual environment (gitignored)
├── config.toml       # Project configuration
├── codemods/         # Your codemod implementations
├── jupyter/          # Jupyter notebooks for exploration
└── codegen-system-prompt.txt  # AI system prompt

Initialization

The directory is created and managed using the gs init command:

gs init [--repo-name NAME] [--organization-name ORG]

Virtual Environment

Graph-sitter maintains its own virtual environment in .codegen/.venv/ to ensure consistent package versions and isolation from your project's dependencies. This environment is:

  • Created using uv for fast, reliable package management
  • Initialized with Python 3.13
  • Automatically managed by Graph-sitter commands
  • Used for running codemods and Jupyter notebooks
  • Gitignored to avoid committing environment-specific files

The environment is created during gs init and used by commands like gs run and gs notebook.

To debug codemods, you will need to set the python virtual environment in your IDE to .codegen/.venv

Configuration

The .env file stores your project settings:

REPOSITORY_OWNER = "your-org"
REPOSITORY_PATH = "/root/git/your-repo"
REPOSITORY_LANGUAGE = "python"  # or other supported language

This configuration is used by Graph-sitter to provide language-specific features and proper repository context.

Git Integration

Graph-sitter automatically adds appropriate entries to your .gitignore:

# Codegen
.codegen/.venv/
.codegen/docs/
.codegen/jupyter/
.codegen/codegen-system-prompt.txt
  • While most directories are ignored, your codemods in .codegen/codemods/ and config.toml are tracked in Git
  • The virtual environment and Jupyter notebooks are gitignored to avoid environment-specific issues

Working with Codemods

The codemods/ directory is where your transformation functions live. You can create new codemods using:

gs create my-codemod PATH [--description "what it does"]

This will:

  1. Create a new file in .codegen/codemods/
  2. Generate a system prompt in .codegen/prompts/ (if using --description)
  3. Set up the necessary imports and decorators

Use gs list to see all codemods in your project.

Jupyter Integration

The jupyter/ directory contains notebooks for interactive development:

from graph_sitter import Codebase
 
# Initialize codebase
codebase = Codebase('../../')
 
# Print stats
print(f"📚 Total Files: {len(codebase.files)}")
print(f"⚡ Total Functions: {len(codebase.functions)}")

A default notebook is created during initialization to help you explore your codebase.

Next Steps

After initializing your .codegen directory:

  1. Create your first codemod:
gs create my-codemod . -d "describe what you want to do"
  1. Run it:
gs run my-codemod --apply-local