Context Augmentation & Reinforcement Layer — Dynamic rules for Claude Code.
npx carl-coreWorks on Mac, Windows, and Linux.
"Rules that load when relevant, disappear when not."
Why CARL · Getting Started · How It Works · Core Concepts · MCP Tools · Migration
Every Claude Code session starts fresh. Your preferences, workflows, and hard-won lessons? Gone. You end up repeating the same instructions:
"Use TypeScript strict mode." "Don't over-engineer." "Run tests after changes."
Static prompts in CLAUDE.md work, but they bloat every session — even when irrelevant. Writing code? You don't need your content creation rules. Debugging? You don't need your planning workflow.
CARL fixes this with just-in-time rule injection:
- Rules load when relevant — Mention "fix bug" and your development preferences appear
- Rules disappear when not — Your context stays lean
- Explicit triggers available — Star-commands (
*commandname) for on-demand modes
The result: Claude remembers how you work without wasting context on rules you don't need right now.
Claude Code users who want persistent preferences without bloated prompts.
You've figured out what works for you — coding style, response format, workflow patterns. CARL makes those preferences stick:
- Define rules once, use them forever
- Rules activate automatically based on context
- Override or extend per-project as needed
- No manual prompt engineering each session
If you find yourself repeating instructions to Claude, CARL is for you.
npx carl-coreThe installer prompts you to choose:
- Global (recommended) — Rules apply to all Claude Code projects (
~/.claude+~/.carl) - Local — Rules apply to current project only (
./.claude+./.carl)
Restart Claude Code after installation.
~/.carl/
├── carl.json # All domains, rules, decisions, config
├── sessions/ # Session state (auto-managed)
└── carl-mcp/ # MCP server for runtime management
├── index.js
├── package.json
└── tools/
├── carl-json.js # Domain/rule/decision/config CRUD
├── decisions.js # Decision logging (v1 compat)
├── domains.js # Domain management (v1 compat)
└── staging.js # Rule proposal pipeline
~/.claude/
├── hooks/carl-hook.py # The injection engine
└── settings.json # Hook registration
~/.mcp.json # MCP server registration
npx carl-core@latestYou type: "help me fix this bug"
│
▼
┌───────────────────────┐
│ CARL Hook Scans │
│ Your Prompt │
└───────────────────────┘
│
▼
┌───────────────────────┐
│ Matches "fix bug" │
│ → DEVELOPMENT domain │
└───────────────────────┘
│
▼
┌───────────────────────┐
│ Injects Your Rules │
│ Into Context │
└───────────────────────┘
│
▼
Claude responds with your
coding preferences baked in
The hook runs on every interaction, reads your .carl/carl.json, and injects only the rules that match your current task.
Everything lives in a single carl.json file:
{
"version": 1,
"config": {
"devmode": false,
"context_brackets": { "FRESH": {...}, "MODERATE": {...}, "DEPLETED": {...} },
"commands": { "BRIEF": [...], "DISCUSS": [...] }
},
"domains": {
"GLOBAL": { "state": "active", "always_on": true, "rules": [...], "decisions": [...] },
"DEVELOPMENT": { "state": "active", "recall": ["fix bug", "write code"], "rules": [...] }
},
"staging": []
}Key design decisions:
- Single source of truth — No scattered files. One JSON file holds everything.
- MCP for runtime management — Add rules, log decisions, toggle domains without editing files.
- Scope merging — Project
.carl/extends global~/.carl/. More-specific overrides less-specific. - Context dedup — Repeated prompts don't re-inject identical rules, saving tokens.
- Session management — Per-session overrides without modifying permanent config.
A domain is a collection of related rules. Create domains for different contexts:
| Example Domain | Trigger Keywords | What It Does |
|---|---|---|
| GLOBAL | (always loaded) | Universal preferences |
| DEVELOPMENT | "fix bug", "write code" | Your coding preferences |
| CONTENT | "write script", "youtube" | Your content creation style |
| CLIENTS | "client project", "deliverable" | Project-specific rules |
When your prompt matches a domain's recall keywords, its rules load automatically.
Explicit triggers using *commandname syntax:
*brief explain recursion
Unlike domains (automatic), star-commands are intentional. Define them in carl.json under config.commands:
"commands": {
"BRIEF": [
"Create a concise session report",
"Include: goals, work completed, decisions, next steps"
]
}Rules that adapt based on remaining context window:
| Bracket | Remaining | Behavior |
|---|---|---|
| FRESH | 70%+ | Lean injection, trust recent context |
| MODERATE | 40-70% | Reinforce key context |
| DEPLETED | 15-40% | Heavy reinforcement, checkpoint progress |
| CRITICAL | <15% | Suggest compaction |
Configured in carl.json under config.context_brackets.
Log important decisions alongside rules. Decisions are per-domain and injected with relevant rules:
{
"id": "dev-001",
"decision": "Use PostgreSQL over SQLite for all new projects",
"rationale": "Need concurrent writes and JSON support",
"date": "2026-03-15",
"recall": ["database", "postgres", "sqlite"]
}CARL includes an MCP server with tools for runtime management. These are available in Claude Code once installed:
| Tool | Description |
|---|---|
carl_v2_list_domains |
List all domains with rule/decision counts |
carl_v2_get_domain |
Get full domain config and rules |
carl_v2_create_domain |
Create a new domain with recall keywords |
carl_v2_toggle_domain |
Enable/disable a domain |
carl_v2_add_rule |
Add a rule to a domain |
carl_v2_remove_rule |
Remove a rule by ID |
carl_v2_replace_rules |
Bulk-replace all rules in a domain |
carl_v2_log_decision |
Log a decision to a domain |
carl_v2_search_decisions |
Search decisions by keyword |
carl_v2_archive_decision |
Archive a decision |
carl_v2_stage_proposal |
Stage a rule proposal for review |
carl_v2_get_staged |
List pending proposals |
carl_v2_approve_proposal |
Approve a proposal into a domain |
carl_v2_get_config |
Get CARL config |
carl_v2_update_config |
Update config fields |
| Location | Scope | Use Case |
|---|---|---|
~/.carl/ |
All projects | Universal preferences |
./.carl/ |
Current project | Project-specific rules |
When both exist, project-level domains override global ones. The hook walks up the directory tree, merging scopes from global to local.
Use the MCP tools (Claude will call these for you):
"Create a TESTING domain with recall keywords: run tests, test coverage, write tests"
Or edit carl.json directly:
"TESTING": {
"state": "active",
"always_on": false,
"recall": ["run tests", "test coverage", "write tests"],
"exclude": [],
"rules": [
{ "id": 0, "text": "Always run the full test suite after changes", "added": "2026-03-23" }
],
"decisions": []
}If you have an existing v1 setup (flat files: manifest, domain files, context, commands):
# If installed via npm:
bash node_modules/carl-core/bin/migrate-v1-to-v2.sh --dry-run ~/.carl
bash node_modules/carl-core/bin/migrate-v1-to-v2.sh ~/.carl
# If cloned from GitHub:
bash bin/migrate-v1-to-v2.sh --dry-run ~/.carl
bash bin/migrate-v1-to-v2.sh ~/.carlThe migration tool:
- Parses all v1 files (manifest, domains, context brackets, star commands, decisions)
- Generates a complete
carl.json - Archives old files to
.carl/_v1-archive/(non-destructive) - Preserves all rules, decisions, and configuration
CARL has a companion: PAUL (Plan-Apply-Unify Loop).
| Tool | Purpose |
|---|---|
| CARL | Dynamic rule injection — how Claude behaves |
| PAUL | Structured development workflow — how work flows |
They complement each other:
- CARL loads PAUL rules when you're in a
.paul/project - PAUL enforces loop integrity (plan, apply, unify)
- CARL keeps PAUL rules out of context when not needed
Without CARL: PAUL rules would bloat every session. Without PAUL: Complex projects lack structure.
Together: lean context + reliable workflow.
Rules not loading?
- Check domain has
"state": "active"in carl.json - Verify recall keywords match your prompt
- Ensure hook is configured in
~/.claude/settings.json
Too many rules loading?
- Make recall keywords more specific
- Use exclude to block unwanted matches
- Split broad domains into focused ones
Context dedup active?
- CARL skips re-injecting rules when the signature hasn't changed
- Forces a full re-inject every 5 prompts
- Override with session config if needed
CARL is part of a broader Claude Code extension ecosystem:
| System | What It Does | Link |
|---|---|---|
| AEGIS | Multi-agent codebase auditing — diagnosis + controlled evolution | GitHub |
| BASE | Builder's Automated State Engine — workspace lifecycle, health tracking, drift prevention | GitHub |
| CARL | Context Augmentation & Reinforcement Layer — dynamic rules loaded JIT by intent | You are here |
| PAUL | Project orchestration — Plan, Apply, Unify Loop | GitHub |
| SEED | Typed project incubator — guided ideation through graduation into buildable projects | GitHub |
| Skillsmith | Skill builder — standardized syntax specs + guided workflows for Claude Code skills | GitHub |
| CC Strategic AI | Skool community — courses, community, live support | Skool |
Static prompts waste tokens on irrelevant rules. CARL loads only what's needed. More room for actual work.
CARL is transparent. See exactly which domains loaded, know why rules activated. No hidden behavior.
CARL provides structure, not opinions. The default domains are examples — customize or replace them entirely.
MIT License. See LICENSE for details.
Chris Kahler — Chris AI Systems
Building tools for AI-assisted development.
Claude Code is powerful. CARL makes it personal.