IPSF — In-Place Session Forking Protocol: a vendor-neutral open specification for deterministic, verifiable context handoff between AI agent sessions.
Author: Mustafa KILINC (@mrblackman)
Version: IPSF-1.2 (Normative Protocol Specification)
Document ID: RFC-IPSF-001
Repository: github.com/mrblackman/ContextFork
💡 Core Principles:
"LLM summarizes; machines verify."
"Don't ask the AI to remember what the machine can verify."
⚠️ Specification Status: RFC Draft — Under Active Development
This repository defines an open, vendor-neutral protocol. The accompanyingcontextfork.pyis a reference implementation that demonstrates the method is buildable — it is not a production-ready tool. We welcome architectural feedback, peer review, and independent implementations from the autonomous agent engineering community.
Modern Large Language Models advertise theoretical context windows of 1M to 2M+ tokens. However, empirical research (Stanford's Lost in the Middle, Chroma's Maximum Effective Context Window, RULER) establishes that effective reasoning accuracy for autonomous agentic coding degrades significantly as token contexts expand ("Context Rot").
In extended engineering sessions (100–250+ steps), developers face two compounding bottlenecks:
- Zero Context Observability: Users operate without real-time indicators for accumulated prompt tokens, tool output weight, or step counts. Sessions silently balloon past 100,000+ tokens, turning every routine prompt into a massive compute drain and triggering severe attention dilution.
- The "New Chat" Abstraction Failure: The traditional "New Chat" button is a destructive reset. Developers resist starting fresh sessions because manually summarizing 50+ steps of architectural decisions, file modifications, and pending tasks creates severe handoff friction.
ContextFork (IPSF-1.2) formalizes an interoperable, vendor-agnostic protocol solving this dilemma through two core pillars:
- Ambient Context Telemetry: Real-time UI visibility into active token count, step count, and attention degradation risk signals.
- Native "Summarize & Fork" (Session Forking): A structured handoff protocol that compresses a bloated session into a verifiable 6-part handoff package, enabling a clean continuation session in the same workspace with preserved architectural decisions and machine-verifiable working state.
In transformer architectures, attention weights dilute over large token horizons. As prompt context grows:
- Attention Dilution: The attention matrix dilutes across historical terminal noise, failed tool attempts, and verbose build logs.
- Repetitive Failure Looping: Models begin treating their own past failed tool calls as "ground truth" or stylistic guidelines, falling into repetitive failure loops.
- Loss of System Constraints: High-priority system instructions (Constitutional rules, security isolation, git practices) placed at the beginning of the context fall into the "Lost in the Middle" trough.
Context Compression ≠ Context Preservation:
Compressing 120,000 tokens into 2,000 tokens is inherently a lossy compression. If an agent summary omits why certain paths failed or lacks machine-verifiable evidence, the newly spawned child agent will repeat identical mistakes. True continuity requires pairing high-level LLM synthesis with deterministic working-tree state.
During an active engineering session on an AI coding agent platform:
- Step Count: 226 steps
- Transcript Size on Disk: 408 KB
- Accumulated Tokens: ~119,400 tokens
At this scale, every user reply forces the model to re-ingest the entire history before outputting a response, burning quota, spiking Time To First Token (TTFT), and multiplying attention dilution risks. This is the concrete problem IPSF addresses.
AI coding environments SHOULD provide ambient, live feedback on the conversation's physical footprint.
Located on the status bar (adjacent to the model selector) or directly under assistant turns:
[ 🟢 34.2k tokens | Step 28 | Normal ]
[ 🟡 68.5k tokens | Step 84 | Caution ]
[ 🔴 119.4k tokens | Step 226 | Critical — Fork Recommended ]
Clicking the badge exposes a diagnostic breakdown complying with context-telemetry.schema.json:
CONTEXT METRICS
────────────────────────────────────────────
Total Active Tokens: 119,400
├── Input / History: 78,200
├── Tool Outputs: 32,400
└── System Prompt: 8,800
Steps Executed: 226
Session Age: 2h 45m
Touched Files: 18 files
Failed Shell Commands: 4 (Handled)
RECOMMENDATION:
⚠️ Attention Dilution Risk Elevated
✓ Recommendation: Trigger "Summarize & Fork"
Rather than hardcoded limits, ContextFork specifies configurable heuristic defaults via context-policy.schema.json. The following are reference defaults only — implementors SHOULD adjust these to their model and task characteristics:
{
"context_policy": {
"tokens": {
"warning_threshold": 50000,
"fork_recommended_threshold": 80000,
"hard_limit": null
},
"steps": {
"warning_threshold": 75,
"fork_recommended_threshold": 120
}
}
}| Token Range | Step Range | Risk Level | Indicator | Recommended Action |
|---|---|---|---|---|
< 50,000 |
< 75 |
Normal | 🟢 Green badge | Standard operating range. Baseline attention density. |
50,000 – 80,000 |
75 – 120 |
Caution | 🟡 Amber badge | Attention dilution risk elevated; avoid large log dumps. |
> 80,000 |
> 120 |
Critical | 🔴 Red badge + alert | High attention dilution risk. Session fork recommended. |
ContextFork transforms session restarts from a destructive wipe into an intelligent, verifiable checkpoint.
flowchart LR
A["Bloated Session (120k tokens)"] --> B["Click: '⚡ Summarize & Fork'"]
B --> C["Agent Generates 6-Part Handoff"]
B --> D["Git Diff & State Auto-Exported"]
C & D --> E["New Clean Session Auto-Launched"]
E --> F["Work Resumes with Architectural Continuity"]
When triggered, a structured synthesis is generated complying with session-handoff.schema.json:
# 🔄 Session Handoff Checkpoint (Forked from Session <ID>)
### 1. Active Goal & Scope
* Exact feature, bug, or architectural milestone being developed.
* Concrete acceptance criteria.
### 2. Settled Decisions, Tradeoffs & Evidence (Provenance)
* Accepted architectural choices and their rationale.
* Explicitly rejected alternatives (prevents re-debating).
* **Evidence:** File paths, commit hashes, or test results proving this decision
(e.g. `src/Auth/JwtService.cs`, Commit `7ed9b80`).
### 3. Working Tree State & Machine Git Metadata
* **Git Status:** HEAD commit, current branch, clean/dirty state.
* **Modified Files:** Exact files created, modified, or deleted (`git diff HEAD --stat`).
### 4. Failed Approaches & Known Pitfalls (⚡ Anti-Loop Shield)
* What was attempted, what failed, and why it was abandoned.
* **Barred Action:** Explicit instruction prohibiting the child agent from retrying
this failed approach.
### 5. Open Risks, Edge Cases & Unknowns
* Lingering technical risks, external dependencies, or unverified assumptions.
### 6. Immediate Next Action
* The single, atomic next command, test, or code edit to execute immediately.Why section 4 ("Failed Approaches") is the most critical:
Without it, a child agent has no record of dead ends. It will re-examine the same failed paths, wasting cycles and regressing. This section is the protocol's primary defense against repetitive failure loops.
A text-only LLM summary is vulnerable to omission or drift. Because git diff HEAD does NOT capture newly created, untracked files, ContextFork specifies a Verifiable Handoff Package complying with verifiable-package.schema.json persisted automatically on fork:
.contextfork/
├── handoff_summary.md # Synthesized 6-part markdown handoff (LLM intent)
├── git_status.json # Untracked, staged, and modified files (Machine truth)
├── git_diff.patch # Exact working-tree diff against parent HEAD (Staged + Unstaged)
├── untracked_manifest.json # Manifest of untracked files (path, size, sha256)
├── untracked/ # Snapshots of new/untracked text files (< 1MB)
└── session_metadata.json # Parent ID, token counts, step duration, full commit SHA
When the child session initializes, it reads the synthesized markdown for intent, while anchoring its physical perception in the deterministic diff, status, and untracked file snapshots.
Design Rationale: The hybrid model — LLM summary paired with machine-generated git artifacts — ensures that even if the summary is imprecise, the child agent can independently verify the actual state of the working tree.
ContextFork provides an official reference CLI written in pure Python 3.10+ standard library, demonstrating that the IPSF method is buildable with zero external dependencies.
Scope Note:
contextfork.pyis a reference implementation — its purpose is to demonstrate the protocol's feasibility and serve as a specification artifact, not to be a production-hardened tool. Independent implementations by IDE vendors and toolchain authors are explicitly encouraged.
# Show repository state and active .contextfork package info
python contextfork.py status
# Export a verifiable handoff package (diff, status, untracked files)
python contextfork.py export --session "session-123" --goal "Refactoring Auth Service"
# Validate package structure and integrity
python contextfork.py validate
# Run an interactive terminal demonstration
python contextfork.py demoThe handoff_summary.md is a structured template. In an AI-assisted workflow:
- Run
python contextfork.py exportto capture the machine state. - Ask the LLM: "Read
.contextfork/handoff_summary.mdand fill in sections 1–4 and 6 based on our session history." - The LLM fills the intent-level sections (Goal, Decisions, Failed Approaches, Next Action).
- Section 3 (Working Tree State) is pre-populated from
git_status.jsonby the export command. - Commit or copy
.contextfork/into the new session's context.
ContextFork provides formal JSON Schemas for tool authors and IDE vendors to implement interoperable context lifecycle management:
| Schema File | Purpose |
|---|---|
session-handoff.schema.json |
Validates the 6-part handoff summary with evidence and provenance fields. |
context-policy.schema.json |
Defines configurable warning/fork token thresholds and step heuristics. |
context-telemetry.schema.json |
Validates the ambient context telemetry payload emitted to IDE UI. |
verifiable-package.schema.json |
Validates the structure and file manifests of the .contextfork/ bundle. |
ContextFork operates within a unified three-tier Agent Context & Efficiency Stack:
┌────────────────────────────────────────────────────────┐
│ AGENT CONTEXT & EFFICIENCY STACK │
└────────────────────────────────────────────────────────┘
│
┌─────────────────────────────────┼─────────────────────────────────┐
▼ ▼ ▼
[ RETRIEVE ] [ MANAGE ] [ TRANSFER ]
git-grep-first ContextFold ContextFork
(Search Policy) (Virtual Memory Paging) (Session Handoff & Shaping)
• Zero token bloat • In-place folding • 6-part verifiable handoff
• git grep --untracked • UI side-drawers • Evidence & Git state
• Anti-Select-String • On-demand hydration • Multi-agent context shaping
Beyond temporal continuity (Session A → Session B), ContextFork enables role-based context shaping: filtering the parent session's context into specialized slices for subagents (Planner, Coder, Tester), so each agent receives only the context relevant to its role.
ContextFork includes an official reference integration for the Model Context Protocol (MCP) (examples/mcp-integration/contextfork_mcp.py), allowing autonomous agents in Claude Desktop, Cursor, Antigravity, and other MCP-compliant hosts to autonomously inspect context telemetry, trigger verifiable checkpoints, and resume continuation sessions.
| Tool Name | Type | Description |
|---|---|---|
get_context_status(workspace_path) |
Read-only | Returns Git repository state (HEAD, branch, dirty tree) and presence of a .contextfork package. |
export_session_context(goal, ...) |
Mutation | Generates the deterministic .contextfork/ package and validates it against the IPSF-1.2 schema. |
validate_session_context(workspace_path) |
Read-only | Validates package manifest integrity, diff applicability, and SHA-256 hashes of untracked files. |
resume_session_context(package_id, ...) |
Mutation | Resumes active development, verifies Git drift, loads past decisions, and marks package as consumed with UTC timestamp and session ID. |
get_package_details(workspace_path) |
Read-only | Returns structured Markdown table of all archived snapshots with consumed state and commit hashes. |
clean_session_context(confirm, ...) |
Mutation | Cleans old consumed snapshot packages with dry-run safety and explicit confirmation. |
read_handoff_summary(package_id) |
Read-only | Reads handoff_summary.md from active or specified snapshot package with zero-pending safety. |
- Core Engine (
contextfork.py): Requires Python 3.10+ and zero external dependencies (pure Python standard library). - MCP Server (
contextfork_mcp.py): Requires the official Python MCP SDK:pip install mcp
Add to your claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"contextfork": {
"command": "python",
"args": [
"/absolute/path/to/ContextFork/examples/mcp-integration/contextfork_mcp.py"
],
"env": {
"PYTHONIOENCODING": "utf-8",
"CONTEXTFORK_ALLOWED_ROOTS": "/absolute/path/to/my-project;/absolute/path/to/ContextFork"
}
}
}
}- Name:
contextfork - Type:
command - Command:
python /absolute/path/to/ContextFork/examples/mcp-integration/contextfork_mcp.py
In your user or workspace mcp_config.json:
{
"mcpServers": {
"contextfork": {
"command": "python",
"args": [
"/absolute/path/to/ContextFork/examples/mcp-integration/contextfork_mcp.py"
],
"env": {
"PYTHONIOENCODING": "utf-8",
"CONTEXTFORK_HOST": "antigravity",
"CONTEXTFORK_ALLOWED_ROOTS": "/absolute/path/to/my-project;/absolute/path/to/ContextFork"
}
}
}
}Host Signal Isolation: Notice that
CONTEXTFORK_HOSTis omitted for Claude Desktop and Cursor. It is set to"antigravity"only when running under Google Antigravity to enable local SQLite conversation summary resolution. Omission ensures strict host isolation.
ContextFork enforces the ZF-026 Allowed Roots Contract:
- Define allowed workspace directories separated by semicolons (
;). - Fail-Closed: All configured paths MUST be absolute existing directories. Relative paths, directory traversal (
..), UNC network paths (\\server\share), junction/symlink links, drive roots (C:\), and user home directories are strictly rejected. - If any entry is invalid, the entire environment variable is rejected to prevent silent security bypasses. See SECURITY.md for full policy details.
Note on Deployment Automation:
scripts/deploy_skill.pyis provided as an environment-specific deployment example tailored for Google Antigravity's schema cache and FastMCP manager. The current test suite and deployment scripts are Windows-oriented. Universal multi-client deployment is tracked in the Roadmap below.
The specification is designed for modular adoption across multiple developer interface layers:
- IDE Platforms (Antigravity, Cursor, Windsurf):
- Ambient status-bar badge for live context telemetry.
- Toolbar action replacing destructive "New Chat" with "Fork Chat with Checkpoint".
- Drawer panel showing verifiable
.contextfork/artifacts.
- CLI & Terminal Tools (Claude Code, Antigravity CLI, Aider):
- Native
/forkor--forkcommands to seed a clean child session from the current state.
- Native
- Agent Orchestration Frameworks (LangChain, AutoGen, CrewAI):
- Context lifecycle middleware and session state provider for subagent context shaping.
🎨 Concept mockup — not a screenshot. This image illustrates the target IDE integration described in §10 Integration Surfaces. No graphical implementation exists yet —
contextfork.pyis a terminal-only reference CLI (see §6 Reference Implementation). The UI shown here is a design goal, not a working feature.
ContextFork is not the first work in session continuity and context management. This section clarifies what the protocol adds:
| Prior Work | What it does | What IPSF adds |
|---|---|---|
Claude Code /compact |
Summarizes the session in-place, replacing old messages | IPSF generates an external, machine-verifiable package; the parent session is preserved and tagged, not destructively modified |
| Amp Handoff | Structured handoff between sessions | IPSF adds the failed_approaches Anti-Loop Shield, provenance-linked evidence, and untracked file capture via the Verifiable Package |
| MemGPT / Letta | Agent memory with hierarchical paging (main context + archival memory) | IPSF focuses on session transfer rather than runtime memory management; ContextFold (a sibling spec) covers in-session virtual memory paging |
| LangGraph Checkpoints | Deterministic graph state snapshots for resumability | IPSF is LLM-native and IDE-level; it captures intent (handoff markdown) alongside state (git artifacts), targeting developer workflow rather than agent graph internals |
git stash / git bundle |
Git-native state preservation | IPSF orchestrates git artifacts at the session protocol level, pairing them with structured LLM-generated summaries the child agent can read directly |
The IPSF contribution: The combination of (1) structured 6-part schema with explicit failed_approaches, (2) provenance-linked evidence, (3) untracked file capture filling the git diff HEAD gap, and (4) a vendor-neutral open schema enabling cross-platform implementation.
The following capabilities are actively planned for upcoming releases:
- Automated Handoff Template Validator & Telemetry: Machine verification of
handoff_summary.mdsections to detect unfilled template placeholders and track lifecycle events. - Universal Cross-Client Deployment Automation: Generalized CLI and open schema for deploying ContextFork skills and MCP configurations across Claude Desktop, Cursor, Windsurf, and Antigravity.
- Atomic Target Deployment Integrity: Content-hash verification, deploy manifest tracking, and atomic rollback protections for target client binary installations.
- Content-Hash Promotion Gate: SHA-256 content-hash comparison and verification of tested sandbox builds prior to developer tier promotion.
- Dedicated Testing Fixtures: Isolated reproducible test environments and mock session fixtures for automated verification without modifying local configurations.
- Cross-Platform Test Suite Matrix: Continuous integration testing expanded across Linux and macOS host environments.
ContextFork maintains a comprehensive security architecture (including ZF-006 through ZF-026 zero-fault constraints). To report vulnerabilities or review our defense-in-depth model, please consult SECURITY.md.
Released under the MIT License.
@misc{kilinc2026contextfork,
author = {Mustafa KILINC (@mrblackman)},
title = {ContextFork: In-Place Session Forking Protocol (IPSF-1.2)},
year = {2026},
publisher = {GitHub},
howpublished = {\url{https://github.com/mrblackman/ContextFork}}
}