RCP-CWK-002a Cowork Device-Switch Handoff

Creates a handoff designed for switching between Mac devices running Cowork

The recipe first runs pre-flight checks (git status, remote configuration, uncommitted changes). Then it executes a standard direct handoff via CWK-002, including Lessons Learned capture and validation. After the handoff is committed locally, it pushes to GitHub using a one-time PAT that is immediately scrubbed from the remote URL. Finally, it generates a prompt file containing everything the new device’s AI needs: a file manifest, expected commit hash, branch name, and step-by-step instructions for verification, pull, and initialization.

Cowork Device-Switch Handoff

Cowork | Session Lifecycle | Difficulty: Intermediate | Time: 3–8 min
Tags: Session, Handoff, Git, Cowork, Device Switch, GitHub, Transfer, Multi-Device

TL;DR

What It Does
Creates a handoff designed for switching between Mac devices running Cowork. It runs a full standard handoff (CWK-002), pushes to GitHub, and generates a device-switch prompt file that the new device’s AI uses to pull, verify file sync, and auto-run session initialization.
How It Works
The recipe first runs pre-flight checks (git status, remote configuration, uncommitted changes). Then it executes a standard direct handoff via CWK-002, including Lessons Learned capture and validation. After the handoff is committed locally, it pushes to GitHub using a one-time PAT that is immediately scrubbed from the remote URL. Finally, it generates a prompt file containing everything the new device’s AI needs: a file manifest, expected commit hash, branch name, and step-by-step instructions for verification, pull, and initialization.
What To Expect
The full CWK-002 handoff process (session data compilation, LL capture, validation gate), followed by a GitHub push and a device-switch prompt file. The prompt file is saved to your project folder. On the new device, you provide this file as your first instruction and the AI handles everything automatically — verifying files, pulling from GitHub, and initializing the session.
Best Results When You
Have a clean git working tree and a configured GitHub remote before starting. The recipe checks for both and will warn you if either is missing. Complete any in-progress file edits before running the device switch.
Time
3–8 minutes (includes standard handoff, GitHub push, and prompt file generation).
Difficulty
Intermediate — requires a GitHub remote and PAT. The mechanics are automated, but troubleshooting a failed push or sandbox pull fallback requires some git familiarity.

How To Start

Use this recipe when ending a session on one device and planning to continue on another. The recipe handles the full handoff, GitHub sync, and generates instructions for the new device.

STEP 1Tell the AI to Create a Device-Switch Handoff

Specify the handoff mode. The mode is passed through to CWK-002 for the standard handoff portion. Quick mode auto-generates; detailed mode lets you review each section.
Available parameters
  • mode · string · optional · default: quick
    Handoff mode passed through to CWK-002. Options: quick (auto-generate from session context), detailed (step-by-step with human review of each section).
Example invocations
Quick device switch
#H->AI::Directive: (Create device-switch handoff)
Detailed device switch
#H->AI::Directive: (Create device-switch handoff, mode detailed)

STEP 2Provide Your GitHub PAT

The recipe needs to push to GitHub so the new device can pull. It will prompt you for a Personal Access Token. The token is used only for this push and immediately scrubbed from the remote URL afterward.

STEP 3Carry the Prompt File to the New Device

The recipe generates a device-switch prompt file in your project folder. Transfer this file to the new device — email it, AirDrop it, or access it from a shared location. The file contains everything the new device’s AI needs.

STEP 4On the New Device, Provide the Prompt File

Open Cowork on the new device with your project folder selected. Provide the device-switch prompt file as your first instruction. The AI will automatically verify files, pull from GitHub (with sandbox fallback if needed), and run session initialization.

Usage Examples

Two scenarios showing device switches — a clean switch and one where the push encounters an issue.
Example 1 · Clean device switch
User:#H->AI::Directive: (Create device-switch handoff)
AI:Running pre-flight checks. Git status: clean. Remote: github.com/CRAFTFramework/CFT-PROJ-CP-067. Branch: main. Pre-flight passed. Executing standard handoff via CWK-002. Handoff H050 written. Fernand validation: 5/5 passed. Please provide your GitHub PAT for the push.
User:ghp_abc123…
AI:Push successful: a7d3f21 on origin/main. PAT scrubbed. Device-switch prompt file generated: DEVICE-SWITCH-PROMPT-H050.txt. Safe to close this session. On the new device, open Cowork with the project folder and provide the prompt file.
[User transfers prompt file and continues on new device]
Example 2 · Device switch with push retry
User:#H->AI::Directive: (Create device-switch handoff, mode detailed)
AI:Pre-flight: uncommitted changes detected in 2 files. Should I stage and commit these before proceeding?
User:Yes
AI:Changes committed. Running detailed handoff — reviewing session summary with you. After confirmation, handoff H051 written. Validation passed. Please provide your PAT.
User:ghp_xyz789…
AI:Push failed — authentication error. The handoff is saved locally. You can retry manually with git push, copy the folder directly, or use the prompt file anyway (it will detect the discrepancy). Prompt file generated: DEVICE-SWITCH-PROMPT-H051.txt.
[User fixes PAT and retries push manually]

How AI Reads This Recipe

When this recipe is triggered, the AI acts as a device-transfer coordinator that wraps the standard handoff with GitHub sync and prompt file generation. The AI should:
  1. RUN pre-flight checks: verify git working tree is clean (or handle uncommitted changes), confirm remote origin is configured, identify current branch and last commit.
  2. EXECUTE RCP-CWK-002 (Cowork Direct Handoff) for the standard handoff, passing through the mode parameter. CWK-002 handles session data compilation, LL capture, validation, and git commit. Do not push yet.
  3. REQUEST the user’s GitHub PAT for the push. Set the remote URL with the PAT, push, then immediately scrub the PAT from the remote URL. Verify push success by checking the remote log.
  4. HANDLE push failure gracefully: save the push status, still generate the prompt file, and inform the user of fallback options (manual push, direct folder copy, or prompt file with discrepancy detection).
  5. GENERATE the device-switch prompt file containing: handoff ID, push commit hash, branch name, file manifest, and step-by-step instructions for the new device (file verification, GitHub pull with sandbox fallback, post-pull verification, session initialization via CWK-001).
  6. WRITE the prompt file to the sessions folder (or project root for flat structures).
  7. PRESENT the final summary with handoff ID, commit hash, push status, prompt file location, and step-by-step instructions for the user to follow on the new device.
The prompt file must be self-contained — the new device’s AI has no context from this session. Include everything needed for verification and initialization. The sandbox fallback procedure in the prompt file is critical for Cowork environments where standard git pull may fail due to file permission restrictions.

When to Use This Recipe

Use this recipe when you:
  • Are ending a session on one Mac and want to continue on another Mac running Cowork.
  • Need to transfer full project context including git history between devices.
  • Want an automated verification and initialization process on the receiving device.
  • Are switching between a desktop and laptop mid-project.
Do not use this recipe when:
You are staying on the same device and just ending your session. Use CWK-002 (Cowork Direct Handoff) instead — it handles everything without the GitHub push and prompt file overhead. Also do not use this recipe if your project does not have a GitHub remote configured; run CWK-004 (Git Initialization) first.

Recipe FAQ

Q.Do I need a GitHub remote set up before using this recipe?

Yes. The recipe checks for a configured remote in pre-flight. If none exists, it stops and recommends running CWK-004 (Git Initialization) first. The remote is required because device switching relies on GitHub as the sync mechanism.

Q.Is my PAT stored anywhere after the push?

No. The PAT is set on the remote URL for the push only and immediately scrubbed afterward. This follows the project’s token-per-session security practice. The next session on either device will need a fresh PAT for any push operations.

Q.What if the pull fails on the new device due to sandbox permissions?

The prompt file includes a sandbox fallback procedure. If standard git pull fails with an “unable to unlink” error, the AI falls back to fetching and extracting individual changed files from the remote. This workaround syncs file contents even when the sandbox restricts git write operations.

Q.Can I use this for switching to a non-Mac device?

The recipe is designed for Mac-to-Mac Cowork transfers. The generated prompt file could work on any device running Cowork, but the sandbox fallback procedures are specific to the Mac Cowork environment. For other platforms, the standard pull path should work without fallbacks.

Q.What happens if I lose the prompt file?

The handoff data is in your chat history file and your git commits are on GitHub. You can manually run CWK-001 on the new device with your project folder, pull from GitHub, and specify the handoff ID to load. The prompt file just automates these steps.

Version History

Changes to this recipe over time. Most recent first.
v1.02a 2026-03-01
Inherits Fernand Pre-Handoff Validation Gate from CWK-002 v1.02a. Validation runs as part of the delegated CWK-002 execution in Step 1.
v1.01a 2026-02-28
Added sandbox fallback procedure for git pull in prompt file (Phase 2). Handles Cowork sandbox file permission restrictions via fetch-and-extract workaround. References LL-026 and LL-031 for degraded git state handling.
v1.00a 2026-02-28
Initial release. Pre-flight checks, delegated CWK-002 handoff, interactive PAT GitHub push with scrub, device-switch prompt file generation with 4-phase verification and initialization.

Get this recipe with CRAFT for Claude Cowork

Cowork recipes ship bundled with CRAFT for Claude Cowork — there’s no separate download. Clone the framework once, and your AI runs every recipe automatically when invoked.

Pull anytime to stay on the latest version — free to clone, no login or email required.

Then start your session

Once CRAFT is in your project folder, open a new Cowork session and ask Claude to initialize. For example:

You

Please initialize my CRAFT session.

Claude

CRAFT session ready. Your project is loaded, your persona is active, and your recipes are available. What would you like to work on?

What is CRAFT for Claude Cowork?

Not familiar with Git? Download as a ZIP

No command line needed. Just download, move, and unzip:

  1. Open the CRAFT framework repo on GitHub.
  2. Click the green Code button, then choose Download ZIP.
  3. Move the downloaded ZIP into your Claude Cowork project folder.
  4. Unzip it: double-click on Mac, or right-click → Extract All on Windows.

Similar Posts