CARL-Qwen Context Augmentation & Reinforcement Layer — Dynamic rules for Qwen Code.

npx carl-qwen

Works on Mac, Windows, and Linux.

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

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

Why CARL

Every Qwen 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 QWEN.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: Qwen remembers how you work without wasting context on rules you don't need right now.

Who This Is For

Qwen 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 Qwen, CARL is for you.

Getting Started

npx carl-qwen

The installer prompts you to choose:

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

Restart Qwen 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
        ├── domains.js      # Domain management
        └── staging.js      # Rule proposal pipeline

~/.qwen/
├── hooks/carl-hook.py  # The injection engine
└── settings.json       # Hook registration

~/.mcp.json             # MCP server registration

Staying Updated

npx carl-qwen@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           │
└───────────────────────┘
│
▼
Qwen 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 Qwen 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 (Qwen 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": []
}

Troubleshooting

Rules not loading?

1. Check domain has "state": "active" in carl.json
2. Verify recall keywords match your prompt
3. Ensure hook is configured in ~/.qwen/settings.json

Too many rules loading?

1. Make recall keywords more specific
2. Use exclude to block unwanted matches
3. 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

Philosophy

Lean Context

Static prompts waste tokens on irrelevant rules. CARL loads only what's needed. More room for actual work.

Explicit Over Magic

CARL is transparent. See exactly which domains loaded, know why rules activated. No hidden behavior.

Your Rules, Your Way

CARL provides structure, not opinions. The default domains are examples — customize or replace them entirely.

License

MIT License. See LICENSE for details.

Author

Chris Kahler — Chris AI Systems Adapted for Qwen Code by tylergriffin1350

Qwen Code is powerful. CARL makes it personal.