Metadata-Version: 2.4
Name: claude-handoff-manager
Version: 0.1.0
Summary: MCP server that automates Claude Code conversation handoffs — no more manual copy-paste when you hit the message cap.
Project-URL: Homepage, https://github.com/AashiDutt/claude-handoff-manager
Author: Country Delight Engineering
License-Expression: MIT
License-File: LICENSE
Keywords: claude,claude-code,handoff,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# claude-handoff-manager

MCP server that automates Claude Code conversation handoffs. No more manual copy-paste when you hit the message cap.

## The Problem

When a Claude Code conversation reaches the message limit, it produces a handoff summary. You then have to:
1. Copy the handoff text
2. Exit / clear the conversation
3. Start a new session
4. Paste the handoff as the first message

This is tedious and breaks your flow.

## The Solution

This MCP server automates the entire handoff cycle:

1. **End of conversation**: Claude calls `save_handoff` - the message is saved to disk and copied to your clipboard
2. **New conversation**: Say `"continue from last handoff"` - Claude calls `load_handoff` and picks up exactly where you left off

Zero manual copy-paste.

## Installation

### Option A: `uvx` from Git (recommended for teams)

Push this repo to your team's Git host, then each developer adds it to their `~/.mcp.json`:

```json
{
  "mcpServers": {
    "handoff-manager": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/YOUR_ORG/claude-handoff-manager", "claude-handoff-manager"],
      "type": "stdio"
    }
  }
}
```

### Option B: `uvx` from PyPI

```json
{
  "mcpServers": {
    "handoff-manager": {
      "command": "uvx",
      "args": ["claude-handoff-manager"],
      "type": "stdio"
    }
  }
}
```

### Option C: Run directly (local development)

```json
{
  "mcpServers": {
    "handoff-manager": {
      "command": "python3",
      "args": ["/path/to/handoff-manager/src/handoff_manager/server.py"],
      "type": "stdio"
    }
  }
}
```

After editing `~/.mcp.json`, **restart Claude Code** to pick up the new server.

## Tools

| Tool | What it does |
|------|-------------|
| `save_handoff` | Saves handoff message to `~/.claude/handoffs/` + copies to clipboard |
| `load_handoff` | Loads the latest (or a specific) handoff in a new conversation |
| `copy_handoff_to_clipboard` | Copies a saved handoff to the system clipboard |
| `list_handoffs` | Lists all saved handoffs with previews |
| `delete_handoff` | Deletes a specific or all handoffs |

## Usage

### Saving (end of a conversation)

Claude will automatically call `save_handoff` when it generates a handoff summary at the message cap. You can also manually trigger it:

> "Save a handoff with the current context"

### Loading (start of a new conversation)

> "Continue from last handoff"

or

> "Load handoff"

Claude calls `load_handoff` and gets the full context from your previous session.

### Listing saved handoffs

> "Show me my saved handoffs"

### Clipboard

> "Copy the last handoff to my clipboard"

## Storage

Handoffs are stored as JSON files in `~/.claude/handoffs/`:

```
~/.claude/handoffs/
  20260611_143022_home-user-myproject.json
  20260611_100515_home-user-otherproject.json
```

Each file contains:
- `id`: Unique identifier (timestamp + project slug)
- `created_at`: UTC timestamp
- `working_dir`: The project directory
- `project_name`: Human-friendly name
- `message`: The full handoff text

## Clipboard Support

Automatically copies to clipboard on save using:
- **macOS**: `pbcopy`
- **Linux X11**: `xclip` or `xsel`
- **Linux Wayland**: `wl-copy`
- **Windows**: `clip`

## Requirements

- Python >= 3.10
- `mcp` SDK >= 1.0.0
- Claude Code CLI

## License

MIT
