Who magic-compact is for#
Developers running long debugging sessions in Claude Code
A multi-hour debugging session in Claude Code accumulates hundreds of tool calls, file reads, and iterative test runs. When the context window fills, built-in compaction discards the session structure and the agent loses the debugging trail. Magic Compact preserves the investigation thread by summarizing old turns individually while caching pruned outputs for retrieval.
Skip if:
Skip if your sessions are short enough to avoid hitting context limits, or if Claude Code's built-in compaction produces enough context fidelity for your workflow. Magic Compact requires a manual command and a session switch after compacting.
OpenCode users managing multi-step agentic workflows
Long agentic workflows in OpenCode benefit from the full feature set: in-place compaction, /magic-trim for lightweight pruning, and /magic-stats for tracking token savings over a session. Users who run continuous OpenCode sessions across complex coding tasks get both context reduction and visibility into the efficiency gains.
Skip if:
Skip if you use Claude Code rather than OpenCode and need in-place compaction or /magic-stats. Those features require the OpenCode plugin API, which Claude Code does not expose.
AI engineers iterating on agent prompts and tool configurations
Iterating on prompt engineering or agent tool configurations generates repetitive tool I/O that clutters the context without adding value. /magic-trim (OpenCode) prunes historical tool output without touching assistant reasoning or user messages, keeping the iteration history visible while cutting the noise from completed calls.
Skip if:
Skip if you need a persistent long-term memory system across sessions rather than in-session context compression. Magic Compact compresses within a session; it does not maintain project memory across separate sessions.
The problem it solves#
Claude Code and OpenCode both include built-in compaction, but their default approach collapses the entire session into a single summary block using a fixed template: Goal, Progress, Key Decisions, and similar categories. An agent that wakes up from this summary has lost the conversation structure: the specific files edited, the reasoning behind a design choice, what a tool call actually returned, and what work remains. For long, complex tasks, a one-paragraph recap leaves the agent reconstructing context from an abstraction that captured a fraction of what mattered.
The second challenge is tool call accumulation. File reads, bash outputs, and task results grow large quickly in any non-trivial agentic workflow. Built-in compaction discards all of this alongside the session narrative. When the agent later needs a file it already read or a command output it already saw, it must redo the work, which burns tokens that compaction was supposed to save.
How it solves it#
Per-turn summarization
Instead of one summary blob for the whole session, Magic Compact replaces each old assistant turn with its own high-fidelity summary. User messages stay verbatim, and tool call structure is preserved. The agent retains a chronological record of what it did and why, rather than a flattened recap that discards the decision trail.
On-demand tool output retrieval
Tool outputs over 128 words or 1024 characters are replaced with an omission notice during compaction. Each notice includes a Content ID (such as omitted-001). The agent calls the read_omitted_content tool with that ID to fetch the original output when it needs stale information that cannot be reproduced with a fresh tool call. Nothing is permanently discarded.
Verbatim user message preservation
Every user message from the original session stays in the compacted context word for word. Requirements, instructions, and corrections remain visible to the agent as written, not paraphrased through a summary layer. This keeps the agent aligned with the original task specification even after heavy compaction.
Backup session before compaction
Running /magic-compact creates a backup of the current session before modifying anything. If compaction fails or produces an unsatisfactory result, the original session remains intact. For Claude Code, compaction produces a new destination session rather than modifying in place; OpenCode compacts in place.
/magic-trim for targeted tool I/O pruning
OpenCode users can run /magic-trim [N] to prune tool I/O from historical turns without summarizing or deleting any assistant or user content. This reduces token count without creating a compaction boundary or calling an LLM, making it faster and cheaper than a full compaction pass. N specifies how many recent turns to leave untouched.
/magic-stats token savings tracking
OpenCode users run /magic-stats to view cumulative token savings for the current conversation: tokens pruned, cached tokens saved, and an estimated cost reduction. This gives concrete visibility into the efficiency gain from compaction and trim operations over a session's lifetime. Not available for Claude Code.
Strengths and trade-offs#
Strengths
- BSD-3-Clause license with no usage restrictionsMagic Compact is BSD-3-Clause licensed, which permits use, modification, and distribution for commercial and team projects with no restrictions beyond attribution. There is no paid tier, managed service requirement, or per-seat fee. The plugin installs locally and runs entirely within the user's existing Claude Code or OpenCode environment.
- Zero configuration, one command to compactCompaction runs on demand with a single /magic-compact command. There is no background process, no always-on memory system, and no recurring prompt injection consuming tokens between turns. The plugin does one job when asked and stays out of the way the rest of the time.
- No cache churn between turnsBecause compaction happens once at the user's request rather than continuously, the token cache stays stable after a compaction run. Context management systems that inject summaries or rewrite context on every turn repeatedly invalidate the cache. Magic Compact avoids that overhead by running once and then staying stable.
- Tool call history survives compactionPruned tool outputs are cached with Content IDs and retrievable via read_omitted_content. This preserves access to past work even after aggressive pruning, unlike built-in compaction which discards tool outputs without a retrieval path. The cache is created during the compaction pass and persists for the session.
Trade-offs
- -Development paused; successor project is Operator MemoryThe README states that Magic Compact development has paused in favor of Operator Memory, its successor project. Magic Compact is described as fully functional and remains installable, but new context-management features are being built into Operator Memory instead. Users who want ongoing development should follow the successor project at github.com/aerovato/operator-memory.
- -Claude Code compacts to a new session, not in placeClaude Code does not expose the plugin API needed to modify the current session's transcript, so Magic Compact creates a new compacted destination session instead of modifying in place. After compaction, you must run /resume <new-session-id> to enter the compacted session. OpenCode does not have this limitation.
- -/magic-trim and /magic-stats are OpenCode onlyThe targeted trim command (/magic-trim) and token savings statistics (/magic-stats) are not available for Claude Code due to plugin API limitations. Claude Code users only get /magic-compact. Users who want the full feature set need to use OpenCode.
magic-compact vs alternatives#
Magic Compact vs Claude Code Native Compaction
Claude Code ships with context compaction as part of the Anthropic commercial subscription. Both approaches target the same problem: context windows fill up during long agentic sessions and the model needs to continue working with reduced context.
| Feature | Magic Compact | Claude Code Native |
|---|---|---|
| License | BSD-3-Clause | Proprietary |
| Summarization style | Per-turn, individual summaries | Whole-session, single blob |
| User message handling | Preserved verbatim | Included in summary |
| Tool output retrieval | Cached with Content IDs, retrievable | Discarded |
| In-place compaction | OpenCode only | Yes |
| Installation required | Yes (plugin) | No (built-in) |
Magic Compact is the better choice when session structure carries forward value. Debugging workflows, iterative refactors, and multi-step agentic tasks all benefit from per-turn summarization: the agent retains what it did in each step and can retrieve pruned tool outputs without rerunning them.
Claude Code's native compaction is the right choice for users who occasionally hit context limits on shorter, simpler sessions. It requires no installation, fires automatically, and produces a serviceable summary for tasks that do not depend on detailed historical context. For users already paying for a Claude subscription, the built-in compaction adds no complexity.
What it's built on#
- Languages
- JavaScriptTypeScript
FAQ#
Is Magic Compact still being maintained?
Magic Compact is fully functional, but the README states that active development has paused in favor of Operator Memory, its successor project. Operator Memory provides durable memory and documentation and will gain context-management features over time. Magic Compact remains installable and works as documented, but new features will not be added here.
Does Magic Compact work with both Claude Code and OpenCode?
Yes, Magic Compact supports both, but with different feature sets. OpenCode gets in-place compaction, /magic-trim for targeted pruning, and /magic-stats for token savings tracking. Claude Code compacts to a new destination session rather than in place due to API limitations, and /magic-trim and /magic-stats are not available for Claude Code.
What happens to tool outputs that get pruned during compaction?
Pruned tool outputs are cached with a Content ID (for example, omitted-001). The agent can call the read_omitted_content tool with that ID to retrieve the original output on demand. Omission notices in the conversation transcript reference these IDs, so the agent knows what was pruned and how to fetch it. Nothing is permanently deleted during a compaction run.
How does Magic Compact differ from Claude Code's built-in compaction?
Built-in compaction collapses the entire session into a single summary using a fixed template. Magic Compact replaces each old assistant turn with its own per-turn summary while keeping user messages verbatim and tool call structure intact. Pruned tool outputs remain retrievable via the read_omitted_content tool. The built-in approach requires no extra installation; Magic Compact offers more structural fidelity for long or complex sessions.
What license does Magic Compact use?
Magic Compact is BSD-3-Clause licensed. This permits use, modification, and redistribution for any purpose, including commercial and team use, with no restrictions beyond attribution. There is no managed-service restriction or usage fee.
Similar open-source tools#
teamai-cli
Git-backed AI config sync for engineering teams
no_human
From ticket to reviewed pull request, on your machine.
FckSignups
Open-source tools that work instantly, no signup required
FreeFlow
Free, open source Mac dictation with AI cleanup and voice macros
patent-disclosure-skill
Chinese patent disclosure drafting with AI-powered point mining
guaardvark
Self-hosted AI workstation with agents, video, voice, and RAG.