Manages Claude Code context window to prevent information loss. Tracks usage, saves state before compaction, and restores seamlessly after restart. Prevents the frustrating loss of work-in-progress when context fills up. Use when working on long tasks, when context is getting full, or when the user says /ctx.

Context Manager

Prevent information loss when your Claude Code context window fills up. Automatically tracks usage, saves state, and restores after restart.

When to Activate

User says /ctx or /ctx save or /ctx check
User asks about context usage or remaining space
User is working on a long task that might exhaust context
Before starting a large task (reading many files, big implementation)

The Problem

Claude Code has a finite context window. When it fills up:

The system compresses earlier messages (lossy)
You lose working state, partial progress, and nuanced context
Multi-step tasks break halfway through
You repeat work you already did

Instructions

`/ctx check` — Check Current Usage

Read the context-usage.json file (updated by Claude Code hooks):

cat .claude/state/context-usage.json 2>/dev/null

Report to the user:

Green (>60% remaining): Plenty of room. Work freely.
Yellow (40-60% remaining): Getting warm. Save state before starting big tasks.
Red (<40% remaining): Save state now. Consider restarting before continuing.

If no tracking file exists, guide setup (see Setup section).

`/ctx save` — Save Current State

Capture everything needed to resume after a restart:

Create state file at .claude/state/assistant-state.md:

# Assistant State

**Saved**: {ISO timestamp}
**Reason**: {why saving — manual save, low context, task checkpoint}

## Current Task
{What you're working on right now}

## What's Done
{Completed steps, with file paths and commit hashes}

## What's Next
{Remaining steps, in order}

## Key Context
{Important facts that would be lost — variable names, design decisions,
 user preferences expressed during this session, error messages that
 led to the current approach}

## Open Files
{Files currently being worked on, with relevant line ranges}

Confirm save — tell the user what was captured

`/ctx restore` — Restore After Restart

At session start, check for saved state:

cat .claude/state/assistant-state.md 2>/dev/null

If state exists:

Read and internalize the saved context
Summarize to the user: "Picking up where we left off — [task summary]"
Continue from "What's Next"

`/ctx auto` — Enable Automatic Management

Set up a hook that monitors context usage and auto-saves:

Create .claude/hooks/context-watchdog.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": { "tool_name": "*" },
        "hooks": [
          {
            "type": "command",
            "command": "node -e \"const f='.claude/state/context-usage.json';const fs=require('fs');try{const d=JSON.parse(fs.readFileSync(f));if(d.remaining_percentage<35){fs.writeFileSync('.claude/state/context-watchdog-triggered','1');console.log('CONTEXT LOW: '+d.remaining_percentage+'% remaining. Run /ctx save now.')}}catch(e){}\""
          }
        ]
      }
    ]
  }
}

This checks context after every tool use and warns when it's getting low.

State File Best Practices

What to Save

Current task description and progress
File paths and line numbers being worked on
Commit hashes of completed work
Design decisions made during this session
User preferences expressed (e.g., "keep it simple", "use TypeScript")
Error messages that informed the current approach
Open questions or blockers

What NOT to Save

Full file contents (they're on disk — just save the path)
Entire conversation history (save the conclusions, not the discussion)
Stale information from earlier in the session that was superseded

Save Points

Good times to save:

After completing a story or task step
Before reading a large file or codebase exploration
Before switching topics
When the user takes a break
After resolving a tricky bug (save the solution context)

Setup

Minimal Setup (5 minutes)

Create the state directory:

mkdir -p .claude/state

Use /ctx save and /ctx restore manually

Full Setup (15 minutes)

Create state directory and context tracking:

mkdir -p .claude/state
echo '{}' > .claude/state/context-usage.json

Add a Claude Code hook to track context usage (requires Claude Code hooks support)
Run your Claude Code session inside tmux for clean restart support:

tmux new-session -s claude "claude"

Enable /ctx auto for automatic warnings

Tips

Save early, save often: The cost of saving is low. The cost of losing context is high.
Restart > clear: /clear only clears history within the session. Restarting Claude Code gives a completely fresh context window.
Front-load reading: Read all the files you'll need at the start of a task, before context fills up with working state.
Use state files as TODO lists: "What's Next" in the state file doubles as your task list after restart.
Checkpoint after breakthroughs: If you just figured out a tricky problem, save the insight immediately.

context-manager