claude-handoff

Превратите любую сессию Claude Code — даже упавшую — в чистый handoff.md, с которого другой ИИ сможет продолжить работу. И дайте Claude Code постоянную память проекта, извлечённую из вашей собственной истории.

chf

Вот и всё. Ваша последняя сессия становится handoff.md: разговор без шума, изменённые файлы, выполненные команды — в начале документа идут инструкции для принимающего ассистента, так что вы можете вставить его прямо в Gemini, GPT, claude.ai или новую сессию Claude Code без какого-либо дополнительного промпта.

Claude Code хранит каждую сессию локально в формате JSONL (~/.claude/projects/…/*.jsonl) — с вызовами инструментов, результатами, блоками размышлений и системными напоминаниями. Существующие экспортёры выгружают всё это в markdown. claude-handoff вместо этого создаёт документ handoff — и, поскольку он умеет читать всю вашу историю, также краткую памятку по проекту.

• Ноль зависимостей. Только стандартная библиотека, Python 3.9+. Пакет из девяти модулей — также поставляется в виде готового однострочного скрипта, который можно curl-нуть и проверить.

• Детерминированность по умолчанию. Никаких API-вызовов, никаких затрат, работает офлайн.

• --llm, когда нужна настоящая сводка. Claude, OpenAI или Gemini по вашему собственному API-ключу — или --llm claude-cli, который запускает локально установленный CLI Claude Code по вашему существующему плану Pro/Max: вообще без API-ключа.

• Без шума. Отбрасывает результаты инструментов, блоки размышлений, системные напоминания, болтовню субагентов, обёртки слэш-команд. Сохраняет намерения пользователя, ответы ассистента, изменённые файлы, выполненные команды — включая файлы и команды субагентов (agent-*.jsonl), чьи полные транскрипты остаются за --include-sidechains.

• Память проекта. chf --brief превращает ВСЮ историю сессий проекта в одну живую памятку (решения, исправления, соглашения, открытые вопросы — со ссылками на сессии); --install-brief-hook внедряет её в каждую новую сессию Claude Code, так что Claude начинает работу, уже зная проект.

• Безопасно для вставки. Строки, похожие на секреты (API-ключи, токены, password=…) удаляются из всех выходных данных — handoff, который вы вставляете в веб-чат, тоже является исходящим трафиком. --anonymize идёт дальше для публичного распространения.

Предварительные требования

Никаких сторонних Python-пакетов, никогда — всё работает на стандартной библиотеке.

Related MCP server: Longhand

Установка

pipx install claude-handoff        # or: pip install claude-handoff

brew install Vasilispapg/tap/claude-handoff   # Homebrew

# or just grab the generated single-file build — stdlib-only, auditable:
curl -O https://raw.githubusercontent.com/Vasilispapg/claude-handoff/main/single/claude_handoff.py
python3 claude_handoff.py --list

Установка пакета даёт две одинаковые команды: claude-handoff и короткий алиас chf. Автодополнение по табуляции:

eval "$(claude-handoff --completions zsh)"    # bash works too

60 секунд: выберите свою ситуацию

Сессия упала, достигнут лимит использования или вы закрыли терминал:

chf -o clipboard

…затем вставьте в claude.ai, ChatGPT, Gemini — или в новую сессию claude. Работает с любой старой сессией; ничего не нужно было устанавливать до сбоя.

Перенос работы из Claude Code в другую модель:

chf --fit 32k -o clipboard         # sized to the receiver's context window

«В какой сессии мы говорили про CORS?»

chf --list --grep "CORS"           # every match, with a 🔍 context preview
chf --grep "CORS"                  # or export the newest match directly

Дать Claude Code постоянную память об этом проекте:

chf --brief --llm claude-cli       # distill ALL sessions → one cited brief
chf --install-brief-hook           # every new session starts knowing it

Настоящая сводка вместо транскрипта (цель / решения / состояние / далее):

chf --llm claude-cli               # your Claude Code login — no API key

Веб-чат claude.ai или ChatGPT вместо терминальной сессии:

chf conversations.json --list      # each app's data export works as input
chf conversations.json --name "webhook bug"

Память проекта (--brief)

Claude Code забывает всё между сессиями — но вся история лежит на вашем диске. chf --brief читает все сессии текущего проекта и записывает один документ памяти в ~/.claude/briefs/<project>.md:

• фактологическая хронология сессий + самые часто изменяемые файлы (детерминированно, бесплатно);

• с --llm — дистиллированная память: решения с их причинами, исправленные баги, соглашения, открытые вопросы — каждый пункт снабжён ссылкой на исходную сессию (chf --name <id> открывает источник).

Заметки по сессиям кэшируются, так что обновление после новых сессий оплачивается только для новых — а огромная сессия (свыше ~120 тыс. символов) обрабатывается в стиле map-reduce внутри заметки, так что путь памяти никогда не обрезается: ничего не теряется молча, при любом размере.

chf --install-brief-hook

устанавливает два хука: SessionStart внедряет памятку как контекст (Claude начинает работу, уже зная проект — повторно внедряется и после /compact), SessionEnd автоматически обновляет фактологическую часть бесплатно. Никакой LLM никогда не запускается из хука; дистиллированная часть обновляется только по вашему запросу. Памятка несёт отметку свежести, и файл, и внедрение предупреждают, когда есть более новые сессии. Полностью локально; редактирование применяется как везде.

→ Пошаговая механика, честная таблица затрат и полное описание дня с ней: docs/GUIDE.md.

Автоматизируйте

chf --install-hook                 # SessionEnd + PreCompact → handoff to ~/.claude/handoffs/
chf --install-brief-hook           # SessionStart/End + PreCompact → project memory (above)

PreCompact важен: непосредственно перед сжатием контекста длинной сессии оба хука делают снимок состояния — handoff сохраняет детали, которые сжатие вот-вот уберёт, а каркас памятки остаётся свежим в середине сессии.

Оба хука неразрушающе редактируют ~/.claude/settings.json, идемпотентны и имеют парные флаги --uninstall-*. Сбои хуков никогда не нарушают основную сессию, и хуки сами по себе не запускают LLM-вызовы и не создают файлы.

Как выглядит результат

# Conversation handoff

> To the receiving assistant: … you are taking over …

## Session
- Project: /home/you/myapp (branch main)
- When: 2026-08-20 09:00 → 09:04
- Activity: 2 user messages, 4 assistant replies, 4 tool calls

## Files created / modified
- /home/you/myapp/auth.py

## Commands run
- python -m pytest tests/test_auth.py -q

_🤖 2 subagent(s) contributed to the work above (--include-sidechains for their transcripts)._

## Conversation
### 🧑 User
the login breaks on unicode passwords…
### 🤖 Assistant
Found it — ascii encoding. Changed to utf-8, tests pass.

Часто используемые команды

chf                                # latest session → handoff.md
chf -i                             # numbered picker; "1,3" or "2-4" merges several
chf --list                         # what sessions do I have? (title · first prompt)
chf --list --format json           # the same, machine-readable
chf --name "login bug"             # newest session whose title/prompt matches
chf "login bug"                    # same — a non-path argument is a name search
chf --grep "CORS"                  # newest session that *talked about* CORS
chf --grep CORS --grep auth        # …that talked about BOTH (AND)
chf a.jsonl b.jsonl                # several paths → ONE merged handoff
chf --project myrepo               # latest session of a specific project
chf path/to/session.jsonl -o -     # explicit file → stdout
chf -o clipboard                   # straight to the clipboard — go paste it
chf --last 5                       # only the last 5 user turns
chf --since 2h                     # only the last 2 hours of the session
chf --fit 32k                      # sized to fit a 32k-token context
chf --include-tools                # keep collapsed per-tool-call detail
chf --include-sidechains           # append full subagent transcripts
chf --anonymize                    # public-safe: ~ paths, no emails/IPs/username
chf --project myrepo --merge       # whole project in ONE handoff, oldest → newest
chf --format json -o session.json  # machine-readable handoff

# LLM summaries (goal / decisions / current state / next steps):
chf --llm claude-cli               # your Claude Code login — no API key
chf --llm ollama                   # local model — fully offline
chf --llm claude                   # Anthropic API   (ANTHROPIC_API_KEY)
chf --llm openai --model gpt-4o    # OpenAI API      (OPENAI_API_KEY)
chf --llm gemini --with-transcript # Google API      (GEMINI_API_KEY)
chf --llm claude-cli --focus "emphasize the API decisions"

# project memory:
chf --brief                        # free factual brief (timeline + files)
chf --brief --llm claude-cli       # + distilled decisions/fixes/conventions

Где ищет? Сессии хранятся в глобальном хранилище Claude Code (~/.claude/projects), так что chf можно запускать откуда угодно. Если ваша текущая директория является проектом (или подпапкой проекта), инструмент ограничивается сессиями этого проекта; родительская «главная папка» ограничивает всеми проектами внутри неё; --any вообще игнорирует директорию. Автовыбор пропускает почти пустые сессии (например, заглушку, оставляемую claude /login), так что «последняя» означает вашу последнюю реальную беседу — явный путь, --name или -i всегда выигрывают.

Большие сессии. Транскрипты, выходящие за один проход (~400 тыс. символов), резюмируются в стиле map-reduce: заметки по частям, затем один синтез — ничего не теряется молча, а готовые части кэшируются в ~/.cache/claude-handoff, так что прерванный запуск бесплатно возобновляется. Части обрабатываются в 4 потока параллельно у API-провайдеров; claude-cli и ollama по замыслу остаются последовательными. В терминале вы видите живой индикатор прогресса:

[█████████░░░░░░░░░░░░░░░] 3/9 chunks | 4m12s elapsed | ~8m left | summarizing part 4/8 (199,867 chars)…

Сессии с данными об использовании API также получают строку Tokens в заголовке, и каждый запуск сообщает приблизительный размер результата в токенах.

Приватность и нулевое доверие

• Ничего никуда не отправляется, если вы не передадите --llm — детерминированный режим полностью офлайн.

• Редактирование включено для всех выходных данных, а не только для LLM-трафика: строки, похожие на секреты (API-ключи, токены, JWT, password=…) удаляются из самого handoff, файлов хуков и MCP-ответов — вставленный документ тоже является исходящим трафиком. --no-redact отключает редактирование для конкретного запуска (и намеренно не разрешён в файле конфигурации).

• --anonymize дополнительно заменяет ваш домашний каталог на ~, а email, IPv4-адреса и ваше имя пользователя — на заглушки; для вставки в публичные issues и форумы.

• --llm claude-cli и --llm ollama остаются в рамках учётной записи и машин, которыми вы уже управляете.

• Защита от prompt-инъекций: в транскриптах регулярно встречается непроверенный текст (веб-страницы в результатах инструментов, вставленные README-файлы). Каждый промпт, который потребляет транскрипт, вводная часть handoff и обёртка внедрения памятки — всё это обрамляет такой контент как данные, а не инструкции; это закреплено тестами. Митигация, а не доказательство; сам парсер никогда ничего не выполняет.

Конфигурация (необязательно)

Поместите параметры по умолчанию, которые вы всегда используете, в ~/.config/claude-handoff/config.json (флаги CLI всегда выигрывают; CLAUDE_HANDOFF_CONFIG переопределяет путь):

{ "llm": "claude-cli", "fit": "32k", "include_tools": true }

Допустимые ключи: llm, model, fit, output, include_tools, include_sidechains, max_chars, anonymize, focus. Защитные переключатели (no_redact) намеренно не конфигурируются — ослабление редактирования должно быть явным выбором при каждом запуске. Сломанная конфигурация предупреждает и игнорируется, но не приводит к фатальной ошибке.

Переменные окружения

claude-cli не требует переменных — он вызывает установленный вами CLI Claude Code и оплачивается по вашему плану Pro/Max (один раз войдите через claude).

MCP-сервер

Любой MCP-клиент (Claude Desktop, Claude Code, …) может получать handoff напрямую:

claude mcp add claude-handoff -- claude-handoff --mcp

Инструменты: list_sessions (что на этой машине) и handoff (создать документ для сессии по имени/проекту/пути; передайте anonymize для версии, доступной для распространения). По умолчанию детерминирован — MCP-клиент может запускать LLM-сводки только если вы запустили сервер с --allow-llm.

Устранение неполадок

claude-handoff: command not found после pip install pip кладёт скрипты в пользовательский каталог bin, который может не быть в PATH. Используйте pipx install claude-handoff или brew — оба управляют PATH — или добавьте ~/.local/bin (Linux) / ~/Library/Python/3.x/bin (macOS) в PATH.

«Не найдено сессий в ~/.claude/projects» Вы на машине (или под пользователем), где ещё не запускали Claude Code, или ваше хранилище находится в другом месте — укажите CLAUDE_HOME. Внутри папки проекта инструмент ограничивается этим проектом; передайте --any, чтобы искать везде.

Выбрана не та сессия «Последняя» пропускает почти пустые заглушки, но всё равно просто самый новый файл. Используйте -i (выбор), --name "часть названия" или --grep "что-то сказанное".

--llm claude-cli не работает или запрашивает аутентификацию Запустите claude один раз и войдите (/login). Это работает даже при вызове изнутри сессии Claude Code — унаследованные переменные окружения CLAUDE* очищаются, так что вложенный CLI аутентифицируется как новый.

«Set ANTHROPIC_API_KEY … to use --llm claude» Провайдерам API нужен ключ в окружении — см. таблицу выше. Ключа нет вообще? Используйте --llm claude-cli (по подписке) или --llm ollama (локально).

--fit отказывается сочетаться с --llm / --max-chars --fit сам определяет размер детерминированного вывода. Если вы не вводили его, вероятно, ваш конфигурационный файл задаёт fit — переопределите, явно убрав --max-chars, или удалите ключ.

Инъекция брифа предупреждает «sessions newer than this brief exist» Это работает штамп свежести: запустите chf --brief --llm claude-cli, чтобы пере-дистиллировать (кэшируется — оплачиваются только новые сессии). Фактическая часть обновляется сама, если установлен хук SessionEnd.

Что-то молча ничего не сделало? Пути, устойчивые по замыслу (битые строки JSONL, нечитаемые файлы, проблемы с кэшем), никогда не прерывают выполнение — добавьте --debug (или CLAUDE_HANDOFF_DEBUG=1), чтобы увидеть, что именно было пропущено и почему. Хуки всегда сообщают об ошибках в stderr, при этом завершаясь с кодом 0.

Искажённые символы в Windows Установите PYTHONUTF8=1 (CI запускает весь набор тестов именно так).

Полный справочник флагов

Дорожная карта

• Экспорты Gemini как входные данные (Google Takeout поставляет только HTML — нужен настоящий, отредактированный экспорт для разработки)

• Цепочки сессий: автоматически определять сессии, продолженные через /compact, и предлагать объединить родословную (--follow)

PR приветствуются.

Сравнение с аналогами

Это пространство не пусто — оно фрагментировано. Выберите инструмент, соответствующий вашей ситуации:

• Экспортёры — claude-conversation-extractor, claude-code-log, claude-code-transcripts, claude-to-markdown — превращают транскрипты в читаемый Markdown/HTML, включая шум инструментов, без рамок передачи.

• Переносчики сессий между CLI — cli-continues (npm i -g continues) читает нативные хранилища сессий 16 кодинг-CLI (включая Claude Code) и внедряет контекстный документ в другой терминальный инструмент. Отлично для Claude Code → Codex/Cursor/Gemini CLI; но не может работать с веб-чатами, не делает LLM-резюмирование и требует Node 22.5+.

• Навыки/плагины передачи внутри сессии — thepushkarp/handoff, claude-session-handoff, claude-code-handoff — отлично если вы не забудете запустить их до конца сессии; модель пишет резюме, используя контекст вашей сессии, а вывод предназначен для следующей сессии Claude.

• Браузерные расширения — Handoff, LLM Context Bridge, ContextSwitch — переносят веб-чаты между ChatGPT/Claude/Gemini; они не видят сессии Claude Code.

claude-handoff — это постфактумный, вставляемый куда угодно угол этой карты: он работает с JSONL после факта — старые сессии, упавшие сессии, сессии, достигшие лимита использования — не требует ничего установленного заранее, по умолчанию стоит ноль токенов, может написать настоящее резюме, когда вы попросите (--llm), и создаёт документ, который может подхватить любая принимающая модель, включая claude.ai, ChatGPT и Gemini в браузере или на телефоне. А с --brief это единственный инструмент, который превращает эту историю в постоянную память проекта.

Разработка

git clone https://github.com/Vasilispapg/claude-handoff && cd claude-handoff
python3 -m unittest discover -s tests -v      # the whole suite (no deps needed)
python3 -m claude_handoff tests/fixtures/agent_session.jsonl -o -   # smoke run
python3 scripts/build_single.py --check       # single-file build is fresh
uvx ruff check claude_handoff scripts tests   # lint (config in pyproject)

Код выполнения находится в пакете claude_handoff/; single/claude_handoff.py генерируется — пересоберите его с помощью python3 scripts/build_single.py после любого изменения пакета (CI падает, если он устарел). Новое поведение парсера начинается с отредактированного фикстура в tests/fixtures/ — см. CONTRIBUTING.md и AGENTS.md (инструкции и инварианты для людей и ИИ-контрибьюторов).

Узнать больше

docs/GUIDE.md — день с claude-handoff: пошаговое руководство, как работает --brief шаг за шагом, честная таблица стоимости, шпаргалка · INDEX.md — карта файлов · docs/DEVELOPMENT.md — архитектура, заметки по схеме JSONL, дизайн-решения · AGENTS.md — руководство для ИИ-агентов-контрибьюторов · CONTRIBUTING.md · CHANGELOG.md

Лицензия

MIT