Best fit

Meridian is most useful if you use Claude Code for:

• multi-hour or multi-day implementation work
• medium or large repositories
• tasks where losing decisions or next steps is expensive
• projects that benefit from structured docs and a running workspace file

If you mostly use Claude Code for tiny one-off edits, Meridian is probably overkill.

Quick start

1. Install the plugin

/plugin marketplace add markmdev/claude-plugins
/plugin install meridian@markmdev

2. Scaffold the project files

Inside the repo you want to use with Meridian:

curl -fsSL https://raw.githubusercontent.com/markmdev/meridian/main/install.sh | bash

That creates a .meridian/ folder with the project-side files Meridian uses.

3. Restart or reload Claude Code

Meridian hooks are provided by the plugin. The scaffolded .meridian/ directory gives the plugin project-specific files to read from.

Updating

Update the project scaffolding:

meridian-update

Or:

curl -fsSL https://raw.githubusercontent.com/markmdev/meridian/main/install.sh | bash

Update the plugin itself:

/plugin update meridian@markmdev

Check the installed project version:

cat .meridian/.version

What gets installed

Meridian has two halves:

Plugin-managed runtime

Installed through Claude Code's plugin system:

• hooks
• agents
• commands
• skills
• Python helper scripts

These live with the plugin and are updated with /plugin update.

Project scaffolding

Installed into your repo by install.sh:

.meridian/
├── SOUL.md
├── WORKSPACE.md
├── config.yaml
├── docs/
├── prompts/
├── scripts/
└── lib/

The installer preserves project state on update, including:

• WORKSPACE.md
• .meridian/workspace/
• .meridian/plans/
• .meridian/config.yaml

How it works

Meridian hooks into Claude Code lifecycle events and adds a little structure at the moments where Claude usually drifts.

Current behavior includes:

• Session start: inject relevant project context
• User prompt submit: track activity, watch for planning mode, reinforce instructions
• Stop: run checklist-style reminders before Claude wraps up
• Pre-compact: checkpoint transcript and session learnings before compaction
• Session end: write last-session context and run the learner

The goal is not to micromanage Claude. The goal is to keep it oriented.

Core files you will care about

.meridian/WORKSPACE.md

The running handoff for the project. Keep it current, short, and operational.

.meridian/docs/

Put durable project docs here. Meridian scans these docs and can steer Claude toward the right one when a task matches its frontmatter hints.

Minimal frontmatter:

---
summary: What this doc covers
read_when:
  - keyword or situation
  - another keyword
---

.meridian/config.yaml

Project-level behavior toggles.

Current built-in options include:

pebble_enabled: false
stop_hook_min_actions: 15
session_learner_mode: project

Recent versions also support extra stop-checklist items and custom instruction reminders.

Typical workflow

1. Install the plugin once.
2. Run the scaffold installer in a repo.
3. Keep WORKSPACE.md and .meridian/docs/ useful.
4. Use Claude Code normally.
5. Let Meridian keep context, docs, and session hygiene from falling apart.

Worktrees

Meridian stores ephemeral session state in ~/.meridian/state/<hash>/, not inside the repo. That means .meridian/ can be shared across worktrees while each worktree still gets isolated runtime state.

If you work heavily with git worktrees, this is a very nice quality-of-life improvement.

FAQ

Does this replace CLAUDE.md?

No. CLAUDE.md is still your core instruction file. Meridian helps those instructions stay alive in practice during longer sessions.

Does Meridian change how I prompt Claude?

Not much. It is designed to improve behavior without forcing a whole new user workflow.

Is Meridian only for huge repos?

No, but the payoff is much bigger once tasks are large enough that session continuity and docs routing matter.

Can I customize it?

Yes. The main entry points are:

• .meridian/config.yaml
• .meridian/docs/
• .meridian/prompts/
• your normal CLAUDE.md

Contributing

Issues and PRs are welcome.

If you are making a meaningful behavior change, update the docs and CHANGELOG.md in the same PR.