Auto-Learn

Automatically detects recurring command patterns during sessions and suggests or applies learnings to CLAUDE.md files.

Overview

The auto-learn system observes commands run during a Claude Code session and, when patterns emerge (same command run multiple times), either suggests adding them as learnings to CLAUDE.md or automatically applies them.

Flow:

1. Observe (PreToolUse on Bash): Tracks commands during the session
2. Synthesize (Stop event): Analyzes patterns and generates suggestions
3. Apply/Suggest: Writes to CLAUDE.md (auto mode) or shows suggestions (suggest mode)

Configuration

Enable and configure via /bluera-base:config:

# Enable auto-learning (opt-in, disabled by default)
/bluera-base:config enable auto-learn

# Set mode: suggest (default) or auto
/bluera-base:config set .autoLearn.mode auto

# Set occurrence threshold (default: 3)
/bluera-base:config set .autoLearn.threshold 5

# Set target file: local (default) or shared
/bluera-base:config set .autoLearn.target shared

Configuration Options

| Option | Path | Values | Default | Description | |--------|------|--------|---------|-------------| | Enabled | .autoLearn.enabled | true/false | false | Opt-in to enable tracking | | Mode | .autoLearn.mode | suggest/auto | suggest | How to handle learnings | | Threshold | .autoLearn.threshold | number | 3 | Occurrences before acting | | Target | .autoLearn.target | local/shared | local | Where to write learnings |

Modes

| Mode | Behavior | |------|----------| | suggest | Shows learnings as systemMessage at session end. User runs /bluera-base:claude-code-md learn to apply. | | auto | Writes learnings directly to target file. Shows confirmation message. |

Targets

| Target | File | Shared | Notes | |--------|------|--------|-------| | local | CLAUDE.local.md | No | Auto-gitignored by Claude Code | | shared | CLAUDE.md | Yes | Committed to repo, shared with team |

Pattern Detection

Commands are normalized and counted during each session:

| Pattern | Example Commands | Suggested Learning | |---------|-----------------|-------------------| | npm:test, bun:test, yarn:test | npm test, bun run test | "Run tests frequently during development" | | npm:lint, bun:lint, cargo:clippy | npm run lint | "Run linter before committing" | | npm:build, cargo:build, go:build | npm run build | "Build verification is part of workflow" | | git:status, git:diff | git status | "Check git status before commits" |

Commands are normalized to tool:subcommand format for consistent tracking.

File Format

Learnings are stored in a marker-delimited region:

## Auto-Learned (bluera-base)
<!-- AUTO:bluera-base:learned -->
- Run tests frequently during development
- Run linter before committing
<!-- END:bluera-base:learned -->

Marker rules:

• Section header: ## Auto-Learned (bluera-base)
• Start marker: <!-- AUTO:bluera-base:learned -->
• End marker: <!-- END:bluera-base:learned -->
• Each learning is a bullet point (-)

Safety Features

Secrets Detection

Learnings matching sensitive patterns are always rejected:

api[_-]?key|token|password|secret|-----BEGIN|AWS_|GITHUB_TOKEN|ANTHROPIC_API|OPENAI_API|private[_-]?key|credential

Deduplication

Before writing, learnings are normalized (lowercase, trimmed) and compared against existing content. Duplicates are silently skipped.

Hard Cap

Maximum 50 learnings in the auto-managed section. If exceeded, a warning is shown and no new learnings are written.

Opt-In

Auto-learn is disabled by default. Users must explicitly enable it:

/bluera-base:config enable auto-learn

State Files

| File | Purpose | |------|---------| | .bluera/bluera-base/state/session-signals.json | Tracks command counts per session |

The signals file is cleared after synthesis (at session end).

Implementation Files

| File | Purpose | |------|---------| | hooks/observe-learning.sh | PreToolUse hook - tracks Bash commands | | hooks/session-end-learn.sh | Stop hook - synthesizes and applies learnings | | hooks/lib/autolearn.sh | Library - writing functions (target resolution, dedup, secrets check) | | hooks/lib/signals.sh | Library - session signals state management | | hooks/lib/config.sh | Library - configuration loading |

Deep Learning (Semantic Analysis)

For more intelligent learning, see the deep-learn feature which uses Claude CLI to semantically analyze session transcripts:

# Enable deep learning (more powerful, uses Claude Haiku)
/bluera-base:config enable deep-learn

Differences:

| Feature | auto-learn | deep-learn | |---------|------------|------------| | Method | Pattern matching | Semantic analysis | | Patterns | 4 hardcoded | Unlimited | | Cost | Free | ~$0.001/session | | Quality | Generic | Project-specific | | Learnings | Auto-applied | Human-reviewed |

Deep learning extracts:

• User corrections ("No, use X instead of Y")
• Error resolutions discovered during work
• Project-specific facts and workflows

Manage deep learnings: /bluera-base:learn show|apply|dismiss

See skills/learn/SKILL.md for full deep learning documentation.

Related

• /bluera-base:config - Enable and configure auto-learn
• /bluera-base:claude-code-md learn - Manually add a learning
• /bluera-base:learn - Manage deep learnings
• skills/learn - Deep learning skill
• skills/claude-code-md-maintainer - Full CLAUDE.md management skill