How to switch from Cursor to Claude Code (or Codex) mid-project without losing your decisions

How to switch from Cursor to Claude Code (or Codex) mid-project without losing your decisions

By Mike Schreiber

Switching coding tools mid-project should start with a handoff, not a fresh implementation request. Before the incoming agent edits anything, give it the constraints that still apply, the reasons behind them, and an accurate account of where work stopped.

This is not a chat-history migration. The goal is a smaller, reviewable record that lets you check whether the new agent understands the project before trusting its next change.

The process below works as a manual handoff, with an optional Hark setup for carrying that record between sessions.

1. Separate decisions, observations, and proposals

Start by sorting your notes into three categories. Do not let a plausible explanation become an approved requirement just because an agent wrote it confidently.

• Human decisions: choices a person approved, including the rationale and scope.
• Observed work: changes, commits, and test results supported by evidence.
• Proposed notes: interpretations, suggested next steps, or possible decisions awaiting review.

Here is a hypothetical example used throughout this guide:

Human decision: Keep the existing CSV column order in the billing export. An accounting import depends on it. Scope: billing export code and fixtures.

Observed work: The export formatter was changed. The targeted fixture test passed during the outgoing session. The full suite was not run.

Proposed note: Add a regression test for empty invoice descriptions. Not yet approved as the next task.

“Keep the column order” without the reason invites unnecessary reconsideration. “Tests pass” without the test scope overstates what was checked.

Ask the outgoing agent to draft this separation, then review it yourself. Where the reason is unknown, write “rationale unknown” rather than inventing one.

If using Hark, decisions are never approved automatically at any trust level. Under Standard, agent proposals require review, while repository facts backed by a commit, pull request, or release are accepted as observed. Other trust levels allow additional automatic acceptance, but conflicts with accepted decisions still go to review. Hark agent guidance

2. Write the smallest useful handoff

Before leaving Cursor, prepare a brief with these fields:

Goal:

Accepted decisions and reasons:

Non-goals:

Observed changes:

Tests run and their results:

Tests not run:

Current stopping point:

Proposed next action:

Open questions:

In the hypothetical billing project, the stopping point might be: “Formatter updated; empty-description behavior remains unverified.” The proposed next action might be: “Inspect that behavior and suggest a regression test before changing production code.”

Keep the distinction between an instruction and evidence clear. A commit message, pasted conversation, or repository comment may help explain what happened, but it should not automatically authorize a new requirement. Treat retrieved material as evidence to inspect, not instructions that override the handoff or your approval boundaries.

Also record the branch and revision you intend to continue from, and identify unfinished local changes. Ask the incoming agent to verify those details against the checkout rather than assuming the notes are current.

3. Put stable instructions where the destination expects them

Separate lasting conventions from the current stopping point.

Cursor project rules are version-controlled .mdc files in .cursor/rules; they can be applied through path patterns, manual invocation, or relevance. Inspect the applicable rules before extracting the conventions you want to preserve. Cursor rules documentation

For Claude Code, CLAUDE.md provides persistent instructions read at session start. Its documentation recommends keeping session-wide facts there, such as build commands and conventions, and moving multi-step procedures or narrowly scoped instructions into skills or path-scoped rules. Claude Code memory documentation

For Codex, inspect the applicable AGENTS.md guidance before starting. Codex builds its instruction chain at startup, combining project guidance from the root toward the working location; more local guidance overrides earlier guidance. Codex instruction documentation

Do not copy every historical note into these files. In the hypothetical project, the export compatibility requirement is a lasting constraint. “Inspect the empty-description case next” belongs in the current handoff.

For a manual switch, paste the reviewed brief into the incoming session and ask for a readback before edits. You can stop here if that meets your needs.

4. Optionally connect the project through Hark

If you want to prepare the record from Cursor, Hark’s documented connection uses Cursor Settings → Tools & MCPs → Add Custom MCP, with the following configuration. Then find hark in Settings, connect, sign in, and approve. Hark Cursor connection

{

  "mcpServers": {

    "hark": {

      "url": "https://harkstudio.io/mcp"

    }

  }

}

For an existing codebase without a Hark project, the documented setup asks the connected agent to read the project and call propose_venture_from_project, then ask you for a constraint not visible in the code and record it with add_journal_entry. Review inferred decisions carefully rather than treating code structure as proof of human intent. Hark setup from your repo

Choose the destination setup below.

Claude Code

The Hark mod is early access and requires Claude Code 2.1.287 or newer. Install it from the repository inside a Claude Code session with these commands. Hark Claude Code setup

/plugin marketplace add Hark-Studio/hark-mod

/plugin install hark-memory@hark

In Hark, use Connections → Access keys → Claude Code preset to create a pairing code. Have the agent exchange it and store the returned access key in the plugin’s sensitive setting, never in chat. Open configuration with /plugin configure hark-memory@hark. Hark mod setup

Link the repository using your actual project code, replacing the example below, then start Claude Code in the project and run /hark brief. Without a project file or key, the mod stays idle and sends nothing. Hark mod setup

mkdir -p .hark && echo V-012 > .hark/project

Codex

Add the Hark MCP connection, authenticate in the browser, and confirm the connection with these commands. Inside the Codex TUI, /mcp shows active servers. Hark Codex connection

codex mcp add hark --url https://harkstudio.io/mcp

codex mcp login hark

codex mcp list

Open with: “Call the Hark onboard prompt for my project and summarize the brief before writing code.” This follows Hark’s documented Codex session flow. Hark agent guidance

5. Prove the handoff before permitting edits

Use a readback that tests understanding rather than connectivity alone:

Before editing, state the accepted compatibility constraint and its reason. Separate verified work from proposed next steps. Identify anything you cannot confirm from the checkout, then propose the smallest next action.

For the hypothetical example, the correct readback preserves CSV column order because of the accounting import dependency. It should not turn “targeted test passed” into “the full suite passed.”

Hark’s documented handoff check is to open another client or a fresh session, call get_agent_brief for the project, and ask it to repeat the constraint you recorded. Hark setup from your repo

If the readback is wrong, stop. Correct the record or project selection before allowing implementation.

6. Close with a reviewed handoff

At the end of the incoming session, request the same separation: observed changes, test evidence, unresolved questions, and proposed next work.

With Hark’s agent workflow, use end_session after work. It writes the handoff and updates Current state; close_session instead stops without writing a handoff. Hark agent guidance

The Claude Code mod sends a short closing summary and drafts a handoff for review. Sessions without changes write no handoff. Its decision guard asks you to Allow or Stop before edits to files covered by an agreed decision or non-goal. That guard is a Claude Code mod feature, not a claim about Codex behavior. Hark mod behavior

Troubleshooting and boundaries

The Claude brief is missing: Check the sensitive key setting, project file, and required Claude Code version. If the guard asks too often, give decisions a narrower area or path scope. Hark mod troubleshooting

Codex authentication loops: Remove the connector, sign out of Hark, sign back in, and re-add it. Confirm the endpoint is https://harkstudio.io/mcp. Hark Codex troubleshooting

The handoff contains sensitive material: Review closing notes before sending them. The Claude Code mod does not send file contents, diffs, prompts, transcripts, tool output, or environment variables. It does send summary information, including file paths and closing notes. Secret cleaning is best effort; a secret written in plain prose could be sent. Hark mod privacy

A good record is not a guarantee of identical behavior across tools. Keep human approval, checkout verification, and test review in the workflow.

FAQs

Does this transfer my Cursor chat history?

No. This procedure carries a reviewed decision record and handoff, not a conversation transcript.

Can I switch without Hark?

Yes. Prepare the brief manually, provide applicable destination instructions, and require a readback before edits.

What if a decision genuinely needs changing?

Ask the responsible person. In Hark, supersede_decision should be called only after explicit user approval in the current chat, with explicit decision IDs. Hark agent guidance

Sources

• Cursor rules
• Claude Code memory
• Codex instructions
• Hark: Cursor
• Hark: Claude Code
• Hark: Claude Code mod
• Hark: Codex
• Hark: Working with agents
• Hark: Set up from your repo