/add-compact

name: add-compact
description: Add /compact command for manual context compaction. Solves context rot in long sessions by forwarding the SDK's built-in /compact slash command. Main-group or trusted sender only.

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:

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:

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

npm test
npm run build

Rebuild container

./src/runtimes/docker/build.sh

> **Service name:** Derived from the directory name: `com.claudeclaw.<dirname>` (macOS) / `claudeclaw-<dirname>` (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

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: `@<assistant> /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: `@<assistant> /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 `@<assistant> /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

git clone <your-fork> /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 @<assistant> /compact from non-main as non-admin, verify denial
# Manual: send @<assistant> /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 comp