Compact

How it works

The /add-compact skill adds a /compact session command that compacts your agent’s conversation history. Long-running sessions accumulate context that degrades the agent’s performance over time — a problem sometimes called “context rot.” Compacting summarizes the conversation so the agent retains the key information without the noise.

The skill works by forwarding the /compact command to the Claude Agent SDK’s built-in slash command handler. This means the compaction is done by the SDK itself, not by a synthetic system prompt or custom summarization. The SDK returns a new session ID after compaction, which the agent-runner forwards to the orchestrator. The session continues seamlessly — no destructive reset occurs.

Before compaction runs, the existing PreCompact hook archives the full transcript to the group’s conversations/ directory. This means you never lose the original conversation — it’s preserved on disk even after the agent’s working context is compressed.

Security

The /compact command is restricted to trusted senders only. In the main group (your private self-chat), any message is trusted. In other groups, only the device owner (is_from_me) can trigger compaction. If an untrusted user in a group sends /compact, they get a denial message and no compaction occurs.

This matters because compaction changes what the agent remembers. A careless or malicious user in a shared group could wipe the agent’s short-term memory if compaction were unrestricted.

Behavior in message batches

If /compact arrives alongside other messages in the same polling batch, the skill handles ordering carefully:

• Messages that arrived before /compact are sent to the agent first and processed normally.
• Compaction runs after those pre-compact messages are handled.
• Messages that arrived after /compact in the batch are preserved and processed on the next poll cycle.

This ensures no messages are silently dropped when compaction happens mid-batch.

What this does not do

• No automatic compaction. This is manual-only — you send /compact when you want it. Automatic threshold-based compaction is a separate concern.
• No /clear command. Clearing is a destructive reset with different semantics. /compact preserves summarized context; /clear would wipe it entirely.
• No cross-group compaction. Each group’s session is isolated. Compacting one group’s session has no effect on another.

Tips

• Use /compact when you notice your agent’s responses becoming less coherent or when it starts forgetting earlier parts of the conversation.
• The archived transcript in conversations/ is a plain text file. You can review it anytime to see what the agent’s context looked like before compaction.
• If the agent reports that compact_boundary was not observed, compaction may still have succeeded — not all SDK versions emit this event. Check the agent’s subsequent responses to verify it’s working with fresh context.