by markmdev
Zero-config Claude Code setup with enforced task scaffolding, structured memory, persistent context after compaction, plug-in code standards, optional TDD mode, and zero behavior changes for developers.
# Add to your Claude Code skills
git clone https://github.com/markmdev/meridianMeridian 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.
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:
CLAUDE.md drift out of focus during long runsMeridian closes those gaps without asking you to completely change how you work.
WORKSPACE.md, project docs, and supporting prompts stay available across sessions.meridian/docs/ can advertise when they should be readMeridian is intentionally opinionated, but it stays behind the scenes. You still talk to Claude normally.
No comments yet. Be the first to share your thoughts!
Meridian is most useful if you use Claude Code for:
If you mostly use Claude Code for tiny one-off edits, Meridian is probably overkill.
/plugin marketplace add markmdev/claude-plugins
/plugin install meridian@markmdev
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.
Meridian hooks are provided by the plugin. The scaffolded .meridian/ directory gives the plugin project-specific files to read from.
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
Meridian has two halves:
Installed through Claude Code's plugin system:
These live with the plugin and are updated with /plugin update.
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.yamlMeridian hooks into Claude Code lifecycle events and adds a little structure at the moments where Claude usually drifts.
Current behavior includes:
The goal is not to micromanage Claude. The goal is to keep it oriented.
.meridian/WORKSPACE.mdThe 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.yamlProject-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.
WORKSPACE.md and .meridian/docs/ useful.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.
CLAUDE.md?No. CLAUDE.md is still your core instruction file. Meridian helps those instructions stay alive in practice during longer sessions.
Not much. It is designed to improve behavior without forcing a whole new user workflow.
No, but the payoff is much bigger once tasks are large enough that session continuity and docs routing matter.
Yes. The main entry points are:
.meridian/config.yaml.meridian/docs/.meridian/prompts/CLAUDE.mdIssues and PRs are welcome.
If you are making a meaningful behavior change, update the docs and CHANGELOG.md in the same PR.