Estimate the Bill Before an Agent Runs a Migration

Before giving an agent permission to migrate a codebase, estimate the cost of reaching a verified result—not merely generating a patch. Repository inspection, test failures, retries, and review all belong in the budget. A useful estimate connects a bounded task to measured usage, then defines where execution must stop.

1. Define the migration’s finish line

Write down the starting state, target state, permitted changes, and acceptance checks. “Upgrade the application” is not a costable task. “Update the database client, replace deprecated calls in the service layer, and pass the integration suite” gives the agent a bounded assignment.

Separate exploration from implementation. Authorize an initial read-only inventory before allowing edits, dependency installation, or database access. Require approval for scope expansion, especially when the agent discovers unrelated cleanup.

2. Count work units, not repository lines

Inventory the files and change patterns that actually matter. Group repeated substitutions separately from semantic changes, such as transaction handling or altered error behavior. File count alone will not capture that difference.

• Discovery: Locate dependencies, affected call sites, configuration, and tests.
• Implementation: Apply each distinct transformation pattern.
• Verification: Run targeted checks and investigate failures.
• Review: Inspect the diff, explain exceptions, and prepare rollback instructions.

Record counts for each category. These become the multipliers in the estimate and make later scope changes visible.

3. Capture the billing assumptions

Record the selected model and the applicable input, output, and any separately priced cached-input rates. Confirm the billing unit and currency. Do not assume that a subscription to a coding tool covers API requests routed through another provider.

When using CodeRelay Hub, record the chosen model and its applicable rates alongside the estimate. Routing through one endpoint simplifies connection setup, but your budget still needs explicit pricing assumptions for the model you select.

Keep non-model expenses separate: test infrastructure, build workers, temporary databases, and other paid services. A token estimate is not the entire migration budget.

4. Run a representative, bounded pilot

Choose a small slice containing a typical transformation and a difficult edge case. Give the agent the same instructions, tools, and verification requirements planned for the full migration. A pilot that skips testing measures patch generation, not completion.

Capture usage for every model request, including failed attempts where usage is reported. Record input tokens, output tokens, separately reported cache usage, elapsed time, tool activity, and completed work units. Preserve missing usage as unknown rather than silently counting it as zero.

Also inspect what gets sent back into context. Repeated file reads, oversized command output, and full test logs are candidates for tighter limits.

5. Build the estimate from measured work

For rates quoted per million tokens, calculate each request as: input tokens × input rate / 1,000,000 + output tokens × output rate / 1,000,000. Apply separate cache categories according to the billing rules, without counting the same tokens twice.

Then estimate: discovery cost + remaining work units × measured cost per comparable unit + verification and review cost. Use separate unit costs for mechanical edits and semantic changes. Keep fixed discovery work separate from costs that repeat per batch.

6. Price recovery paths explicitly

Create a base case and a difficult case using concrete events: another test-and-repair cycle, investigation of an unfamiliar subsystem, or escalation to a different model. Estimate those events from pilot observations where possible. Label unmeasured allowances as assumptions, not evidence.

Avoid an unexplained contingency percentage. “One additional integration-test repair cycle” gives reviewers something they can challenge and operators something they can recognize.

7. Enforce a stopping policy

Set limits for spending, requests, retries, elapsed time, and concurrent work. Decide which component checks them before dispatching another request. Leave headroom for requests already in flight; stopping new work does not cancel charges already incurred.

Require approval before expanding scope or changing models. At each checkpoint, save the diff, usage ledger, verification results, and remaining-work estimate. Keep production credentials unavailable unless explicitly required and approved.

8. Reconcile before scaling up

Compare the pilot estimate with billed usage, investigate discrepancies, and revise the remaining budget before continuing. Release work in batches with clear acceptance checks. The goal is not a perfectly predicted bill; it is a migration whose cost and stopping conditions remain understandable throughout execution.

Open a free workspace in CodeRelay Hub.