Universal Context Handoff

AI coding tools are getting better at implementation, but context often gets lost when work moves across sessions, repositories, or assistant environments. Universal Context Handoff is a small local-first attempt to preserve that handoff context as Markdown/JSON artifacts that humans and AI agents can both read.

Overview

Universal Context Handoff is a local-first CLI tool and assistant skill designed to capture and transfer coding session context between different AI coding environments (e.g., Claude Code, Codex CLI, and Antigravity legacy transcript logs) and local repositories.

Why I built it

AI coding tools excel at implementation tasks within active sessions, but they remain highly transactional. When a session ends or work moves to a different repository or a separate assistant environment (like switching from Claude Code in the terminal to an IDE agent), the accumulated context — decisions made, rejected directions, and next steps — is frequently lost.

This project is a practical attempt to define a simple handoff protocol to bridge this gap, ensuring that both developers and incoming AI agents can resume work with minimal friction.

What it does

The tool operates via a simple command-line interface handoff that runs locally on your machine. When executed, it:

Extracts session history: Reads and parses transaction logs, shell histories, and session transcript files.
Generates handoff artifacts: Compiles the parsed history into a standard .handoffs/ directory containing structured Markdown and JSON summaries.
Redacts sensitive data: Performs best-effort local redaction of sensitive identifiers, tokens, and personal details before generating the final handoff brief.

Current support matrix

Source	Status
Claude Code JSONL sessions	Supported
Codex CLI `rollout-*.jsonl` sessions	Supported
Codex archived `rollout-*.jsonl` sessions	Supported
Antigravity legacy JSONL transcript logs	Experimental
Antigravity IDE `.db` / `.pb` formats	Not supported yet
Claude.ai web transcript extraction	Manual import only
Claude Cowork	Not supported / unknown

Privacy and safety note

[!IMPORTANT] This tool is strictly local-first and does not upload data to any third-party cloud. However, generated handoff artifacts can still contain sensitive code fragments or proprietary details. Redaction is best-effort only, and users should manually review Markdown, JSON, and ZIP artifacts before sharing, committing, publishing, or sending them to another person or agent.

What I learned

Context is heavier than code: Preserving the rationale behind code changes is often more critical for the next agent than the raw diff itself.
Schema boundaries are fragile: Session format schemas drift rapidly across tool versions. Writing rigid parsers is a losing battle; a loose, fault-tolerant tokenized approach works better for long-term handoff stability.
Redaction requires human-in-the-loop: Fully automated regex-based redaction will always miss edge cases. Standardizing a human-in-the-loop “review before handoff” step is essential for safe operation.

What it is not

It is not a cloud-based memory or sync system.
It is not an agent orchestrator or runner.
It is not currently published on npm.

Next steps

Explore parsing capabilities for IDE-based agent databases.
Refine the automated redaction rulesets.
Test handoff briefs against wider models to evaluate context retrieval accuracy.