seamless-claude

seamless-claude

Zero-downtime compaction for Claude Code.

Every time Claude Code compacts your context window, you sit idle for minutes while it summarises your session. With long conversations, that's 3+ minutes of dead time — and it happens repeatedly.

seamless-claude eliminates the wait. It monitors context usage via the statusline, fires background compaction early, and injects a wrap-up instruction when context is critical. Fresh sessions auto-resume from the prepared summary. Zero downtime.

Two modes

Full Mode (recommended)

Configure the statusline and seamless-claude owns the entire compaction lifecycle:

Context at 70%  →  background compaction starts
                   (summary ready in ~2 min)

Context at 90%  →  wrap-up instruction injected
                   ("finish up, start fresh")

User starts     →  summary auto-injected into
fresh session      new context window

Important: Disable Claude Code's built-in auto-compaction. seamless-claude replaces it entirely — running both will cause conflicts. See Setup.

Basic Mode (fallback)

Without statusline configuration, seamless-claude falls back to hook-only operation:

• Native compaction fires at default threshold
• PreCompact hook spawns the compactor (user waits)
• SessionStart hook injects the summary
• Still better than nothing (structured resume)

How it works

The summary is structured into six sections:

1. Session Summary — what was requested, accomplished, and what remains
2. Technical Context — file paths, commands, config values, error messages (verbatim)
3. User Intent — the user's original requests, clarifications, and constraints (verbatim)
4. Knowledge Extractions — reusable decisions, learnings, patterns, and blockers
5. Next Steps — priority-ordered action items
6. Active Context — working directory, branch, key files

Install

From marketplace (recommended)

/plugin marketplace add RemoteCTO/claude-plugins-marketplace
/plugin install seamless-claude

Manual

/install-plugin RemoteCTO/seamless-claude

Either method installs the hooks (PreCompact, SessionStart, UserPromptSubmit) automatically. Basic Mode works immediately — no further setup needed.

For Full Mode (recommended), continue to Setup.

Updating

The plugin cache path includes the version number. After updating, you must update the statusline path in ~/.claude/settings.json to match the new version:

# Find the new path
find ~/.claude/plugins -name statusline.mjs \
  -path '*seamless*' 2>/dev/null

Update the statusLine.command value in settings.json with the new path, then restart Claude Code.

Setup (Full Mode)

Full Mode adds proactive monitoring via the statusline. Three steps:

1. Find the plugin path

The plugin installs to a versioned cache directory. Find it with:

find ~/.claude/plugins -name statusline.mjs \
  -path '*seamless*' 2>/dev/null

This returns something like:

~/.claude/plugins/cache/remotecto-plugins/seamless-claude/0.1.1/scripts/statusline.mjs

2. Add the statusline to settings.json

Edit ~/.claude/settings.json and add the statusLine block using the full path from step 1:

{
  "statusLine": {
    "type": "command",
    "command": "node ~/.claude/plugins/cache/remotecto-plugins/seamless-claude/0.1.1/scripts/statusline.mjs"
  }
}

3. Disable native auto-compaction

seamless-claude replaces Claude Code's built-in compaction. Running both causes conflicts — native compaction fires at ~90%, the same threshold where seamless-claude injects its wrap-up.

Add to the env block in settings.json:

{
  "env": {
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "100"
  }
}

Setting this to 100 effectively disables native compaction (it would only fire at 100%, which never happens). seamless-claude handles everything instead.

4. Restart Claude Code

Restart for the changes to take effect. You should see the built-in statusline:

seamless: 45% █████████░░░░░░░░░░░

If you have an existing statusline you want to keep, see Using with an existing statusline.

The statusline shows context usage after every response:

seamless: 45% █████████░░░░░░░░░░░
seamless: 73% ██████████████░░░░░░ 🔄 a1b2c3d4
seamless: 80% ████████████████░░░░ ✅ a1b2c3d4
seamless: 80% ████████████████░░░░ ❌ a1b2c3d4
seamless: 92% ██████████████████░░ ⚠️ a1b2c3d4

The session hash (first 8 chars of ID) appears once compaction starts. Icons:

Icon	Status	Meaning
—	idle	Monitoring, below threshold
🔄	compacting	Background compaction running
✅	ready	Summary ready for resume
❌	error	Compaction failed
⚠️	wrapup	Context critical, finishing up