Skip to content
Back to search

compact-plus

MarketplaceWorks with Claude CodeGitHub

Claude Code plugin: preserve and restore working state around /compact

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/u-ichi-compact-plus/badge.svg)](/listings/u-ichi-compact-plus)

HTML

<a href="/listings/u-ichi-compact-plus"><img src="/api/listings/u-ichi-compact-plus/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code

Add this GitHub repository as a marketplace, then install the plugin from it.

claude plugin marketplace add u-ichi/compact-plus --scope user
claude plugin install compact-plus@compact-plus

Codex

Add the same GitHub repository as a marketplace, then install the Codex plugin.

codex plugin marketplace add u-ichi/compact-plus
codex plugin add compact-plus@compact-plus

Review and trust the hook definitions when Codex prompts. Start a new thread after installation so Codex loads the installed plugin and hooks.

Updating

Refresh the GitHub marketplace snapshot, then update or reinstall the plugin.

# Claude Code
claude plugin update compact-plus@compact-plus

# Codex
codex plugin marketplace upgrade compact-plus
codex plugin add compact-plus@compact-plus

For local development, replace `u-ichi/compact-plus` in the marketplace-add command with the absolute path to this repository. The plugin reference remains `compact-plus@compact-plus`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 21 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "compact-plus",
  3. "owner": {
  4. "name": "u1"
  5. },
  6. "metadata": {
  7. "description": "Local marketplace for the compact-plus plugin.",
  8. "version": "1.3.2"
  9. },
  10. "plugins": [
  11. {
  12. "name": "compact-plus",
  13. "description": "Preserve Claude Code and Codex session state around context compaction.",
  14. "version": "1.3.2",
  15. "author": {
  16. "name": "u1"
  17. },
  18. "source": "./"
  19. }
  20. ]
  21. }
README.md · README · 229 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # compact-plus
  2. [Japanese README](./README.ja.md) | [Architecture](./docs/architecture.md)
  3. A transparent Claude Code and Codex plugin that preserves working state around `/compact`. It does not replace either runtime's compaction algorithm; it augments compaction through documented hooks.
  4. ## What It Does
  5. - Backs up the transcript before compaction and writes a 10-section state file with an LLM
  6. - Injects the state file, plan file, and original-source reminder after compaction through `additionalContext`
  7. - Recovers mechanically observable skills and commands; unobservable Codex skill use is recorded as `Not verified`
  8. - When context usage crosses a configured threshold, the next user prompt receives a suggestion to run `/compact`
  9. - 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`
  10. - Provides the `/compact-plus` skill for manual state capture
  11. ## Usage
  12. After installation, just run `/compact` as usual. **No additional action is required** — the flow is fully transparent.
  13. - Both manual `/compact` and auto-compaction trigger the same hook path
  14. - Before compaction: the PreCompact hook automatically backs up the transcript and generates the 10-section state file
  15. - After compaction: Claude Code and Codex recover exactly once through `SessionStart(source=compact)` before the first post-compaction prompt
  16. - The agent does not need to call any specific skill or perform any preparation
  17. Optional enhancements:
  18. - Pass an instruction such as `/compact keep the security-related decisions` to send priority guidance to the state-generation LLM
  19. - 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
  20. ## Requirements
  21. - Claude Code v2.x or later, or a Codex version with plugin compaction hooks
  22. - An LLM backend through `claude -p` or `codex exec`
  23. - 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
  24. - The Codex Spark fallback assumes ChatGPT Pro access. You can switch the fallback to models such as `gpt-5.4` or `gpt-5.5`
  25. ## Installation
  26. ### Claude Code
  27. Add this GitHub repository as a marketplace, then install the plugin from it.
  28. ```bash
  29. claude plugin marketplace add u-ichi/compact-plus --scope user
  30. claude plugin install compact-plus@compact-plus
  31. ```
  32. ### Codex
  33. Add the same GitHub repository as a marketplace, then install the Codex plugin.
  34. ```bash
  35. codex plugin marketplace add u-ichi/compact-plus
  36. codex plugin add compact-plus@compact-plus
  37. ```
  38. Review and trust the hook definitions when Codex prompts.
  39. Start a new thread after installation so Codex loads the installed plugin and hooks.
  40. ### Updating
  41. Refresh the GitHub marketplace snapshot, then update or reinstall the plugin.
  42. ```bash
  43. # Claude Code
  44. claude plugin update compact-plus@compact-plus
  45. # Codex
  46. codex plugin marketplace upgrade compact-plus
  47. codex plugin add compact-plus@compact-plus
  48. ```
  49. For local development, replace `u-ichi/compact-plus` in the marketplace-add command with the absolute path to this repository.
  50. The plugin reference remains `compact-plus@compact-plus`.
  51. ## Configuration
  52. 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.
  53. ### Backend Overrides
  54. Two environment variables replace the primary and fallback commands as whole shell commands.
  55. | env var | Meaning |
  56. |---|---|
  57. | `COMPACT_PLUS_PRIMARY_BACKEND` | Complete shell command for the primary backend. Set to an empty string (`""`) to skip the primary backend |
  58. | `COMPACT_PLUS_FALLBACK_BACKEND` | Complete shell command for the fallback backend. Set to an empty string to skip the fallback backend |
  59. Environment variables available inside those commands:
  60. - `$SYSTEM_PROMPT`: the LLM system prompt from `prompts/state-summary.md`
  61. - `$SESSION_ID`: Claude Code session id
  62. - `$TRANSCRIPT_PATH`: transcript JSONL path
  63. - `$MAX_OUTPUT_TOKENS`: LLM output cap
  64. Default values are embedded in `hooks/precompact-state-summary.sh`.
  65. Example `~/.claude/settings.json` override for a lower-cost Haiku backend:
  66. ```json
  67. {
  68. "env": {
  69. "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\""
  70. }
  71. }
  72. ```
  73. Example replacing the primary backend with Codex Spark (requires ChatGPT Pro; served through Cerebras for higher throughput):
  74. ```json
  75. {
  76. "env": {
  77. "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\""
  78. }
  79. }
  80. ```
  81. 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.
  82. Example disabling the fallback:
  83. ```json
  84. {
  85. "env": {
  86. "COMPACT_PLUS_FALLBACK_BACKEND": ""
  87. }
  88. }
  89. ```
  90. ### Transcript, Squash, and Two-Pass Tuning
  91. | env var | default | Meaning |
  92. |---|---|---|
  93. | `COMPACT_PLUS_TRANSCRIPT_MODE` | `incremental` | Transcript selection mode: `incremental`, `head-tail`, or `tail` |
  94. | `COMPACT_PLUS_TRANSCRIPT_HEAD_TURNS` | `5` | Number of turns to keep from the head side |
  95. | `COMPACT_PLUS_TRANSCRIPT_TAIL_TURNS` | `25` | Number of turns to keep from the tail side |
  96. | `COMPACT_PLUS_TRANSCRIPT_HEAD_KB` | `10` | Head-side byte cap in KB |
  97. | `COMPACT_PLUS_TRANSCRIPT_TAIL_KB` | `40` | Tail-side byte cap in KB |
  98. | `COMPACT_PLUS_RAW_DELTA_FACTOR` | `20` | Incremental mode reads at most `TAIL_KB * N` of raw transcript delta before squashing. Set `0` for unbounded |
  99. | `COMPACT_PLUS_INCREMENTAL_REFRESH` | `10` | Full rebuild every N runs. Set `0` to disable |
  100. | `COMPACT_PLUS_MAX_OUTPUT_TOKENS` | `4096` | LLM output cap for backends that read it |
  101. | `COMPACT_PLUS_BACKEND_TIMEOUT` | `80` | Per-backend timeout in seconds. Primary and fallback run serially inside the 180s hook budget. Set `0` to disable |
  102. | `COMPACT_PLUS_SQUASH_ENABLED` | `1` | Enables or disables tool result squash |
  103. | `COMPACT_PLUS_SQUASH_READ_LINES` | `100` | Replaces Read tool output above N lines with `[Read: N lines from path]` |
  104. | `COMPACT_PLUS_SQUASH_BASH_CHARS` | `500` | Replaces Bash output above N characters with `[Bash: exit code, N chars output]` |
  105. | `COMPACT_PLUS_TWO_PASS` | `1` | Enables or disables two-pass self-critique |
  106. ### Warn Thresholds
  107. Claude Code and Codex use separate settings:
  108. | Runtime | env var | default | Source |
  109. |---|---|---:|---|
  110. | Claude Code | `COMPACT_WARN_THRESHOLD` | base repository setting | `home/hooks/claude/statusline.sh` writes the marker consumed by this plugin |
  111. | Codex | `COMPACT_PLUS_CODEX_WARN_THRESHOLD` | `75` | compact-plus reads the latest token-count event from the current thread rollout |
  112. Both values are context **usage** percentages. Changing one does not change the other. Codex uses the same effective-window basis as its context display by excluding the current 12,000-token fixed baseline. Codex also verifies that the rollout's `session_meta.id` matches the current `session_id`; missing, malformed, or mismatched rollout data produces no notification.
  113. ### `/compact` Arguments
  114. When you pass natural-language instructions, such as `/compact keep the important design decisions`, compact-plus forwards those instructions to the state-generation LLM as priority guidance.
  115. ## Runtime Flow
  116. 1. **PreCompact hook**
  117. - `precompact-transcript-backup.sh` copies the transcript JSONL to `~/.claude/backups/transcripts/` or `${CODEX_HOME:-$HOME/.codex}/backups/transcripts/`
  118. - `precompact-state-summary.sh` applies semantic chunking and tool output squash to the transcript, then calls the primary or fallback backend and writes the 10-section state file
  119. 2. **PostCompact hook**
  120. - `compaction-recovery.sh` resets the warning cooldown, and either consumes the injected mark left by `SessionStart` or writes a recovery marker when no injection has happened yet
  121. 3. **Recovery hook**
  122. - `sessionstart-compaction-recovery.sh` handles `SessionStart(source=compact)` for both Claude Code and Codex
  123. - It injects the saved state content, active plan reference when present, and original-source reminder through `additionalContext`
  124. - The two runtimes order the compaction hooks differently, so the two hooks agree through a handshake rather than a fixed sequence. Claude Code dispatches `SessionStart(source=compact)` **before** `PostCompact`, so on the first compaction there is no marker yet; the hook injects on the strength of the state file and leaves an injected mark, and the later `PostCompact` consumes that mark instead of arming a marker. Codex dispatches `PostCompact` **first**, so the marker already exists and `SessionStart` consumes it. Either way the state is injected exactly once
  125. - `userpromptsubmit-compaction-recovery.sh` stays registered as the fallback channel. Codex dispatches the start hook to root threads only, so a thread-spawn subagent receives no start hook after compaction and recovers through the next `UserPromptSubmit`; parent messages reach a subagent as user input. The marker is consumed once, so a thread that already recovered at `SessionStart` is a no-op on the following prompt
  126. - `userpromptsubmit-compact-plus-reminder.sh` consumes warn markers and injects a lightweight notification plus a three-line state recitation when available
  127. 4. **SessionStart hook**
  128. - `sessionstart-export-session-id.sh` writes `export CLAUDE_CODE_SESSION_ID=<id>` to `$CLAUDE_ENV_FILE` so the `/compact-plus` skill can obtain the session id through the bundled `scripts/get-session-id.sh` wrapper without depending on any file outside the plugin
  129. 5. **Manual fallback (`/compact-plus` skill)**
  130. - The agent follows the `SKILL.md` 10-section procedure and writes the state file manually
  131. ## State File Sections
  132. State files start with `# Compact Prep State` and use the same 10-section order in both the manual skill and LLM-generated output.
  133. 1. `## Active Plan`
  134. 2. `## Current Phase`
  135. 3. `## TaskList Summary`
  136. 4. `## Session Decisions`
  137. 5. `## Constraints and Blockers`
  138. 6. `## Worker Topology`
  139. 7. `## Skills Invoked`
  140. 8. `## Editing Files`
  141. 9. `## Failed Attempts`
  142. 10. `## Recovery Notes`
  143. ## Marker Files
  144. | path | writer | reader | Purpose |
  145. |---|---|---|---|
  146. | `${TMPDIR}/claude-compact-state/<session_id>.md` | `precompact-state-summary.sh` / `/compact-plus` skill | recovery hook / agent | Pre-compaction state |
  147. | `${TMPDIR}/claude-compact-state-offset/<session_id>` | `precompact-state-summary.sh` | `precompact-state-summary.sh` | Incremental byte offset |
  148. | `${TMPDIR}/claude-compact-state-counter/<session_id>` | `precompact-state-summary.sh` | `precompact-state-summary.sh` | Refresh cycle counter |
  149. | `${TMPDIR}/claude-compacted/<session_id>` | `compaction-recovery.sh` | `sessionstart-compaction-recovery.sh` / `userpromptsubmit-compaction-recovery.sh` | One-shot PostCompact marker |
  150. | `${TMPDIR}/claude-compact-injected/<session_id>` | `sessionstart-compaction-recovery.sh` | `compaction-recovery.sh` | Injected mark: `SessionStart` already delivered the state, so `PostCompact` skips the marker |
  151. | `${TMPDIR}/claude-compact-warn/<session_id>` | base repo `statusline.sh` | `userpromptsubmit-compact-plus-reminder.sh` | Threshold warning |
  152. | `${TMPDIR}/claude-compact-warned/<session_id>` | `userpromptsubmit-compact-plus-reminder.sh` | statusline / recovery hook | Notification cooldown |
  153. | `${TMPDIR}/claude-active-plan/<session_id>` | plan-management hook | recovery hook | Active plan path |
  154. | `${TMPDIR}/codex-compact-state/<thread_id>.md` | `precompact-state-summary.sh` / `/compact-plus` skill | Codex recovery hook / agent | Codex pre-compaction state |
  155. | `${TMPDIR}/codex-compacted/<thread_id>` | `compaction-recovery.sh` | `sessionstart-compaction-recovery.sh` / `userpromptsubmit-compaction-recovery.sh` | Codex one-shot recovery marker |
  156. | `${TMPDIR}/codex-compact-injected/<thread_id>` | `sessionstart-compaction-recovery.sh` | `compaction-recovery.sh` | Codex injected mark for the same handshake |
  157. | `${TMPDIR}/codex-compact-warned/<thread_id>` | reminder hook | reminder / recovery hook | Codex notification cooldown |
  158. On Codex, `<thread_id>` is the thread that actually compacted. Hook input carries `session_id` as the identity shared by the root thread and all of its descendants, plus `agent_id` for a thread-spawn subagent, so every artifact is keyed on `agent_id` when present and on `session_id` otherwise (`compact_plus_artifact_key` in `scripts/runtime-paths.sh`). Keying on `session_id` alone would file a subagent's state under the parent and overwrite the parent's own state file.
  159. ## Architecture
  160. See [docs/architecture.md](./docs/architecture.md) for the design overview, Claude Code and Codex CLI compaction comparison, hook boundaries, marker ownership, and source references.
  161. ## Development Checks
  162. ```bash
  163. python3 -m json.tool .claude-plugin/plugin.json >/dev/null
  164. python3 -m json.tool .claude-plugin/marketplace.json >/dev/null
  165. python3 -m json.tool .codex-plugin/plugin.json >/dev/null
  166. python3 -m json.tool .agents/plugins/marketplace.json >/dev/null
  167. python3 -m json.tool hooks/hooks.json >/dev/null
  168. bash -n hooks/*.sh scripts/*.sh tests/*.sh
  169. bash tests/test-runtime.sh
  170. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.