dobbe

dobbe migration

Plan and execute dependency migrations with AI-powered analysis.

Synopsis

dobbe migration plan --from <dep> --to <dep> [OPTIONS]
dobbe migration run  --from <dep> --to <dep> [OPTIONS]

Description

dobbe migration provides two subcommands for dependency migration:

• plan - Analyze a repository and generate a step-by-step migration plan without making any code changes.
• run - Execute the migration using an agentic apply-verify loop that iteratively applies changes, runs tests, and fixes failures until convergence.

Both subcommands accept dependency specifiers in the form package==version (e.g., requests==2.28.0). When --repo is omitted, the repository is auto-detected from the current working directory.

---

migration plan

Synopsis

dobbe migration plan --from <dep> --to <dep> [OPTIONS]

Description

migration plan analyzes the repository’s codebase to identify all usages of the source dependency, evaluates API differences with the target dependency, and produces a structured migration plan. The plan includes estimated complexity, ordered steps, file paths, breaking-change flags, and risk assessments. No code changes are made.

Flowchart

┌─────────────────────────────────────────────────────┐
│  dobbe migration plan --from requests --to httpx    │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Parse CLI args + merge config defaults              │
│  - repo from --repo or CWD auto-detect               │
│  - format from --format or config                    │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Auto-detect repo (if --repo omitted)                │
│  Read git remote from CWD -> org/repo                │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Discover MCP servers + extra tools                  │
│  (~/.claude/settings.json)                           │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Run migration plan via Claude                       │
│  - Scan imports, usages, config files                │
│  - Compare source/target API surfaces                │
│  - Identify breaking changes + risks                 │
│  - Produce ordered step list                         │
│  Tools: [Bash, Read, Grep, Glob] + MCP               │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Save session (best-effort)                          │
│  Enables cross-command resume                        │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Render output                                       │
│  --format table (default) / json / markdown          │
│  --output file (optional)                            │
└─────────────────────────────────────────────────────┘

Options

Option	Type	Default	Description
--repo / -r	str	-	Repository to analyze (org/repo). Auto-detected from CWD if omitted.
--from	str	(required)	Source dependency (e.g., requests==2.28.0)
--to	str	(required)	Target dependency (e.g., httpx==0.25.0)
--format / -f	str	config default	Output format: table, json, markdown
--output	str	-	Write output to file instead of stdout
--quiet / -q	bool	False	Suppress progress output

Both --from and --to are required.

Examples

Analyze a migration from requests to httpx

dobbe migration plan --repo acme/web-app --from "requests==2.28.0" --to "httpx==0.25.0"

Auto-detect repo from CWD

cd ~/projects/api
dobbe migration plan --from "flask==2.3.0" --to "fastapi==0.104.0"

JSON output for CI integration

dobbe migration plan --repo acme/web-app --from "django==4.2" --to "django==5.0" --format json --output plan.json

Markdown report

dobbe migration plan --repo acme/web-app --from "celery==5.2" --to "celery==5.3" --format markdown

---

migration run

Synopsis

dobbe migration run --from <dep> --to <dep> [OPTIONS]

Description

migration run executes a full dependency migration using an agentic apply-verify loop. The agent first generates a migration plan, then iteratively applies code changes, runs tests, and fixes any failures. The loop continues until tests pass (convergence) or the maximum number of iterations is reached. On convergence, a pull request is created by default.

Flowchart

┌─────────────────────────────────────────────────────┐
│  dobbe migration run --from requests --to httpx     │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Parse CLI args + merge config defaults              │
│  - repo from --repo or CWD auto-detect               │
│  - format from --format or config                    │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Auto-detect repo (if --repo omitted)                │
│  Read git remote from CWD -> org/repo                │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Discover MCP servers + extra tools                  │
│  (~/.claude/settings.json)                           │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Resolve local path                                  │
│  CWD path / configured paths / common dirs           │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Agentic apply-verify loop (up to --max-iterations)  │
│                                                      │
│  ┌────────────────────────────────────────────┐      │
│  │  Iteration 1..N                            │      │
│  │  1. Generate / refine migration plan       │      │
│  │  2. Apply code changes                     │      │
│  │  3. Run tests                              │      │
│  │  4. If tests fail -> diagnose + loop       │      │
│  │  5. If tests pass -> converged             │      │
│  └────────────────────────────────────────────┘      │
│                                                      │
│  Tools: [Bash, Read, Grep, Glob, Edit] + MCP         │
└─────────────────────────┬───────────────────────────┘
                          │
                    ┌─────┴──────┐
                    │ Converged? │
                    └─────┬──────┘
                   yes/   │   \no
                  ┌───┐   │   ┌────────────────────┐
                  │   v   │   v                    │
┌─────────────────────────────────────────────────────┐
│  --create-pr (default): create pull request          │
│  --no-pr: skip PR creation                           │
│  --dry-run: plan only, no code changes applied       │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Save session (best-effort)                          │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Render migration report                             │
│  --format table (default) / json / markdown          │
└─────────────────────────┬───────────────────────────┘
                          │
                          v
┌─────────────────────────────────────────────────────┐
│  Optional: Notify                                    │
│  --notify slack / jira -> send report                │
└─────────────────────────────────────────────────────┘

Options

Option	Type	Default	Description
--repo / -r	str	-	Repository to migrate (org/repo). Auto-detected from CWD if omitted.
--from	str	(required)	Source dependency (e.g., requests==2.28.0)
--to	str	(required)	Target dependency (e.g., httpx==0.25.0)
--max-iterations	int	3	Max apply-verify iterations (1-10)
--create-pr / --no-pr	bool	True	Create a pull request on convergence
--base	str	-	Base branch for the PR (auto-detected if not specified)
--dry-run	bool	False	Generate plan only, no code changes applied
--format / -f	str	config default	Output format: table, json, markdown
--notify	str	-	Send report to platform (slack, jira)
--channel	str	-	Notification channel (e.g., #migrations)
--quiet / -q	bool	False	Suppress progress output

Both --from and --to are required.

Examples

Run a migration with default settings

dobbe migration run --repo acme/web-app --from "requests==2.28.0" --to "httpx==0.25.0"

Auto-detect repo from CWD

cd ~/projects/api
dobbe migration run --from "flask==2.3.0" --to "fastapi==0.104.0"

Increase iteration limit for complex migrations

dobbe migration run --repo acme/web-app --from "django==4.2" --to "django==5.0" --max-iterations 5

Dry run (plan only, no code changes)

dobbe migration run --repo acme/web-app --from "celery==5.2" --to "celery==5.3" --dry-run

Skip PR creation

dobbe migration run --repo acme/web-app --from "pytest==7.0" --to "pytest==8.0" --no-pr

Specify base branch and notify Slack

dobbe migration run --repo acme/web-app --from "requests==2.28.0" --to "httpx==0.25.0" \
  --base develop --notify slack --channel "#migrations"

JSON output for CI

dobbe migration run --repo acme/web-app --from "sqlalchemy==1.4" --to "sqlalchemy==2.0" \
  --format json --quiet

---

CWD Auto-Detect

Both subcommands support automatic repository detection when --repo is omitted. The command reads the git remote from the current working directory and derives the org/repo slug. This means you can run the command from inside a cloned repository:

cd ~/projects/my-api
dobbe migration plan --from "requests==2.28.0" --to "httpx==0.25.0"
dobbe migration run  --from "requests==2.28.0" --to "httpx==0.25.0"

If the current directory is not a git repository or has no remote, the command will print an error and exit.

Internal Architecture

Migration Plan Model

The MigrationPlan produced by the plan subcommand includes:

• repo - target repository
• from_dep / to_dep - source and target dependency specifiers
• estimated_complexity - AI-assessed complexity (low, medium, high)
• total_steps - number of migration steps
• breaking_changes - count of steps flagged as breaking
• risks - list of identified risk factors
• steps - ordered list with description, file path, breaking-change flag, and notes

Apply-Verify Loop

The run subcommand uses a MigrationConfig to drive an iterative loop:

1. The agent generates a migration plan (or refines one from a previous iteration).
2. Code changes are applied to the local repository.
3. Tests are executed to verify correctness.
4. If tests fail, the agent diagnoses failures and loops back.
5. The loop exits when tests pass (converged) or --max-iterations is reached.

Migration Report Model

The MigrationReport produced by the run subcommand includes:

• converged - whether tests passed within the iteration limit
• iterations_used - number of apply-verify cycles executed
• pr_url - URL of the created pull request (if applicable)
• plan - the underlying MigrationPlan
• summary - AI-generated summary of changes made
• error - error message if the migration failed

Session Storage

Both subcommands save their output to the session store (command: migration_plan or command: migration_run), enabling cross-command workflows where later commands can reference migration results.

See Also

• Configuration reference - default format settings
• MCP integrations - GitHub MCP for PR creation, Slack/Jira for notifications
• setup - configure default notification channels

This site is open source. Improve this page.