handover 0.2.0__tar.gz

handover-0.2.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug report
+about: Report a bug or unexpected behavior in handover
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## Description
+
+A clear and concise description of what the bug is.
+
+## Steps to Reproduce
+
+1. Run `handover ...`
+2. With input file of type: ...
+3. See error
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include the full error message or output.
+
+## Environment
+
+- **CLI version:** `handover --version`
+- **Python version:** `python --version`
+- **OS:** (e.g. macOS 14, Ubuntu 22.04, Windows 11)
+- **Input format:** (e.g. single JSON, bulk JSONL, Markdown)
+- **Mode:** (e.g. default / `--no-llm` / `--dry-run`)
+
+## Additional Context
+
+Any other context that might help (e.g. anonymized snippet of the input file that triggers the issue).

handover-0.2.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,34 @@
+---
+name: Feature request
+about: Suggest a new feature or improvement for handover
+title: '[FEATURE] '
+labels: enhancement
+assignees: ''
+---
+
+## Problem Statement
+
+What problem does this feature solve? Who is the user experiencing it?
+(e.g. "As a developer using Gemini for design and Claude Code for implementation, I have no way to...")
+
+## Proposed Solution
+
+A clear description of the feature you'd like to see. How would it work from the user's perspective?
+
+## Alternatives Considered
+
+What other solutions or workarounds have you considered? Why are they not sufficient?
+
+## Phase
+
+Which project phase does this belong to?
+
+- [ ] Phase 1 — Claude chat → Claude Code (current)
+- [ ] Phase 2 — Universal chat sources (ChatGPT, Gemini, Perplexity adapters)
+- [ ] Phase 3 — Reverse handover (terminal → chat)
+- [ ] Phase 4 — Additional target agent adapters (Aider, Goose, Codex CLI)
+- [ ] Other / cross-cutting
+
+## Additional Context
+
+Any mockups, examples, or related issues that provide more context.

handover-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- Briefly describe what this PR does and why. -->
+
+## Changes
+
+<!-- List the key changes made. -->
+
+## Checklist
+
+- [ ] Tests added (or updated) for new/changed behaviour
+- [ ] Docs updated (README, docstrings, relevant docs/ page)
+- [ ] If adding a new adapter: `docs/adding-an-adapter.md` guide was followed
+- [ ] `PLAN.md` updated if any implementation tasks are now complete
+- [ ] CI passes (no new test failures)
+
+## Related Issues
+
+<!-- Closes #<issue_number> -->

handover-0.2.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 3

handover-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main, feature/**]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check handover/ tests/
+      - name: Ruff format check
+        run: ruff format --check handover/ tests/
+      - name: Mypy
+        run: mypy handover/
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v --cov=handover --cov-report=term-missing --cov-fail-under=80

handover-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Release to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test-before-release:
+    name: Test before release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dev dependencies
+        run: pip install -e ".[dev]"
+      - name: Ruff lint
+        run: ruff check handover/ tests/
+      - name: Ruff format check
+        run: ruff format --check handover/ tests/
+      - name: Mypy
+        run: mypy handover/
+      - name: Run tests with coverage gate
+        run: pytest tests/ -v --cov=handover --cov-fail-under=80
+
+  build:
+    name: Build distribution
+    needs: test-before-release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build tools
+        run: pip install hatchling build
+      - name: Build package
+        run: python -m build
+      - name: Store distribution packages
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-to-testpypi:
+    name: Publish to TestPyPI (dry run)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/handover
+    permissions:
+      id-token: write  # Required for TestPyPI Trusted Publisher
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+      - name: Verify install from TestPyPI
+        run: |
+          pip install --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ \
+            handover
+          handover --version
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    needs: [build, publish-to-testpypi]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/handover
+    permissions:
+      id-token: write  # Required for PyPI Trusted Publisher
+    steps:
+      - name: Download distribution packages
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

handover-0.2.0/.gitignore

@@ -0,0 +1,102 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+parts/
+var/
+sdist/
+develop-eggs/
+.installed.cfg
+lib/
+lib64/
+conversations.json
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Distribution / packaging
+.Python
+pip-log.txt
+pip-delete-this-directory.txt
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+htmlcov/
+
+# Installers
+*.manifest
+*.spec
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.local
+.env.*.local
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+Icon
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# handover-specific
+.handover/
+dev_docs/
+
+# Claude Code project config (local only — machine-specific permissions)
+.claude/

handover-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [click, anthropic, jinja2]
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml

handover-0.2.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+Versioning follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-04-05
+
+### Added
+- Claude adapter (`parsers/claude.py`) supporting both `.jsonl` (bulk export) and `.json` (single chat / browser extension) input formats
+- Support for Claude bulk JSON array export format (`conversations.json`)
+- Adapter pattern with `BaseParser` in `parsers/base.py` — extensible to future sources (ChatGPT, Gemini, etc.)
+- Heuristic summarizer (`heuristics.py`) for keyword-based context extraction when `--no-llm` is passed
+- LLM summarizer using Anthropic SDK (`claude-sonnet-4-6`) for AI-generated `CLAUDE.md` and `PLAN.md` artifacts
+- Jinja2-based generator with templates for `CLAUDE.md` and `PLAN.md`
+- CLI (`handover`) with subcommands: `run`, `list`, `init`
+- `--no-llm` flag for offline/heuristic-only mode
+- Full test suite with 80% coverage gate
+- GitHub Actions CI (lint + test matrix on Python 3.11 + 3.12)
+- GitHub Actions release pipeline to TestPyPI and PyPI via Trusted Publisher
+
+[Unreleased]: https://github.com/mohankrishnaalavala/handover/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/mohankrishnaalavala/handover/releases/tag/v0.2.0

handover-0.2.0/CLAUDE.md

@@ -0,0 +1,39 @@
+# handover — Universal AI Chat to Local Agent Handover Tool
+
+## Project Goal
+CLI tool that parses AI chat exports and generates CLAUDE.md + PLAN.md
+artifacts for local terminal agents to ingest. Phase 1: Claude chat only.
+
+## Tech Stack
+- Language: Python 3.11+
+- CLI: Click (with subcommands: main, list, init)
+- Templates: Jinja2
+- API: Anthropic SDK (claude-sonnet-4-6 for summarization)
+- Testing: pytest + pytest-cov
+- Packaging: pyproject.toml / hatchling
+
+## Architecture Rules
+- Parser uses adapter pattern: one class per source in parsers/
+- BaseParser in parsers/base.py defines the interface all adapters must implement
+- Summarizer calls Claude API unless --no-llm; then delegates to heuristics.py
+- Heuristics are keyword-rule-based — keep them simple and documented
+- Generator uses Jinja2 templates only — never hardcode output format in Python
+- All data models are dataclasses in models.py with full type hints
+- schema_version must be bumped in models.py when HandoverContext fields change
+
+## Coding Standards
+- Type hints on all functions and methods
+- Docstrings on all public methods
+- Tests required for: parser output, heuristics rules, generator file output
+- Mocked API calls in test_summarizer.py — never hit real API in tests
+- No dependencies beyond: click, anthropic, jinja2, pytest, pytest-cov
+
+## Key Commands
+- Run tests: pytest tests/ -v --cov=handover
+- Install locally: pip install -e .
+- Run CLI: handover --help
+
+## Phase 1 Focus
+- Claude adapter only (parsers/claude.py)
+- Do NOT build ChatGPT adapter yet — that is Phase 2
+- Both input formats: .jsonl (bulk) and .json (single chat via browser extension)

handover-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,65 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by following the instructions in [SECURITY.md](SECURITY.md) or by
+contacting the maintainer via the [GitHub profile](https://github.com/mohankrishnaalavala).
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Enforcement Guidelines
+
+**1. Correction** — Private written warning, clarity around the violation.
+
+**2. Warning** — A warning with consequences for continued behavior.
+
+**3. Temporary Ban** — Temporary ban from any interaction or public communication.
+
+**4. Permanent Ban** — Permanent ban from any public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

handover-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to handover
+
+Thank you for your interest in contributing! `handover` is an open-source project and contributions are very welcome.
+
+## Setup
+
+```bash
+git clone https://github.com/mohankrishnaalavala/handover.git
+cd handover
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest tests/ -v --cov=handover --cov-report=term-missing
+```
+
+All tests must pass before submitting a PR. Never commit code that breaks existing tests.
+
+## Primary Contribution Path: Adding a New Source Adapter
+
+Adding a new source (ChatGPT, Gemini, Perplexity, etc.) is the primary way to contribute. Each adapter is one self-contained class in `handover/parsers/`. A contributor can own an adapter end-to-end as an isolated PR.
+
+See **[docs/adding-an-adapter.md](docs/adding-an-adapter.md)** for the complete step-by-step guide.
+
+In brief, adding a new adapter means:
+1. Create `handover/parsers/{source_name}.py` — subclass `BaseParser`
+2. Register the adapter in `parsers/__init__.py`
+3. Add a test fixture in `tests/fixtures/`
+4. Add tests in `tests/test_parser.py`
+5. Update the supported formats table in `README.md`
+6. Add the source name to the `--source` flag in `cli.py`
+
+## Code Standards
+
+The following standards are taken directly from `CLAUDE.md` and apply to all contributions:
+
+- **Type hints** on all functions and methods
+- **Docstrings** on all public methods
+- **Tests required** for: parser output, heuristics rules, generator file output
+- Mocked API calls in `test_summarizer.py` — never hit the real Anthropic API in tests
+- No additional dependencies beyond: `click`, `anthropic`, `jinja2`, `pytest`, `pytest-cov`
+
+## Submitting a Pull Request
+
+1. Fork the repo and create a feature branch
+2. Make your changes, add tests, update docs
+3. Run `pytest tests/ -v` — all tests must pass
+4. Update `PLAN.md` if your PR completes any listed tasks
+5. Open a PR against `main` using the PR template
+
+## Project Phases
+
+Before contributing, it helps to understand the roadmap:
+
+- **Phase 1** (current): Claude chat → Claude Code. This is what we're building now.
+- **Phase 2**: Universal chat sources — ChatGPT, Gemini, Perplexity adapters. **This is the main open contribution path.**
+- **Phase 3**: Reverse handover — Claude Code session logs → readable handover doc.
+- **Phase 4**: Additional target agents (Aider, Goose, Codex CLI).
+
+Please check open issues and the `PLAN.md` before starting work to avoid duplicating effort.

handover-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohan Krishnaa Alavala
+
+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.