majiayu000 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:
- Observe (PreToolUse on Bash): Tracks commands during the session
- Synthesize (Stop event): Analyzes patterns and generates suggestions
- 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 learningsskills/learn- Deep learning skillskills/claude-code-md-maintainer- Full CLAUDE.md management skill