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

The project-discovery need scaffolds a guided five-phase product cadrage (_grimoire/cadrage/: brief → brainstorm → understanding → requirements → spec) and turns its completeness into a standard verify gate. Details: docs/cadrage.md.

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 · Cadrage · 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.54.0

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.54.0
File	Size	Uploaded
grimoire_kit-3.54.0.tar.gz	4.1 MB	Sep 17, 2026	Details

Built distribution (wheel)

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

Total release size: 8.6 MB

Release files / grimoire_kit-3.54.0.tar.gz

Download URL	grimoire_kit-3.54.0.tar.gz
Size	4.1 MB
Tags	Source
SHA-256 checksum How to use checksums	`c66216ad1ec69f624655a37df24076b13813cc9f0a44e8a0763ee40433af485f`
BLAKE2b-256 checksum How to use checksums	`47f47a920e6351c9098b99ef8779e2d6dca7379144f9d899777e57b58f0e58e3`
Upload date	Sep 17, 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/d6b3072ae41f586c6b9c056aec97183e6d5190ed

Workflow

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

Artifact

Subject: grimoire_kit-3.54.0.tar.gz
SHA-256 checksum: c66216ad1ec69f624655a37df24076b13813cc9f0a44e8a0763ee40433af485f Verifying attestations

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

Download URL	grimoire_kit-3.54.0-py3-none-any.whl
Size	4.4 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`58def417c31b869f4e3376f9d3bd7605435382a16e2ea3463e24b709f0858dec`
BLAKE2b-256 checksum How to use checksums	`687d160e3c4b7d4a980b5b141c91abf97d3462d612e207de1d50848e3b349c1c`
Upload date	Sep 17, 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/d6b3072ae41f586c6b9c056aec97183e6d5190ed

Workflow

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

Artifact

Subject: grimoire_kit-3.54.0-py3-none-any.whl
SHA-256 checksum: 58def417c31b869f4e3376f9d3bd7605435382a16e2ea3463e24b709f0858dec Verifying attestations