|
| 1 | +--- |
| 2 | +title: Beginners Guide |
| 3 | +description: New to AI Loadout? This page explains what it is, who it's for, and walks you through your first five minutes. |
| 4 | +sidebar: |
| 5 | + order: 99 |
| 6 | +--- |
| 7 | + |
| 8 | +## What is this tool? |
| 9 | + |
| 10 | +AI Loadout is a context-aware knowledge router for AI agents. When you give an AI agent a large set of rules, instructions, or domain knowledge, dumping everything into context every session wastes tokens and clutters the agent's attention. AI Loadout solves this by maintaining a lightweight **dispatch table** (always loaded) that routes the agent to topic-specific **payloads** (loaded on demand). |
| 11 | + |
| 12 | +The dispatch table is a JSON index where each entry has an ID, keywords, a priority tier, and a token estimate. When the agent receives a task like "fix the CI workflow," the matcher scores entries by keyword overlap and returns the relevant payloads -- in this case, your CI rules -- while leaving unrelated knowledge unloaded. |
| 13 | + |
| 14 | +The library also provides a hierarchical resolver that merges indexes across four layers (global, org, project, session), an agent runtime contract (`planLoad`) that wraps the full resolve-match-load sequence, and an observability layer for tracking which payloads actually get used. |
| 15 | + |
| 16 | +## Who is this for? |
| 17 | + |
| 18 | +AI Loadout is designed for: |
| 19 | + |
| 20 | +- **AI tool authors** building agents that need structured access to domain knowledge without overloading context windows |
| 21 | +- **Teams managing shared rules** across multiple projects who want a global/org/project layer hierarchy |
| 22 | +- **Claude Code users** who maintain large CLAUDE.md files and want to break them into routed, on-demand payloads |
| 23 | +- **Anyone building AI-powered CLI tools** that need to load the right instructions for the right task |
| 24 | + |
| 25 | +You do NOT need this if your agent's total instructions fit comfortably in a single prompt (under ~2,000 tokens). AI Loadout shines when you have tens of knowledge payloads that should be loaded selectively. |
| 26 | + |
| 27 | +## Prerequisites |
| 28 | + |
| 29 | +- **Node.js 20 or later** -- check with `node --version` |
| 30 | +- **npm** -- comes with Node.js |
| 31 | +- **TypeScript** is recommended but not required; the library ships compiled JavaScript with type declarations |
| 32 | + |
| 33 | +No native dependencies, no build tools, no database. It runs anywhere Node.js runs. |
| 34 | + |
| 35 | +## Your First 5 Minutes |
| 36 | + |
| 37 | +### 1. Install the package |
| 38 | + |
| 39 | +```bash |
| 40 | +npm install @mcptoolshop/ai-loadout |
| 41 | +``` |
| 42 | + |
| 43 | +Or install globally for the CLI: |
| 44 | + |
| 45 | +```bash |
| 46 | +npm install -g @mcptoolshop/ai-loadout |
| 47 | +``` |
| 48 | + |
| 49 | +### 2. Create a dispatch table |
| 50 | + |
| 51 | +Create a file at `.claude/loadout/index.json` in your project: |
| 52 | + |
| 53 | +```json |
| 54 | +{ |
| 55 | + "version": "1.0.0", |
| 56 | + "generated": "2026-01-01T00:00:00Z", |
| 57 | + "entries": [ |
| 58 | + { |
| 59 | + "id": "testing-rules", |
| 60 | + "path": ".rules/testing.md", |
| 61 | + "keywords": ["test", "jest", "vitest", "coverage"], |
| 62 | + "patterns": ["test_suite"], |
| 63 | + "priority": "domain", |
| 64 | + "summary": "Testing conventions and required coverage thresholds", |
| 65 | + "triggers": { "task": true, "plan": true, "edit": false }, |
| 66 | + "tokens_est": 400, |
| 67 | + "lines": 30 |
| 68 | + }, |
| 69 | + { |
| 70 | + "id": "never-skip-tests", |
| 71 | + "path": ".rules/core.md", |
| 72 | + "keywords": [], |
| 73 | + "patterns": [], |
| 74 | + "priority": "core", |
| 75 | + "summary": "Non-negotiable: every commit must include tests", |
| 76 | + "triggers": { "task": true, "plan": true, "edit": true }, |
| 77 | + "tokens_est": 120, |
| 78 | + "lines": 8 |
| 79 | + } |
| 80 | + ], |
| 81 | + "budget": { |
| 82 | + "always_loaded_est": 120, |
| 83 | + "on_demand_total_est": 400, |
| 84 | + "avg_task_load_est": 200, |
| 85 | + "avg_task_load_observed": null |
| 86 | + } |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +### 3. Match a task |
| 91 | + |
| 92 | +```typescript |
| 93 | +import { matchLoadout } from "@mcptoolshop/ai-loadout"; |
| 94 | +import { readFileSync } from "node:fs"; |
| 95 | + |
| 96 | +const index = JSON.parse(readFileSync(".claude/loadout/index.json", "utf-8")); |
| 97 | +const results = matchLoadout("add unit tests for the parser", index); |
| 98 | + |
| 99 | +for (const { entry, score, matchedKeywords, mode } of results) { |
| 100 | + console.log(`${entry.id}: score=${score}, mode=${mode}, matched=[${matchedKeywords}]`); |
| 101 | +} |
| 102 | +// never-skip-tests: score=1, mode=eager, matched=[] |
| 103 | +// testing-rules: score=0.25, mode=lazy, matched=[test] |
| 104 | +``` |
| 105 | + |
| 106 | +The core entry always appears (score 1.0, mode eager). The domain entry matched on the keyword "test" and got a score of 0.25 (1 out of 4 keywords matched). |
| 107 | + |
| 108 | +### 4. Use the agent runtime |
| 109 | + |
| 110 | +```typescript |
| 111 | +import { planLoad } from "@mcptoolshop/ai-loadout"; |
| 112 | + |
| 113 | +const plan = planLoad("add unit tests for the parser"); |
| 114 | +console.log("Preload:", plan.preload.map(m => m.entry.id)); |
| 115 | +console.log("On-demand:", plan.onDemand.map(m => m.entry.id)); |
| 116 | +console.log("Token cost:", plan.preloadTokens, "preload +", plan.onDemandTokens, "on-demand"); |
| 117 | +``` |
| 118 | + |
| 119 | +### 5. Validate your index |
| 120 | + |
| 121 | +```bash |
| 122 | +ai-loadout validate .claude/loadout/index.json |
| 123 | +``` |
| 124 | + |
| 125 | +This checks for structural issues: missing fields, duplicate IDs, non-kebab-case IDs, domain entries without keywords, summaries over 120 characters, and negative budget values. |
| 126 | + |
| 127 | +## Common Mistakes |
| 128 | + |
| 129 | +**Putting everything at `core` priority.** Core entries are always loaded regardless of the task. If you make everything core, you lose the benefit of on-demand routing. Reserve core for truly non-negotiable rules (3-5 entries max). |
| 130 | + |
| 131 | +**Forgetting keywords on domain entries.** Domain entries with no keywords can never be matched by the matcher. The `validate` command catches this as an error (`EMPTY_KEYWORDS`). |
| 132 | + |
| 133 | +**Using regex in patterns.** The `patterns` field contains named intents like `"ci_pipeline"` -- they are matched as plain string lookups against the underscore-split words, not as regular expressions. A pattern of `"ci_pipeline"` matches a task containing the word "ci" or "pipeline." |
| 134 | + |
| 135 | +**Huge payloads behind a single entry.** If one payload is 5,000 tokens and others are 200, the budget becomes misleading. Break large payloads into focused sub-topics with separate entries. |
| 136 | + |
| 137 | +**Hand-editing the budget numbers.** The `budget` object should reflect the actual token estimates from your entries. When adding or removing entries, update the budget totals accordingly, or use tooling (like `@mcptoolshop/claude-rules`) that regenerates them automatically. |
| 138 | + |
| 139 | +## Next Steps |
| 140 | + |
| 141 | +- Read [Concepts](/ai-loadout/handbook/concepts/) to understand priority tiers, the resolver layer stack, and merge semantics |
| 142 | +- Read [API Reference](/ai-loadout/handbook/reference/) for the full list of exports and CLI commands |
| 143 | +- Try `ai-loadout resolve` to see how the resolver discovers and merges your indexes |
| 144 | +- Try `ai-loadout explain <entry-id>` to trace how a specific entry resolves across layers |
| 145 | +- Explore the [CLI commands](/ai-loadout/handbook/reference/#cli) for budget analysis, dead entry detection, and keyword overlap reporting |
| 146 | + |
| 147 | +## Glossary |
| 148 | + |
| 149 | +| Term | Definition | |
| 150 | +|------|------------| |
| 151 | +| **Dispatch table** | The `LoadoutIndex` JSON structure containing entries and a budget. Always loaded into agent context as a lightweight routing index. | |
| 152 | +| **Payload** | A markdown file containing domain knowledge (rules, instructions, reference material). Loaded on demand when the matcher finds a keyword hit. | |
| 153 | +| **Entry** | A single row in the dispatch table (`LoadoutEntry`). Contains an ID, path to the payload file, keywords, patterns, priority, summary, triggers, and token estimate. | |
| 154 | +| **Priority** | One of `core` (always loaded), `domain` (loaded when keywords match), or `manual` (never auto-loaded, explicit lookup only). | |
| 155 | +| **Load mode** | How an entry enters context: `eager` (immediately, for core), `lazy` (on demand, for domain), or `manual` (explicit lookup only). | |
| 156 | +| **Layer** | One level in the resolver hierarchy: global (~/.ai-loadout/), org ($AI_LOADOUT_ORG), project (.claude/loadout/), or session ($AI_LOADOUT_SESSION). Later layers override earlier ones. | |
| 157 | +| **Resolver** | The module that discovers index files from canonical layer paths and merges them deterministically. | |
| 158 | +| **Provenance** | A mapping from entry ID to the layer name it came from. Answers "where did this rule originate?" | |
| 159 | +| **Frontmatter** | YAML-like metadata at the top of a payload file (between `---` delimiters). Contains id, keywords, patterns, priority, and triggers. The source of truth for routing metadata. | |
| 160 | +| **Budget** | Token estimates for context planning: always-loaded total, on-demand total, and average task load. Helps answer "how much context am I saving?" | |
| 161 | +| **Dead entry** | An entry that has never been loaded according to usage logs. Candidate for demotion to manual or removal. | |
| 162 | +| **Keyword overlap** | When multiple entries share the same keyword, creating routing ambiguity. Detected by `findKeywordOverlaps()`. | |
0 commit comments