handoff

Turn a coding-agent session JSONL plus the current git worktree into a next-session brief. No language model. No network. MIT.

python3 handoff --session tests/fixtures/claude_session.jsonl

Install

Python 3.10+ and git on PATH. From this repo, no install step:

python3 handoff --help

Optional editable install:

pip install -e .
handoff --help

One-command run

python3 handoff --session tests/fixtures/claude_session.jsonl

--latest uses the newest Claude Code JSONL for the current directory:

python3 handoff --latest

Write a file instead of stdout:

python3 handoff --session tests/fixtures/claude_session.jsonl -o HANDOFF.md

The CLI is complete without SKILL.md. The Skill only teaches an agent when to run this command.

Real fixture → real brief

Input is the committed transcript tests/fixtures/claude_session.jsonl: a user ask to fix a login redirect, an Edit of src/auth.py, pytest tests/test_auth.py -q with exitCode 0, then the assistant claiming tests and lint.

Ran from this repo against a throwaway git worktree that also had an uncommitted notes.md (same command as above, with -C pointing at that worktree):

# Handoff

## Goal
Fix the login redirect in src/auth.py so failed logins stay on /login

## Status
in progress (uncommitted changes on main); assistant claims are unverified

## Files changed
- `src/auth.py` (session: Edit)
- `notes.md` (git)

## Commands run
- `pytest tests/test_auth.py -q`  exit 0

## Unverified claims
- Assistant said “Lint is clean” (lint) with no matching successful command.

## Next safe action
Re-run the claimed check (lint) before continuing.

“All tests pass” is not listed as unverified because the session recorded a matching pytest with exit 0. “Lint is clean” is, because no lint command ran.

What it reads

Flag	Source
--session PATH	Claude Code JSONL (user / assistant, tool_use paired with tool_result / toolUseResult.exitCode, Edit / Write / Bash) or a Codex rollout-*.jsonl
--latest	~/.claude/projects/<cwd with every non-alphanumeric character as ->/*.jsonl, newest mtime
git	git status --porcelain and git diff --stat HEAD in -C / cwd

Default path does not call a model, does not phone home, and does not send the session anywhere.

Skill

SKILL.md is an Agent Skill for Claude Code / Codex / OpenCode / Cursor: run this CLI; do not summarize the JSONL in prose.

Tests

python3 -m unittest discover -s tests -v

License

MIT

Background on why this shape: recommendation.md (not the product).