---
title: "Universal Context Handoff"
type: project
description: "A local-first CLI and assistant skill for preserving AI coding session context across repositories and tools like Claude Code, Codex CLI, and Antigravity. Built as a practical handoff protocol, not a cloud memory system."
summary: "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."
ai_summary: "Local-first CLI and assistant skill for preserving AI coding session context across repositories and environments (Claude Code, Codex, Antigravity legacy JSONL)."
status: public
visibility: public
language: en
topics: [ai-workflow, developer-tools, context-handoff]
tags: [cli, handoff, open-source]
audience: [builders, developers]
publishedAt: 2026-07-07
updatedAt: 2026-07-07
featured: true
related: [prompts/agentic-handoff-brief]
sourceStatus: original
sourceSensitivity: public
projectStatus: active
role: "builder"
artifactType: tool
artifactUrl: "https://github.com/1beenlee/universal-context-handoff"
repoUrl: "https://github.com/1beenlee/universal-context-handoff"
publicProof: ["v0.1.0 release", "Main commit 536eae9"]
canonicalUrl: "https://wbeen-personal-kb.vercel.app/projects/universal-context-handoff"
---

## 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:

1. **Extracts session history:** Reads and parses transaction logs, shell histories, and session transcript files.
2. **Generates handoff artifacts:** Compiles the parsed history into a standard `.handoffs/` directory containing structured Markdown and JSON summaries.
3. **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`.

## Links

- **Repository:** [1beenlee/universal-context-handoff](https://github.com/1beenlee/universal-context-handoff)
- **v0.1.0 Release:** [v0.1.0 Release Notes](https://github.com/1beenlee/universal-context-handoff/releases/tag/v0.1.0)
- **Main Commit:** [536eae9](https://github.com/1beenlee/universal-context-handoff/commit/536eae9)

## 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.

---

Canonical page: https://wbeen-personal-kb.vercel.app/projects/universal-context-handoff
This is the AI-readable Markdown mirror. Public, curated content only.