Switching models halfway through a project is not just a settings change. Your repository preserves the code, but it does not automatically preserve the reasoning behind unfinished work. A reliable switch gives the next model a clear starting point, a bounded task, and evidence that the project still works. Follow these steps whenever you change the model powering your coding agent.
1. Choose a Concrete Boundary for the Model Switch
Switch after a recognizable milestone: a failing test has been reproduced, an interface has been defined, or an implementation is ready for review. Avoid switching while the agent is editing files or while a tool command still needs approval.
Write down why you are switching. For example, you might move from Claude Sonnet 5.5 to DeepSeek V4 Pro to evaluate another model on a clearly scoped implementation task. Treat that as an experiment, not proof that either model is universally better.
2. Preserve the Working Tree Before Changing Models
Ask the current agent to stop making changes and report its status. Inspect the working tree with git status and review tracked changes with git diff. Check untracked files separately; they may contain essential tests or configuration.
If the changes form a coherent checkpoint, commit only the intended files. Otherwise, preserve them using your normal local workflow. Do not discard unfinished edits merely to create a clean handoff. Record which changes belong to you so the next agent does not overwrite them.
3. Write a Handoff Note That Survives the Session
Create a short repository note, such as AGENT_HANDOFF.txt, or use your team's existing handoff location. Keep secrets and customer data out of it. Include enough information to resume the task without copying the entire conversation:
- Goal: the requested behavior and acceptance criteria.
- Current state: completed work, modified files, and unfinished changes.
- Decisions: constraints, rejected approaches, and compatibility requirements.
- Evidence: commands run, observed results, and known failures.
- Next action: one specific task the incoming model should attempt.
Distinguish verified facts from assumptions. “The parser test passed” is useful only if the note identifies the command and makes clear whether it ran before or after the latest edits.
4. Configure the Replacement Model Through a Compatible Client
Check whether your coding client supports the destination model and API format. An in-session model selector may preserve visible conversation history, but changing providers or clients may require a new session. Do not assume that a selectable model inherits every previous tool result or permission.
SwiftRelay is a practical option when you want pay-as-you-go access to multiple model families through one relay. It works with Claude Code, Codex, Gemini CLI, and OpenAI-compatible SDKs, though each client's supported model and protocol combinations still matter.
For SwiftRelay configuration, Claude Code and Gemini CLI take the bare host, https://api.fastapirelay.com; OpenAI-compatible SDKs use https://api.fastapirelay.com/v1. Use the exact model identifier supplied by the service rather than guessing from a display name. Sign up for SwiftRelay if you want to try this workflow with its small new-account gift credit.
5. Ask the Incoming Model to Reconstruct the Task
Start with a read-only instruction: “Read the handoff note, inspect the current diff, and summarize the goal, constraints, and next action. Do not edit files yet.”
Compare that summary with your intent. Correct misunderstandings before authorizing changes, especially around public interfaces, dependency additions, and files outside the task. Recheck tool permissions rather than assuming the previous session's approvals carry over.
6. Run One Bounded Task and Compare the Evidence
Give the replacement model a narrow assignment, such as fixing one failing test without changing the public API. Run the relevant checks before and after its edits when practical. This separates existing failures from regressions introduced during the handoff.
Review the resulting diff yourself. Look for unrelated refactors, weakened assertions, deleted coverage, and accidental configuration changes. Passing tests are evidence, not a substitute for checking whether the implementation satisfies the original request.
7. Update the Handoff Before Continuing Development
Once the bounded task is accepted, update the handoff note with the new state and test results. Commit the intended changes when appropriate, then continue with the replacement model. If the experiment fails, return to your checkpoint deliberately without erasing unrelated work. The goal is continuity: changing models should not mean restarting the project.