Skip to main content
skill CX Codex

capsule-compact — Claude Code skill: what it does and how to install

The capsule-compact Claude Code skill condenses long chains of context capsules. Run it on request or when a chain has grown too long.

MIT ★ 26 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wrg32786/aigent-os --skill capsule-compact -a claude-code
Open on GitHub

What capsule-compact does

The skill runs python3 daemons/capsule-compact.py <head_capsule_id> from the vault root, following parent links back from the chosen head. Once a chain reaches five capsules, it combines the three oldest into one summary. The script rewires the links and tags each compacted capsule with compacted_into.

The summary uses structured fields: objectives, live open threads, and held decisions. No LLM is involved, and the original capsules stay on disk. The script does not follow forks or compact automatically at /close; that step only reports the chain length. Set a different threshold or summary size with --threshold N and --summarize-count N. Running it requires python3.

What it helps with

  • condense a long context-capsule chain
  • combine older capsules into one summary
  • update parent links after compaction
  • keep source capsules marked with their summary

Example prompts for the agent

  • Compact the capsule chain starting at head_capsule_id.
  • Summarize the older capsules in this chain.
  • Compact the chain at a threshold of five, summarizing three capsules.

How to install capsule-compact

1Skills CLI (Vercel)

npx skills add wrg32786/aigent-os --skill capsule-compact -a claude-code

2Manually: put the files in place

~/.claude/skills/capsule-compact/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/capsule-compact/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about capsule-compact

How do I install capsule-compact in Claude Code?

Run npx skills add wrg32786/aigent-os --skill capsule-compact -a claude-code. The skill file will be at ~/.claude/skills/capsule-compact/SKILL.md.

What does capsule-compact do?

When a chain has at least five capsules, it combines the three oldest into a structured summary and adjusts the parent links. The original files remain on disk and receive a compacted_into marker.

What does capsule-compact need to run?

It requires python3. Run the script from the vault root with python3 daemons/capsule-compact.py <head_capsule_id>.

Source text

SKILL.md · MIT
---
name: capsule-compact
agent: none
description: "Compact capsule chains by summarizing older capsules. Use when manually compacting capsules or a context chain grows too long."
allowed-tools: Bash, Read
user-invocable: true
triggers:
  - capsule compact
  - compact chain
  - chain compaction
  - compact capsules
  - /capsule-compact
  - chain too long
---

# /capsule-compact

Run `python3 daemons/capsule-compact.py <head_capsule_id>` from the vault root.

The script:
1. Walks `parent_capsule_id` chain backward from the head
2. If chain length >= 5, summarizes the oldest 3 capsules into a single `chain-summary-<head>-<date>.md` capsule
3. Updates pointers: boundary capsule's parent → summary; summary's parent → original chain root's parent
4. Marks each compacted capsule with `compacted_into: <summary_id>` (they stay on disk for archeology)

## When to run

- /close Step 0.5 PART E (v0.4.5) reports the capsule chain length when the threshold is hit
- Manually before a session-heavy week to keep /open Step 2.5 fast
- After narrative-reconstruction archeology when the chain has grown unwieldy

## Defaults

- Threshold: 5 capsules
- Summarize-count: 3 oldest

Override via `--threshold N` and `--summarize-count N` flags.

## What it does NOT do

- Does not auto-compact at /close. Hints, you decide.
- Does not delete compacted capsules. Each gets `compacted_into:` marker.
- Does not LLM-summarize. Concatenates structured fields (objective, open_threads still live, held decisions).
- Does not walk forks. parent_capsule_id is strictly linear.

## Cross-links

- [[concepts/Somatic v0.4.5 Chain Compaction]] — spec
- [[concepts/context-capsule]] — base capsule schema

© wrg32786 · MIT · wrg32786/aigent-os

Similar skills

SKILL.md skills catalog →

From the same set58

The whole set →
compact-note The compact-note Claude Code skill condenses long notes and logs while keeping the reasoning behind decisions. It runs on requests to shorten a note, log, or memory. CX Codex +1 ★ 26repo stars comms-summarize The comms-summarize Claude Code skill summarizes unread messages from an inbox, channel, or thread. It flags items that need action and separates them from FYI and stale messages. CX Codex +1 ★ 26repo stars cognitive-update The cognitive-update Claude Code skill updates goals, beliefs, self-model fields, and procedures from explicit evidence. It activates for cognitive or runtime state changes. CX Codex +1 ★ 26repo stars codex-adapter The codex-adapter Claude Code skill hands one bounded, mechanical change to OpenAI Codex CLI. It activates on an explicit request to delegate a rename, config edit, or scripted replacement. CX Codex +1 ★ 26repo stars close This Claude Code skill saves session outcomes to durable memory and prepares a resume point. Run /close to wrap up work and update notes in vault/. CX Codex +1 ★ 26repo stars brief This Claude Code skill drafts a structured brief for handing work to a sub-agent. It runs when a task needs to be assigned, handed off, or explained to another agent. CX Codex +1 ★ 26repo stars body-check The body-check Claude Code skill reads existing signals about context, memory, and pending work. It reports the current state and suggests a next action. CX Codex +1 ★ 26repo stars agent-fitness The agent-fitness Claude Code skill tracks sub-agent dispatch results and highlights blocked or failed runs. It responds to requests about agent calibration and performance trends. CX Codex +1 ★ 26repo stars

Project sponsors

Companies that keep this analytics open