meridian

Meridian

Meridian makes Claude Code more reliable on real projects.

It adds persistent project context, smarter session handoff, and lightweight workflow enforcement so Claude is less likely to lose the plot halfway through a long task.

What problem it solves

Claude Code is great at short bursts. It gets shakier when work stretches across a big repo, multiple sessions, or a lot of moving pieces.

Common failure modes:

• Context gets lost after compaction or a fresh session
• Important project docs exist, but Claude does not read the right ones at the right time
• Instructions in CLAUDE.md drift out of focus during long runs
• Work stops in an awkward half-finished state with missing docs, review, or cleanup
• The same mistakes repeat because nothing turns session learnings into project memory

Meridian closes those gaps without asking you to completely change how you work.

What Meridian gives you

• Better session continuity: important project context is re-injected when a session starts or compacts
• A real project workspace: WORKSPACE.md, project docs, and supporting prompts stay available across sessions
• Smarter doc routing: docs in .meridian/docs/ can advertise when they should be read
• Instruction reinforcement: Meridian can remind Claude to follow your local guidance during long sessions
• End-of-task quality pressure: the stop checklist nudges Claude to finish the boring but important parts
• Session learning: a background learner can update workspace/docs based on what actually happened

Meridian is intentionally opinionated, but it stays behind the scenes. You still talk to Claude normally.

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.