Claude Code Handoff System

A bidirectional workflow system that enables seamless orchestration between Claude chat (strategist) and Claude Code (executor) via Google Drive as a shared context layer.

Overview

This system solves the "context switching" problem when working between Claude's different interfaces:

• Strategist mode (Claude.ai chat): High-level planning, architecture decisions, and project direction
• Executor mode (Claude Code): Hands-on coding, debugging, and file manipulation

Claude Chat (🧠) ↔ Google Drive (📏) ↔ Claude Code (👨‍💻)
Strategist         Shared Context         Executor

Core Features

• /handoff: Capture Claude Code session state and send it to the strategist
• /pickup: Download and execute strategist prompts in Claude Code
• Automatic git management: Commits and pushes changes automatically
• Organized Drive storage: Separates prompts and digests by project
• Agentic execution: Automatic error handling and halting on wrong premises

Prerequisites

• Active Claude Pro/Team subscription
• Claude Code installed
• Google Drive account
• Git and Dotfiles repo setup
• macOS or Linux (Windows untested)
• Node.js 16+ and pnpm
• rclone for Drive sync

Setup

Step 1: Claude.ai Configuration

1. Enable Google Drive Connector:

   • Go to Claude.ai settings > Integrations
   • Connect Google Drive with full permissions
   • Test with: "List my recent Drive files"

2. Create base Drive folder:

   Create gdrive:claude-handoff in your Drive for context files
   

Step 2: Claude Code Installation

1. Download Claude Code:

   • Visit claude.ai/download
   • Install for your platform

2. Basic Setup:

   # Verify installation
   claude-code --version
   
   # Initialize Claude Code in project
   cd ~/projects/your-project
   claude-code --init

3. (Dangerous Zone) -- Faster & Smooth:🚨 For experienced users who want a frictionless experience:

   claude-code --dangerously-skip-permissions

   Warning: This disables safety checks and allows Claude Code to run without manual approval for most operations. Only use if you trust your Claude Code sessions and are comfortable with autonomous file operations.

Step 3: Rclone Setup for Drive Sync

1. Install rclone:

   # macOS
   brew install rclone
   
   # Linux
   curl https://rclone.org/install.sh | sudo bash

2. Configure Google Drive:

   # Authenticate with Google Drive
   rclone config
   
   # Follow prompts to create "gdrive" remote
   # Select: Google Drive authentication

3. Test configuration:

   # Verify Drive access
   rclone lsd gdrive: | head -10

Step 4: Main Codebase Clone & Install

1. Clone the repository:

   cd ~/projects
   git clone https://github.com/<your-username>/claude-code-handoff.git
   cd claude-code-handoff

2. Install dependencies:

   pnpm install
   pnpm run test
   pnpm run build

3. Link CLI tools globally:

   # Link the CLIs for global access
   sudo ln -sf "$(pwd)/dist/cch-digest.js" /usr/local/bin/cch-digest
   sudo ln -sf "$(pwd)/dist/cch-pickup.js" /usr/local/bin/cch-pickup
   
   # Verify
   which cch-digest
   which cch-pickup

Step 5: Global Skills Deployment

1. Create Claude Code skills directory:

   mkdir -p ~/.claude/skills

2. Sync skills from dotfiles repo:

   git clone https://github.com/<your-username>/claude-dotfiles.git
   cp -r claude-dotfiles/.claude/skills/* ~/.claude/skills/

   Alternatively, copy skill files manually from this repo's .claude/skills/ directory.

Step 6: Initialize Project Directories

In your project repos:

cd your-project

# Create sessions directory
mkdir -p sessions

# Initialize Claude Code in it
claude-code --init

Step 7: Claude.ai Usage Setup

1. Introduce the workflow in a new conversation:

   Hi Claude, I'm using a pickup/handoff workflow system between you (strategist) and Claude Code (executor).
   
   When I ask you to create prompts for development tasks:
   - Structure them with frontmatter (project, created_at, environment)
   - Include specific halting conditions
   - Add clear "report back" requirements
   - Write in markdown code blocks for copy-paste
   
   You can read my latest work via Google Drive at gdrive:claude-handoff/digests/<project>/
   

2. (Optional) Add to your Claude.ai custom instructions:

   I use a Claude Code handoff system. When creating development prompts, format them with:
   - Frontmatter with project/timestamp
   - Specific halting conditions
   - Clear deliverables and "report back" sections
   

Usage

Basic Workflow

1. Start in Claude Chat:

   • Discuss project direction and planning
   • Create a prompt for Claude Code with specific halting conditions

2. Switch to Claude Code:

   cd ~/projects/your-project
   claude-code # or --dangerously-skip-permissions

3. Execute strategist prompts:

   /pickup
   

4. Hand off results:

   /handoff
   

5. Repeat cycle: Back to Claude Chat for further analysis

Example Conversation Flow

Strategist phase (Claude.ai chat):

You: "I need to add error handling to our API endpoints. Check the latest digest and create a prompt for Claude Code."

Claude: [Reads latest digest from Drive] "Based on your latest work in src/api.ts, here's the prompt:

```markdown
---
project: my-api
created_at: 2026-04-20T10:00:00
environment: error-handling-improvement
---

# Task: Add comprehensive error handling to API endpoints
[rest of structured prompt]
```
"

Executor phase (Claude Code):

You: [Copies prompt, switches to Claude Code, runs /pickup]
Claude Code: [Executes task, adds error handling, runs tests]
You: /handoff

Back to strategist:

Claude: [Reads new digest] "Great! I see you've added robust error handling. Next step: let's add logging..."

Key Skills

• /handoff: Generates a formatted session digest, commits to git, and uploads to Drive
• /pickup: Fetches and executes strategist prompts from Drive
• /add-dir: Creates new working directories
• /advisor: Queries a stronger model for complex decisions
• /init: Sets up Claude Code in a new project

Prompt Structure (Strategist → Code)

For effective pickup, structure your Claude Chat prompts with:

---
project: project-name
created_at: 2026-04-20T05:00:00
environment: description
---

# Task: Clear objective

## Halting conditions
1. List specific pre-conditions
2. Security/integrity checks

## Guidelines
- Specific actions to take
- File modification instructions

## Report back
- What to verify after execution
- Specific output formats desired

Open Source Considerations

Current Status

• Repository: https://github.com/<your-username>/claude-code-handoff
• License: Not yet determined
• Dependencies: All NPM, no proprietary code

Open Source Readiness Checklist

• Remove personal configuration
• Depersonalize git commits
• Clean up API keys or credentials
• Add contribution guidelines
• Choose license: MIT / Apache 2.0 / GPL
• Write installation automation scripts
• Create a changelog

Recommended Path

1. First release: Beta tag for friends & colleagues
2. Gather feedback: Bugs, feature requests, ease of setup
3. Public release: v1.0 with mature organization

Recommended license: MIT (simple permissive, standard for tools)

Troubleshooting

Common Issues

• Claude Code not finding skills: Verify files in ~/.claude/skills/
• cch-digest not found: Re-run pnpm run build and check global links
• Drive access error: Re-run rclone config
• Claude Code permissions issues: Consider --dangerously-skip-permissions flag

Debugging

Examine Claude Code logs:

# Check last session logs
ls -lat ~/projects/your-project/sessions/

# Verify Drive connection
rclone ls gdrive:claude-handoff/ | head -5

Contributing

This is a personal tool made public for others to adapt. Feel free to copy and modify for your own workflows.

For bug reports and feature requests, open an issue describing:

• Your setup (OS, Claude Code version)
• Steps to reproduce
• Expected vs actual behavior

---

Built in sync between Claude chat ⇄ Claude Code for efficient AI-assisted development workflows.