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.

​

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

​

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

​

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)}")

​

Next Steps

After initializing your .codegen directory:

1. Create your first codemod:

gs create my-codemod . -d "describe what you want to do"

2. Run it:

gs run my-codemod --apply-local