<div align="center">

CARL

Context Augmentation & Reinforcement Layer — Dynamic rules for Claude Code.

<br>

npx carl-core

Works on Mac, Windows, and Linux.

<br>

<br>

"Rules that load when relevant, disappear when not."

<br>

Why CARL · Getting Started · How It Works · Core Concepts · MCP Tools · Migration

</div>

---

Why CARL

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:

1. Rules load when relevant — Mention "fix bug" and your development preferences appear
2. Rules disappear when not — Your context stays lean
3. 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.

---

Who This Is For

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.

---

Getting Started

npx carl-core

The installer prompts you to choose:

1. Global (recommended) — Rules apply to all Claude Code projects (~/.claude + ~/.carl)
2. Local — Rules apply to current project only (./.claude + ./.carl)

Restart Claude Code after installation.

What Gets Installed

~/.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

Staying Updated

npx carl-core@latest

---

How It Works

You 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.

Architecture (v2)

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.

---

Core Concepts

Domains

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.

Star-Commands

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"
  ]
}

Context Brackets

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.

Decisions

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"]
}

---

MCP Tools

CARL includes an MCP server with tools for runtime management. These are available in Claude Code once installed:

v2 Tools (carl.json)

| 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 |

---

Configuration

Global vs Local

| 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.

Creating a Domain

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": []
}

---

Upgrading from v1

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 ~/.carl

The 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 + PAUL

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.

---

Troubleshooting

Rules not loading?

1. Check domain has "state": "active" in carl.json 2