grimoire-kit

The governed operating system for AI agents in your IDE — verify, don't trust.

_{English — version française (complète)}

Quick Start • Governed Standard • Architecture • Features • Full guide • Changelog

Why Grimoire Kit?

AI coding assistants run on trust: you hope the agent kept its guardrails, remembered the context, and produced evidence for what it claims. Grimoire Kit replaces that hope with verifiable governance:

A governed agentic standard — 36 declarative patterns (security, memory, context, observability, quality…) verified fail-closed by grimoire standard verify / audit / score / gate check. If a required proof is missing, the gate fails.
Agent teams with personas and semantic memory — specialized agents, persistent memory across sessions, delivery contracts, quality automation.
One config, every assistant — grimoire init generates portable entrypoints (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules) plus a .mcp.json, so the same project works with Copilot, Claude Code, Codex, Gemini CLI and Cursor.
Native on each host, not lowest-common-denominator — one host-neutral description of the project is rendered per host: sub-agents with their own context window and tool boundary, on-demand skills, slash commands, and lifecycle hooks that actually refuse a destructive call, or the closure of a task whose evidence gates are red. What a host cannot execute is reported as an explicit degradation, never dropped in silence. See grimoire host --help and docs/hosts.md.

Quick Start

Animated demo: grimoire init, standard init --needs, verify OK, compliance score 81/70, gate check OK

# Install (uv recommended)
uv tool install grimoire-kit

# Or with pipx
pipx install grimoire-kit

# One command: init + identity + governed standard + health check
grimoire up my-project --archetype web-app

# Existing project (idempotent — re-running only fills the gaps)
cd your-project/
grimoire up . --name "My Project"

# Detect and enroll existing projects on your machine
grimoire cockpit scan ~/dev

# Health check + repair (regenerates missing wrappers and .mcp.json)
grimoire doctor . --fix

# Local multi-project dashboard (background + browser)
grimoire cockpit

Step-by-step path (what grimoire up chains for you)

grimoire init . --name "My Project"   # scaffold: context, agents, memory, entrypoints
grimoire setup                        # propagate identity into instructions
grimoire standard init . --needs ...  # governed standard artifacts
grimoire doctor                       # health check

Multi-assistant — grimoire init writes portable assistant entrypoints pointing to a single canonical instruction file, and registers the Grimoire MCP server in .mcp.json (OS-neutral, via grimoire-mcp). No per-assistant duplication.

The governed agentic standard

Declare what your project needs; Grimoire resolves a maturity profile (starter → controlled → orchestrated → governed → production) and activates governed patterns — 36 in the catalog. Each pattern scaffolds a declarative artifact (_grimoire/standard/*.yaml) and a fail-closed check:

grimoire standard needs                        # needs grouped by tier, with footprint
grimoire standard plan --needs solo-prototyping  # preview without writing anything
grimoire standard init . --needs solo-prototyping # minimal recommended start
grimoire standard init . --interactive         # guided setup

grimoire standard verify       # artifacts present + conform to the profile
grimoire standard audit        # compliance report + remediation actions
grimoire standard score        # multi-dimensional compliance score
grimoire standard gate check   # CI gate: fails when required evidence is missing

Example controls: tool blast-radius limits, controller/agent privilege separation, prompt-injection firewall, decision council, memory integrity, LLM cost registry + reliability SLO, guardrail contracts (input/output/tool/model), visual evidence, workspace isolation, per-environment policies.

Reference: governed controls (36 patterns) · standard integration · install by needs

Architecture

Three layers, one wheel (pip install grimoire-kit):

Layer	What it provides
SDK Python (`src/grimoire/`)	`grimoire` CLI (Typer), governed standard engine, memory manager with pluggable backends, MCP server, archetype registry
Shell framework (`framework/`)	108 standalone Python tools (agent lifecycle, quality, orchestration), lifecycle hooks, prompt templates
Archetypes (`archetypes/`)	Pre-configured agent packs: `web-app`, `infra-ops`, `platform-engineering`, `creative-studio`, `fix-loop`, `minimal`…

Details in ARCHITECTURE.md.

Features

Feature	Description
Team of Teams	Vision / Build / Ops agent teams with delivery contracts between them
Semantic memory	Qdrant vector search with JSON fallback; contradiction detection, consolidation, failure museum
Completion contract	`cc-verify.sh` detects the stack and verifies build + tests + lint before anything is called "done"
Local cockpit	Packaged local dashboard for all your Grimoire projects: portfolio, cost/trace observability, governed memory management (`127.0.0.1` only)
Boomerang orchestration	The orchestrator decomposes, delegates to sub-agents in parallel, aggregates results
MCP server	12 tools exposed to any MCP client — including the governed standard itself

Experimental R&D features (session branching, agent darwinism, stigmergy, dream mode…) are documented separately in docs/rnd.md — functional and tested, but exploratory surface.

CLI, SDK and MCP

grimoire init | doctor | status | up | validate     # project lifecycle
grimoire add <agent> | remove <agent> | registry    # agents & archetypes
grimoire standard …                                 # governed standard (see above)
grimoire cockpit …                                  # local dashboard daemon
grimoire memory …                                   # governed memory operations

from pathlib import Path
from grimoire.tools import PreflightCheck

report = PreflightCheck(Path(".")).run()
print(report.status)  # GO / GO-WITH-WARNINGS / NO-GO

MCP server (grimoire-mcp, stdio) exposes 12 tools: project_context, status, agent_list, config, harmony_check, memory_store, memory_search, add_agent, standard_verify, standard_audit, standard_score, standard_gate — agents can query and enforce the governed standard directly.

Quality

5 990+ tests (pytest), coverage gate ≥ 70 % (Codecov)
mypy strict on the SDK, ruff lint + format
CI matrix: Ubuntu / Windows / macOS × Python 3.12 / 3.13, CodeQL, dependency audit with governed, time-boxed waivers
Releases: SBOM (CycloneDX), smoke tests, PyPI trusted publishing (OIDC)

Documentation

Getting started · Concepts · SDK guide · CLI reference · MCP integration · FAQ — full docs (French) on the documentation site.

Contributing & License

Contributions welcome — see CONTRIBUTING.md. MIT — see LICENSE.

Release files for grimoire-kit 3.43.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for grimoire-kit 3.43.1
File	Size	Uploaded
grimoire_kit-3.43.1.tar.gz	3.8 MB	Sep 11, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for grimoire-kit 3.43.1
File	Interpreter	ABI	Platform	Reset
grimoire_kit-3.43.1-py3-none-any.whl 4.2 MB Sep 11, 2026	Python 3	none	any	Details

Total release size: 8.0 MB

Release files / grimoire_kit-3.43.1.tar.gz

Download URL	grimoire_kit-3.43.1.tar.gz
Size	3.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`f012d65b1b8a044fe9ffe2b4896ba1cf359df8a89b8b6625e29c7b61471bb777`
BLAKE2b-256 checksum How to use checksums	`2f78c0b6f41e78d9d1a7b6adaaef88ef0b251c2690c4d683cb73ab9ea5b0502b`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Guilhem-Bonnet/Grimoire-kit
Publishing commit: github.com/Guilhem-Bonnet/Grimoire-kit/tree/1b65f68509ef97211cb173c00d0b7c4407f8b338

Workflow

Publishing configuration: github.com/Guilhem-Bonnet/Grimoire-kit/blob/1b65f68509ef97211cb173c00d0b7c4407f8b338/.github/workflows/publish.yml
Publishing logs: github.com/Guilhem-Bonnet/Grimoire-kit/actions/runs/34613774277/attempts/1

Artifact

Subject: grimoire_kit-3.43.1.tar.gz
SHA-256 checksum: f012d65b1b8a044fe9ffe2b4896ba1cf359df8a89b8b6625e29c7b61471bb777 Verifying attestations

Release files / grimoire_kit-3.43.1-py3-none-any.whl

Download URL	grimoire_kit-3.43.1-py3-none-any.whl
Size	4.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`feeba367ba879198fb95baffead8ffe820f6dc3fc7f9052ad2bc0c4b385fdd43`
BLAKE2b-256 checksum How to use checksums	`221b5125c02e0b3f7ed811be3fc795e69406e139f119dca0ab9b7a0577a16291`
Upload date	Sep 11, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Guilhem-Bonnet/Grimoire-kit
Publishing commit: github.com/Guilhem-Bonnet/Grimoire-kit/tree/1b65f68509ef97211cb173c00d0b7c4407f8b338

Workflow

Publishing configuration: github.com/Guilhem-Bonnet/Grimoire-kit/blob/1b65f68509ef97211cb173c00d0b7c4407f8b338/.github/workflows/publish.yml
Publishing logs: github.com/Guilhem-Bonnet/Grimoire-kit/actions/runs/34613774277/attempts/1

Artifact

Subject: grimoire_kit-3.43.1-py3-none-any.whl
SHA-256 checksum: feeba367ba879198fb95baffead8ffe820f6dc3fc7f9052ad2bc0c4b385fdd43 Verifying attestations