| name | configure-grimoire |
| description | Use when the user wants to view, edit, remove, or validate their grimoire settings — including reading current preferences, changing or deleting a setting, switching a named profile, or checking settings.toml for contradictions and expired entries. |
| source | Settings management patterns (VS Code settings UI, Git config get/set/unset); XDG Base Directory Specification (freedesktop.org) |
| tags | ["settings","configuration","preferences","profile","toml","view","edit","validate"] |
Configure Grimoire
Read, update, or validate settings.toml — the single source of truth for all grimoire preferences and configuration.
Why This Is Best Practice
Adopted by: Every major developer tool provides a guided settings interface alongside raw file editing — VS Code settings.json + Settings UI, Git git config get/set/unset, npm .npmrc + npm config. Guided operations prevent syntax errors and silent overwrites that raw editing can introduce.
Impact: Configuration drift — where users forget what they set, or stale settings silently govern behavior — is one of the primary causes of "why is it doing that?" confusion. VS Code's settings validation (invalid key detection) reduced user-reported configuration bugs by catching errors at write time rather than at apply time. Explicit confirmation before destructive operations (delete, overwrite) is standard across all major CLI tools (git config --unset, npm config delete).
Why best: Manual TOML editing is error-prone (syntax, wrong key names, stale dates). A guided interface validates before writing, confirms before deleting, and surfaces the full settings cascade so the user knows which file actually governs a domain.
Sources: XDG Base Directory Specification (freedesktop.org); VS Code settings documentation; Git config documentation (git help config)
Steps
Step 1: Detect operation
| User signal | Operation |
|---|
| "show", "view", "what are my settings for X", "list my preferences" | show |
| "edit", "update", "change", "set X to Y" | edit |
| "remove", "delete", "unset", "clear" | remove |
| "add to", "append to", "add a profile", "add X to profiles/practices/disabled" | config-add |
| "remove from", "drop from", "remove from profiles/practices/disabled" | config-remove |
| "list presets", "show presets", "what presets exist" | preset-list |
| "switch to X profile", "use X profile", "activate profile" | switch-profile |
| "show context", "full state", "what's my setup", "grimoire context" | context |
| "set up MCP", "configure Claude Code", "add grimoire to AI assistant", "MCP config" | mcp-setup |
| "validate", "check settings", "any issues" | validate |
| "add registry", "remove registry", "list registries", "manage skill sources" | route to install-grimoire |
Step 2: Load settings
Grimoire-first (preferred): If grimoire CLI is available, run grimoire context (human) or grimoire settings for the merged view with per-field source attribution. grimoire settings shows section headers ([standards], [standards.X]) with active profiles automatically expanded to their resolved skill lists — no manual layer merging or profile resolution needed.
Fallback (grimoire not installed): Resolve the active settings by merging in order (highest wins):
<project>/.grimoire/settings.toml (local — committed, --local)
> ~/.config/grimoire/settings.toml (global — XDG primary, --global)
> /etc/grimoire/settings.toml (system — machine-wide, --system)
Within any file, cascade by specificity: [domain.subdomain] > [domain] > [global]
Step 3a: Show
Display the merged effective settings for the requested domain (or all domains):
Effective settings for engineering/architecture:
Source: .grimoire/settings.toml (project)
practices: ["SOLID principles: production code", "KISS: scripts, prototypes"]
fallback: "ask"
author: "@backend-team"
note: "agreed in ADR-014"
expires: "2026-09-01"
Active profile: (none — using default)
Overrides from: (no global entry for this domain)
Show which file each key came from if multiple files contribute.
Step 3b: Edit
TOML parse guard: If the target settings file exists but cannot be parsed as valid TOML (syntax error), stop immediately. Output: 'Settings file at [path] has a syntax error — cannot edit safely. Fix the TOML syntax first (e.g., unclosed quote, missing =, invalid array). Inspect with: cat [path].' Do not overwrite a malformed file.
Parse the requested change from user input. Show what will change, then ask which file to write to using a platform-aware prompt:
Note: Prefer grimoire config set <key> <value> for single-key changes. For list-type keys (profiles, practices, disabled), use grimoire config add/remove — these are idempotent and won't create duplicates:
grimoire config add standards.profiles engineering
grimoire config remove standards.profiles engineering
grimoire config add standards.engineering.practices "Google Engineering Practices"
grimoire config remove standards.engineering.practices "Google Engineering Practices"
Higher-precedence warning: Before writing to a settings file, check if a higher-precedence layer already sets this key. Precedence order (highest to lowest): session pins → .grimoire/settings.toml (local) → ~/.config/grimoire/settings.toml (global) → /etc/grimoire/settings.toml (system). If a higher-precedence layer already defines this key, the edit to the lower layer will have no effect. Warn: 'Note: [higher-layer] already sets [key]=[value]. Your change to [lower-layer] will be overridden until you remove or update the higher-precedence setting.'
After file selection, confirm and write. Never write invalid TOML.
Post-edit validate: After writing the settings change, offer: 'Validate settings now? This will show the resolved effective spec and confirm your change took effect. [y/n]'. If yes, invoke check-best-practice-compliance with scope=[current project] to show the resolved spec.
Step 3c: Remove
Ask which file to remove from using a platform-aware prompt:
After file selection, show what will be removed and ask key vs section using a platform-aware prompt:
If removing from the project file would expose a global default the user didn't intend, show the effective value after removal before confirming.
After confirmation, remove the key or section. If the domain section becomes empty, use a platform-aware confirm (Claude Code: AskUserQuestion; OpenCode: question — same schema as AskUserQuestion; Gemini: ask_user type: confirm; other: [y/n]) to ask whether to remove the section header too.
Step 3d: Config add / remove
For list-type keys, use add/remove instead of set — they are idempotent and preserve other list values:
grimoire config add <key> <value> [--global]
grimoire config remove <key> <value> [--global]
Supported list keys: standards.profiles, standards.<domain>.practices, standards.<domain>.disabled.
Show the effective list after the operation using grimoire config get <key>.
Step 3e: Preset list
grimoire preset list
Lists all presets from all installed registries. Presets are ready-made settings bundles — apply one with grimoire init --preset <name>.
Step 3f: Switch profile
Store the active profile for a domain in settings.toml (project) or global settings — use grimoire config set:
grimoire config set standards.engineering.architecture.active-profile prototype
grimoire config set standards.engineering.architecture.active-profile prototype --global
Confirm the switch:
Switched engineering/architecture to profile: prototype
Stored in: .grimoire/settings.toml (local, committed) or ~/.config/grimoire/settings.toml (global)
Active practices:
1. KISS
2. YAGNI
To reset to default: grimoire config unset standards.engineering.architecture.active-profile
Step 3e: Validate
Check the merged settings for issues:
| Check | Issue |
|---|
require + disabled overlap | Contradiction — skill can't be both required and disabled |
expires date < today | Preference has expired — flag for review or removal |
remind date ≤ today | Reminder due — surface to user |
| Unknown key names | Typo in key name — flag |
[domain.profiles.X] referenced but no matching profile | Profile defined but never activated |
Output:
Validating settings files...
.grimoire/settings.toml (local)
⚠️ engineering/architecture: expires "2026-09-01" is past — still apply? (platform-aware confirm: Claude Code `AskUserQuestion` with "Keep" and "Remove"; OpenCode `question` — same schema as `AskUserQuestion`; Gemini `ask_user type: confirm`; other `[keep / remove]`)
❌ engineering/testing: "apply-tdd" is in both require and disabled — contradiction
✅ engineering/development: OK
~/.config/grimoire/settings.toml (global)
✅ global: OK
1 error, 1 warning across 3 files. Fix errors before conflicts can be resolved correctly.
Step 3f: Context
Run grimoire context to show the full ground truth in one shot — installed agents, resolved settings with source attribution, active profiles with expanded skill lists, compliance status, and structural rule findings.
grimoire context # human-readable
grimoire context --json # machine-readable JSON
Output includes a project: line showing the resolved project directory (useful when --project-dir or GRIMOIRE_PROJECT_DIR is set).
Via MCP: call grimoire_context tool — available to any AI assistant configured with grimoire mcp serve.
Step 3g: MCP setup
Configure the AI assistant to connect to grimoire natively via MCP:
-
Run: grimoire mcp config --target <assistant>
Supported targets: claude, cursor, windsurf, cline
-
Add the printed config snippet to the assistant's MCP config file. Example for Claude Code (~/.claude/mcp.json or .claude/mcp.json):
{
"mcpServers": {
"grimoire": {
"command": "grimoire",
"args": ["mcp", "serve"]
}
}
}
If the AI assistant runs outside the project root (common with desktop apps), pin the project directory so grimoire reads the right settings and compliance reports:
{
"mcpServers": {
"grimoire": {
"command": "grimoire",
"args": ["--project-dir", "/absolute/path/to/project", "mcp", "serve"]
}
}
}
Alternatively, set GRIMOIRE_PROJECT_DIR=/absolute/path/to/project in the assistant's environment config.
- Restart the assistant. All 29 grimoire MCP tools are now available (see
install-grimoire for the full tool list).
When NOT to Use
- Adding a new preference from scratch: use
pin-best-practice-preference — it guides the full pin flow with scope selection.
- Resolving conflicts between skills: use
resolve-best-practice-conflict — it loads both SKILL.md files, identifies the specific contradiction, and updates priorities.
- Installing or upgrading grimoire: use
install-grimoire.
Common Mistakes
Editing the wrong file: always confirm which file (local, global, system) before writing. A setting in .grimoire/settings.toml commits to repo (--local). Personal settings belong in --global.
Removing without checking cascade: deleting a key from the project file may expose a global default the user didn't intend. Show the effective value after removal before confirming.
Profile confusion: active-profile is personal — use --global flag to keep it out of the committed project file.
