HandoffKit

HandoffKit creates a clean resume packet when an AI coding session gets interrupted.

Run it inside the repository you were working on. It collects the current git state, recent commits, changed files, agent instruction files, verification scripts, deterministic risk notes, and optional resume context into one paste-ready Markdown packet for Codex, Claude Code, Cursor, Gemini, ChatGPT, or another agent.

It is local-first and deterministic: the CLI reads your local git/filesystem state, redacts likely secrets, and prints Markdown or JSON. It does not call an LLM API, upload your repository, create commits, or write files unless you explicitly ask for output, cache, checkpoint, import, or export.

Use HandoffKit when the next agent needs the session state, not a full repo dump.

2-Minute Quickstart

From inside any git repository:

pnpm dlx @kingkyylian/handoffkit pack --goal "Continue this branch" --no-diff --budget 1800

Paste the generated packet into your next agent. It will include the live branch, status, recent commits, changed files, detected instruction files, package scripts, risk notes, scanner availability, and next-agent reminders.

When you have an interrupted transcript or previous handoff file:

pnpm dlx @kingkyylian/handoffkit resume codex-transcript.txt --goal "Continue from the interrupted session"

resume turns labelled transcript notes into structured completed work, remaining work, failed commands, open questions, and verification state before merging that with the current repository state.

Node.js 22 or newer is required.

Why It Exists

AI coding sessions get interrupted: context windows fill up, tools change, laptops sleep, a model gets stuck, or work needs to move from Claude Code to Codex or Cursor. The hard part is not feeding an entire repo to an agent. The hard part is explaining what happened on this branch, what already failed, and what the next agent should do first.

HandoffKit creates a deterministic handoff packet with the pieces another assistant needs first:

• current branch and git status
• recent commits
• staged and unstaged diff summaries
• changed file list
• detected instruction files such as AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules, and .github/copilot-instructions.md, with compact redacted previews
• package manager and common verification scripts from package.json
• best-effort redaction for likely secrets

What The Packet Looks Like

This abbreviated shape is manually verified against current CLI output:

# Handoff Packet

## Goal
Docs smoke

## Repository
- Repository: `handoffkit-docs-20`
- Branch: `docs-readme-conversion-20`
- Changed files: 2

## Git Status
```text
## docs-readme-conversion-20...origin/main
 M README.md
 M ROADMAP.md
```

## Changed Files
- `README.md`
- `ROADMAP.md`

## Package
- Package: `@kingkyylian/handoffkit`
- Package manager: `pnpm`
- Verification scripts:
  - `pnpm build`
  - `pnpm test`
  - `pnpm typecheck`
  - `pnpm lint`
  - `pnpm check`

## Risk Notes
- **low**: Documentation changed - Documentation-only changes still need examples, command names, and release instructions checked against the current CLI behavior.

## Next Agent Notes
- Use this packet as the starting context for the next coding session.
- Verify commands locally before claiming completion.
- This packet was generated from local git and filesystem state.
- Likely secrets were redacted from generated output.
- No LLM APIs were called.

Full patch text is omitted by default. Use --include-diff only when the next agent needs bounded tracked patches and safe untracked previews.

Resume Example

Given a raw Codex-style transcript:

Done this session
- Added Codex raw transcript fixture

Failed commands
- pnpm check failed before fixture update

Next steps
1. Document transcript resume imports

Verification
- CI passed on main

handoffkit resume tests/fixtures/resume/codex-raw-transcript.txt --goal "Docs resume smoke" extracts the work state before producing a normal packet:

## Resume State
### Completed
- Added Codex raw transcript fixture
### Remaining
- Document transcript resume imports
### Failed Commands
- pnpm check failed before fixture update
### Open Questions
None detected.
### Verification
- CI passed on main
- Next safest action: Document transcript resume imports

That is the reason to use resume instead of pasting raw notes: the next assistant sees completed work, remaining work, failure history, and verification state in predictable sections.

Positioning

HandoffKit is not a repo ingestion tool. It is not trying to replace Repomix, Gitingest, or long-lived repo instruction tools.

Its job is narrower: capture the live state of an interrupted AI coding session so another agent can resume without guessing.

Need	Better fit
Hand off an in-progress branch, interrupted debugging session, or copied agent transcript	HandoffKit
Feed a whole repository into a prompt or external summarizer	Repo ingestion tools
Maintain durable project rules for every agent session	Agent instruction files or repo instruction tools
Share a quick manual note with no local repo state	A short hand-written note

Use these tools together when it helps. HandoffKit can include instruction-file previews and compact branch state, but it intentionally does not replace durable project guidance or full-repo context tools.

HandoffKit vs. Repo Instruction Tools

Repo instruction tools such as AgentFit help shape reusable project guidance for AI agents. HandoffKit has a different job: it captures the live state of a coding session right now.

Use repo instruction tools to maintain durable agent rules. Use HandoffKit when you need to hand off an in-progress branch, debugging session, or partially completed change to another assistant without pasting raw diffs and secrets by hand.

Current MVP

The current CLI focuses on the useful handoff surface:

• local git state
• changed files
• recent commits
• diff summaries and optional patches
• agent instruction file previews
• package verification scripts
• best-effort secret redaction

It is useful today, but the goal is to stay focused on interrupted-session handoff quality rather than becoming a generic repo dumper. See ROADMAP.md for the next features that should make HandoffKit harder to replace with a manual paste.

Install

Run without installing:

pnpm dlx @kingkyylian/handoffkit pack --goal "Make your own goal"

Or install it globally:

pnpm add -g @kingkyylian/handoffkit

For local development:

pnpm install
pnpm build

Usage

From inside a git repository:

handoffkit pack --goal "Make your own goal"

Focus on the branch delta since a base ref:

handoffkit pack --since main --goal "Continue this branch"

Run safe verification scripts and include the result:

handoffkit pack --verify --goal "Fix remaining failures"

Verification only runs known script names such as typecheck, lint, test, and build. Scripts with obvious destructive or publishing commands are skipped, and each verification command has a bounded runtime.

Run optional local secret scanners and include bounded redacted results:

handoffkit pack --scan-secrets --goal "Review before handoff"

Optimize the packet for a target agent:

handoffkit pack --for codex --goal "Resume implementation"

Target profiles keep the same collected facts but adjust the title, section order, and next-agent notes for the selected tool. They do not invent project state or call model-specific APIs.

During development:

pnpm dev pack --goal "Make your own goal"

Write to a file:

handoffkit pack --goal "Finish the CLI MVP" --output handoff.md

JSON output:

handoffkit pack --goal "Review this branch" --format json

Include full patch text:

handoffkit pack --goal "Continue implementation" --include-diff

Untracked previews are limited to regular text files. Binary files, symlinks, generated directories, and oversized previews are bounded or omitted so packets stay paste-safe.

Omit diff summaries and patches:

handoffkit pack --goal "Summarize repo state" --no-diff
handoffkit pack --goal "Continue from recent cache" --include-cache

Set a rough Markdown token budget:

handoffkit pack --goal "Prepare a compact handoff" --budget 3000

Run verification directly:

handoffkit verify
handoffkit verify --cache

Inspect deterministic risk notes:

handoffkit risk

Run optional local secret scanners directly:

handoffkit scan-secrets

Resume from a previous handoff or transcript:

handoffkit resume previous-handoff.md --goal "Continue from here"
handoffkit resume claude-code-session.jsonl --goal "Continue from Claude Code"
handoffkit resume codex-transcript.txt --goal "Continue from Codex"
handoffkit resume previous-handoff.md --goal "Continue from here" --cache
handoffkit resume --from-cache latest --goal "Continue cached session"

resume accepts prior handoff Markdown and common copied or exported agent transcript shapes, including Claude Code JSONL text blocks, Codex raw transcript text, Cursor Markdown exports, and Gemini copied responses. It extracts completed work, remaining steps, failed commands, open questions, and verification notes when those labels are present.

Save a durable checkpoint and resume from it later:

handoffkit checkpoint save --goal "Continue this branch"
handoffkit checkpoint save --goal "Review after tests" --verify
handoffkit resume docs/checkpoints/LATEST.md --goal "Continue from checkpoint"

checkpoint save writes a timestamped Markdown file plus docs/checkpoints/LATEST.md by default. Use --output-dir <path> to choose a different checkpoint directory. Checkpoint writes are explicit; pack, resume, verify, and risk do not create checkpoint files.

Inspect local cache artifacts:

handoffkit cache list
handoffkit cache show resume latest
handoffkit cache export resume latest --output resume-cache.json
handoffkit cache import resume-cache.json

CLI Options

Option	Description
--goal <text>	The handoff goal to place at the top of the packet.
--output <path>	Write the packet to a file instead of stdout.
--format markdown|json	Render Markdown or JSON. Defaults to Markdown.
--for generic|codex|claude|cursor	Tune the packet heading and prompt shape for a target agent.
--budget <tokens>	Rough Markdown token budget. Defaults to 4000.
--since <ref>	Focus committed branch delta on a base ref such as main.
--verify	Run safe verification scripts and include results in the packet.
--scan-secrets	Run optional local secret scanners and include bounded redacted results.
--cache	Explicitly write local verification or resume artifacts under .handoffkit/.
--include-cache	Include recent .handoffkit artifact summaries in pack output.
--from-cache <ref>	Resume from a cached resume artifact such as latest or resume/latest.
--include-diff	Include full tracked patches and bounded untracked previews.
--no-diff	Omit diff summaries and full patches.

Local Cache

Cache writes are opt-in. verify --cache, pack --verify --cache, and resume --cache write redacted JSON artifacts under .handoffkit/verification or .handoffkit/resume. Use cache list and cache show to inspect artifacts, cache export and cache import to move redacted cache artifacts between clones, resume --from-cache latest to continue from the latest cached resume source, and pack --include-cache to include recent cache summaries in a new handoff packet. The cache directory is ignored by default so repeated handoffs do not pollute git status or generated reports.

See docs/CACHE.md for the file layout.

What Gets Collected

HandoffKit reads local git and filesystem metadata from the current repository:

• branch, status, recent commits, changed files, and diff summaries
• full tracked patch text only when --include-diff is used
• untracked file names in summaries, and untracked file preview content only when --include-diff is used
• compact previews of detected instruction files
• package manager and verification scripts from the root package.json
• optional verification results when --verify is used
• optional local cache summaries when --include-cache is used
• deterministic risk notes from changed file paths
• optional secret scanner availability, local config files, and install guidance for gitleaks and secretlint
• bounded, redacted secret scan results when --scan-secrets is used

checkpoint save uses the same collected facts to write a durable progress file under docs/checkpoints or the directory passed to --output-dir.

What Never Happens

• No LLM API calls.
• No network requests from the CLI.
• No git writes, commits, staging, or branch changes.
• No files are written unless --output, explicit --cache, checkpoint save, or an explicit cache import/export command is provided.

Development

pnpm install
pnpm typecheck
pnpm lint
pnpm test
pnpm build
pnpm check
pnpm pack:dry-run

Release

Releases are manual and should happen only after CI, package dry-run, and install smoke tests pass. The preferred path is the GitHub Release workflow with an NPM_TOKEN repository secret that can publish from CI without an interactive OTP, so npm provenance is attached to the published package.

See docs/RELEASE.md for the release checklist.

Security Model

HandoffKit is local-first and deterministic. It reads local git and filesystem state, renders a report, and redacts likely secrets from generated output. Redaction is best effort, so review packets before pasting them into a third-party tool.

When --scan-secrets is used, HandoffKit runs installed local scanners only. It does not install scanners, send code to a service, or fail when gitleaks or secretlint is missing.

When scanner config files such as .gitleaks.toml, .gitleaksignore, .secretlintrc.*, or secretlint.config.* are present, HandoffKit reports them in the packet so the next agent knows which local policy files exist.

License

MIT