Magicite helps your AI agent find and load useful project instructions through a local MCP server. Keep skills with your project, review what the agent loads, and let your host execute the instructions.
What it does · Get started · Harness integration · For skill authors · For LLM builders · Docs
As an LLM project grows, useful instructions spread across prompt files, agents, and personal notes. Magicite gives those instructions a local registry and an MCP interface. The host can ask for a route, inspect the decision, and load a selected skill's body with current content and policy digests.
This is useful when you want to:
- Keep reusable task instructions in versionable files alongside a project.
- Give an LLM host a structured way to find and load relevant instructions.
- Review the exact content before trusting an imported skill.
- Record use and outcomes, then inspect proposed lifecycle changes.
- Experiment with skill composition while keeping stable routing as the default.
Magicite is a routing and governance layer. It does not execute skill instructions, grant the host new permissions, or guarantee better answers. The agent host remains responsible for interpreting instructions and for its own tools, permissions, and sandbox.
Magicite 1.0.0 is available on PyPI. It supports Python 3.11 and 3.12. Install it in a permanent environment that your MCP host can run:
python3.12 -m venv "$HOME/.local/share/magicite/venv"
"$HOME/.local/share/magicite/venv/bin/python" -m pip install magicite==1.0.0
"$HOME/.local/share/magicite/venv/bin/magicite" --versionFor Python 3.11, substitute python3.11. Keep the environment at a stable
absolute path; your host configuration will call its magicite executable.
For artifact and provenance verification, see Install.
Magicite requires Python 3.11+ for the installer, network access during setup, and an existing project directory. Clone the repository and run the supported installer from its checkout:
git clone https://github.com/Rynaro/magicite.git
cd magicite
python3 scripts/install_magicite.py --package . --project-root /absolute/path/to/your-projectThe installer prepares a persistent project runtime in .magicite/venv, then
runs the full first-install pipeline: a pinned protected Python runtime, a
dedicated custodian service identity, reviewed policy enrollment, service
startup, authority journal initialization, embedding model fetch, registry
index sync, a real stdio MCP check, and harness activation. It requests administrator authorization through sudo for the protected service setup; you do
not need to create custody files or service accounts by hand. Setup downloads
the runtime and dependencies and fetches the embedding model, so allow network
access and disk space for these assets.
For a new enrollment, the installer prints the exact baseline policy and its
SHA-256 digest, then asks you to approve those bytes. For unattended setup, pass
--accept-default-policy to explicitly accept that baseline. Existing
protected enrollment and its policy are retained when you rerun the installer.
Automated service installation supports macOS with launchd and glibc Linux with
systemd on x86_64 and aarch64. Linux containers without systemd, musl Linux, and
other operating systems are unsupported by this installer. To install from a
built wheel instead of this checkout, set --package /path/to/magicite.whl.
Choose a single harness with --harness claude, --harness codex, or
--harness opencode; the default is all three. The package channel shown in
this README does not imply that a release containing the installer is
published.
The installer verifies that the MCP server starts and exposes its routing methods, then writes the project harness configuration. The harness still needs to trust or approve the local MCP server and reload its session. That native harness approval is the final user step. The installer reports an empty registry as operational with zero skills; add or import skills before routing can return any.
For existing installations managed outside the project installer, magicite setup --project-root PATH remains a configuration-only operation. It writes
harness files but does not install protected custody, start its service, fetch
the model, sync the index, or verify an MCP connection. See the
custody operator guide for the manual and recovery
procedures.
For Claude Code's optional Tier-2 hooks, see the host adapter guide. MCP integrations work without those hooks.
The supported v1 operating profile is Linux with protected project custody.
An administrator sets up a separate custodian identity and protected authority
for the project before the project connects. This keeps edits in the project
from silently granting trust or changing protected policy. It is a prerequisite
for use, not something magicite init installs for you.
-
Ask a Linux administrator to follow Setup for the project. It provisions custody and initializes the project's journal.
-
In that enrolled project, fetch the model and connect Claude Code:
cd /absolute/path/to/project /absolute/path/to/magicite/venv/bin/magicite init --host claude --fetch-model--fetch-modelauthorizes downloading the default embedding model. Omit this flag if the model is already cached for the same client account and environment. You can also provide the canonical project path with--project-root /absolute/path/to/project. -
Reconnect Claude Code, then follow Quick Setup to register a skill, review it, and try a route.
init checks existing custody, runs a local model inference, merges the
Magicite MCP entry and its marked instruction block, and checks the local MCP
connection. It does not provision custody, approve skills, or promote drafts.
An optional --fetch-model flag authorizes model download only. Keep the
default human-review mode; approval of an imported draft does not by itself
make that draft eligible for routing.
After Quick Setup has connected the host and you have a reviewed, eligible skill, ask your assistant something like:
Use Magicite to find instructions for reviewing this change. Show me the route result, then load the selected skill using the returned content and policy digests before following it.
Magicite may select a skill or abstain. Review the selection and the loaded content in your host before it acts. Abstention is a valid outcome when no eligible skill is a good fit.
OpenCode's installed major version selects its configuration layout. V1 uses
mcp.magicite and instruction references; V2 uses mcp.servers.magicite and an
auto-loaded AGENTS.md block because V2 ignores the instructions list.
Owned V1 entries upgrade during setup. The shared instruction block remains
while either Codex or OpenCode V2 is enabled. See the official
V2 MCP configuration and
V2 instructions.
Integrations are project-scoped and enabled by default when you run setup. You can deactivate or restore a harness at any time:
The project installer keeps its executable in .magicite/venv; use it explicitly
(or activate that venv).
/absolute/path/to/your-project/.magicite/venv/bin/python -m magicite harness status \
--project-root /absolute/path/to/your-project
/absolute/path/to/your-project/.magicite/venv/bin/python -m magicite harness disable \
--project-root /absolute/path/to/your-project --harness codex
/absolute/path/to/your-project/.magicite/venv/bin/python -m magicite harness enable \
--project-root /absolute/path/to/your-project --harness codexUse --harness all (the default) to apply an action across Claude Code, Codex,
and OpenCode. A disabled harness stays disabled through later magicite setup
runs; harness enable reverses that opt-out. Status describes integration
files on disk, not whether a harness has approved or loaded the server.
Engrams are human-readable Markdown files. In engram/1.0, the front matter
names the skill and describes what it does, when it applies, and which typed
capabilities it requires or produces. The body contains the procedure. Start
with the beginner native v1 example and the
format guide when authoring your own.
The router binds its v1 routing view to a digest of the body. Finish edits
before reviewing the current content digest; a file's own trust fields do not
approve it.
The newcomer path in Quick Setup shows registration,
human digest review, approval, routing, and loading. It also explains importing
existing SKILL.md files. Those imports can start as drafts and need lifecycle
preparation after approval.
The stable dense-v1 policy ranks eligible skills using their canonical
routing content and applies typed eligibility, contraindication, and bounded
composition rules. It is the default and remains nonadaptive: learned weights
and Dream consolidation do not silently change its ordering.
Magicite also records session-scoped use and outcome signals. Its resumable Dream workflow consolidates durable skill and relationship changes through reviewable lifecycle operations. This makes behavior inspectable; it does not establish that graph composition or learning improves retrieval quality. Adaptive policies are experimental and are not the stable default.
The 16 MCP tools fall into five practical groups:
| Use | Tools |
|---|---|
| Retrieve and inspect | route, load_skill_body, introspect, flag_dead |
| Record signals | signal_use, signal_outcome, session_end |
| Manage the registry | register, sync, checkpoint, export |
| Govern lifecycle | nucleate, sharpen, promote, archive |
| Consolidate evidence | consolidate |
See the generated runtime reference for tool schemas, and Protocol and signals for the behavior behind them. The MCP server uses stdio; host-specific hooks can improve signal capture but are optional.
At the protocol level, a typical client first calls route with a query and
session ID. If the result is selected, it takes the selected skill name,
content digest, and policy digest from that response and passes them to
load_skill_body at level L2. This binds the loaded procedure to the
decision the client just inspected. The exact request fields and stale-decision
handling are shown in Quick Setup.
The project stores portable engrams and a local SQLite index under
.magicite/. The index can be rebuilt from source files, but it is only one
part of project state: approvals, evidence, policy, protected trust authority,
and custody history have separate recovery requirements. Do not treat a copy
of the database or the engram files alone as a complete backup; see
Operations.
Autonomous approval is off by default. Keep it off and review imported content by digest. Magicite's MCP tools do not expose arbitrary shell, SQL, or filesystem access, and skill bodies remain instructions for the host rather than code Magicite runs. See Trust and governance for the detailed model.
Magicite 1.0.0 is published on PyPI, as wheel and source artifacts on GitHub Releases, and as a signed multi-architecture OCI image. The release delivers the local MCP workflow, protected lifecycle controls, and recovery mechanisms described above.
The release does not claim improved retrieval quality, a validated scale or performance envelope, production adoption, or independent security certification. These remain qualification work; see the release record and post-v1 issues. Production macOS custody is also unqualified; use the documented Linux profile.
The OCI image is a distribution option, not a custody installer. For signature, digest, and deployment guidance, use the release page and Operations.
| If you want to… | Read… |
|---|---|
| Follow the end-to-end first steps in a project | First steps with Magicite |
| Install the published package | Install |
| Provision a project before use | Setup |
| Connect a host and try a skill | Quick Setup |
| Understand the system design | Architecture |
| Learn routing, signals, and Dream | Learning model |
| Author or migrate engrams | Engram format |
| Read MCP contracts and signal tiers | Protocol and signals |
| Review trust, approvals, and recovery | Trust and governance and Operations |
| Understand evidence and open hypotheses | Evaluation and Authority |
| Find the full document map | Documentation index |
This repository uses uv for development:
uv sync --all-extras
uv run magicite toolsFor project conventions and the generated documentation contract, start with AGENTS.md and EIDOLONS.md. The changelog and GitHub Releases track changes.
Magicite is available under the Apache License 2.0.