Installation

This guide gets you from zero to a working Morph setup: binaries installed, repo initialized, and your IDE (Cursor, Claude Code, or OpenCode) recording every prompt and response and able to commit the filesystem.

What you get: Rich structured traces of every agent interaction -- tool calls, file reads/edits, shell commands, prompts, and responses -- stored as immutable Runs with Traces in the Morph object store. File tree snapshots via morph commit or MCP tools, independent of Git. Always-on recording via IDE hooks so you don't depend on the agent calling a tool.

1. Install the Morph binaries

You need two executables: morph (CLI) and morph-mcp (MCP server used by Cursor, Claude Code, and OpenCode).

With Homebrew (macOS):

brew tap r/morph
brew install morph

This installs both morph and morph-mcp.

From source (Rust):

git clone <morph-repo-url>

cd morph
cargo install --path morph-cli
cargo install --path morph-mcp

This installs to ~/.cargo/bin. Ensure that directory is on your PATH.

Verify: Run morph --help and morph-mcp --version. Running morph-mcp with no arguments will appear to hang — it's waiting for an IDE to connect over stdio; that's expected.

2. Initialize a Morph repo

Morph requires a git repository. If your project is not yet a git repo, either run git init first or pass --git-init to morph init so it does it for you. From the root of the project you want to track:

cd /path/to/your/project
morph init                # prompts to run `git init` for you if .git/ is missing
# or, equivalent for scripts:
morph init --git-init     # always runs `git init` first
morph init --no-git-init  # never prompt; fail fast if .git/ is missing

This creates a .morph/ directory (objects, refs, config, prompts, runs, traces) alongside the existing .git/ and adds .morph/ to .git/info/exclude so morph state is never tracked by git. Nothing else is modified. You only need to do this once per project.

morph init also writes an opinionated default RepoPolicy that requires tests_total and tests_passed on every commit. Use morph policy require-metrics <name>... to relax or change the gate (pass no names to disable it). If you need a policy-free repo for scripted tests, the hidden --no-default-policy flag opts out at init time. See EVAL-DRIVEN.md for the full spec-first workflow.

Quick path: one command for Cursor (recommended)

After morph init, you can install Cursor MCP config, hooks, and rules in one step:

morph setup cursor

This writes (or merges into) .cursor/mcp.json, .cursor/hooks.json, .cursor/rules/*.mdc, and the hook scripts into .cursor/ in your project (so only dot-directories like .cursor/ and .morph/ are visible, Git-style). Then open the project in Cursor; ensure morph and morph-mcp are on your PATH. No manual MCP or hook setup needed.

Quick path: one command for OpenCode

After morph init, you can install OpenCode MCP config, agent instructions, and the recording plugin in one step:

morph setup opencode

This writes (or merges into) opencode.json, AGENTS.md, and .opencode/plugins/morph-record.ts in your project. Then open the project in OpenCode; ensure morph and morph-mcp are on your PATH.

Quick path: one command for Agent of Empires (`aoe`)

If you drive multiple agents through Agent of Empires, install the AoE integration in one step:

morph setup aoe

This writes lifecycle hooks (always commit on on_create / on_destroy, plus a per-launch Run) into .agent-of-empires/config.toml, seeds [sandbox].environment and [sandbox].extra_volumes so morph hooks work inside AoE Docker sandboxes, and ships a Dockerfile.morph-aoe reference image. By default it also delegates to setup cursor / setup opencode / setup claude-code so prompt/response recording works regardless of which agent AoE launches. See AOE-SETUP.md.

3. Set up your IDE

Morph works with Cursor, Claude Code, and OpenCode. Each IDE uses the same morph-mcp server for MCP tools and provides recording mechanisms so every prompt and response is captured.

IDE	Full guide	What you configure
Cursor	CURSOR-SETUP.md	MCP server in Cursor settings; hooks (beforeSubmitPrompt, afterAgentResponse, stop) and hook scripts in the project.
Claude Code	CLAUDE-CODE-SETUP.md	MCP server in Claude Code config; hooks (UserPromptSubmit, Stop) and hook scripts in the project.
OpenCode	OPENCODE-SETUP.md	MCP server in `opencode.json`; `AGENTS.md` for agent instructions; recording plugin in `.opencode/plugins/`.

Cursor

Add the Morph MCP server in Cursor (Settings → MCP) so the agent can use morph_record_session, morph_stage, morph_commit, etc.
Enable hooks so Cursor records every prompt and response: add .cursor/hooks.json and the three hook scripts (see CURSOR-SETUP.md). Hooks use beforeSubmitPrompt (capture prompt), afterAgentResponse (capture full response), and stop (fallback).

Cursor Marketplace: A Morph plugin can bundle rules, hooks config, and hook scripts so "add Morph to Cursor" is one step after the plugin is installed. The Cursor Marketplace allows plugins to ship scripts and MCP config but not binaries — so you still install the Morph binaries (step 1) and run morph init (step 2) yourself. The plugin only configures Cursor. The marketplace is curated; plugins are submitted for review. When a Morph plugin is listed, you'll be able to install it from the marketplace and then add the binaries + init if you haven't already.

Claude Code

Add the Morph MCP server in Claude Code's MCP configuration (e.g. in .claude/settings.json).
Enable hooks so Claude Code records every prompt and response: add the Morph hook scripts under .claude/hooks/ and a hooks section in .claude/settings.json for UserPromptSubmit and Stop (see CLAUDE-CODE-SETUP.md).

OpenCode

Add the Morph MCP server in opencode.json under the mcp key.
Add AGENTS.md so the agent records sessions via MCP after every task.
Install the recording plugin at .opencode/plugins/morph-record.ts for supplementary always-on recording.

Or run morph setup opencode to do all three in one step (see OPENCODE-SETUP.md).

4. Verify

MCP: In your IDE, confirm the Morph MCP server is connected (Cursor: Settings → MCP; Claude Code: your MCP config; OpenCode: opencode mcp list).
Recording: Send a prompt and let the agent respond. Check that a run was stored: e.g. ls .morph/objects/ or inspect .morph/hooks/logs/morph-record.log.
Commit: Run morph add . and morph commit -m "first snapshot" (or use the MCP tools from the IDE).

5. Run the hosted service (optional)

For team-wide inspection and collaboration, run the Morph hosted service:

morph serve                    # serve current repo at http://127.0.0.1:8765
morph serve --port 9000        # custom port
morph serve --repo team=/path  # named multi-repo

The service exposes a stable JSON API for browsing commits (with behavioral status), runs, traces, pipelines, certifications, and policy. See v0-spec.md § 16 for the full API reference.

6. Next steps

Commit the filesystem: CURSOR-SETUP.md § Committing / CLAUDE-CODE-SETUP.md § Committing / OPENCODE-SETUP.md § Committing.
Use Morph with Git: MORPH-AND-GIT.md.
Sync between machines: MULTI-MACHINE.md walks through bare repos, SSH transport, morph push/morph pull/morph sync. If you're hosting the server, see SERVER-SETUP.md. The merge engine those workflows depend on is documented in MERGE.md.
MCP tool reference: CURSOR-SETUP.md § MCP Tool Reference (same tools in all IDEs).
Hosted service API: v0-spec.md § 16.

Troubleshooting

Symptom	What to do
"not a morph repository"	Run `morph init` in the project root. If the IDE uses a different cwd, set `MORPH_WORKSPACE` in the MCP config to the project path (see IDE setup guide).
MCP server not found / ENOENT	Ensure `morph-mcp` is on PATH or use the full path in MCP config. Restart the IDE after changing config.
Sessions not recorded	Confirm hooks are configured and hook script paths are correct. Cursor: `.cursor/hooks.json` with beforeSubmitPrompt, afterAgentResponse, stop; scripts in `.cursor/`. Claude Code: `hooks` in `.claude/settings.json`; scripts in `.claude/hooks/`. OpenCode: ensure `AGENTS.md` exists and morph MCP server is connected. See the IDE guide's debugging section.
Empty `.morph/prompts/` or no new runs	If you rely on the agent calling `morph_record_session`, ensure the Cursor rule / `AGENTS.md` is present and applied. Prefer hook-based recording so every turn is captured without agent cooperation.

For IDE-specific issues (workspace path, hook payloads, script paths), see the full Cursor, Claude Code, or OpenCode setup guide.

FilesExpand file tree

INSTALLATION.md

Latest commit

History