The .codegen Directory

The .codegen directory contains your project’s Codegen configuration, codemods, and supporting files. It’s automatically created when you run codegen 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 codegen init command:

codegen init [--fetch-docs] [--repo-name NAME] [--organization-name ORG]

​

Virtual Environment

Codegen 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 Codegen commands
• Used for running codemods and Jupyter notebooks
• Gitignored to avoid committing environment-specific files

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

​

Configuration

The config.toml file stores your project settings:

organization_name = "your-org"
repo_name = "your-repo"
programming_language = "python"  # or other supported language

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

​

Git Integration

Codegen 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:

codegen create my-codemod [--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 codegen 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:

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

2. Run it:

codegen run my-codemod --apply-local

3. Deploy it for team use:

codegen deploy my-codemod