Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/markmdev/meridian

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.
https://github.com/markmdev/meridian

ai-agents anthropic automation claude claude-code developer-tools developer-workflow nextjs nodejs open-source productivity software-engineering task-runner tdd typescript workflow-automation zero-config

Last synced: 20 days ago
JSON representation

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.

Awesome Lists containing this project

README 

          
![Logo](https://github.com/user-attachments/assets/9eb140c8-b938-4e77-ab94-0461a6d919fd)



# Meridian



**Behavioral guardrails for Claude Code** — enforced workflows, persistent context, and quality gates for complex tasks.



**Current version:** `0.6.0` (2026-02-28) | [Changelog](CHANGELOG.md)



> If Meridian helps your work, please **star the repo** and share it.

> Follow updates: [X (@markmdev)](http://x.com/markmdev) • [LinkedIn](http://linkedin.com/in/markmdev)



---



## The Problem



Claude Code is powerful, but on complex tasks it struggles with:



| Problem | What happens |

|---------|--------------|

| **Context loss** | After compaction, Claude forgets decisions, requirements, and what it was working on |

| **No built-in memory** | Claude can't remember lessons learned — it repeats the same mistakes because it doesn't know it already made them |

| **Forgets prompt details** | With large context, Claude starts ignoring parts of your `CLAUDE.md` instructions |

| **Shallow planning** | Plans lack depth, miss integration steps, and break during implementation |

| **No task continuity** | When you return to a task next session, Claude doesn't know what was done, decided, or tried |



You can write instructions in `CLAUDE.md`, but with large context Claude starts forgetting details from the prompt.



---



## What Meridian Does



Meridian uses Claude Code's hooks system to enforce behaviors automatically:



| Capability | How it works |

|------------|--------------|

| **Context survives compaction** | Hooks re-inject task state, guidelines, and your docs after every compaction |

| **Session continuity** | Agent workspace (`WORKSPACE.md`) tracks decisions, discoveries, and context across sessions — Claude picks up where it left off |

| **Pre-compaction warning** | Monitors token usage and prompts Claude to save context before compaction happens |

| **Detailed plans that work** | Planning skill guides Claude through thorough discovery, design, and integration planning |

| **Quality gates** | Plan-reviewer and code-reviewer agents validate work before proceeding |

| **Your custom docs injected** | Add docs to `.meridian/docs/` with `summary` + `read_when` frontmatter — they're auto-discovered and injected when relevant |



**Your behavior doesn't change.** You talk to Claude the same way. Meridian works behind the scenes.



---



## When Meridian Shines



Meridian is designed for **large, complex, long-running tasks** where:

- Work spans multiple sessions

- Context loss would be costly

- Quality matters

- You want Claude to learn from past mistakes



For simple tasks (quick edits, one-off questions), Meridian won't help much — but it won't hurt either. It stays out of the way.



---



## Architecture



```mermaid

flowchart TB

    subgraph Claude["Claude Code"]

        User[Developer]

    end



    subgraph Hooks["Hooks (Enforce Workflow)"]

        H1[SessionStart]

        H2[PreToolUse]

        H3[PostToolUse]

        H4[Stop]

    end



    subgraph Skills["Skills (Structured Workflows)"]

        S1[planning]

    end



    subgraph Agents["Agents (Quality Gates)"]

        A1[plan-reviewer]

        A2[code-reviewer]

        A3[docs-researcher]

    end



    subgraph Files[".meridian/ (Persistent State)"]

        F1[WORKSPACE.md]

        F2[api-docs/]

        F3[CODE_GUIDE.md]

    end



    User -->|talks to| Claude

    Claude -->|triggers| Hooks

    H1 -->|injects context| Files

    H2 -->|enforces review| Agents

    H3 -->|reminds task creation| Skills

    H4 -->|requires updates| Files

    Skills -->|read/write| Files

    Agents -->|validate against| Files

```



### How Components Work Together



```mermaid

sequenceDiagram

    participant Dev as Developer

    participant CC as Claude Code

    participant Hook as Hooks

    participant Skill as Skills

    participant Agent as Agents

    participant Files as .meridian/



    Note over Dev,Files: Session Start

    Dev->>CC: Opens project

    CC->>Hook: SessionStart triggers

    Hook->>Files: Reads tasks, guides, context

    Hook->>CC: Injects context

    Hook->>CC: Blocks until acknowledged



    Note over Dev,Files: Planning Phase

    Dev->>CC: Describes complex task

    CC->>Skill: Uses planning skill

    Skill->>CC: Guides through methodology

    CC->>Hook: Tries to exit plan mode

    Hook->>Agent: Spawns plan-reviewer

    Agent->>Files: Reads CODE_GUIDE, context

    Agent->>CC: Returns score + findings

    alt Score < 9

        CC->>CC: Iterates on plan

    else Score >= 9

        Hook->>CC: Allows exit

    end



    Note over Dev,Files: Implementation Phase

    CC->>Hook: PreToolUse triggers

    Hook->>Files: Checks token count

    alt Approaching limit

        Hook->>CC: Prompts to save context

        CC->>Files: Updates workspace

    end

    CC->>CC: Implements plan



    Note over Dev,Files: Completion

    Dev->>CC: Requests stop

    CC->>Hook: Stop triggers

    Hook->>CC: Blocks until updates done

    CC->>Agent: Spawns code-reviewer

    Agent->>Files: Reviews changes

    Agent->>CC: Returns issues (if any)

    CC->>Files: Updates task status

    CC->>Files: Updates workspace

    Hook->>CC: Allows stop

```



---



## Quick Start



### Install



```bash

# 1. Install the plugin

/plugin marketplace add markmdev/claude-plugins

/plugin install meridian@markmdev



# 2. Scaffold project files

cd /path/to/your/project

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

```



### Update



```bash

# Update project scaffolding (.meridian/)

meridian-update



# Update hooks, agents, skills

/plugin update meridian@markmdev

```



### Check installed version



```bash

cat .meridian/.version

```



---



## Why Not Just CLAUDE.md?



| | `CLAUDE.md` | Meridian |

|-|-------------|----------|

| **Large context** | Claude forgets prompt details as context grows | Hooks reinforce key behaviors throughout the session |

| **Task continuity** | None — each session starts fresh | Context files track progress, decisions, next steps |

| **Quality gates** | None | Plan review + code review before proceeding |

| **Custom docs** | Must be read manually each session | Docs in `.meridian/docs/` with `read_when` frontmatter hints, auto-discovered and injected |



`CLAUDE.md` is a static prompt. Meridian hooks actively enforce behaviors and inject context throughout the session.



---



## Components Deep Dive



Hooks — Enforce Workflow



Hooks are Python scripts triggered at Claude Code lifecycle events. They can inject context, block actions, or modify behavior.



| Hook | Trigger | What it does |

|------|---------|--------------|

| `context-injector.py` | SessionStart | Injects workspace, tasks, CODE_GUIDE into context |

| `plan-review.py` | PreToolUse (ExitPlanMode) | Requires plan-reviewer before implementation |

| `action-counter.py` | PostToolUse | Tracks actions for stop hook threshold |

| `plan-approval-reminder.py` | PostToolUse (ExitPlanMode) | Reminds to create Pebble issues (if enabled) |

| `stop-checklist.py` | Stop | Requires context updates and code review |

| `plan-mode-tracker.py` | UserPromptSubmit | Prompts planning skill when entering Plan mode |

| `session-cleanup.py` | SessionEnd | Cleans up session state files |



Hooks are managed by the plugin system and share utilities from `lib/meridian_config.py`.



Skills — Structured Workflows



Skills are reusable instruction sets that activate when invoked.



### Planning Skill



Guides Claude through comprehensive planning so plans don't break during implementation:

1. **Requirements Interview** — Up to 40 questions across multiple rounds to deeply understand the task

2. **Deep Discovery** — Use direct tools (Glob, Grep, Read) to research the codebase; Explore agents only for conceptual questions

3. **Design** — Choose approach, define target state, verify assumptions against actual code

4. **Decomposition** — Break into subtasks with clear dependencies

5. **Integration** — Explicitly plan how modules connect (mandatory for multi-module plans)

6. **Documentation** — Each phase must include CLAUDE.md and human docs steps (mandatory)



Plans describe **what and why**, not how. The plan-reviewer agent validates plans against the actual codebase before implementation begins.



### Prompt Writing Skill



General-purpose guidance for writing effective prompts for any AI system:

- **Remove redundancy** — Merge overlapping content, deduplicate examples

- **Remove noise** — Cut excessive dividers, wrapper tags, verbose explanations

- **Sharpen instructions** — Make them direct and actionable

- **Keep load-bearing content** — Workflow steps, quality criteria, rules that matter



Works for Claude Code artifacts (skills, agents, hooks) and any other AI prompts.



Agents — Quality Gates



Agents are specialized subagents that validate work. All reviewers use an **issue-based system** — no scores, just issues or no issues. Loop until all issues are resolved.



### Plan Reviewer



Validates plans before implementation:

- Verifies file paths and API assumptions against codebase

- Checks for missing steps, dependencies, integration plan, documentation steps

- Trusts plan claims about packages/versions (user may have private access)

- Returns score (must reach 9+ to proceed) + findings



### Code Reviewer



Deep code review that finds real bugs:

1. Loads project context (workspace, CODE_GUIDE, active plan)

2. Gets changes via git diff

3. For each changed file: reads full file, traces data flow, checks callers/imports

4. Classifies issues: p0 (crashes/security), p1 (bugs), p2 (minor)

5. Returns structured findings — the main agent handles issue tracking



Focuses on issues that actually matter, not checklist items or style preferences.



### Docs Researcher



Researches external tools, APIs, and products:

- Builds comprehensive knowledge docs in `.meridian/api-docs/`

- Covers current versions, API operations, rate limits, best practices, gotchas

- Uses relevant MCPs or skills if available for web research

- Run before using any external library not already documented



### Implement



Executes detailed implementation specs autonomously:

- Takes a specific spec and implements it precisely

- Reports ambiguity instead of asking questions (non-blocking for parallel execution)

- Runs typecheck/tests and fixes failures up to 3 iterations

- Spawn multiple in parallel for independent tasks



### Pebble Scaffolder



Creates Pebble issue hierarchy from plans (when Pebble enabled):

- Creates epic for overall plan

- Creates task per phase as children of epic

- Adds dependencies between sequential phases

- Invoked automatically after plan approval



Configuration



### Project Config (`.meridian/config.yaml`)



```yaml

# Plan review behavior

plan_review_min_actions: 20  # Skip plan review if < N actions (default: 20)



# Pebble issue tracking

pebble_enabled: false



# Stop hook behavior

stop_hook_min_actions: 15  # Skip stop hook if < N actions since last user input



# Session learner

session_learner_mode: "project"  # "project" (default) or "assistant"

```



### CODE_GUIDE System



- **Baseline** (`CODE_GUIDE.md`) — Default standards for Next.js/React + Node/TS

- **Hackathon Addon** — Relaxes rules for fast prototypes

- **Production Addon** — Tightens rules for production systems



Precedence: Baseline → Project Type Addon



File Structure



```

your-project/

├── .meridian/

│   ├── config.yaml                   # Project configuration

│   ├── WORKSPACE.md                  # Agent's living knowledge base (always injected)

│   ├── workspace/                    # Workspace sub-pages (linked from WORKSPACE.md)

│   ├── CODE_GUIDE.md                 # Coding standards

│   ├── SOUL.md                       # Agent identity

│   ├── api-docs/                     # External API documentation

│   ├── docs/                         # Project knowledge docs (auto-discovered)

│   ├── prompts/                      # Injected prompts

│   │   └── agent-operating-manual.md

│   ├── scripts/                      # User-facing utilities

│   │   ├── state-dir.sh              # Resolve state directory

│   │   ├── setup-work-until.sh       # Work-until loop setup

│   │   └── learner-log.py            # Session learner log viewer

│   └── plans/                        # Archived implementation plans

│   # Note: session state lives in ~/.meridian/state/ (not inside .meridian/)

│

│   # Plugin files (managed by /plugin — don't edit directly):

│   # hooks/hooks.json, scripts/*.py, agents/*.md, commands/*.md, skills/*/

└── your-code/

```



---



## Work-Until Loop



The `/work-until` command creates an iterative loop where Claude keeps working on a task until a completion condition is met.



### Usage



```bash

# Basic: work until phrase is true

/work-until Fix all failing tests --completion-phrase "All tests pass"



# With iteration limit

/work-until Implement auth feature --completion-phrase "Feature complete" --max-iterations 10



# Just iteration limit (no phrase)

/work-until Refactor the API layer --max-iterations 5

```



### How It Works



1. **Start**: `/work-until` creates a loop state file with your task

2. **Work**: Claude works on the task normally

3. **Stop blocked**: When Claude tries to stop, the hook intercepts

4. **Check completion**: Hook looks for `PHRASE` in output

5. **Continue or exit**:

   - If phrase found (and TRUE) → loop ends

   - If max iterations reached → loop ends

   - Otherwise → task is resent, Claude continues



### Key Points



- **Workspace preserves history**: Between iterations, Claude writes to its workspace, so it knows what was tried

- **Normal stop checks still run**: Workspace updates, tests/lint/build — all enforced each iteration

- **Completion phrase must be TRUE**: Claude cannot lie to escape the loop

- **Monitor progress**: `cat $(.meridian/scripts/state-dir.sh)/loop-state` shows current iteration



### Example Flow



```

You: /work-until Fix the auth bug --completion-phrase "All auth tests pass" --max-iterations 5



Claude: [Works on fix, runs tests, some fail]

Claude: [Tries to stop]

→ Hook blocks: "Iteration 2 of 5 — continue working"



Claude: [Reads workspace, sees what was tried]

Claude: [Fixes another issue, runs tests, all pass]

Claude: All auth tests pass

→ Hook allows stop: "✅ Completion phrase detected"

```



---



## Git Worktrees



Since v0.4.0, Meridian stores session state (counters, flags, locks) in `~/.meridian/state/` instead of inside `.meridian/`. This means you can symlink the entire `.meridian/` directory across worktrees — shared docs, plans, and workspace with isolated session state.



### Setup



```bash

# Create a worktree as usual

git worktree add ../my-feature feature-branch



# Symlink .meridian/ from the main worktree

ln -s /absolute/path/to/main/.meridian ../my-feature/.meridian

```



That's it. Each worktree gets its own session state automatically (based on its absolute path), while sharing all docs, plans, workspace, and config.



### What's shared vs isolated



| Content | Shared? | Why |

|---------|---------|-----|

| `docs/` | Yes | Reference material should be visible everywhere |

| `plans/` | Yes | Plans are project-wide |

| `workspace/` | Yes | Accumulated knowledge benefits all sessions |

| `WORKSPACE.md` | Yes | Project knowledge base |

| `config.yaml` | Yes | Project settings |

| `CODE_GUIDE.md` | Yes | Coding standards |

| Session state | No | Counters, flags, locks are per-session (in `~/.meridian/state/`) |



### Notes



- The session learner updates the shared `WORKSPACE.md` — lessons from any worktree flow to all others

- Concurrent workspace updates from parallel sessions are rare; Claude Code's file conflict detection handles the edge case

- The plugin handles hooks, agents, and skills automatically — no need to symlink `.claude/` across worktrees



---



## FAQ



**Who is Meridian for?**



Anyone using Claude Code for complex, multi-session work. Solo developers and teams alike benefit from enforced workflows and persistent context.



**Does Meridian change how I interact with Claude?**



No. You talk to Claude the same way. Meridian works behind the scenes through hooks.



**What happens on simple tasks?**



Nothing. Hooks fire but don't block anything meaningful. The overhead is minimal.



**Can I customize the CODE_GUIDE?**



Yes. Edit `.meridian/CODE_GUIDE.md` to add project-specific rules. It's injected every session.



**Can I disable features?**



Yes. In `.meridian/config.yaml`:

```yaml

pebble_enabled: false              # Disable Pebble issue tracking integration

stop_hook_min_actions: 15           # Skip stop hook if < N actions (default: 15)

plan_review_min_actions: 20         # Skip plan review if < N actions (default: 20)

session_learner_mode: "assistant"   # "project" (default) or "assistant"

```



**How is this different from subagents?**



Subagents don't share live context, re-read docs (token waste), and can't be resumed after interrupts. Meridian keeps Claude as the primary agent and injects context directly.



---



## Contributing



PRs and issues welcome at [github.com/markmdev/meridian](https://github.com/markmdev/meridian)



**License:** MIT



---



## Star & Share



If Meridian improves your Claude Code sessions:



- **Star this repo** so others can find it

- Share your experience on [X (@markmdev)](http://x.com/markmdev) or [LinkedIn](http://linkedin.com/in/markmdev)