---
name: contextoptimize
description: Frees up the context window and keeps it lean. Use whenever the user types /contextoptimize, says the session is slow, long, forgetful or "running out of context", asks what is eating their context or tokens, wants to compact or clear without losing their place, or asks to trim CLAUDE.md, skills, plugins or MCP servers. Also use before starting a long task in a session that is already heavy.
---

# Context optimize

The context window is shared by two things: what loads before the user types anything (memory files, skill and agent descriptions, plugin hooks, MCP tool lists) and what this conversation has piled up (file reads, tool output, old plans). This skill deals with both, in that order, because a handoff written first makes every later step safe.

Work through the four steps. Keep the user-facing output short: they asked for less text in their window, not more.

## 1. Save the state of this session

Before anything is compacted or cleared, write down what would be lost. Create or update `HANDOFF.md` in the project root (use the project's existing handoff file if it has one, and append a dated section instead of rewriting it). Include only what the next session cannot rediscover in under a minute:

- the goal, in one or two sentences
- decisions made and why, including options that were rejected
- what is done, what is half done (with file paths and line numbers), what is next
- exact commands that worked: build, test, run
- open questions waiting on the user

Leave out anything the repo already says. A handoff that restates the README is noise.

## 2. Measure what loads every session

Run the bundled script from the project folder:

```bash
python3 ~/.claude/skills/contextoptimize/scripts/context_audit.py .
```

It is read-only and prints a table of estimated tokens for the CLAUDE.md chain, every skill and subagent description, each enabled plugin, plus the hooks and MCP servers it found. It cannot see MCP tool schemas or hook output, so also ask the user to run `/context` if they want exact numbers for those.

## 3. Report and propose

Show the user a short table: the top five costs, and for each one a specific fix with the tokens it would save. Rank by savings. Typical fixes, most valuable first:

| Finding | Fix |
|---|---|
| A plugin with dozens of skills the user rarely uses | Turn it off in `enabledPlugins`; copy the one or two skills they do use into `~/.claude/skills` |
| MCP servers not needed in this project | Disable for the session with `/mcp`, or move from user scope to the project that needs it |
| CLAUDE.md over about 200 lines | Move reference material into a file loaded on demand and leave a one-line pointer |
| Instructions repeated in global and project CLAUDE.md | Keep one copy, in the narrower file |
| Skill descriptions over about 100 words | Tighten the description; the body only loads when used, so move detail there |
| Subagents that are never dispatched | Archive them |
| A SessionStart hook injecting a long prompt | Shorten or remove the hook if its plugin is not earning its place |

Explain each fix in one line. Do not pad the report with findings that save under a few hundred tokens.

## 4. Apply only what the user approves

These are the user's settings, and some skills look unused right up until they are needed. So:

- Ask before changing anything, and apply only the fixes they pick.
- Never delete. Move files to a dated archive folder such as `~/.claude/_archive/YYYY-MM-DD-contextoptimize/` with a `MANIFEST.md` listing what moved and the command to move it back.
- Back up `settings.json` and any CLAUDE.md before editing them.
- Disabling a plugin is an edit to `enabledPlugins`, not an uninstall.
- After changes, re-run the script and show before and after totals.

## Then free the conversation itself

Once the handoff exists, tell the user which of these fits, and why:

- `/compact` with a focus, for example `/compact keep the failing test output and the plan for step 3`: when the current task continues and recent detail matters.
- `/clear`, then "read HANDOFF.md and continue": when the task is changing, or the session has been compacted more than once already. A fresh window with a good handoff beats a third compaction.

Changes to skills, plugins and MCP servers only take effect in a new session, so say that plainly.

## Habits worth mentioning once

If the audit shows the conversation itself was the problem, offer one or two of these, not the whole list: read files in ranges instead of whole; send broad searches to a subagent so only the answer comes back; pipe long command output through `tail` or `grep`; start a new session per task.