How Claude Code vs OpenHands changes migration economics

Portability pays only when the freedom to change models or runtimes saves more engineering time than the second platform consumes. Most teams compare feature tables, prove that both agents can edit the same repository, and call the result portable. That test misses the expensive parts: instructions, permissions, tool authentication, CI event handling, output parsing, and the person who owns every upgrade.

Claude Code and OpenHands make different tradeoffs. Claude Code gives a tightly integrated path around Anthropic's coding agent, with documented project settings, hooks, MCP configuration, and a first-party GitHub Action. OpenHands gives you a broader model and deployment boundary through its CLI, cloud offering, open-source runtime, and Software Agent SDK. Neither choice is universally safer or cheaper. The answer depends on what you want the option to switch away from, and how often you expect to exercise that option.

Portability is an operating choice, not a model dropdown

A portable model setting does not make an agent workflow portable. Model portability means you can point an agent at another provider or model. Workflow portability means the replacement still reads the right instructions, receives equivalent tools, obeys the same approval policy, runs in CI, returns machine-readable results, and leaves enough evidence to debug a bad run. Teams routinely blur these two ideas and then underestimate a migration by an order of magnitude.

OpenHands exposes model selection as an explicit configuration boundary. Its CLI documentation shows provider, model, API key, and optional base URL in ~/.openhands/agent_settings.json; temporary environment overrides use LLM_MODEL, LLM_API_KEY, and LLM_BASE_URL. The SDK follows the LiteLLM naming convention, such as provider/model_name, which makes model experiments a normal part of the design. A team that must run an internal endpoint, compare several providers, or use a locally hosted model gets real option value from that boundary.

Claude Code lets you select supported Claude models with the model option, aliases, settings, and environment variables. It can also run through Anthropic's API and supported enterprise platforms. That is choice within an Anthropic-centered product, not provider-neutral orchestration. If your procurement requirement says, "We must be able to replace the model vendor without replacing the agent runtime," Claude Code alone does not meet it. If the requirement says, "We need to move between approved Claude deployments without rebuilding developer workflow," it may meet it with much less machinery.

Write the required escape hatch in one sentence before comparing tools. Examples include "run the same pull-request review against two model providers," "keep source code inside our controlled runtime," or "replace the interactive client while retaining shared MCP tools." If nobody can name the event that triggers a switch, portability is an insurance policy without a covered loss. You will keep paying its premium through configuration drift.

Model choice is the easiest part to move

Changing a model identifier takes minutes; restoring task quality can take weeks. Agents depend on tool-call reliability, context handling, patch discipline, instruction priority, and recovery after a failed command. Two models that both accept chat messages and tool schemas can behave differently enough to break the same unattended workflow.

This is where OpenHands has the clearer experimentation surface. You can parameterize provider, model, base URL, and credentials, then run a fixed task set through the CLI or SDK. That helps when model diversity is a business requirement. It does not remove model-specific tuning. OpenHands documentation warns that effective local models need capable hardware and models suited to instruction following and agent behavior. An endpoint responding to a compatible API is not evidence that it can finish a repository task.

Claude Code reduces the combinations you must validate. Its prompts, tools, session behavior, permissions, and model family evolve as one product. The smaller matrix often matters more than theoretical choice for a team with one platform engineer. A provider-neutral layer can create six combinations of model, runtime, and sandbox while the team has capacity to test two. Untested portability is configuration inventory, not resilience.

Use a behavioral contract instead of a favorite benchmark. Keep ten to twenty tasks taken from your own work: a failing unit test, a small feature behind an existing interface, a database migration review, an ambiguous bug report, a documentation correction, and a task that must refuse a dangerous command. Record success criteria that scripts can check. A useful result row looks like this:

{"case":"auth-cookie-regression","agent":"openhands","model":"provider/model","exit_code":0,"tests_passed":true,"forbidden_paths_changed":[],"human_review_minutes":11}

Run the same cases after any model or agent upgrade. Compare completion, prohibited changes, review time, token or API cost, and retries. Do not reduce the decision to pass rate. A run that passes after rewriting half the repository can cost more review time than a clean failure.

Model flexibility repays migration when you use it: negotiating provider terms, meeting a data-location rule, routing low-risk tasks to a cheaper model, or recovering from a provider outage. If every production workflow remains pinned to one Claude model because it performs best, moving to OpenHands bought a capability you are not consuming. That can still be a rational hedge, but put the hedge in the budget rather than disguising it as immediate savings.

Workflow configuration carries the hidden switching cost

Repository instructions look like prose, but they behave like program logic. Claude Code commonly receives project guidance through CLAUDE.md, settings under .claude/, permissions, hooks, commands, skills, and plugins. OpenHands has its own agent settings, runtime choices, microagents or repository guidance, security settings, conversation controls, and SDK composition. Copying the sentences preserves only the most visible layer.

Consider an instruction that says, "Run focused tests before the full suite." In one setup, a hook may block a commit until a command succeeds. In another, that sentence is advice the model may interpret. Those are not equivalent controls. A hook has an event, matcher, input, exit status, and failure mode. A prompt has probabilistic compliance. During migration, classify every behavior as instruction, deterministic control, credential boundary, or operator habit. Rebuild each item with the same enforcement level.

Create a workflow inventory in the repository rather than in a meeting document:

behaviors:
  - id: protect_generated_client
    trigger: before_file_write
    enforcement: block
    paths: ["src/generated/**"]
    evidence: "tool event plus denied path"
  - id: focused_tests
    trigger: after_edit
    enforcement: advise
    command: "./scripts/test-changed"
    evidence: "command and exit code"
  - id: release_approval
    trigger: before_command
    enforcement: human
    command_pattern: "./scripts/release*"
    evidence: "approver identity and decision"

The exact file format is yours. Its job is to expose semantics that a platform-specific directory hides. During a Claude Code to OpenHands trial, mark each behavior as native, adapted, externalized, or dropped. "Adapted" needs an owner and a test. "Dropped" needs a risk acceptance, not a quiet omission.

Security deserves a separate equivalence test. An approval prompt is not a sandbox, and a sandbox is not a credential policy. Record which process can read repository secrets, reach the network, install dependencies, modify git history, and write outside the workspace. Then test denials rather than trusting configured names. A migrated agent that completes more tasks by inheriting broader credentials has not preserved workflow quality; it has changed risk. Compare the human decision point too. Ten low-context prompts in a CI run invite blind approval, while one structured approval with command, target, and reason can be reviewed. Portability must preserve the decision a reviewer can actually make.

The popular recommendation to maintain identical prompts for both agents is wrong. Identical text gives you textual symmetry while tool names, event models, permissions, and context loading differ. Maintain one short, platform-neutral policy for invariant rules, then thin adapters for each agent. The shared policy might ban edits under generated paths; one adapter can enforce that through Claude Code permissions or hooks, while another applies an OpenHands security control or an external filesystem check. Equivalence is the target, not identical files.

Configuration also includes what developers remember. Slash commands, resume behavior, local overrides, approval prompts, and recovery steps become muscle memory. Include onboarding and support tickets in migration cost. A tool that saves five minutes per task can still lose if every engineer needs repeated help after minor configuration changes.

MCP compatibility does not make integrations portable

MCP standardizes how an agent discovers and calls external tools, but it does not standardize every host decision around those calls. Both products support MCP. That gives you reusable server definitions and schemas, which is meaningful. It does not guarantee the same transport support, authentication flow, configuration scope, tool filtering, approval experience, environment handling, startup behavior, or output limits.

Claude Code's MCP manual distinguishes local, project, and user scopes. Project configuration lives in .mcp.json, can enter version control, and requires approval before use. The manual also documents stdio and remote HTTP connections, environment expansion, OAuth for remote servers, and commands such as claude mcp list. Its debugging guide calls out a failure I have seen in many toolchains: relative executable paths resolve from the launch directory, so an MCP server works in one shell and fails in CI or a different subdirectory.

OpenHands' SDK guide configures servers through an mcpServers dictionary and can filter exposed tools with a regular expression. Its OAuth example stores tokens through the underlying client and requires browser interaction on first use. The guide explicitly says that this flow does not suit fully automated headless jobs unless the provider offers another authentication method. That qualification matters more than a checkbox marked "OAuth supported."

Test an integration contract at the MCP boundary. For each server, capture transport, startup command or URL, required environment variables, authentication method, exposed tool names, destructive annotations, expected timeout, and maximum useful response size. Then run four probes:

1. Start the server from the repository root and from a nested directory.
2. List tools and compare names plus input schemas.
3. Call one read-only tool with a known result and one denied write tool.
4. Restart without cached credentials in a headless environment.

The fourth probe finds the expensive surprises. A developer's browser session can hide a CI authentication gap for months. A local stdio command can depend on a package runner that your production image does not contain. A project file can reference an environment variable that exists on laptops but not on pull requests from forks.

Keep MCP servers outside either agent's private configuration when they are strategic. Package the server, pin its dependency version, test its schema, and generate host-specific entries from a small source record. You still need adapters because the host configurations differ, but you stop duplicating the integration's behavior. MCP reduces the adapter width; it does not erase the adapter.

CI exposes the architectural difference

CI turns an assistant into a production dependency. Interactive use tolerates clarification, browser authentication, a developer noticing a strange diff, and a manual retry. A pull-request job needs a defined event, permission set, workspace, secret policy, timeout, output contract, concurrency rule, and failure disposition. The choice between Claude Code and OpenHands becomes much clearer once those nouns are written down.

Claude Code provides a first-party GitHub Action path and a manual workflow option. Its documentation shows claude_args for limits and model selection, including controls for maximum turns, model selection, and MCP configuration. That shortens the path to issue triage, pull-request work, or review in GitHub. The coupling is intentional: your workflow depends on the action's inputs, Anthropic authentication, Claude Code permissions, and the behavior of that release.

OpenHands documents CI integration through its Software Agent SDK and composite GitHub Actions for jobs such as pull-request review. The SDK route gives you more control over agent construction, tools, events, callbacks, and runtime. You pay for that control by owning more application code. If you need GitLab, an internal queue, or a custom sandbox policy, that ownership may be exactly why you migrate. If GitHub is your only control plane, replacing a maintained action with your own SDK wrapper can be an expensive way to achieve the same result.

Treat CI outputs as an API. Do not let downstream steps scrape conversational prose. Require an exit code and a result object with stable fields:

{"status":"changes_proposed","commit":"abc1234","checks":{"unit":"passed","lint":"passed"},"review_required":true,"artifacts":["agent.patch","run-events.jsonl"]}

Claude Code print mode supports structured output options for scripting, while OpenHands offers headless and SDK paths with programmatic events. The field names above are a wrapper contract, not a claim that either tool emits that exact object. Build the wrapper once per platform and make the rest of CI depend on your contract.

A safe migration shadows before it writes. Run the candidate agent on the same event, with repository write credentials removed, and store its proposed patch as an artifact. Compare changed files, test results, wall time, spend, and reviewer minutes for at least a representative slice of work. Then allow writes on low-risk repositories while keeping release, infrastructure, dependency, and secret changes behind human approval. Agent success in CI means bounded failure, not maximum autonomy.

CI also reveals license, image, and upgrade ownership. OpenHands can run open source locally, in its cloud service, or through an SDK, so somebody must choose and maintain that deployment boundary. Claude Code moves more runtime decisions into the product but leaves you responsible for action versions, permissions, secrets, and repository policy. Neither removes operational work; they place it in different columns.

Migration cost belongs in engineer-hours

The install is usually the cheapest line item. Price the migration as discovery, adaptation, validation, rollout, and rollback work. Include the hours of senior engineers who understand the existing exceptions. Those exceptions are precisely what a clean-room migration overlooks.

Use a break-even calculation that a founder can audit:

migration_hours = inventory + adapters + integration_tests + ci_rebuild + training + rollback_plan
monthly_net_savings = current_maintenance_hours - candidate_maintenance_hours
                    + model_or_runtime_savings_in_engineer_hours
break_even_months = migration_hours / monthly_net_savings

Convert cash differences into engineer-hours with a loaded hourly rate, but keep the cash figures beside the conversion. API savings and payroll time are not interchangeable operationally. A lower model bill may help finance while the platform engineer still loses a day every month to compatibility fixes.

Suppose discovery takes 24 hours, workflow adapters 48, MCP and credential work 32, CI rebuilding 40, evaluation 36, training 16, and rollback preparation 12. The migration totals 208 hours. If OpenHands cuts model and runtime cost by the equivalent of 12 engineering hours each month but adds 8 hours of platform maintenance, net savings are 4 hours. Break-even takes 52 months. If a vendor constraint would otherwise cost 80 hours during each of two expected procurement events, include that expected avoided cost carefully; do not pretend it is monthly productivity.

Run three cases: optimistic, base, and adverse. The adverse case should include one broken provider adapter, one MCP authentication change, and a model regression that forces retuning. If the decision works only in the optimistic case, it is a bet on quiet dependencies. That may be acceptable for a small experimental workflow, but it is poor reasoning for the system that reviews every pull request.

Migration cost also depends on reversibility. Keep the existing CI job available behind a flag until the candidate has survived the agreed observation window. Store agent-neutral task fixtures and result records. Avoid transforming every repository at once. A reversible migration costs a little more at the start and dramatically less when the new path fails on an untested repository shape.

Do not count sunk evaluation time as a reason to finish. Teams often spend forty hours on a proof of concept, dislike the operational result, then migrate because abandoning the trial feels wasteful. The trial bought information. Use it. The remaining migration hours must still beat the future savings.

Monthly maintenance decides whether portability pays

Maintenance is the recurring premium for portability. Measure it by cause, not by a single bucket called "AI tooling." A useful ledger separates agent upgrades, model retuning, provider changes, MCP server work, CI repairs, security review, developer support, and evaluation runs. Without that split, the flexible platform receives blame for model churn or gets credit for work another team quietly absorbs.

For eight to twelve weeks, record each maintenance event with start time, owner, affected repositories, trigger, and resolution. Count interrupted developer time as well as the platform engineer's keyboard time. One broken configuration that consumes two hours centrally and fifteen minutes for twenty developers costs seven hours, not two.

Claude Code often wins when a small team wants one opinionated interactive and GitHub workflow, already accepts Anthropic as the model boundary, and values fewer components. Maintenance concentrates on project instructions, permissions, hooks, MCP servers, action versions, and evaluation after product updates. The vendor owns more of the integrated runtime, so your team has fewer provider combinations to support.

OpenHands often wins when provider or deployment choice has concrete business value, when the agent must live inside a larger application, or when CI needs custom event handling and sandbox control. Maintenance includes the runtime or cloud choice, model-provider compatibility, SDK or CLI changes, images, security policy, integrations, and the same evaluation discipline. The broader boundary is useful because you can replace parts. It also gives you more part combinations that can fail.

Set a maintenance budget before adoption. For a small production deployment, the number might be a fixed half-day per month plus a quarterly evaluation window; for an agent platform across many repositories, it will be larger. The exact allowance matters less than the response when you exceed it. Decide whether you will reduce the model matrix, retire an MCP server, pin a release, narrow CI scope, or assign a platform owner. "We will keep both current" is not an operating plan.

Dual-running deserves its own line. Keeping Claude Code for developers and OpenHands for automation can be sensible because the workflows differ. Keeping duplicate implementations of every interactive command, MCP server, CI job, and policy usually doubles verification work without doubling value. Share evaluation cases and agent-neutral policies, then choose one primary implementation per workflow.

A two-repository trial answers the hard questions

A credible trial uses one ordinary repository and one awkward repository. The ordinary one shows baseline setup. The awkward one contains the monorepo boundary, generated code, long test suite, private package source, unusual build image, or approval rule that has defeated past automation. Migrating only the clean repository measures documentation quality, not operational fit.

Start by freezing the current contract. Record the agent version, model, repository instructions, enabled tools, MCP schemas, CI event, permissions, secrets, output artifacts, and ten representative tasks. Run those tasks on the current setup and save results. Do not tune the candidate against memories of how the incumbent performed.

Next, implement only the minimum candidate path that preserves enforcement. Translate instructions, rebuild deterministic controls, connect one necessary MCP server, and wrap CI output. Leave optional commands and convenience integrations out. This prevents the trial from becoming a platform rewrite before you have evidence.

Run both agents in read-only shadow mode on the same commit and task input. Reviewers should score the results without knowing which agent produced them when practical. Track task completion, wrong-file edits, test evidence, reviewer minutes, retries, spend, and operator intervention. Add free-text notes for surprising behavior because a numeric score will not explain why a run was unsafe.

Then force three failures: remove an MCP credential, return an oversized tool result, and make a required test time out. Observe whether the job fails closed, reports a useful error, preserves artifacts, and can resume without corrupting the workspace. Happy-path demos rarely expose the migration cost; recovery behavior does.

Finish the trial with an operations review, not a feature vote. Ask who patches the integration, who approves model changes, how quickly the old path can return, which configuration is shared, and what monthly work disappears. If those answers depend on an enthusiastic engineer continuing unpaid custodial work, the candidate has no sustainable owner.

The output is a short decision record with four numbers: migration hours remaining, expected monthly net savings, adverse-case monthly maintenance, and break-even months. Attach the workflow inventory and failed-task evidence. A founder can make a decision from that packet without watching another agent demo.

Choose the constraint that will last two years

The right platform matches the constraint you expect to keep, not the capability that looks impressive this quarter. Choose Claude Code when the team wants a cohesive Claude-centered workflow, uses GitHub or straightforward headless automation, and benefits more from reducing platform surface than from changing providers. Choose OpenHands when model or runtime choice is a written requirement, the agent must be embedded through an SDK, or custom deployment and CI control justify owning the extra layers.

Keep Claude Code and add OpenHands selectively when one workflow has a different constraint. A regulated automation job may need a controlled runtime while interactive development stays on Claude Code. A model evaluation service may belong in OpenHands while a small product team keeps the simpler daily tool. Split by workflow, not by developer preference, or every repository accumulates two half-maintained paths.

Do not migrate for abstract fear of lock-in. Lock-in has a price only when it blocks a likely move, weakens purchasing power, violates a policy, or makes an outage intolerable. Calculate that exposure beside migration and maintenance hours. Staying put can be the disciplined decision when the escape event is remote and the current workflow works.

Do migrate when the present boundary already causes recurring work. If teams build unofficial proxies to reach other models, maintain brittle wrappers around CI, or cannot place the runtime where policy requires, they are paying migration cost in fragments without receiving a supported platform. Consolidating that work under OpenHands can reduce both risk and ownership ambiguity.

In a Team & AI Audit at oleg.is, I treat agent choice as an operating-model decision: the five-day, $5,000 review must identify at least $50,000 per year in savings or it is free. Whether you use an outside review or your own spreadsheet, demand the same discipline from the decision.

Put the break-even formula and maintenance ledger in the approval record. Set a date to compare forecast hours with actual hours. If portability does not remove a real constraint or lower recurring work, stop funding the duplicate path. If it does, protect the shared contracts and keep platform-specific adapters thin enough that the next migration is smaller than this one.