Coihuin Compress

Context compression at natural breakpoints, not reactive to token limits.

Workflow

Session 1 (new work):
  → "checkpoint" → creates new checkpoint
  → chkcc current <checkpoint> → set as current

Session 2+ (continuing):
  → Read checkpoint file
  → chkcc current <checkpoint> → set as current
  → work + continuous maintenance
  → "archive" when done

Continuous Maintenance

This is the core principle. Don't wait for "delta" commands. Update the checkpoint as you work:

| When This Happens | Update This Section | |-------------------|---------------------| | Decision made | → Decisions | | File created/modified/deleted | → Artifact Trail | | Task completed | → Play-By-Play, Current State | | Blocker hit | → Breadcrumbs, Next Actions | | Direction changes | → Session Intent, Next Actions |

Update immediately, not in batches. Small, frequent updates keep the checkpoint alive in your working memory.

Checkpoint States

| State | Location | Meaning | |-------|----------|---------| | current | checkpoints/active/ | The ONE checkpoint being actively worked on | | active | checkpoints/active/ | In-progress work (not immediate focus) | | archived | checkpoints/archive/ | Completed work |

chkcc current <checkpoint>  # Set as current
chkcc current               # Show current
chkcc current --clear       # Clear current
chkcc status                # Show all active with summaries

Operations

Checkpoint

Create new state snapshot.

Trigger: "checkpoint", "create checkpoint"

How:

Read checkpoint-format.md for structure
Extract "What Must Survive" from conversation
Generate checkpoint following the format
Save to checkpoints/active/<name>.md
Update checkpoints/active/INDEX.md

Delta (Explicit)

Force a structured update when you want visibility into what changed.

Trigger: "delta", "update checkpoint"

How:

Add ## Delta: <timestamp> section to checkpoint
Summarize what changed since last delta
Update main sections with current state

Note: With continuous maintenance, explicit deltas are less necessary. Use when you want a clear marker of progress.

Fork Detection

When work diverges into parallel streams, offer options:

Strong signals (any one suggests fork):

User says work is unrelated
Different issue/ticket involved
Fundamental context switch

Weak signals (two+ together suggest fork):

Working in entirely different files
Scope expanding beyond original intent
New dependencies unrelated to current work

When detected, present options:

A) Create separate checkpoint (sets parent for lineage)
B) Continue with current (expand scope)
C) Set aside divergent work

Not a fork: Trivial fixes, config changes, supporting changes for main work.

Directory Structure

checkpoints/
├── active/
│   ├── INDEX.md
│   └── chk-*.md
├── archive/
│   └── chk-*.md
└── LEARNINGS.md          # Accumulated insights from archives

Reference Files

| File | Purpose | |------|---------| | checkpoint-format.md | Checkpoint structure specification | | index-format.md | INDEX.md structure specification | | LEARNINGS.md | Accumulated learnings from archived checkpoints |

Priority Hierarchy (token pressure)

Must Keep: Problem, session intent, decisions, current state, next actions
Should Keep: Recent artifacts, recent play-by-play, technical context, breadcrumbs
Can Summarize: Older play-by-play, completed artifacts, historical decisions

Quality Self-Check

Before finalizing updates, verify:

Problem Clarity: Could a fresh agent understand without the conversation?
Decision Rationale: Is the "why" captured, not just the "what"?
State Specificity: Concrete progress, not vague status?
Action Actionability: Can someone execute Next Actions immediately?
Fresh Agent Test: Loading this cold, would you know exactly what to do?

coihuin-compress