Skip to content
Back to search

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/markmdev--meridian/badge.svg)](/listings/markmdev--meridian)

HTML

<a href="/listings/markmdev--meridian"><img src="/api/listings/markmdev--meridian/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 222 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ![Logo](https://github.com/user-attachments/assets/9eb140c8-b938-4e77-ab94-0461a6d919fd)
  2. # Meridian
  3. Meridian makes Claude Code more reliable on real projects.
  4. 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.
  5. ## What problem it solves
  6. 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.
  7. Common failure modes:
  8. - Context gets lost after compaction or a fresh session
  9. - Important project docs exist, but Claude does not read the right ones at the right time
  10. - Instructions in `CLAUDE.md` drift out of focus during long runs
  11. - Work stops in an awkward half-finished state with missing docs, review, or cleanup
  12. - The same mistakes repeat because nothing turns session learnings into project memory
  13. Meridian closes those gaps without asking you to completely change how you work.
  14. ## What Meridian gives you
  15. - Better session continuity: important project context is re-injected when a session starts or compacts
  16. - A real project workspace: `WORKSPACE.md`, project docs, and supporting prompts stay available across sessions
  17. - Smarter doc routing: docs in `.meridian/docs/` can advertise when they should be read
  18. - Instruction reinforcement: Meridian can remind Claude to follow your local guidance during long sessions
  19. - End-of-task quality pressure: the stop checklist nudges Claude to finish the boring but important parts
  20. - Session learning: a background learner can update workspace/docs based on what actually happened
  21. Meridian is intentionally opinionated, but it stays behind the scenes. You still talk to Claude normally.
  22. ## Best fit
  23. Meridian is most useful if you use Claude Code for:
  24. - multi-hour or multi-day implementation work
  25. - medium or large repositories
  26. - tasks where losing decisions or next steps is expensive
  27. - projects that benefit from structured docs and a running workspace file
  28. If you mostly use Claude Code for tiny one-off edits, Meridian is probably overkill.
  29. ## Quick start
  30. ### 1. Install the plugin
  31. ```bash
  32. /plugin marketplace add markmdev/claude-plugins
  33. /plugin install meridian@markmdev
  34. ```
  35. ### 2. Scaffold the project files
  36. Inside the repo you want to use with Meridian:
  37. ```bash
  38. curl -fsSL https://raw.githubusercontent.com/markmdev/meridian/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 59 on GitHub
  39. ```
  40. That creates a `.meridian/` folder with the project-side files Meridian uses.
  41. ### 3. Restart or reload Claude Code
  42. Meridian hooks are provided by the plugin. The scaffolded `.meridian/` directory gives the plugin project-specific files to read from.
  43. ## Updating
  44. Update the project scaffolding:
  45. ```bash
  46. meridian-update
  47. ```
  48. Or:
  49. ```bash
  50. curl -fsSL https://raw.githubusercontent.com/markmdev/meridian/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 79 on GitHub
  51. ```
  52. Update the plugin itself:
  53. ```bash
  54. /plugin update meridian@markmdev
  55. ```
  56. Check the installed project version:
  57. ```bash
  58. cat .meridian/.version
  59. ```
  60. ## What gets installed
  61. Meridian has two halves:
  62. ### Plugin-managed runtime
  63. Installed through Claude Code's plugin system:
  64. - hooks
  65. - agents
  66. - commands
  67. - skills
  68. - Python helper scripts
  69. These live with the plugin and are updated with `/plugin update`.
  70. ### Project scaffolding
  71. Installed into your repo by `install.sh`:
  72. ```text
  73. .meridian/
  74. ├── SOUL.md
  75. ├── WORKSPACE.md
  76. ├── config.yaml
  77. ├── docs/
  78. ├── prompts/
  79. ├── scripts/
  80. └── lib/
  81. ```
  82. The installer preserves project state on update, including:
  83. - `WORKSPACE.md`
  84. - `.meridian/workspace/`
  85. - `.meridian/plans/`
  86. - `.meridian/config.yaml`
  87. ## How it works
  88. Meridian hooks into Claude Code lifecycle events and adds a little structure at the moments where Claude usually drifts.
  89. Current behavior includes:
  90. - Session start: inject relevant project context
  91. - User prompt submit: track activity, watch for planning mode, reinforce instructions
  92. - Stop: run checklist-style reminders before Claude wraps up
  93. - Pre-compact: checkpoint transcript and session learnings before compaction
  94. - Session end: write last-session context and run the learner
  95. The goal is not to micromanage Claude. The goal is to keep it oriented.
  96. ## Core files you will care about
  97. ### `.meridian/WORKSPACE.md`
  98. The running handoff for the project. Keep it current, short, and operational.
  99. ### `.meridian/docs/`
  100. Put durable project docs here. Meridian scans these docs and can steer Claude toward the right one when a task matches its frontmatter hints.
  101. Minimal frontmatter:
  102. ```yaml
  103. ---
  104. summary: What this doc covers
  105. read_when:
  106. - keyword or situation
  107. - another keyword
  108. ---
  109. ```
  110. ### `.meridian/config.yaml`
  111. Project-level behavior toggles.
  112. Current built-in options include:
  113. ```yaml
  114. pebble_enabled: false
  115. stop_hook_min_actions: 15
  116. session_learner_mode: project
  117. ```
  118. Recent versions also support extra stop-checklist items and custom instruction reminders.
  119. ## Typical workflow
  120. 1. Install the plugin once.
  121. 2. Run the scaffold installer in a repo.
  122. 3. Keep `WORKSPACE.md` and `.meridian/docs/` useful.
  123. 4. Use Claude Code normally.
  124. 5. Let Meridian keep context, docs, and session hygiene from falling apart.
  125. ## Worktrees
  126. 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.
  127. If you work heavily with git worktrees, this is a very nice quality-of-life improvement.
  128. ## FAQ
  129. ### Does this replace `CLAUDE.md`?
  130. No. `CLAUDE.md` is still your core instruction file. Meridian helps those instructions stay alive in practice during longer sessions.
  131. ### Does Meridian change how I prompt Claude?
  132. Not much. It is designed to improve behavior without forcing a whole new user workflow.
  133. ### Is Meridian only for huge repos?
  134. No, but the payoff is much bigger once tasks are large enough that session continuity and docs routing matter.
  135. ### Can I customize it?
  136. Yes. The main entry points are:
  137. - `.meridian/config.yaml`
  138. - `.meridian/docs/`
  139. - `.meridian/prompts/`
  140. - your normal `CLAUDE.md`
  141. ## Contributing
  142. Issues and PRs are welcome.
  143. If you are making a meaningful behavior change, update the docs and [CHANGELOG.md](CHANGELOG.md) in the same PR.
install.sh · Bundled script · 364 lines · 1 finding marked
  1. #!/bin/bash
  2. set -euo pipefail
  3. # Meridian Installer — scaffolding only
  4. # Hooks, agents, skills, and commands are managed by the Claude Code plugin.
  5. # Usage: curl -fsSL https://raw.githubusercontent.com/markmdev/meridian/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 6 on GitHub
  6. # Or: ./install.sh [--version X.X.X] [target-dir]
  7. REPO="markmdev/meridian"
  8. VERSION=""
  9. TARGET_DIR="."
  10. MANIFEST_FILE=".meridian/.manifest"
  11. # Colors (disabled if not terminal)
  12. if [[ -t 1 ]]; then
  13. RED='\033[0;31m'
  14. GREEN='\033[0;32m'
  15. YELLOW='\033[1;33m'
  16. BLUE='\033[0;34m'
  17. NC='\033[0m'
  18. else
  19. RED='' GREEN='' YELLOW='' BLUE='' NC=''
  20. fi
  21. log() { echo -e "${GREEN}[meridian]${NC} $1"; }
  22. warn() { echo -e "${YELLOW}[meridian]${NC} $1"; }
  23. error() { echo -e "${RED}[meridian]${NC} $1" >&2; exit 1; }
  24. info() { echo -e "${BLUE}[meridian]${NC} $1"; }
  25. # Parse arguments
  26. while [[ $# -gt 0 ]]; do
  27. case $1 in
  28. --version|-v) VERSION="$2"; shift 2 ;;
  29. --check)
  30. # Check installed version
  31. if [[ -f ".meridian/.version" ]]; then
  32. echo "Installed: $(cat .meridian/.version)"
  33. else
  34. echo "Meridian not installed in current directory"
  35. fi
  36. exit 0
  37. ;;
  38. --help|-h)
  39. cat << 'EOF'
  40. Meridian Installer (scaffolding only)
  41. Hooks, agents, skills, and commands are managed by the Claude Code plugin.
  42. This script installs .meridian/ project scaffolding.
  43. Usage: install.sh [OPTIONS] [target-dir]
  44. Options:
  45. --version, -v VERSION Install specific version (default: latest)
  46. --check Show installed version and exit
  47. --help, -h Show this help
  48. Examples:
  49. install.sh # Install latest to current dir
  50. install.sh ~/my-project # Install latest to ~/my-project
  51. install.sh -v 0.6.0 . # Install specific version
  52. curl -fsSL URL/install.sh | bash # Install from web
  53. State files preserved on update:
  54. - .meridian/WORKSPACE.md
  55. - .meridian/workspace/
  56. - .meridian/config.yaml (merged with new defaults)
  57. - .meridian/api-docs/
  58. Update flow:
  59. Scaffolding: curl -fsSL URL/install.sh | bash (or meridian-update)
  60. Plugin: /plugin update meridian@markmdev
  61. EOF
  62. exit 0
  63. ;;
  64. -*) error "Unknown option: $1. Use --help for usage." ;;
  65. *) TARGET_DIR="$1"; shift ;;
  66. esac
  67. done
  68. # Resolve target directory
  69. if [[ ! -d "$TARGET_DIR" ]]; then
  70. error "Target directory does not exist: $TARGET_DIR"
  71. fi
  72. TARGET_DIR=$(cd "$TARGET_DIR" && pwd)
  73. # Check dependencies
  74. command -v curl >/dev/null 2>&1 || error "curl is required"
  75. command -v tar >/dev/null 2>&1 || error "tar is required"
  76. command -v python3 >/dev/null 2>&1 || error "python3 is required"
  77. # Get version (latest if not specified)
  78. if [[ -z "$VERSION" ]]; then
  79. log "Fetching latest version..."
  80. VERSION=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" 2>/dev/null | grep '"tag_name"' | head -1 | cut -d'"' -f4 || true)
  81. # Fallback: get latest tag
  82. if [[ -z "$VERSION" ]]; then
  83. VERSION=$(curl -fsSL "https://api.github.com/repos/$REPO/tags" 2>/dev/null | grep '"name"' | head -1 | cut -d'"' -f4 || true)
  84. fi
  85. if [[ -z "$VERSION" ]]; then
  86. error "Could not determine latest version. Specify manually with --version"
  87. fi
  88. fi
  89. # Normalize version (remove 'v' prefix if present for consistency)
  90. VERSION="${VERSION#v}"
  91. log "Installing Meridian v$VERSION to $TARGET_DIR"
  92. # Check if already at this version
  93. if [[ -f "$TARGET_DIR/.meridian/.version" ]]; then
  94. CURRENT=$(cat "$TARGET_DIR/.meridian/.version" | tr -d 'v')
  95. if [[ "$CURRENT" == "$VERSION" ]]; then
  96. info "Already at version $VERSION. Reinstalling..."
  97. fi
  98. fi
  99. # Download to temp directory
  100. TEMP_DIR=$(mktemp -d)
  101. trap "rm -rf '$TEMP_DIR'" EXIT
  102. log "Downloading..."
  103. # Try different URL patterns
  104. DOWNLOAD_SUCCESS=false
  105. for url in \
  106. "https://github.com/$REPO/archive/refs/tags/v$VERSION.tar.gz" \
  107. "https://github.com/$REPO/archive/refs/tags/$VERSION.tar.gz" \
  108. "https://github.com/$REPO/releases/download/v$VERSION/meridian.tar.gz" \
  109. "https://github.com/$REPO/releases/download/$VERSION/meridian.tar.gz"
  110. do
  111. if curl -fsSL "$url" -o "$TEMP_DIR/meridian.tar.gz" 2>/dev/null; then
  112. DOWNLOAD_SUCCESS=true
  113. break
  114. fi
  115. done
  116. if [[ "$DOWNLOAD_SUCCESS" == false ]]; then
  117. error "Could not download version $VERSION. Check if version exists."
  118. fi
  119. # Extract
  120. log "Extracting..."
  121. tar -xzf "$TEMP_DIR/meridian.tar.gz" -C "$TEMP_DIR"
  122. # Find the extracted directory (handles different archive structures)
  123. # GitHub archives create: meridian-VERSION/ containing the repo
  124. EXTRACT_DIR=$(find "$TEMP_DIR" -maxdepth 1 -type d -name "meridian*" | head -1)
  125. if [[ -z "$EXTRACT_DIR" || ! -d "$EXTRACT_DIR" ]]; then
  126. error "Could not find extracted directory"
  127. fi
  128. # The actual Meridian scaffolding is in the .meridian/ subdirectory
  129. if [[ -d "$EXTRACT_DIR/meridian/.meridian" ]]; then
  130. SOURCE_DIR="$EXTRACT_DIR/meridian"
  131. elif [[ -d "$EXTRACT_DIR/.meridian" ]]; then
  132. SOURCE_DIR="$EXTRACT_DIR"
  133. else
  134. error "Could not find Meridian files (.meridian directory) in archive"
  135. fi
  136. is_state_file() {
  137. local file="$1"
  138. case "$file" in
  139. .meridian/WORKSPACE.md) return 0 ;;
  140. .meridian/workspace|.meridian/workspace/*) return 0 ;;
  141. .meridian/config.yaml) return 0 ;;
  142. .meridian/api-docs|.meridian/api-docs/*) return 0 ;;
  143. .meridian/plans|.meridian/plans/*) return 0 ;;
  144. .meridian/.manifest) return 0 ;;
  145. .meridian/.version) return 0 ;;
  146. esac
  147. return 1
  148. }
  149. # Check if this is an update or fresh install
  150. if [[ -f "$TARGET_DIR/$MANIFEST_FILE" ]]; then
  151. MODE="update"
  152. HAS_MANIFEST=true
  153. log "Existing installation detected, updating..."
  154. elif [[ -f "$TARGET_DIR/.meridian/.version" || -f "$TARGET_DIR/.meridian/config.yaml" ]]; then
  155. MODE="update"
  156. HAS_MANIFEST=false
  157. log "Existing installation detected (no manifest), updating..."
  158. else
  159. MODE="install"
  160. HAS_MANIFEST=false
  161. log "Fresh installation..."
  162. fi
  163. # If updating with manifest, delete old managed files (except state files)
  164. if [[ "$MODE" == "update" && "$HAS_MANIFEST" == true ]]; then
  165. DELETED=0
  166. while IFS= read -r file || [[ -n "$file" ]]; do
  167. [[ -z "$file" ]] && continue
  168. if ! is_state_file "$file" && [[ -e "$TARGET_DIR/$file" ]]; then
  169. rm -rf "$TARGET_DIR/$file"
  170. ((DELETED++)) || true
  171. fi
  172. done < "$TARGET_DIR/$MANIFEST_FILE"
  173. if [[ $DELETED -gt 0 ]]; then
  174. info "Removed $DELETED old file(s)"
  175. fi
  176. fi
  177. # Copy files and build manifest
  178. > "$TEMP_DIR/manifest.txt"
  179. COPIED=0
  180. copy_dir() {
  181. local src_base="$1"
  182. local dst_base="$2"
  183. local prefix="$3"
  184. if [[ ! -d "$src_base" ]]; then
  185. return
  186. fi
  187. while IFS= read -r -d '' src_file; do
  188. rel_path="${src_file#$src_base/}"
  189. full_rel="$prefix$rel_path"
  190. dst_file="$dst_base/$rel_path"
  191. # Skip state files on update
  192. if [[ "$MODE" == "update" ]] && is_state_file "$full_rel"; then
  193. continue
  194. fi
  195. # Create directory and copy file
  196. mkdir -p "$(dirname "$dst_file")"
  197. cp "$src_file" "$dst_file"
  198. echo "$full_rel" >> "$TEMP_DIR/manifest.txt"
  199. ((COPIED++)) || true
  200. done < <(find "$src_base" -type f -print0)
  201. }
  202. # Copy .meridian/ scaffolding only
  203. log "Installing files..."
  204. copy_dir "$SOURCE_DIR/.meridian" "$TARGET_DIR/.meridian" ".meridian/"
  205. info "Copied $COPIED file(s)"
  206. # Merge config.yaml if updating and both exist
  207. if [[ "$MODE" == "update" && -f "$TARGET_DIR/.meridian/config.yaml" && -f "$SOURCE_DIR/.meridian/config.yaml" ]]; then
  208. log "Merging config.yaml..."
  209. MERGE_OUTPUT=$(python3 - "$TARGET_DIR/.meridian/config.yaml" "$SOURCE_DIR/.meridian/config.yaml" << 'PYTHON_SCRIPT'
  210. import sys
  211. def parse_yaml_simple(content):
  212. """Simple YAML parser for flat key: value files"""
  213. result = {}
  214. for line in content.split('\n'):
  215. # Skip empty lines and comments
  216. stripped = line.strip()
  217. if not stripped or stripped.startswith('#'):
  218. continue
  219. if ':' in line:
  220. key, _, value = line.partition(':')
  221. key = key.strip()
  222. value = value.strip()
  223. # Remove inline comments
  224. if '#' in value:
  225. value = value.split('#')[0].strip()
  226. # Handle types
  227. if value.lower() == 'true':
  228. value = True
  229. elif value.lower() == 'false':
  230. value = False
  231. elif value.isdigit():
  232. value = int(value)
  233. result[key] = value
  234. return result
  235. def merge_configs(user_path, default_path):
  236. """Add missing keys from default to user config"""
  237. with open(user_path, 'r') as f:
  238. user_content = f.read()
  239. with open(default_path, 'r') as f:
  240. default_content = f.read()
  241. user_config = parse_yaml_simple(user_content)
  242. default_config = parse_yaml_simple(default_content)
  243. # Find keys in default that aren't in user
  244. new_keys = []
  245. for key, value in default_config.items():
  246. if key not in user_config:
  247. new_keys.append((key, value))
  248. if not new_keys:
  249. print("Config up to date")
  250. return
  251. # Append new keys to user config file
  252. with open(user_path, 'a') as f:
  253. f.write('\n# Added by Meridian v' + (sys.argv[3] if len(sys.argv) > 3 else '') + '\n')
  254. for key, value in new_keys:
  255. if isinstance(value, bool):
  256. value = str(value).lower()
  257. f.write(f'{key}: {value}\n')
  258. print(f"Added: {', '.join(k for k, _ in new_keys)}")
  259. if __name__ == '__main__':
  260. merge_configs(sys.argv[1], sys.argv[2])
  261. PYTHON_SCRIPT
  262. ) || true
  263. if [[ -n "$MERGE_OUTPUT" ]]; then
  264. info "$MERGE_OUTPUT"
  265. fi
  266. fi
  267. # Write manifest and version
  268. sort -u "$TEMP_DIR/manifest.txt" > "$TARGET_DIR/$MANIFEST_FILE" 2>/dev/null || true
  269. echo "$VERSION" > "$TARGET_DIR/.meridian/.version"
  270. # Make scripts executable
  271. log "Setting permissions..."
  272. find "$TARGET_DIR/.meridian/scripts" -type f \( -name "*.py" -o -name "*.sh" \) -exec chmod +x {} \; 2>/dev/null || true
  273. # Check if plugin is installed
  274. PLUGIN_INSTALLED=false
  275. if [[ -d "$HOME/.claude/plugins/cache/markmdev/meridian" ]]; then
  276. PLUGIN_INSTALLED=true
  277. fi
  278. # Success
  279. echo ""
  280. echo -e "${GREEN}Meridian v$VERSION installed successfully${NC}"
  281. echo ""
  282. echo " Location: $TARGET_DIR"
  283. echo " Mode: $MODE"
  284. echo ""
  285. if [[ "$MODE" == "install" ]]; then
  286. echo "Next steps:"
  287. if [[ "$PLUGIN_INSTALLED" == false ]]; then
  288. echo " 1. Install the plugin:"
  289. echo " /plugin marketplace add markmdev/claude-plugins"
  290. echo " /plugin install meridian@markmdev"
  291. echo " 2. Review .meridian/config.yaml for settings"
  292. echo " 3. Add docs to .meridian/docs/ with summary + read_when frontmatter"
  293. echo " 4. Open project in Claude Code — hooks activate automatically"
  294. else
  295. echo " 1. Review .meridian/config.yaml for settings"
  296. echo " 2. Add docs to .meridian/docs/ with summary + read_when frontmatter"
  297. echo " 3. Open project in Claude Code — hooks activate automatically"
  298. fi
  299. echo ""
  300. fi
  301. if [[ "$MODE" == "update" ]]; then
  302. echo "Updated .meridian/ scaffolding. State preserved:"
  303. echo " - WORKSPACE.md + workspace/"
  304. echo " - config.yaml (merged)"
  305. echo " - api-docs/"
  306. echo ""
  307. echo "To update hooks/agents/skills: /plugin update meridian@markmdev"
  308. echo ""
  309. fi

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.