Codeshift

Don't just flag the update. Fix the break.

Codeshift is an AI-powered CLI tool that migrates Python code when dependencies are upgraded. Unlike Dependabot or Renovate which only bump version numbers, Codeshift rewrites your code to be compatible with new library APIs.

Why Codeshift?

Upgrading a dependency often means updating dozens of call sites to match a new API. Codeshift automates that:

Scans your project for outdated dependencies
Detects breaking changes from changelogs and migration guides
Rewrites your code using deterministic AST transforms or LLM assistance
Shows a detailed diff with explanations before touching any file

Features

Deterministic AST transforms for 15 popular libraries (no LLM required)
Auto-generated knowledge bases - fetches changelogs and migration guides from GitHub, parses them with an LLM to detect breaking changes
Tiered migration engine - deterministic transforms first, KB-guided LLM second, pure LLM fallback last
Confidence-based change detection - shows HIGH/MEDIUM/LOW confidence breaking changes before migration
Beautiful diff output with per-change explanations
Backup and restore so you can safely revert
Batch upgrades - migrate all outdated dependencies in one command

Supported Libraries

Tier 1 (Deterministic AST Transforms - Free, No LLM Required)

Library	Migration Path	Status
Pydantic	v1 → v2	Supported
FastAPI	0.x → 0.100+	Supported
SQLAlchemy	1.4 → 2.0	Supported
Pandas	1.x → 2.x	Supported
Requests	Various	Supported
Django	3.x → 4.x/5.x	Supported
Flask	1.x → 2.x/3.x	Supported
NumPy	1.x → 2.x	Supported
attrs	attr → attrs	Supported
Celery	4.x → 5.x	Supported
Click	7.x → 8.x	Supported
aiohttp	2.x → 3.x	Supported
httpx	0.x → 0.24+	Supported
Marshmallow	2.x → 3.x	Supported
pytest	6.x → 7.x/8.x	Supported

Any Library (Auto-Generated Knowledge Base)

Codeshift can migrate any Python library by automatically fetching changelogs from GitHub and detecting breaking changes. For libraries not in Tier 1, it uses KB-guided or pure LLM migration.

Installation

pip install codeshift

For development:

pip install codeshift[dev]

Verify the installation:

codeshift --help

Quick Start

pip install codeshift
codeshift upgrade pydantic --target 2.5.0
codeshift diff && codeshift apply

That's it! Codeshift scans your code, transforms it, and shows exactly what changed.

Before / After

Pydantic v1	Pydantic v2
`class Config:`	`model_config = ConfigDict()`
`@validator`	`@field_validator`
`.dict()`	`.model_dump()`
`parse_obj()`	`model_validate()`

More Options

# Scan your project for all outdated dependencies
codeshift scan

# Or upgrade everything at once
codeshift upgrade-all

Example Output

$ codeshift upgrade pydantic --target 2.5.0

╭──────────────────────── Codeshift Migration ─────────────────────────╮
│ Upgrading Pydantic to version 2.5.0                                  │
│ Migration guide: https://docs.pydantic.dev/latest/migration/         │
╰──────────────────────────────────────────────────────────────────────╯

Fetching knowledge sources...
   ✓ GitHub: CHANGELOG.md
   ✓ GitHub: docs/migration.md

Breaking changes detected:

   HIGH CONFIDENCE:
   ├── .dict() → .model_dump()
   ├── @validator → @field_validator
   └── class Config → model_config = ConfigDict()

   MEDIUM CONFIDENCE:
   ├── .json() → .model_dump_json()
   └── parse_obj() → model_validate()

Scanning for library usage...
Found 12 imports from pydantic
Found 45 usages of pydantic symbols

┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┓
┃ File               ┃ Changes ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━┩
│ src/models/user.py │       5 │ Ready  │
│ src/api/schemas.py │       3 │ Ready  │
└────────────────────┴─────────┴────────┘

Total: 8 changes across 2 files

Commands

`codeshift scan`

Scan your project for outdated dependencies and available migrations.

codeshift scan [OPTIONS]

Options:
  --path, -p PATH       Path to scan (default: current directory)
  --fetch-changes       Fetch changelogs and detect breaking changes
  --major-only          Only show major version upgrades
  --json-output         Output results as JSON
  --verbose, -v         Show detailed output

Example:

$ codeshift scan

Found 13 dependencies

Outdated Dependencies (5)
┏━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━━━┓
┃ Package    ┃ Current ┃ Latest ┃ Type  ┃   Tier   ┃
┡━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━━━┩
│ pydantic   │     1.0 │  2.5.0 │ Major │  Tier 1  │
│ rich       │    13.0 │ 14.0.0 │ Major │ Tier 2/3 │
└────────────┴─────────┴────────┴───────┴──────────┘

Suggested Migrations (2)
  pydantic 1.0 → 2.5.0 (Tier 1 - deterministic)
  rich 13.0 → 14.0.0 (Tier 2/3 - LLM-assisted)

Quick commands:
  codeshift upgrade pydantic --target 2.5.0
  codeshift upgrade rich --target 14.0.0

`codeshift upgrade`

Analyze your codebase and propose changes for a specific library upgrade.

codeshift upgrade <library> --target <version> [OPTIONS]

Arguments:
  LIBRARY               Library name to upgrade (required)

Options:
  --target, -t VERSION  Target version to upgrade to (required)
  --path, -p PATH       Path to analyze (default: current directory)
  --file, -f PATH       Analyze a single file instead of the entire project
  --dry-run             Show what would be changed without saving state
  --verbose, -v         Show detailed output

`codeshift upgrade-all`

Upgrade all outdated packages to their latest versions in one go.

codeshift upgrade-all [OPTIONS]

Options:
  --path, -p PATH       Path to analyze (default: current directory)
  --all                 Include all outdated packages (not just Tier 1)
  --tier1-only          Only upgrade Tier 1 libraries (deterministic transforms)
  --major-only          Only perform major version upgrades
  --include, -i LIB     Only include specific libraries (repeatable)
  --exclude, -e LIB     Exclude specific libraries (repeatable)
  --update-deps         Update dependency files with new versions (default: yes)
  --no-update-deps      Skip updating dependency files
  --dry-run             Show what would be changed without saving state
  --verbose, -v         Show detailed output

`codeshift diff`

View the detailed diff of proposed changes.

codeshift diff [OPTIONS]

Options:
  --path, -p PATH       Path to the project (default: current directory)
  --file, -f FILE       Show diff for a specific file only
  --no-color            Disable colored output
  --context, -c INT     Number of context lines (default: 3)
  --summary             Show only a summary without the full diff

`codeshift show`

Show the full transformed or original code for a file.

codeshift show <file_path> [OPTIONS]

Arguments:
  FILE_PATH             File to display (required)

Options:
  --path, -p PATH       Path to the project (default: current directory)
  --original            Show the original code instead of the transformed version

`codeshift apply`

Apply the proposed changes to your files.

codeshift apply [OPTIONS]

Options:
  --path, -p PATH       Path to the project (default: current directory)
  --file, -f FILE       Apply changes to a specific file only
  --backup              Create .bak backup files before applying changes
  --yes, -y             Skip confirmation prompt
  --validate            Validate syntax after applying (default: yes)
  --no-validate         Skip syntax validation

`codeshift reset`

Cancel the current migration and clear all pending changes.

codeshift reset [OPTIONS]

Options:
  --path, -p PATH       Path to the project (default: current directory)
  --yes, -y             Skip confirmation prompt

`codeshift restore`

Restore files from a backup created by apply --backup.

codeshift restore <backup_dir> [OPTIONS]

Arguments:
  BACKUP_DIR            Path to backup directory (required)

Options:
  --path, -p PATH       Path to the project (default: current directory)
  --yes, -y             Skip confirmation prompt

`codeshift libraries`

List all supported libraries and their migration paths.

codeshift libraries

`codeshift status`

Show current migration status, pending changes, and quota info.

codeshift status [OPTIONS]

Options:
  --path, -p PATH       Path to the project (default: current directory)

Account Commands

codeshift login              # Login to enable cloud features
codeshift register           # Create a new account
codeshift logout             # Logout and remove credentials
codeshift whoami             # Show current user info
codeshift quota              # Show usage and limits
codeshift upgrade-plan       # View or upgrade your plan
codeshift billing            # Open billing portal

How It Works

┌─────────────────────────────────────────────────────────────────────┐
│                     Knowledge Acquisition Pipeline                   │
│  ┌─────────────┐   ┌──────────────────┐   ┌─────────────────────┐  │
│  │ Local Cache │──▶│ On-Demand Gen    │──▶│ LLM Parser          │  │
│  │ (instant)   │   │ (fetches sources)│   │ (breaking changes)  │  │
│  └─────────────┘   └──────────────────┘   └─────────────────────┘  │
│                            │                                        │
│            ┌───────────────┴───────────────┐                       │
│            │  Source Fetchers              │                       │
│            │  ├── GitHub (CHANGELOG.md)    │                       │
│            │  ├── Docs (migration guides)  │                       │
│            │  └── Release notes            │                       │
│            └───────────────────────────────┘                       │
└─────────────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│                    Migration Engine (Tiered)                        │
│  Tier 1: AST Transforms  │  Tier 2: KB-Guided  │  Tier 3: LLM      │
│  (deterministic)         │  (context + LLM)    │  (fallback)       │
└─────────────────────────────────────────────────────────────────────┘

Fetch Knowledge - discovers and fetches changelogs, migration guides from GitHub/PyPI
Parse Changes - uses an LLM to extract breaking changes with confidence levels (HIGH/MEDIUM/LOW)
Scan Codebase - finds imports and usage of the target library using libcst
Tiered Migration:
- Tier 1: deterministic AST transforms for 15 supported libraries - no LLM needed
- Tier 2: knowledge base guided migration with LLM assistance
- Tier 3: pure LLM migration for unknown patterns
Validate - runs syntax checks on the transformed code
Report - shows a detailed diff with explanations for each change

Pydantic v1 → v2 Example

Codeshift handles the following Pydantic migrations automatically:

v1 Pattern	v2 Replacement
`Config` class	`model_config = ConfigDict(...)`
`@validator`	`@field_validator` with `@classmethod`
`@root_validator`	`@model_validator`
`.dict()`	`.model_dump()`
`.json()`	`.model_dump_json()`
`.schema()`	`.model_json_schema()`
`.parse_obj()`	`.model_validate()`
`orm_mode = True`	`from_attributes = True`
`Field(regex=...)`	`Field(pattern=...)`

Configuration

Codeshift can be configured via pyproject.toml:

[tool.codeshift]
# Path patterns to exclude from scanning
exclude = ["tests/*", "migrations/*"]

# Enable/disable LLM fallback
use_llm = true

# Anthropic API key (can also use ANTHROPIC_API_KEY env var)
# anthropic_api_key = "sk-..."

GitHub Action

Run Codeshift automatically in CI with the official GitHub Action:

- uses: Ragab-Technologies/codeshift@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

This will scan for outdated dependencies, run Tier 1 deterministic migrations, and open a PR with the changes. No API key required for Tier 1 transforms.

See docs/github-action.md for full documentation, all inputs/outputs, and example workflows.

Environment Variables

Variable	Required	Description
`ANTHROPIC_API_KEY`	For Tier 2/3	Enables LLM-powered migrations
`GITHUB_TOKEN`	No	Higher GitHub API rate limits

Pricing

Tier	Price	What You Get
Free	$0/month	Tier 1 deterministic transforms for all 15 supported libraries. Runs entirely locally.
Pro	$19/month	Tier 2 KB-guided LLM migrations for any library
Unlimited	$49/month	Tier 3 pure LLM migrations + priority support

# Login to access Pro/Unlimited features
codeshift login

# Check your current plan and usage
codeshift quota

License

This software is licensed under the MIT License.

You are free to use, modify, and distribute this software. The CLI tool and all transforms are fully open source.

Name		Name	Last commit message	Last commit date
Latest commit History 152 Commits
.github		.github
action-scripts		action-scripts
assets		assets
codeshift		codeshift
docs		docs
examples/workflows		examples/workflows
tests		tests
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
commitlint.config.js		commitlint.config.js
noxfile.py		noxfile.py
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

Ragab-Technologies/Codeshift

Folders and files

Latest commit

History

Repository files navigation

Codeshift

Why Codeshift?

Features

Supported Libraries

Tier 1 (Deterministic AST Transforms - Free, No LLM Required)

Any Library (Auto-Generated Knowledge Base)

Installation

Quick Start

Before / After

More Options

Example Output

Commands

codeshift scan

codeshift upgrade

codeshift upgrade-all

codeshift diff

codeshift show

codeshift apply

codeshift reset

codeshift restore

codeshift libraries

codeshift status

Account Commands

How It Works

Pydantic v1 → v2 Example

Configuration

GitHub Action

Environment Variables

Pricing

License

About

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors 3

Uh oh!

Languages

`codeshift scan`

`codeshift upgrade`

`codeshift upgrade-all`

`codeshift diff`

`codeshift show`

`codeshift apply`

`codeshift reset`

`codeshift restore`

`codeshift libraries`

`codeshift status`

Packages