AI Session Compaction: Cross-Harness Audit Guide
Compare how Claude Code, Codex, Gemini CLI, and other AI coding tools compact sessions, see what survives, and run a practical audit before your next handover.
AI Session Compaction: Cross-Harness Audit Guide
What Happens to Your AI Coding Session When Context Gets Compacted?
An AI coding session holds more than just the current prompt. It can include decisions you made, unfinished tasks, project conventions, tool output, and those little details you haven't committed to the repo yet. At some point, many coding assistants compact that context to make room for new work. What that means in practice depends on the tool - and that's where handovers can quietly fail.
A summary might keep the broad goal but drop a file path, a constraint, or a key distinction. A rule file might be reloaded in one harness and ignored in another. Even the sign that compaction happened can look different depending on which tool you're using.
Version 0.5 of session-handover addresses this with a cross-harness compaction matrix. It lays out what triggers compaction, how it's performed, what tends to survive, what can get lost, and where to pin durable context ahead of time. This guide explains what the matrix covers, how to run it, and how to use it without treating a heuristic audit like a guarantee.
Why compaction behavior matters across AI coding tools
Compaction is a context-management step: when a conversation grows too large for the active window, a tool reduces or replaces part of the working context so the session can continue. The implementation isn't consistent. Different harnesses can use different triggers, different summaries, different sets of retained messages, and different ways of loading project instructions.
This matters most when you move work between tools, or when you come back to a session after a long break. You might think you're picking up the same task, but the next harness doesn't necessarily inherit the same state. One tool might reload a root-level instruction file from disk; another might keep your user messages while replacing earlier assistant turns; a third might treat committed project files as the durable reference.
It's also easy to assume compaction is "just a summary." In reality, it's a boundary between two working contexts. The new context might preserve the objective, but not every condition that made the old approach safe. A migration note, a test result, a decision not to touch a particular file, or a warning about generated code can outweigh several paragraphs of general summary.
Why a summary is not the same as durable state
A summary helps with continuity, but it's still a representation of what came before. It isn't guaranteed to be complete, and it may not be re-injected the same way across tools. Durable state is information you deliberately store somewhere the next session can retrieve - like a repository instruction file or a handover note.
This distinction matters a lot for teams that use more than one coding assistant. If an instruction only exists in the live conversation, switching harnesses can make it disappear. If you write it to a file the next harness reads, it's more likely to survive - but file discovery and instruction loading still depend on how that tool is configured.
A tool-by-tool example
The v0.5 report describes a few patterns. In Claude Code, the project-root CLAUDE.md is re-injected from disk; the report cites eight of eight measured compactions in a study by rulestack. By contrast, path-scoped rules and nested CLAUDE.md files can be lost until the tool reads the matching file again. The report also notes that invoked skill bodies returned in six of eight measured cases, sometimes with stale text after an edit.
Codex CLI behaves differently. Its remote v2 compaction returns an encrypted blob along with retained user messages. The local fallback drops all assistant messages and puts the summary into a user message marked CONTEXT CHECKPOINT. Reasoning items are filtered before summarization, and the compaction prompt has been configurable since v0.50.
These details aren't interchangeable. A workflow that assumes an assistant message will remain in the transcript may behave differently under the local fallback than under remote compaction. That's the point of the matrix: make those differences visible before you rely on them.
What the session-handover matrix compares
The compact-matrix command is meant to answer a practical question: if this harness compacts a session, where should important state live before that happens? It compares the trigger, the mechanism, what survives, what might get dropped, and a durable anchor for each harness.
A durable anchor is the location the report recommends for preserving relevant state. It isn't a promise that a harness will always read the file, or that every instruction will be followed. Think of it as a concrete place to check - rather than assuming conversational context will still be there.
Harnesses and anchors in v0.5
The matrix covers Claude Code, Codex CLI, Gemini CLI, Aider, OpenCode, Copilot CLI, Cursor, and Cline. The documented anchors include:
CLAUDE.mdfor Claude CodeGEMINI.mdfor Gemini CLI- Committed files for Aider
AGENTS.mdfor OpenCodecopilot-instructions.mdfor Copilot CLI.cursor/rulesfor Cursor.clinerulesfor Cline
The source description doesn't spell out an anchor for every listed tool to the same level of detail, so check the matrix directly instead of guessing. A filename is only useful if the tool recognizes it, and if it's actually relevant to the work you're doing.
Use the matrix to ask better questions
The value isn't just knowing a tool has a /compact command. For a real handover, ask:
- What causes the boundary? Is compaction manual, automatic, or both?
- What replaces the old context? Is there a summary, a checkpoint message, a retained-message set, or something else?
- Which information is retained or excluded? Compare what happens to user messages, assistant messages, tool output, and project instructions.
- Where should state be pinned? Decide where the next session should look before the context gets tight.
- How strong is the evidence? Separate documented or measured behavior from community-reported behavior.
This turns a product comparison into a workflow check. Tool design is only one part of reliability; your repo conventions and handover habits matter too.
How to run the v0.5 audit
The package is available from PyPI and has no third-party dependencies. Install it with:
pip install session-handoverThen print the cross-harness comparison:
session-handover compact-matrixTo save a Markdown report you can review or share, use:
session-handover compact-matrix --out MATRIX.mdTo compare two harnesses side by side, use --compare:
session-handover compact-matrix --compare claude-code codex-cliTo inspect one harness, use --harness:
session-handover compact-matrix --harness codex-cliThe matrix is most useful when you treat it as input to a project decision. For example, a team standardizing on a handover file can check which harnesses load which repository instructions, then choose an anchor that matches the tools you actually use. If one anchor won't cover everything, consider a small shared handover document plus harness-specific instruction files.
A workable pre-compaction checklist
Before a long session gets compacted - or before handing it to another tool - write down what the next session needs to act safely:
- Current objective: What's being changed, and what's explicitly out of scope?
- Progress: Which files changed, which checks ran, and what's still unfinished?
- Decisions: What approach was chosen, and what alternatives were ruled out?
- Constraints: Which compatibility, security, product, or client requirements must hold?
- Open questions: What needs verification instead of guesswork?
- Durable location: Which repository file or instruction anchor should contain this information?
Keep the note operational. "Continue improving the API" is too vague to be a useful handover. "The endpoint is implemented; run the integration test for pagination, then check whether the existing response shape must stay backward-compatible" gives the next session a concrete sequence and a real constraint to verify.
How much detail you need depends on how expensive it is to get wrong. A small refactor might only need current status and the test command. A production migration or anything security-sensitive needs explicit assumptions, rollback considerations, and verification steps.
What the Codex audit changes
Version 0.5 also improves audit-compact, the command that detects compaction boundaries. Earlier detection relied on bare marker strings. The updated audit recognizes several actual checkpoint shapes described for Codex:
- The remote v1
CONTEXT CHECKPOINTassistant message - The local fallback prefix, "another language model started to solve this problem..."
- Response items with
type=compaction
A lone /compact command line is treated as a trigger, not proof that a replacement boundary actually happened. That distinction keeps the audit from inventing a compaction event just because a user typed the command. It's a small implementation detail with a practical effect: the audit only helps if it identifies the event that truly changed context, not an instruction that might cause compaction.
What the audit can and cannot establish
The project describes extraction as a heuristic recall floor, and matching as token overlap, not semantic analysis. In plain terms, it tries to identify items and compare their text using a relatively simple signal. It may miss information that gets expressed differently after summarization, and overlapping words don't prove that meaning was preserved.
That's why the audit should support review, not replace it. If an item matters, inspect the source and the resulting checkpoint yourself. Don't treat a successful match as proof that intent, qualification, or operational consequence survived intact.
The tool also isn't designed to block by default: the audit exits with status 0. In CI, you can use --fail-on-drop if you want detected drops to fail the job. That's useful for surfacing omissions, but it doesn't magically turn heuristic detection into semantic verification. Use it if the signal helps your process; don't wire it into a release gate without understanding what it's actually measuring.
Limitations and a practical handover workflow
The matrix is an evolving audit, not a formal specification for every harness. The project labels some entries as "community": those are widely reported, but not formally verified. That should change how you weigh the results. Treat measured behavior, official documented behavior, and community-reported behavior as different levels of confidence.
Tool behavior can also shift across versions and configurations. Codex's configurable compaction prompt is one example of why a single description might not match every setup. Before standardizing a process, verify the behavior with the exact harness versions and settings your team uses.
Even with that, a lightweight workflow can give real protection:
- Pick the critical state. Identify decisions, constraints, and unfinished work that would be expensive to reconstruct.
- Write it to a durable anchor. Use a repo file or instruction location the next harness will read.
- Check the matrix. Confirm how the tool handles compaction and where it expects durable instructions.
- Run the audit where it helps. Use the report to spot likely losses, not to certify semantic equivalence.
- Verify after handover. Ask the receiving session to restate the task, constraints, and next action. Fix gaps before it edits files.
Process has a cost. If every tiny change requires a long handover document, the documentation burden can outweigh the risk reduction. Scale the procedure to the impact. For routine tasks, a short status note may be enough. For work spanning tools, people, or a production release, preserving assumptions and verification steps is usually worth it.
The project frames itself as a lightweight CLI focused on the compaction-diff boundary, not a spec-first workflow. Its author describes SpecWeave as covering heavier process needs. That split makes sense: a focused audit tool should answer a narrow operational question without trying to manage every part of software delivery.
Conclusion
Compaction isn't consistent across AI coding tools. The mechanism, retained context, and instruction files differ - so a handover that works in one harness can still lose important details in another. session-handover v0.5 makes those differences easier to inspect and improves Codex checkpoint detection.
Start with the matrix, identify the durable anchor for the tools you actually use, and capture critical decisions before you hand anything over. Then verify what the next session understood. The audit can reduce blind spots, but it can't guarantee every nuance survived.
Install the package and generate a report with session-handover compact-matrix --out MATRIX.md. For the original release details, see the v0.5 announcement.