Metadata-Version: 2.4
Name: handover
Version: 0.2.0
Summary: Universal AI chat to local agent handover tool
Project-URL: Homepage, https://github.com/mohankrishnaalavala/handover
Project-URL: Issues, https://github.com/mohankrishnaalavala/handover/issues
Author: Mohan Krishnaa Alavala
License: MIT
License-File: LICENSE
Keywords: agent,ai,claude,claude-code,cli,handover
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40.0
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# handover

> *Design in chat. Build in terminal. Zero context lost.*

`handover` is an open-source CLI tool that bridges AI chat interfaces (Claude, ChatGPT, Gemini, and others) to local terminal coding agents (Claude Code, Codex CLI, etc.). It extracts decisions, plans, and intent from a chat conversation and generates structured handover artifacts that a local agent can immediately act on — without re-explaining anything.

[![PyPI version](https://img.shields.io/pypi/v/handover.svg)](https://pypi.org/project/handover/)
[![Python versions](https://img.shields.io/pypi/pyversions/handover.svg)](https://pypi.org/project/handover/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/mohankrishnaalavala/handover/actions/workflows/ci.yml/badge.svg)](https://github.com/mohankrishnaalavala/handover/actions/workflows/ci.yml)

---

## Install

```bash
pip install handover
```

---

## Quickstart

```bash
# Basic usage — single conversation file
handover --input conversation.json --output ./my-project/

# List all conversations in a bulk export
handover list export.jsonl

# Bulk export — select a specific conversation by title
handover --input export.jsonl --title "API Design Discussion" --output ./my-project/
```

---

## `--dry-run` Demo

```
$ handover --input chat.json --dry-run

🔍 Parsing conversation: "API Design Discussion"
   Source: claude | Messages: 34 | Format: single-json v1.0

📋 Extracted HandoverContext:
   Goal: Build a FastAPI REST API with JWT auth and PostgreSQL
   Tech Stack: Python, FastAPI, PostgreSQL, pytest
   Decisions:
     • async handlers — high concurrency expected
     • JWT auth — stateless API requirement
   Tasks: 6 items
   Constraints: 2
   Open Questions: 1

📄 Would write:
   → ./my-project/CLAUDE.md  (1.2 KB)
   → ./my-project/PLAN.md    (0.4 KB)

Run without --dry-run to write files.
```

---

## Supported Input Formats

| Source | Format | How to Get |
|--------|--------|------------|
| Claude.ai bulk export | `.jsonl` (one JSON object per line) | Settings → Privacy → Export Data |
| Claude.ai single chat | `.json` | Claude Conversation Exporter browser extension |
| Claude.ai single chat | `.md` | Browser extension (Markdown export) |

---

## All Flags

```bash
handover --input chat.json --output ./my-project/ --source claude   # explicit adapter
handover --input chat.json --output ./my-project/ --dry-run         # print, don't write
handover --input chat.json --output ./my-project/ --no-llm          # rule-based only, no API key needed
handover --input chat.json --output ./my-project/ --launch          # run `claude` after writing
handover --input chat.json --output ./my-project/ --template ~/.handover/templates/

handover list export.jsonl                  # enumerate conversations in bulk export
handover init                               # scaffold customizable templates to ~/.handover/
```

---

## Roadmap

| Phase | Source | Target | Status |
|-------|--------|--------|--------|
| 1 | Claude chat | Claude Code | **This release** |
| 2 | ChatGPT, Gemini, Perplexity | Claude Code | Open contribution path |
| 3 | Claude Code sessions (`~/.claude/projects/`) | Claude chat | High value — spec next |
| 4 | Any chat | Codex CLI, Aider, Goose | Future |

---

## Contributing

The primary contribution path is adding a new source adapter. Each adapter is an isolated Python class anyone can own end-to-end. See [docs/adding-an-adapter.md](docs/adding-an-adapter.md) for the step-by-step guide.

For general contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).

---

## Full PRD

The complete Product Requirements Document is available at [handover-prd-v2.md](handover-prd-v2.md).

---

## License

MIT © 2026 Mohan Krishnaa Alavala
