claude-learn

claude-learn is an autonomous background daemon for Claude Code that reduces token consumption by 45-55%. It watches your sessions, detects repeated token-wasting patterns, and auto-applies safe optimizations to your CLAUDE.md files, enforcement hooks, skills, and RTK config

Installation

Mac/Linux

curl -fsSL https://raw.githubusercontent.com/ArhanCodes/claude-learn/main/install.sh | bash

Windows

iwr -useb https://raw.githubusercontent.com/ArhanCodes/claude-learn/main/install.ps1 | iex

Add to PATH (one-time, Mac/Linux)

After installing, add ~/.local/bin to your shell's PATH so the claude-learn command is available in every terminal:

# zsh (default on modern macOS)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# fish
fish_add_path ~/.local/bin

Open a new terminal or source your rc file to activate.

Savings

User type	Savings
Light (few sessions/week)	10–20%
Regular (daily, 2–3 projects)	45–55%
Heavy (daily, long projects)	55–65%
+ Anthropic API key (LLM summaries)	60–70%

Quick Start

After installing the daemon is already running. You don't need to do anything, but if you want to peek:

# See what it's detected in your usage
claude-learn analyze

# See concrete suggestions
claude-learn suggest

# See what's been auto-applied
claude-learn history

# Check token savings so far
claude-learn savings

To adjust behavior:

claude-learn config set interval_seconds 30     # more frequent
claude-learn config set threshold 3             # more aggressive
claude-learn config set enabled false           # pause without uninstalling

How It Works

• Claude Code writes JSONL transcripts to ~/.claude/projects/
• claude-learn daemon polls every 60s ─ parses new sessions
  • runs 12 pattern detectors
  • filters for safe + not-already-applied
  • applies ≤5 changes per tick
• Auto-writes to:
  • CLAUDE.md (real extracted summaries + rules)
  • .claude/settings.json (enforcement hooks)
  • ~/.claude/skills/ (generated skills)
  • rtk-enabled.txt (commands routed through RTK)
• Next Claude Code session reads optimised config → tokens saved

claude-learn configures Claude Code rather than proxying it. After apply, savings compound on every future session with zero runtime overhead.

What It Detects

Twelve patterns across four layers:

Configuration layer

• repeated-file-read - same file read 3+ times → inline real summary (imports, signatures, classes)
• repeated-bash — same command re-run → document or RTK-route
• bloated-output — npm install, git log, etc. → RTK-route
• vendor-exploration — Claude entering node_modules/.git/target/ → ignore rules
• repeated-grep — same search → document target location
• cache-miss — low cache hit rate → restructure CLAUDE.md for caching
• cross-project-pattern — same waste in multiple projects → global CLAUDE.md

Output layer

• verbose-output — responses averaging >2000 tokens/turn → adds "be concise" rule
• write-for-small-change — Write used for tiny edits → installs Write→Edit hook
• tool-sequence — repeated 3-tool sequences → suggests bundling

Enforcement layer (auto-installed hooks)

• Write → Edit gate — blocks Write for files <40 lines
• Bash bloat filter — warns when bloated commands bypass RTK
• Read interceptor — nudges Claude to check CLAUDE.md summary before re-reading

Resilience layer

• context-overflow → generates session primer per project
• unsummarized-file → inline structural summary
• Cross-session memory at ~/.claude/claude-learn-memory.json

Commands

Control

claude-learn install / uninstall     # register/deregister auto-start
claude-learn start / stop            # control daemon
claude-learn status                  # daemon state + savings so far
claude-learn config [set <k> <v>]    # show/edit settings live

Analysis and manual apply

claude-learn analyze [-v]            # patterns + potential savings
claude-learn suggest [--threshold N] # concrete suggestions
claude-learn apply [--dry-run]       # interactive apply with preview
claude-learn apply --yes             # bulk apply
claude-learn savings                 # token accounting
claude-learn projects                # list tracked projects