Lode MCP server

Lode

English | 한국어 | Documentation | 한국어 문서

Lode keeps a project's agreed direction, the reasons behind changes and the remaining work in project records, so a later AI conversation continues from them instead of from an old chat's memory. It works with Codex, Claude Code and OpenCode, restores saved work after compaction and finds the context a task needs through a bounded project graph. Use it when a project lasts longer than one conversation.

Beta. See the changelog and installation guide. Local .lode records stay outside plugin packages.

First request · Install · Daily use · Recovery

Quick start

Codex:

codex plugin marketplace add binary1215/lode --ref lode-codex-marketplace
codex plugin add lode-agent-core@lode-agent-plugin

Claude Code:

claude plugin marketplace add binary1215/lode@lode-claude-marketplace
claude plugin install lode-agent-core@lode-agent-plugin

Restart the client, open your project and put your real task in the first request:

Use Lode Agent Core for this project. Resume its existing state if one exists;
otherwise initialize the Core. Then find the cause of this login failure and fix it.

Terms such as Project, Session, Checkpoint and Canon are defined in the glossary. OpenCode, the optional CLI and existing HEAD installations are covered under Install.

Why use it · Who it is for · How to use it · Install · Advanced use · Core model · Graph · Capabilities · Docs

What Lode Agent Core does

Lode records the agreed goal, the evidence behind changes and what remains to do. Later conversations can read those project records instead of relying on the old chat's memory.

Use your coding agent in Codex, Claude Code or a configured OpenCode workspace. There is no separate application to operate.

Why use it

It is most useful when the project lasts longer than one conversation.

Continue after compaction or session loss

Continue from the saved purpose, decisions, progress and next step. Recovery checks current constraints, and a newer user request wins over an older continuation. Lode saves checkpoints at meaningful changes or handoffs. Short investigations can retain selected reasons and uncertainty without a Run or checkpoint; neither needs a record on every turn.

Recovery covers recorded work direction, so unsaved conversation may be lost. Supported Hooks can supply bounded prompt/final-response references as quoted P5 context. They are neither a full transcript nor proof of current approval. Host support differs; see Compaction recovery, Session recovery and Session work context and Host support.

Continue in a new folder or on another computer

Ask Lode to move the selected project records with you. It preserves the chosen Session and current shared constraints, keeps destination settings, and leaves completed effects alone. Optional Codex native history has a separate, narrowly measured restore path; see Project portability.

Give each task bounded, reviewable context

Describe the change. Lode reads the repository and selects the code and decision evidence it needs. When a context handoff is useful, the Context Compiler packs that material and reports exclusions and uncertainty. Keyword overlap does not prove relevance. You do not fill in evidence forms or manage budgets, and the compiler does not certify inclusion or semantic sufficiency. See Context Compiler.

Review why a change happened

Git shows changed bytes. Lode also keeps the intended outcome, permitted scope, checks, review and next step. In managed work, a worker result cannot approve itself: independent review and the explicit decision stay separate. See Execution Lineage and ChangeSets.

Inspect recorded reasons and cited source differences in the recorded context view, or ask Lode for a local, read-only Graph Explorer snapshot. Citations and nearby nodes do not by themselves prove what caused a change.

Connect product intent to code and tests

Trace reviewed product concepts to files, symbols and tests, then inspect suggested change impacts. Inferred meaning stays a candidate until the user accepts it. See Feature mapping.

Additional benefits

Optional workflows record Git and deployment evidence, product-specific observations, policy drift and measurements. Collected data does not become a product decision on its own, and a missing connector does not block ordinary coding. Built-in analytics and production-database connectors are not all provided. See the capability list and documentation.

Who it is for

If you…	Lode helps you…
Build a product over many AI conversations	Continue without re-explaining its direction each time.
Maintain a large or long-lived repository	Find the evidence needed for a change, including earlier decisions.
Coordinate teammates or several workers	Keep ownership, results and review distinct while integrating one outcome.
Switch between Codex, Claude Code and OpenCode	Keep project records independent of a provider conversation.

For a one-off script or a short experiment where chat history is enough, you may not need it. Lode does not make model output automatically trustworthy, and a graph or database is not the authority for what the product should mean.

Install

Requires Node.js 24 or newer. Use the commands for the client you already use.

Choose the path for your tool. The Codex and Claude Code packages include the conversation Skill, MCP server and verified native bundle for supported hosts. Only the matching host binary runs. OpenCode uses the project setup below; the CLI is optional for ordinary conversation.

Install for Codex · Install for Claude Code · Set up OpenCode

Installation puts files in place. Project initialization/resume connects the chosen repository; optional instruction linking preserves your existing text. The agent checks Host tool loading separately. A package version or generated file alone does not prove that the Host loaded it. You do not need another doctor/setup step before starting ordinary work.

New installations use lode-agent-core@lode-agent-plugin. Already using HEAD? Keep updating your existing installation; no second plugin or project-record conversion is needed. The MCP server is named lode.

If Host permissions or automation name mcp__head_core__... or mcp__lode_core__..., they do not migrate through the Core's head_* aliases. After loading an update, inspect the Host's actual MCP tool list for server lode and use those exact names when updating your own rules. Preserve the existing configuration and running connection until you choose to change them; a disk update alone does not reload the Host. See the MCP-name details.

Codex Git marketplace

Intermediate betas use verified marketplace publication; Git tags are reserved for separately designated releases. See the changelog and publication policy.

The repository is binary1215/lode. Its Lode marketplace is published on lode-codex-marketplace; the former repository URL still redirects here.

codex plugin marketplace add binary1215/lode --ref lode-codex-marketplace
codex plugin add lode-agent-core@lode-agent-plugin

Restart Codex after installation, start a new task so the installed Skill and MCP server are loaded, then use the first-request example with your own task. Codex still will not run Lode hooks until you trust them: open /hooks in the CLI, or Review hooks / Settings > Hooks in the desktop app. Trust the project as well, or project-local .codex layers stay unloaded. lode doctor <project> reports whether that trust record is present.

Installing the plugin does not initialize a project, contact GraphDB, choose a model or approve Product Canon. Those operations still use the typed Core boundary and require explicit user review where consequential.

Claude Code Git marketplace

claude plugin marketplace add binary1215/lode@lode-claude-marketplace
claude plugin install lode-agent-core@lode-agent-plugin

Restart Claude Code after installation so the installed Skill and lode MCP server are loaded, then use the first-request example with your own task.

Claude Code copies the plugin into its versioned cache and locates the MCP entry through ${CLAUDE_PLUGIN_ROOT}. The source Core and existing Project identities stay unchanged. Installation alone does not authorize project changes, Product Canon review, GraphDB access or a model choice.

Claude Code and OpenCode project projections

When using the user-scoped installation below, initialize the project with --runtime opencode for OpenCode or --runtime claude for Claude Code. Use --runtime codex for Codex; combine these only if you want multiple integrations. Marketplace-installed Claude Code users can request the same initialization through the bundled Skill. Lode creates CLAUDE.md, AGENTS.md, and opencode.json only when you pass --write-root-instructions (or MCP write_root_instruction_files: true). The same opt-in works on later init/resume and distribution install --project. Without it, generated OpenCode configuration is guidance, not an active connection. A verified plugin MCP connection avoids a duplicate project .mcp.json. Standalone Claude uses the verified selected installation launcher, with an exact local package fallback. No new environment-variable setup is required. Existing files are preserved and generated manual-integration projections remain under the selected root's .lode/generated/ or existing .head/generated/ directory.

OpenCode's local configuration names node and {env:LODE_PLUGIN_ROOT} rather than an absolute Node binary or install path. Claude Code uses ${CLAUDE_PLUGIN_ROOT}; Codex uses the plugin-relative .mcp.json and ${PLUGIN_ROOT} in hooks. Set LODE_PLUGIN_ROOT to the Lode install when OpenCode is started without the packaged plugin. The packaged plugin can repair an empty env-expanded path in memory only when the original managed configuration hash and current package identity match; it does not take over a user-owned or edited configuration. If the installation path changes, install Lode on that PC and ask the agent to resume the existing Project. At the same canonical Project path, this preserves Project and Session IDs and the selected runtimes while updating the host installation identity. Packaged launch paths use client placeholders; standalone Claude launch paths can be machine-local. A project-owned opencode.json or opencode.jsonc stays unchanged; the generated copy remains available as a connection reference. Init, resume and status report instructions and MCP separately: configured locally, missing, disabled, conflicting, multiple entries or unknown. They reuse an existing sufficient AGENTS connection or legacy server alias instead of asking for duplicates. Ask the agent to connect only the missing items within your setup request, preserving model, permissions, other servers and instruction order. A disabled entry or conflicting launch needs its specific choice resolved only if you want to change it. JSONC, unresolved Host variables and uninspectable files remain unknown; Lode does not parse-and-rewrite them or block ordinary work. These are local file observations, not proof that the running OpenCode Host loaded them.

If you move or copy the complete Project folder, explicitly resume it at the new path. Lode verifies the retained owner and preserves Project/Session IDs and historical records; a status read alone does not adopt the new location. This does not transfer a native Host binding or replay execution. See Session recovery. Check the running Host's MCP tool loading separately.

If you choose instruction linking during setup, Lode can append a small block to an existing instruction file once, preserving its original content; when the file does not exist yet, linking creates it with only that block. Claude Code uses its instruction-file imports; Codex receives a directive to read the project instructions. Declining leaves the file unchanged and does not block your task or trigger another setup offer. See the installation guidance for your Host; generated instructions alone do not prove that a running Host read them.

After initialization, start claude or opencode in the project. Follow the Host’s approval policy for the selected MCP connection. An existing verified plugin connection does not require a duplicate project server. The runtime-native instruction/config files are projections; the selected .lode/ or existing .head/ remains the single canonical Project root.

User-scoped CLI

Supported runtime: Node.js 24 or newer; CI uses Node.js 24.18.0. You also need either Git or a downloaded source archive. Git inside the target project, Go, GraphDB, and a provider runtime are optional.

Windows PowerShell:

git clone https://github.com/binary1215/lode.git lode
Set-Location .\lode
.\scripts\install.ps1 --native auto --project C:\path\to\project --runtime codex

lode-agent --version

macOS or Linux:

git clone https://github.com/binary1215/lode.git lode
cd lode
./scripts/install.sh --native auto --project /path/to/project --runtime codex

lode-agent --version

The installer stages a content-verified release in the current user's data directory and writes launchers to ~/.local/bin. It does not edit a shell profile, a Codex cache, remote GraphDB, or an existing project before the explicit --project initialization step. The example selects Codex only; replace codex with claude or opencode for that client. --version identifies the executing CLI, not the running Host's loaded tools. Use existing status/doctor diagnostics only when needed.

New Lode installations use lode-agent-core@lode-agent-plugin, lode_* and Lode Skill names. Existing codex-marketplace and claude-marketplace addresses keep head-agent-core@head-agent-plugin, head_* and their existing Skill names. Each package registers one lode server and lists one tool vocabulary; both run the same implementation. Keep the marketplace you already use rather than installing both.

For an existing HEAD installation, continue with its usual update commands:

codex plugin marketplace upgrade head-agent-plugin
codex plugin add head-agent-core@head-agent-plugin

claude plugin marketplace update head-agent-plugin
claude plugin update head-agent-core@head-agent-plugin

Existing .head/ records, IDs and selected Session stay intact; new projects use .lode/. Known operation aliases are not redirects for the Host-owned mcp__head_core__... or mcp__lode_core__... names. A disk update does not reload a running Host. Existing user-owned configuration is preserved, and generated alternatives use the new server name. Historical packages retain their exact bytes and namespace for verified rollback.

Your first request

After installing and loading the plugin, open your project and include the real task in your first request. There is no separate setup conversation.

Use Lode Agent Core for this project. Resume its existing state if one exists;
otherwise initialize the Core. Then find the cause of this login failure and fix it.

Replace the login failure with your own task. Lode continues it after initialization and verified recovery; you can keep asking for work in the same conversation.

Not installed yet? Give your coding agent this README and ask:

Install Lode for Codex using its existing official installation path. Reuse a
valid installation and preserve my project instructions and current connections.
Do the steps you are allowed to perform; tell me only what needs my action.
Then use it in this project to investigate the login failure.

Replace Codex and the task with your client and goal. This starts from the README even without an installed Skill. The agent performs the authorized steps it can, checks the results, and continues your task. You may still need to approve Host access, log in or restart the app yourself. The agent does not restart it for you.

How to use it

Start with the first-request example. Describe the outcome you want, then work in ordinary language.

Prepare only the code and decision evidence needed for this change, then proceed.

Keep one overall plan and use parallel workers only for the independent parts.

Lode normally works directly. When delegation helps, it gives the current tool's workers a clear scope, checks their results and combines them. If the tool cannot delegate, Lode continues directly or sequentially. Ordinary delegation does not require a managed Run, worker registry or extra approval.

You can also ask:

Need	Example request
Resume remaining work	“Continue from the saved Todo and tell me what is still open.”
Keep the plan current	“Combine the implementation and review results, then adjust the next step for what we learned.”
Understand a change	“Show the recorded reason and the before/after source for this change.”

These are ordinary requests. They add no save form, required review ceremony or new approval step.

Separate conversations, shared direction

Independent tasks can keep separate work Sessions while sharing the project goal and current constraints. Starting a new conversation preserves other tasks' progress. You do not maintain Session IDs or routing forms. See Graph discovery and independent Sessions.

After compaction or provider replacement, conversation entry checks the available saved work direction. You do not need to request recovery or supply a checkpoint ID.

Recovery uses saved records and does not guarantee preservation of the full unsaved conversation. Supported Hooks may supply bounded prompt/final-response references as quoted context. Host delivery and managed continuation have different support limits; see Session work context and Host support and capability status.

You do not write JSON, operate GraphDB, choose a token tier or decide which MCP call to make. Lode asks when a decision belongs to you: for example, approving product meaning, resolving an ambiguous scope, or allowing a consequential external change. Ordinary investigation and small authorized fixes stay ordinary work.