compact-plus

compact-plus

Japanese README | Architecture

A transparent Claude Code plugin that raises /compact session continuity (state capture, recovery guidance, and skill recall) above Codex CLI parity. It does not replace Claude Code's compaction algorithm — it augments compaction through the documented hook surface.

What It Does

• Backs up the transcript before compaction and writes a 10-section state file with an LLM
• Injects the state file, plan file, and original-source reminder after compaction through additionalContext
• Recovers the list of skills invoked earlier in the session — a mechanism not present in the Codex CLI baseline
• When context usage crosses a configured threshold (default 60%), the next user prompt receives a suggestion to run /compact
• Alongside that reminder, the plugin injects a three-line recitation (Active Plan, Current Phase, and the most recent Session Decision from the state file) into additionalContext, so the agent keeps its bearings during the last few turns before compaction actually runs. This does not change the compaction algorithm itself; it is a focus aid that reduces late-session drift between warn and the real /compact
• Provides the /compact-plus skill for manual state capture

Usage

After installation, just run /compact as usual. No additional action is required — the flow is fully transparent.

• Both manual /compact and auto-compaction trigger the same hook path
• Before compaction: the PreCompact hook automatically backs up the transcript and generates the 10-section state file
• After compaction: recovery guidance is automatically injected into additionalContext through the UserPromptSubmit hook on the next user prompt
• The agent does not need to call any specific skill or perform any preparation

Optional enhancements:

• Pass an instruction such as /compact keep the security-related decisions to send priority guidance to the state-generation LLM
• Invoke /compact-plus manually right before compaction if you want to leave richer recovery notes; this switches to the fallback path where the agent writes the structured state itself

Requirements

• Claude Code v2.x or later
• An LLM backend through claude -p or codex exec
• The default configuration uses claude -p --model claude-sonnet-5 --effort medium as the primary backend and codex exec --model gpt-5.3-codex-spark as the fallback backend
• The Codex Spark fallback assumes ChatGPT Pro access. You can switch the fallback to models such as gpt-5.4 or gpt-5.5

Installation

Add the local marketplace, then install the plugin.

claude plugin marketplace add /path/to/compact-plus --scope user
claude plugin install compact-plus@compact-plus-local

Configuration

Following the Claude Code plugin model, write environment variables under the env block in ~/.claude/settings.json. For temporary per-session overrides, shell export also works.

Backend Overrides

Two environment variables replace the primary and fallback commands as whole shell commands.

env var	Meaning
COMPACT_PLUS_PRIMARY_BACKEND	Complete shell command for the primary backend. Set to an empty string ("") to skip the primary backend
COMPACT_PLUS_FALLBACK_BACKEND	Complete shell command for the fallback backend. Set to an empty string to skip the fallback backend

Environment variables available inside those commands:

• $SYSTEM_PROMPT: the LLM system prompt from prompts/state-summary.md
• $SESSION_ID: Claude Code session id
• $TRANSCRIPT_PATH: transcript JSONL path
• $MAX_OUTPUT_TOKENS: LLM output cap

Default values are embedded in hooks/precompact-state-summary.sh.

Example ~/.claude/settings.json override for a lower-cost Haiku backend:

{
  "env": {
    "COMPACT_PLUS_PRIMARY_BACKEND": "claude -p --model claude-haiku-4-5-20251001 --effort low --permission-mode dontAsk --output-format text --no-session-persistence --system-prompt \"$SYSTEM_PROMPT\""
  }
}

Example replacing the primary backend with Codex Spark (requires ChatGPT Pro; served through Cerebras for higher throughput):

{
  "env": {
    "COMPACT_PLUS_PRIMARY_BACKEND": "tmp=$(mktemp \"${TMPDIR:-/tmp}/compact-plus-codex.XXXXXX\"); { printf \"%s\\n\\n\" \"$SYSTEM_PROMPT\"; cat; } | codex exec --model gpt-5.3-codex-spark --sandbox read-only --skip-git-repo-check --dangerously-bypass-hook-trust --ignore-user-config --ephemeral --output-last-message \"$tmp\" - >/dev/null && cat \"$tmp\"; status=$?; rm -f \"$tmp\"; exit \"$status\""
  }
}

Codex output can prepend a CLI preamble to stdout, so --output-last-message "$tmp" is used to capture only the final message. This mirrors the default fallback implementation.

Example disabling the fallback:

{
  "env": {
    "COMPACT_PLUS_FALLBACK_BACKEND": ""
  }
}

Transcript, Squash, and Two-Pass Tuning