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]

The --fetch-docs flag downloads API documentation and examples specific to your project’s programming language.

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.

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

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

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

Use codegen list to see all codemods in your project.

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

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:

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