--- name: Add Compact Command slug: add-compact-command category: AI Engineering description: Add Compact Command adds a /compact session command to manually compact conversation history in long-running Claude sessions. Use it to reduce context rot while keeping the same logical session and honoring main-group or trusted-sender access rules. github: "https://github.com/sbusso/claudeclaw/tree/main/skills/add-compact" language: TypeScript stars: 193 forks: 60 install: "npx degit https://github.com/sbusso/claudeclaw/tree/main/skills/add-compact ~/.claude/skills/add-compact" installs_to: ~/.claude/skills/add-compact source_path: skills/add-compact/SKILL.md collection_size: 25 category_size: 3278 collection_url: "https://dirskills.com/collections/sbusso/claudeclaw" added: 2026-09-06T05:18:59.272Z last_synced: 2026-09-06T05:18:59.272Z canonical_url: "https://dirskills.com/skills/add-compact-command" --- # Add Compact Command Add Compact Command adds a /compact session command to manually compact conversation history in long-running Claude sessions. Use it to reduce context rot while keeping the same logical session and honoring main-group or trusted-sender access rules. **Install:** ```bash npx degit https://github.com/sbusso/claudeclaw/tree/main/skills/add-compact ~/.claude/skills/add-compact ``` ## README # Add /compact Command Adds a `/compact` session command that compacts conversation history to fight context rot in long-running sessions. Uses the Claude Agent SDK's built-in `/compact` slash command — no synthetic system prompts. **Session contract:** `/compact` keeps the same logical session alive. The SDK returns a new session ID after compaction (via the `init` system message), which the agent-runner forwards to the orchestrator as `newSessionId`. No destructive reset occurs — the agent retains summarized context. ## Phase 1: Pre-flight Check if `src/session-commands.ts` exists: ```bash test -f src/session-commands.ts && echo "Already applied" || echo "Not applied" ``` If already applied, skip to Phase 3 (Verify). ## Phase 2: Apply Code Changes Merge the skill branch: ```bash git fetch upstream skill/compact git merge upstream/skill/compact ``` > **Note:** `upstream` is the remote pointing to `sbusso/claudeclaw`. If using a different remote name, substitute accordingly. This adds: - `src/session-commands.ts` (extract and authorize session commands) - `src/session-commands.test.ts` (unit tests for command parsing and auth) - Session command interception in `src/index.ts` (both `processGroupMessages` and `startMessageLoop`) - Slash command handling in `agent/runner/src/index.ts` ### Validate ```bash npm test npm run build ``` ### Rebuild container ```bash ./src/runtimes/docker/build.sh ``` > **Service name:** Derived from the directory name: `com.claudeclaw.` (macOS) / `claudeclaw-` (Linux). For example, if cwd is `my-assistant`, the service is `com.claudeclaw.my-assistant`. Determine the correct service name before running service commands below. ### Restart service ```bash launchctl kickstart -k gui/$(id -u)/com.claudeclaw # macOS # Linux: systemctl --user restart claudeclaw ``` ## Phase 3: Verify ### Integration Test 1. Start ClaudeClaw in dev mode: `npm run dev` 2. From the **main group** (self-chat), send exactly: `/compact` 3. Verify: - The agent acknowledges compaction (e.g., "Conversation compacted.") - The session continues — send a follow-up message and verify the agent responds coherently - A conversation archive is written to `groups/{folder}/conversations/` (by the PreCompact hook) - Container logs show `Compact boundary observed` (confirms SDK actually compacted) - If `compact_boundary` was NOT observed, the response says "compact_boundary was not observed" 4. From a **non-main group** as a non-admin user, send: `@ /compact` 5. Verify: - The bot responds with "Session commands require admin access." - No compaction occurs, no container is spawned for the command 6. From a **non-main group** as the admin (device owner / `is_from_me`), send: `@ /compact` 7. Verify: - Compaction proceeds normally (same behavior as main group) 8. While an **active container** is running for the main group, send `/compact` 9. Verify: - The active container is signaled to close (authorized senders only — untrusted senders cannot kill in-flight work) - Compaction proceeds via a new container once the active one exits - The command is not dropped (no cursor race) 10. Send a normal message, then `/compact`, then another normal message in quick succession (same polling batch): 11. Verify: - Pre-compact messages are sent to the agent first (check container logs for two `runAgent` calls) - Compaction proceeds after pre-compact messages are processed - Messages **after** `/compact` in the batch are preserved (cursor advances to `/compact`'s timestamp only) and processed on the next poll cycle 12. From a **non-main group** as a non-admin user, send `@ /compact`: 13. Verify: - Denial message is sent ("Session commands require admin access.") - The `/compact` is consumed (cursor advanced) — it does NOT replay on future polls - Other messages in the same batch are also consumed (cursor is a high-water mark — this is an accepted tradeoff for the narrow edge case of denied `/compact` + other messages in the same polling interval) - No container is killed or interrupted 14. From a **non-main group** (with `requiresTrigger` enabled) as a non-admin user, send bare `/compact` (no trigger prefix): 15. Verify: - No denial message is sent (trigger policy prevents untrusted bot responses) - The `/compact` is consumed silently - Note: in groups where `requiresTrigger` is `false`, a denial message IS sent because the sender is considered reachable 16. After compaction, verify **no auto-compaction** behavior — only manual `/compact` triggers it ### Validation on Fresh Clone ```bash git clone /tmp/claudeclaw-test cd /tmp/claudeclaw-test claude # then run /add-compact npm run build npm test ./src/runtimes/docker/build.sh # Manual: send /compact from main group, verify compaction + continuation # Manual: send @ /compact from non-main as non-admin, verify denial # Manual: send @ /compact from non-main as admin, verify allowed # Manual: verify no auto-compaction behavior ``` ## Security Constraints - **Main-group or trusted/admin sender only.** The main group is the user's private self-chat and is trusted (see `docs/SECURITY.md`). Non-main groups are untrusted — a careless or malicious user could wipe the agent's short-term memory. However, the device owner (`is_from_me`) is always trusted and can compact from any group. - **No auto-compaction.** This skill implements manual compaction only. Automatic threshold-based compaction is a separate concern and should be a separate skill. - **No config file.** ClaudeClaw's philosophy is customization through code changes, not configuration sprawl. - **Transcript archived before compaction.** The existing `PreCompact` hook in the agent-runner archives the full transcript to `conversations/` before the SDK compacts it. - **Session continues after compaction.** This is not a destructive reset. The conversation continues with summarized context. ## What This Does NOT Do - No automatic compaction threshold (add separately if desired) - No `/clear` command (separate skill, separate semantics — `/clear` is a destructive reset) - No cross-group compaction (each group's session is isolated) - No changes to the container image, Dockerfile, or build script ## Troubleshooting - **"Session commands require admin access"**: Only the device owner (`is_from_me`) or main-group senders can use `/compact`. Other users are denied. - **No compact_boundary in logs**: The SDK may not emit this event in all versions. Check the agent-runner logs for the warning message. Compaction may still have succeeded. - **Pre-compact failure**: If messages before `/compact` fail to process, the error message says "Failed to process messages before /compact." The cursor advances past sent output to prevent duplicates; `/compact` remains pending for the next attempt.