claude-handoff-manager 0.1.0__tar.gz

claude_handoff_manager-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/

claude_handoff_manager-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Country Delight Engineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

claude_handoff_manager-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+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

claude_handoff_manager-0.1.0/README.md

@@ -0,0 +1,141 @@
+# 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

claude_handoff_manager-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "claude-handoff-manager"
+version = "0.1.0"
+description = "MCP server that automates Claude Code conversation handoffs — no more manual copy-paste when you hit the message cap."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Country Delight Engineering" },
+]
+keywords = ["claude", "mcp", "handoff", "claude-code", "model-context-protocol"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "mcp>=1.0.0",
+]
+
+[project.scripts]
+claude-handoff-manager = "handoff_manager.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/handoff_manager"]
+
+[project.urls]
+Homepage = "https://github.com/AashiDutt/claude-handoff-manager"

claude_handoff_manager-0.1.0/src/handoff_manager/__init__.py

@@ -0,0 +1,3 @@
+"""Handoff Manager - MCP server for Claude Code conversation handoffs."""
+
+__version__ = "0.1.0"

claude_handoff_manager-0.1.0/src/handoff_manager/server.py

@@ -0,0 +1,310 @@
+"""
+Handoff Manager MCP Server
+===========================
+Automates the conversation handoff workflow in Claude Code.
+
+When a conversation hits the message cap:
+  1. Claude calls save_handoff() with the handoff summary
+  2. User starts a new session
+  3. User says "continue from last handoff" -> load_handoff() returns the context
+  4. No more manual copy-paste
+
+Storage: ~/.claude/handoffs/<timestamp>_<project_slug>.json
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+HANDOFFS_DIR = Path.home() / ".claude" / "handoffs"
+HANDOFFS_DIR.mkdir(parents=True, exist_ok=True)
+
+# ---------------------------------------------------------------------------
+# MCP Server
+# ---------------------------------------------------------------------------
+mcp = FastMCP(
+    "handoff-manager",
+    instructions=(
+        "This server manages conversation handoffs for Claude Code. "
+        "Use save_handoff at the end of a conversation to persist the handoff "
+        "summary. Use load_handoff at the start of a new conversation to "
+        "retrieve the context. Use copy_handoff_to_clipboard to copy to the "
+        "system clipboard."
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def _project_slug(working_dir: str) -> str:
+    """Create a filesystem-safe slug from a working directory path."""
+    return working_dir.strip("/").replace("/", "-").replace(" ", "_") or "default"
+
+
+def _handoff_path(handoff_id: str) -> Path:
+    return HANDOFFS_DIR / f"{handoff_id}.json"
+
+
+def _list_handoff_files() -> list[Path]:
+    """Return handoff files sorted newest-first."""
+    files = sorted(
+        HANDOFFS_DIR.glob("*.json"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    return files
+
+
+def _copy_to_clipboard(text: str) -> str:
+    """Copy text to system clipboard. Returns status message."""
+    system = platform.system()
+    try:
+        if system == "Darwin":
+            proc = subprocess.Popen(["pbcopy"], stdin=subprocess.PIPE)
+            proc.communicate(text.encode("utf-8"))
+            return "Copied to clipboard (pbcopy)."
+        elif system == "Linux":
+            for cmd in [
+                ["xclip", "-selection", "clipboard"],
+                ["xsel", "--clipboard", "--input"],
+            ]:
+                if shutil.which(cmd[0]):
+                    proc = subprocess.Popen(cmd, stdin=subprocess.PIPE)
+                    proc.communicate(text.encode("utf-8"))
+                    return f"Copied to clipboard ({cmd[0]})."
+            if shutil.which("wl-copy"):
+                proc = subprocess.Popen(["wl-copy"], stdin=subprocess.PIPE)
+                proc.communicate(text.encode("utf-8"))
+                return "Copied to clipboard (wl-copy)."
+            return "No clipboard tool found. Install xclip, xsel, or wl-copy."
+        elif system == "Windows":
+            proc = subprocess.Popen(["clip"], stdin=subprocess.PIPE)
+            proc.communicate(text.encode("utf-16le"))
+            return "Copied to clipboard (clip)."
+        else:
+            return f"Unsupported platform for clipboard: {system}"
+    except Exception as e:
+        return f"Clipboard copy failed: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+@mcp.tool()
+def save_handoff(
+    message: str,
+    working_dir: str = "",
+    project_name: str = "",
+) -> str:
+    """Save a conversation handoff message for later retrieval.
+
+    Call this at the end of a conversation when the message cap is reached.
+    The handoff message is persisted to disk so the next conversation can
+    pick up where this one left off.
+
+    Args:
+        message: The full handoff summary text (the fenced code block content).
+        working_dir: The working directory of the current project (auto-detected if empty).
+        project_name: Optional human-friendly project name for easier identification.
+    """
+    if not message.strip():
+        return "Error: handoff message cannot be empty."
+
+    now = datetime.now(timezone.utc)
+    ts = now.strftime("%Y%m%d_%H%M%S")
+    wd = working_dir or os.getcwd()
+    slug = _project_slug(wd)
+    handoff_id = f"{ts}_{slug}"
+
+    payload = {
+        "id": handoff_id,
+        "created_at": now.isoformat(),
+        "working_dir": wd,
+        "project_name": project_name or slug,
+        "message": message,
+    }
+
+    path = _handoff_path(handoff_id)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    clip_status = _copy_to_clipboard(message)
+
+    return (
+        f"Handoff saved successfully.\n"
+        f"  ID: {handoff_id}\n"
+        f"  Path: {path}\n"
+        f"  Project: {payload['project_name']}\n"
+        f"  Clipboard: {clip_status}\n\n"
+        f"To resume in a new conversation, the user can say:\n"
+        f'  "continue from last handoff" or "load handoff"'
+    )
+
+
+@mcp.tool()
+def load_handoff(
+    handoff_id: str = "",
+    working_dir: str = "",
+) -> str:
+    """Load the most recent handoff message to continue a previous conversation.
+
+    Call this at the start of a new conversation to restore context from a
+    previous session that hit the message cap.
+
+    Args:
+        handoff_id: Specific handoff ID to load. If empty, loads the most recent one.
+        working_dir: Filter handoffs by working directory. If empty, returns the most recent regardless of project.
+    """
+    if handoff_id:
+        path = _handoff_path(handoff_id)
+        if not path.exists():
+            return f"Error: No handoff found with ID '{handoff_id}'."
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        return (
+            f"Handoff loaded (ID: {payload['id']}).\n"
+            f"Project: {payload['project_name']}\n"
+            f"Saved at: {payload['created_at']}\n"
+            f"Working dir: {payload['working_dir']}\n\n"
+            f"--- HANDOFF MESSAGE ---\n\n"
+            f"{payload['message']}"
+        )
+
+    files = _list_handoff_files()
+    if not files:
+        return "No handoffs found. Nothing to resume."
+
+    if working_dir:
+        slug = _project_slug(working_dir)
+        files = [f for f in files if slug in f.stem]
+
+    if not files:
+        return f"No handoffs found for working directory: {working_dir}"
+
+    path = files[0]
+    payload = json.loads(path.read_text(encoding="utf-8"))
+
+    return (
+        f"Handoff loaded (ID: {payload['id']}).\n"
+        f"Project: {payload['project_name']}\n"
+        f"Saved at: {payload['created_at']}\n"
+        f"Working dir: {payload['working_dir']}\n\n"
+        f"--- HANDOFF MESSAGE ---\n\n"
+        f"{payload['message']}"
+    )
+
+
+@mcp.tool()
+def copy_handoff_to_clipboard(
+    handoff_id: str = "",
+) -> str:
+    """Copy a handoff message to the system clipboard.
+
+    Useful when you want to manually paste the handoff into another tool
+    or conversation.
+
+    Args:
+        handoff_id: Specific handoff ID. If empty, copies the most recent one.
+    """
+    if handoff_id:
+        path = _handoff_path(handoff_id)
+        if not path.exists():
+            return f"Error: No handoff found with ID '{handoff_id}'."
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    else:
+        files = _list_handoff_files()
+        if not files:
+            return "No handoffs found."
+        payload = json.loads(files[0].read_text(encoding="utf-8"))
+
+    status = _copy_to_clipboard(payload["message"])
+    return f"Handoff '{payload['id']}': {status}"
+
+
+@mcp.tool()
+def list_handoffs(
+    working_dir: str = "",
+    limit: int = 10,
+) -> str:
+    """List saved handoff messages.
+
+    Args:
+        working_dir: Filter by working directory. If empty, lists all.
+        limit: Max number of handoffs to return (default 10).
+    """
+    files = _list_handoff_files()
+    if not files:
+        return "No handoffs saved yet."
+
+    if working_dir:
+        slug = _project_slug(working_dir)
+        files = [f for f in files if slug in f.stem]
+
+    if not files:
+        return f"No handoffs found for: {working_dir}"
+
+    files = files[:limit]
+    lines = []
+    for f in files:
+        payload = json.loads(f.read_text(encoding="utf-8"))
+        preview = payload["message"][:80].replace("\n", " ")
+        lines.append(
+            f"  [{payload['id']}]\n"
+            f"    Project: {payload['project_name']}\n"
+            f"    Saved: {payload['created_at']}\n"
+            f"    Dir: {payload['working_dir']}\n"
+            f"    Preview: {preview}..."
+        )
+
+    return f"Found {len(files)} handoff(s):\n\n" + "\n\n".join(lines)
+
+
+@mcp.tool()
+def delete_handoff(
+    handoff_id: str = "",
+    delete_all: bool = False,
+) -> str:
+    """Delete a saved handoff or all handoffs.
+
+    Args:
+        handoff_id: The ID of the handoff to delete. Required unless delete_all is True.
+        delete_all: If True, deletes ALL saved handoffs. Use with caution.
+    """
+    if delete_all:
+        files = _list_handoff_files()
+        count = len(files)
+        for f in files:
+            f.unlink()
+        return f"Deleted all {count} handoff(s)."
+
+    if not handoff_id:
+        return "Error: provide a handoff_id or set delete_all=True."
+
+    path = _handoff_path(handoff_id)
+    if not path.exists():
+        return f"Error: No handoff found with ID '{handoff_id}'."
+
+    path.unlink()
+    return f"Deleted handoff: {handoff_id}"
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+def main() -> None:
+    """CLI entry point for the MCP server."""
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()