{"id":33319297,"url":"https://github.com/markmdev/meridian","last_synced_at":"2026-03-03T21:09:12.664Z","repository":{"id":324001610,"uuid":"1095553325","full_name":"markmdev/meridian","owner":"markmdev","description":"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.","archived":false,"fork":false,"pushed_at":"2026-02-28T20:34:22.000Z","size":774,"stargazers_count":138,"open_issues_count":3,"forks_count":12,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-28T23:45:37.558Z","etag":null,"topics":["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"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markmdev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-13T07:51:57.000Z","updated_at":"2026-02-28T20:33:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/markmdev/meridian","commit_stats":null,"previous_names":["markmdev/meridian"],"tags_count":110,"template":false,"template_full_name":null,"purl":"pkg:github/markmdev/meridian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fmeridian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fmeridian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fmeridian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fmeridian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markmdev","download_url":"https://codeload.github.com/markmdev/meridian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Fmeridian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30061029,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-03T18:21:05.932Z","status":"ssl_error","status_checked_at":"2026-03-03T18:20:59.341Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2025-11-19T20:00:31.566Z","updated_at":"2026-03-03T21:09:12.658Z","avatar_url":"https://github.com/markmdev.png","language":"Python","readme":"![Logo](https://github.com/user-attachments/assets/9eb140c8-b938-4e77-ab94-0461a6d919fd)\n\n# Meridian\n\n**Behavioral guardrails for Claude Code** — enforced workflows, persistent context, and quality gates for complex tasks.\n\n**Current version:** `0.6.0` (2026-02-28) | [Changelog](CHANGELOG.md)\n\n\u003e If Meridian helps your work, please **star the repo** and share it.\n\u003e Follow updates: [X (@markmdev)](http://x.com/markmdev) • [LinkedIn](http://linkedin.com/in/markmdev)\n\n---\n\n## The Problem\n\nClaude Code is powerful, but on complex tasks it struggles with:\n\n| Problem | What happens |\n|---------|--------------|\n| **Context loss** | After compaction, Claude forgets decisions, requirements, and what it was working on |\n| **No built-in memory** | Claude can't remember lessons learned — it repeats the same mistakes because it doesn't know it already made them |\n| **Forgets prompt details** | With large context, Claude starts ignoring parts of your `CLAUDE.md` instructions |\n| **Shallow planning** | Plans lack depth, miss integration steps, and break during implementation |\n| **No task continuity** | When you return to a task next session, Claude doesn't know what was done, decided, or tried |\n\nYou can write instructions in `CLAUDE.md`, but with large context Claude starts forgetting details from the prompt.\n\n---\n\n## What Meridian Does\n\nMeridian uses Claude Code's hooks system to enforce behaviors automatically:\n\n| Capability | How it works |\n|------------|--------------|\n| **Context survives compaction** | Hooks re-inject task state, guidelines, and your docs after every compaction |\n| **Session continuity** | Agent workspace (`WORKSPACE.md`) tracks decisions, discoveries, and context across sessions — Claude picks up where it left off |\n| **Pre-compaction warning** | Monitors token usage and prompts Claude to save context before compaction happens |\n| **Detailed plans that work** | Planning skill guides Claude through thorough discovery, design, and integration planning |\n| **Quality gates** | Plan-reviewer and code-reviewer agents validate work before proceeding |\n| **Your custom docs injected** | Add docs to `.meridian/docs/` with `summary` + `read_when` frontmatter — they're auto-discovered and injected when relevant |\n\n**Your behavior doesn't change.** You talk to Claude the same way. Meridian works behind the scenes.\n\n---\n\n## When Meridian Shines\n\nMeridian is designed for **large, complex, long-running tasks** where:\n- Work spans multiple sessions\n- Context loss would be costly\n- Quality matters\n- You want Claude to learn from past mistakes\n\nFor simple tasks (quick edits, one-off questions), Meridian won't help much — but it won't hurt either. It stays out of the way.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TB\n    subgraph Claude[\"Claude Code\"]\n        User[Developer]\n    end\n\n    subgraph Hooks[\"Hooks (Enforce Workflow)\"]\n        H1[SessionStart]\n        H2[PreToolUse]\n        H3[PostToolUse]\n        H4[Stop]\n    end\n\n    subgraph Skills[\"Skills (Structured Workflows)\"]\n        S1[planning]\n    end\n\n    subgraph Agents[\"Agents (Quality Gates)\"]\n        A1[plan-reviewer]\n        A2[code-reviewer]\n        A3[docs-researcher]\n    end\n\n    subgraph Files[\".meridian/ (Persistent State)\"]\n        F1[WORKSPACE.md]\n        F2[api-docs/]\n        F3[CODE_GUIDE.md]\n    end\n\n    User --\u003e|talks to| Claude\n    Claude --\u003e|triggers| Hooks\n    H1 --\u003e|injects context| Files\n    H2 --\u003e|enforces review| Agents\n    H3 --\u003e|reminds task creation| Skills\n    H4 --\u003e|requires updates| Files\n    Skills --\u003e|read/write| Files\n    Agents --\u003e|validate against| Files\n```\n\n### How Components Work Together\n\n```mermaid\nsequenceDiagram\n    participant Dev as Developer\n    participant CC as Claude Code\n    participant Hook as Hooks\n    participant Skill as Skills\n    participant Agent as Agents\n    participant Files as .meridian/\n\n    Note over Dev,Files: Session Start\n    Dev-\u003e\u003eCC: Opens project\n    CC-\u003e\u003eHook: SessionStart triggers\n    Hook-\u003e\u003eFiles: Reads tasks, guides, context\n    Hook-\u003e\u003eCC: Injects context\n    Hook-\u003e\u003eCC: Blocks until acknowledged\n\n    Note over Dev,Files: Planning Phase\n    Dev-\u003e\u003eCC: Describes complex task\n    CC-\u003e\u003eSkill: Uses planning skill\n    Skill-\u003e\u003eCC: Guides through methodology\n    CC-\u003e\u003eHook: Tries to exit plan mode\n    Hook-\u003e\u003eAgent: Spawns plan-reviewer\n    Agent-\u003e\u003eFiles: Reads CODE_GUIDE, context\n    Agent-\u003e\u003eCC: Returns score + findings\n    alt Score \u003c 9\n        CC-\u003e\u003eCC: Iterates on plan\n    else Score \u003e= 9\n        Hook-\u003e\u003eCC: Allows exit\n    end\n\n    Note over Dev,Files: Implementation Phase\n    CC-\u003e\u003eHook: PreToolUse triggers\n    Hook-\u003e\u003eFiles: Checks token count\n    alt Approaching limit\n        Hook-\u003e\u003eCC: Prompts to save context\n        CC-\u003e\u003eFiles: Updates workspace\n    end\n    CC-\u003e\u003eCC: Implements plan\n\n    Note over Dev,Files: Completion\n    Dev-\u003e\u003eCC: Requests stop\n    CC-\u003e\u003eHook: Stop triggers\n    Hook-\u003e\u003eCC: Blocks until updates done\n    CC-\u003e\u003eAgent: Spawns code-reviewer\n    Agent-\u003e\u003eFiles: Reviews changes\n    Agent-\u003e\u003eCC: Returns issues (if any)\n    CC-\u003e\u003eFiles: Updates task status\n    CC-\u003e\u003eFiles: Updates workspace\n    Hook-\u003e\u003eCC: Allows stop\n```\n\n---\n\n## Quick Start\n\n### Install\n\n```bash\n# 1. Install the plugin\n/plugin marketplace add markmdev/claude-plugins\n/plugin install meridian@markmdev\n\n# 2. Scaffold project files\ncd /path/to/your/project\ncurl -fsSL https://raw.githubusercontent.com/markmdev/meridian/main/install.sh | bash\n```\n\n### Update\n\n```bash\n# Update project scaffolding (.meridian/)\nmeridian-update\n\n# Update hooks, agents, skills\n/plugin update meridian@markmdev\n```\n\n### Check installed version\n\n```bash\ncat .meridian/.version\n```\n\n---\n\n## Why Not Just CLAUDE.md?\n\n| | `CLAUDE.md` | Meridian |\n|-|-------------|----------|\n| **Large context** | Claude forgets prompt details as context grows | Hooks reinforce key behaviors throughout the session |\n| **Task continuity** | None — each session starts fresh | Context files track progress, decisions, next steps |\n| **Quality gates** | None | Plan review + code review before proceeding |\n| **Custom docs** | Must be read manually each session | Docs in `.meridian/docs/` with `read_when` frontmatter hints, auto-discovered and injected |\n\n`CLAUDE.md` is a static prompt. Meridian hooks actively enforce behaviors and inject context throughout the session.\n\n---\n\n## Components Deep Dive\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eHooks — Enforce Workflow\u003c/strong\u003e\u003c/summary\u003e\n\nHooks are Python scripts triggered at Claude Code lifecycle events. They can inject context, block actions, or modify behavior.\n\n| Hook | Trigger | What it does |\n|------|---------|--------------|\n| `context-injector.py` | SessionStart | Injects workspace, tasks, CODE_GUIDE into context |\n| `plan-review.py` | PreToolUse (ExitPlanMode) | Requires plan-reviewer before implementation |\n| `action-counter.py` | PostToolUse | Tracks actions for stop hook threshold |\n| `plan-approval-reminder.py` | PostToolUse (ExitPlanMode) | Reminds to create Pebble issues (if enabled) |\n| `stop-checklist.py` | Stop | Requires context updates and code review |\n| `plan-mode-tracker.py` | UserPromptSubmit | Prompts planning skill when entering Plan mode |\n| `session-cleanup.py` | SessionEnd | Cleans up session state files |\n\nHooks are managed by the plugin system and share utilities from `lib/meridian_config.py`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eSkills — Structured Workflows\u003c/strong\u003e\u003c/summary\u003e\n\nSkills are reusable instruction sets that activate when invoked.\n\n### Planning Skill\n\nGuides Claude through comprehensive planning so plans don't break during implementation:\n1. **Requirements Interview** — Up to 40 questions across multiple rounds to deeply understand the task\n2. **Deep Discovery** — Use direct tools (Glob, Grep, Read) to research the codebase; Explore agents only for conceptual questions\n3. **Design** — Choose approach, define target state, verify assumptions against actual code\n4. **Decomposition** — Break into subtasks with clear dependencies\n5. **Integration** — Explicitly plan how modules connect (mandatory for multi-module plans)\n6. **Documentation** — Each phase must include CLAUDE.md and human docs steps (mandatory)\n\nPlans describe **what and why**, not how. The plan-reviewer agent validates plans against the actual codebase before implementation begins.\n\n### Prompt Writing Skill\n\nGeneral-purpose guidance for writing effective prompts for any AI system:\n- **Remove redundancy** — Merge overlapping content, deduplicate examples\n- **Remove noise** — Cut excessive dividers, wrapper tags, verbose explanations\n- **Sharpen instructions** — Make them direct and actionable\n- **Keep load-bearing content** — Workflow steps, quality criteria, rules that matter\n\nWorks for Claude Code artifacts (skills, agents, hooks) and any other AI prompts.\n\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAgents — Quality Gates\u003c/strong\u003e\u003c/summary\u003e\n\nAgents 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.\n\n### Plan Reviewer\n\nValidates plans before implementation:\n- Verifies file paths and API assumptions against codebase\n- Checks for missing steps, dependencies, integration plan, documentation steps\n- Trusts plan claims about packages/versions (user may have private access)\n- Returns score (must reach 9+ to proceed) + findings\n\n### Code Reviewer\n\nDeep code review that finds real bugs:\n1. Loads project context (workspace, CODE_GUIDE, active plan)\n2. Gets changes via git diff\n3. For each changed file: reads full file, traces data flow, checks callers/imports\n4. Classifies issues: p0 (crashes/security), p1 (bugs), p2 (minor)\n5. Returns structured findings — the main agent handles issue tracking\n\nFocuses on issues that actually matter, not checklist items or style preferences.\n\n### Docs Researcher\n\nResearches external tools, APIs, and products:\n- Builds comprehensive knowledge docs in `.meridian/api-docs/`\n- Covers current versions, API operations, rate limits, best practices, gotchas\n- Uses relevant MCPs or skills if available for web research\n- Run before using any external library not already documented\n\n### Implement\n\nExecutes detailed implementation specs autonomously:\n- Takes a specific spec and implements it precisely\n- Reports ambiguity instead of asking questions (non-blocking for parallel execution)\n- Runs typecheck/tests and fixes failures up to 3 iterations\n- Spawn multiple in parallel for independent tasks\n\n### Pebble Scaffolder\n\nCreates Pebble issue hierarchy from plans (when Pebble enabled):\n- Creates epic for overall plan\n- Creates task per phase as children of epic\n- Adds dependencies between sequential phases\n- Invoked automatically after plan approval\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eConfiguration\u003c/strong\u003e\u003c/summary\u003e\n\n### Project Config (`.meridian/config.yaml`)\n\n```yaml\n# Plan review behavior\nplan_review_min_actions: 20  # Skip plan review if \u003c N actions (default: 20)\n\n# Pebble issue tracking\npebble_enabled: false\n\n# Stop hook behavior\nstop_hook_min_actions: 15  # Skip stop hook if \u003c N actions since last user input\n\n# Session learner\nsession_learner_mode: \"project\"  # \"project\" (default) or \"assistant\"\n```\n\n### CODE_GUIDE System\n\n- **Baseline** (`CODE_GUIDE.md`) — Default standards for Next.js/React + Node/TS\n- **Hackathon Addon** — Relaxes rules for fast prototypes\n- **Production Addon** — Tightens rules for production systems\n\nPrecedence: Baseline → Project Type Addon\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFile Structure\u003c/strong\u003e\u003c/summary\u003e\n\n```\nyour-project/\n├── .meridian/\n│   ├── config.yaml                   # Project configuration\n│   ├── WORKSPACE.md                  # Agent's living knowledge base (always injected)\n│   ├── workspace/                    # Workspace sub-pages (linked from WORKSPACE.md)\n│   ├── CODE_GUIDE.md                 # Coding standards\n│   ├── SOUL.md                       # Agent identity\n│   ├── api-docs/                     # External API documentation\n│   ├── docs/                         # Project knowledge docs (auto-discovered)\n│   ├── prompts/                      # Injected prompts\n│   │   └── agent-operating-manual.md\n│   ├── scripts/                      # User-facing utilities\n│   │   ├── state-dir.sh              # Resolve state directory\n│   │   ├── setup-work-until.sh       # Work-until loop setup\n│   │   └── learner-log.py            # Session learner log viewer\n│   └── plans/                        # Archived implementation plans\n│   # Note: session state lives in ~/.meridian/state/ (not inside .meridian/)\n│\n│   # Plugin files (managed by /plugin — don't edit directly):\n│   # hooks/hooks.json, scripts/*.py, agents/*.md, commands/*.md, skills/*/\n└── your-code/\n```\n\n\u003c/details\u003e\n\n---\n\n## Work-Until Loop\n\nThe `/work-until` command creates an iterative loop where Claude keeps working on a task until a completion condition is met.\n\n### Usage\n\n```bash\n# Basic: work until phrase is true\n/work-until Fix all failing tests --completion-phrase \"All tests pass\"\n\n# With iteration limit\n/work-until Implement auth feature --completion-phrase \"Feature complete\" --max-iterations 10\n\n# Just iteration limit (no phrase)\n/work-until Refactor the API layer --max-iterations 5\n```\n\n### How It Works\n\n1. **Start**: `/work-until` creates a loop state file with your task\n2. **Work**: Claude works on the task normally\n3. **Stop blocked**: When Claude tries to stop, the hook intercepts\n4. **Check completion**: Hook looks for `\u003ccomplete\u003ePHRASE\u003c/complete\u003e` in output\n5. **Continue or exit**:\n   - If phrase found (and TRUE) → loop ends\n   - If max iterations reached → loop ends\n   - Otherwise → task is resent, Claude continues\n\n### Key Points\n\n- **Workspace preserves history**: Between iterations, Claude writes to its workspace, so it knows what was tried\n- **Normal stop checks still run**: Workspace updates, tests/lint/build — all enforced each iteration\n- **Completion phrase must be TRUE**: Claude cannot lie to escape the loop\n- **Monitor progress**: `cat $(.meridian/scripts/state-dir.sh)/loop-state` shows current iteration\n\n### Example Flow\n\n```\nYou: /work-until Fix the auth bug --completion-phrase \"All auth tests pass\" --max-iterations 5\n\nClaude: [Works on fix, runs tests, some fail]\nClaude: [Tries to stop]\n→ Hook blocks: \"Iteration 2 of 5 — continue working\"\n\nClaude: [Reads workspace, sees what was tried]\nClaude: [Fixes another issue, runs tests, all pass]\nClaude: \u003ccomplete\u003eAll auth tests pass\u003c/complete\u003e\n→ Hook allows stop: \"✅ Completion phrase detected\"\n```\n\n---\n\n## Git Worktrees\n\nSince 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.\n\n### Setup\n\n```bash\n# Create a worktree as usual\ngit worktree add ../my-feature feature-branch\n\n# Symlink .meridian/ from the main worktree\nln -s /absolute/path/to/main/.meridian ../my-feature/.meridian\n```\n\nThat's it. Each worktree gets its own session state automatically (based on its absolute path), while sharing all docs, plans, workspace, and config.\n\n### What's shared vs isolated\n\n| Content | Shared? | Why |\n|---------|---------|-----|\n| `docs/` | Yes | Reference material should be visible everywhere |\n| `plans/` | Yes | Plans are project-wide |\n| `workspace/` | Yes | Accumulated knowledge benefits all sessions |\n| `WORKSPACE.md` | Yes | Project knowledge base |\n| `config.yaml` | Yes | Project settings |\n| `CODE_GUIDE.md` | Yes | Coding standards |\n| Session state | No | Counters, flags, locks are per-session (in `~/.meridian/state/`) |\n\n### Notes\n\n- The session learner updates the shared `WORKSPACE.md` — lessons from any worktree flow to all others\n- Concurrent workspace updates from parallel sessions are rare; Claude Code's file conflict detection handles the edge case\n- The plugin handles hooks, agents, and skills automatically — no need to symlink `.claude/` across worktrees\n\n---\n\n## FAQ\n\n**Who is Meridian for?**\n\nAnyone using Claude Code for complex, multi-session work. Solo developers and teams alike benefit from enforced workflows and persistent context.\n\n**Does Meridian change how I interact with Claude?**\n\nNo. You talk to Claude the same way. Meridian works behind the scenes through hooks.\n\n**What happens on simple tasks?**\n\nNothing. Hooks fire but don't block anything meaningful. The overhead is minimal.\n\n**Can I customize the CODE_GUIDE?**\n\nYes. Edit `.meridian/CODE_GUIDE.md` to add project-specific rules. It's injected every session.\n\n**Can I disable features?**\n\nYes. In `.meridian/config.yaml`:\n```yaml\npebble_enabled: false              # Disable Pebble issue tracking integration\nstop_hook_min_actions: 15           # Skip stop hook if \u003c N actions (default: 15)\nplan_review_min_actions: 20         # Skip plan review if \u003c N actions (default: 20)\nsession_learner_mode: \"assistant\"   # \"project\" (default) or \"assistant\"\n```\n\n**How is this different from subagents?**\n\nSubagents 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.\n\n---\n\n## Contributing\n\nPRs and issues welcome at [github.com/markmdev/meridian](https://github.com/markmdev/meridian)\n\n**License:** MIT\n\n---\n\n## Star \u0026 Share\n\nIf Meridian improves your Claude Code sessions:\n\n- **Star this repo** so others can find it\n- Share your experience on [X (@markmdev)](http://x.com/markmdev) or [LinkedIn](http://linkedin.com/in/markmdev)\n","funding_links":[],"categories":["Tools \u0026 Utilities"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmdev%2Fmeridian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkmdev%2Fmeridian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmdev%2Fmeridian/lists"}