claudikins-automatic-context-manager

v1.1.1-beta - Native hooks implementation. This is beta software - expect rough edges. Please report bugs here.

Automatic context management for Claude Code. Monitors token usage and triggers at 60% context saturation, prompting for session handoff with an auto-generated summary that opens in a fresh session.

Requirements

Claude Code CLI and Python 3.

Why

LLM attention weights distribute across all context tokens. As context fills, per-token attention decreases and earlier information receives less weight during generation.

What It Does

1. Statusline displays current context percentage
2. At 60% threshold, creates flag file for UserPromptSubmit hook
3. Hook injects context prompting Claude to use AskUserQuestion for handoff confirmation
4. On confirmation, captures structured state (todos, modified files, git status)
5. Saves state to .claude/claudikins-acm/handoff-state.json and human-readable handoff.md
6. Opens new terminal session with claude command
7. SessionStart hook detects and loads structured state into fresh context

Installation

Claude Code

1. /plugin marketplace add elb-pr/claudikins-marketplace
2. /plugin → navigate to Claudikins Marketplace → install

git clone https://github.com/elb-pr/claudikins-automatic-context-manager.git
./install.sh

How It Works

flowchart TD
    A[Statusline monitors context] -->|every 300ms| B{Context >= 60%?}
    B -->|No| A
    B -->|Yes| C[Create threshold flag file]
    C --> D[UserPromptSubmit hook fires]
    D --> E[AskUserQuestion prompt]
    E --> F{User response}
    F -->|YES| G[Capture structured state]
    G --> H[Save handoff-state.json + handoff.md]
    H --> I[Open new terminal session]
    I --> J[SessionStart hook loads state]
    F -->|SNOOZE| K[Wait 5 minutes]
    K --> A
    F -->|DISMISS| L[Disable for session]

Configuration

Run /acm:config for interactive setup, or edit ~/.claude/claudikins-acm.conf directly.

Platform Support

Troubleshooting

Handoff not triggering Check context has reached threshold. Snooze may be active, or handoff already triggered this session.

New terminal not opening Platform detection may have failed. Check platforms/ for your terminal. Falls back to clipboard with instructions.

Handoff not loading in new session Must be in the same project directory. Verify .claude/claudikins-acm/handoff.md exists and SessionStart hook is installed.

Roadmap

• Semantic triggers - Detect degradation signals (repetition, errors, stuck loops) rather than relying solely on token thresholds
• Performance - Replace regex JSON parsing with jq or Python single-pass extraction
• Incremental summaries - Build context summaries progressively rather than only at handoff
• MCP integration - Expose handoff status and manual trigger as MCP tools
• IDE extension - VS Code integration for non-CLI users

Uninstall