Claudeclaw add-compact

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.

install

source · Clone the upstream repo

git clone https://github.com/sbusso/claudeclaw

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/sbusso/claudeclaw "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/add-compact" ~/.claude/skills/sbusso-claudeclaw-add-compact && rm -rf "$T"

manifest: skills/add-compact/SKILL.md

source content

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

Start ClaudeClaw in dev mode:
```
npm run dev
```
From the main group (self-chat), send exactly:
```
/compact
```
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"
From a non-main group as a non-admin user, send:
```
@<assistant> /compact
```
Verify:
- The bot responds with "Session commands require admin access."
- No compaction occurs, no container is spawned for the command
From a non-main group as the admin (device owner /
```
is_from_me
```
), send:
```
@<assistant> /compact
```
Verify:
- Compaction proceeds normally (same behavior as main group)
While an active container is running for the main group, send
```
/compact
```
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)
Send a normal message, then
```
/compact
```
, then another normal message in quick succession (same polling batch):
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
From a non-main group as a non-admin user, send
```
@<assistant> /compact
```
:
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
From a non-main group (with
```
requiresTrigger
```
enabled) as a non-admin user, send bare
```
/compact
```
(no trigger prefix):
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
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 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.