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.
Badge for your README
Markdown
[](/listings/markmdev--meridian)HTML
<a href="/listings/markmdev--meridian"><img src="/api/listings/markmdev--meridian/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- 
- # 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
- ```bash
- /plugin marketplace add markmdev/claude-plugins
- /plugin install meridian@markmdev
- ```
- ### 2. Scaffold the project files
- Inside the repo you want to use with Meridian:
- ```bash
- 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
- ```
- 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:
- ```bash
- meridian-update
- ```
- Or:
- ```bash
- 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
- ```
- Update the plugin itself:
- ```bash
- /plugin update meridian@markmdev
- ```
- Check the installed project version:
- ```bash
- 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`:
- ```text
- .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:
- ```yaml
- ---
- summary: What this doc covers
- read_when:
- - keyword or situation
- - another keyword
- ---
- ```
- ### `.meridian/config.yaml`
- Project-level behavior toggles.
- Current built-in options include:
- ```yaml
- 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](CHANGELOG.md) in the same PR.
install.sh · Bundled script · 364 lines · 1 finding marked
- #!/bin/bash
- set -euo pipefail
- # Meridian Installer — scaffolding only
- # Hooks, agents, skills, and commands are managed by the Claude Code plugin.
- # 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
- # Or: ./install.sh [--version X.X.X] [target-dir]
- REPO="markmdev/meridian"
- VERSION=""
- TARGET_DIR="."
- MANIFEST_FILE=".meridian/.manifest"
- # Colors (disabled if not terminal)
- if [[ -t 1 ]]; then
- RED='\033[0;31m'
- GREEN='\033[0;32m'
- YELLOW='\033[1;33m'
- BLUE='\033[0;34m'
- NC='\033[0m'
- else
- RED='' GREEN='' YELLOW='' BLUE='' NC=''
- fi
- log() { echo -e "${GREEN}[meridian]${NC} $1"; }
- warn() { echo -e "${YELLOW}[meridian]${NC} $1"; }
- error() { echo -e "${RED}[meridian]${NC} $1" >&2; exit 1; }
- info() { echo -e "${BLUE}[meridian]${NC} $1"; }
- # Parse arguments
- while [[ $# -gt 0 ]]; do
- case $1 in
- --version|-v) VERSION="$2"; shift 2 ;;
- --check)
- # Check installed version
- if [[ -f ".meridian/.version" ]]; then
- echo "Installed: $(cat .meridian/.version)"
- else
- echo "Meridian not installed in current directory"
- fi
- exit 0
- ;;
- --help|-h)
- cat << 'EOF'
- Meridian Installer (scaffolding only)
- Hooks, agents, skills, and commands are managed by the Claude Code plugin.
- This script installs .meridian/ project scaffolding.
- Usage: install.sh [OPTIONS] [target-dir]
- Options:
- --version, -v VERSION Install specific version (default: latest)
- --check Show installed version and exit
- --help, -h Show this help
- Examples:
- install.sh # Install latest to current dir
- install.sh ~/my-project # Install latest to ~/my-project
- install.sh -v 0.6.0 . # Install specific version
- curl -fsSL URL/install.sh | bash # Install from web
- State files preserved on update:
- - .meridian/WORKSPACE.md
- - .meridian/workspace/
- - .meridian/config.yaml (merged with new defaults)
- - .meridian/api-docs/
- Update flow:
- Scaffolding: curl -fsSL URL/install.sh | bash (or meridian-update)
- Plugin: /plugin update meridian@markmdev
- EOF
- exit 0
- ;;
- -*) error "Unknown option: $1. Use --help for usage." ;;
- *) TARGET_DIR="$1"; shift ;;
- esac
- done
- # Resolve target directory
- if [[ ! -d "$TARGET_DIR" ]]; then
- error "Target directory does not exist: $TARGET_DIR"
- fi
- TARGET_DIR=$(cd "$TARGET_DIR" && pwd)
- # Check dependencies
- command -v curl >/dev/null 2>&1 || error "curl is required"
- command -v tar >/dev/null 2>&1 || error "tar is required"
- command -v python3 >/dev/null 2>&1 || error "python3 is required"
- # Get version (latest if not specified)
- if [[ -z "$VERSION" ]]; then
- log "Fetching latest version..."
- VERSION=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" 2>/dev/null | grep '"tag_name"' | head -1 | cut -d'"' -f4 || true)
- # Fallback: get latest tag
- if [[ -z "$VERSION" ]]; then
- VERSION=$(curl -fsSL "https://api.github.com/repos/$REPO/tags" 2>/dev/null | grep '"name"' | head -1 | cut -d'"' -f4 || true)
- fi
- if [[ -z "$VERSION" ]]; then
- error "Could not determine latest version. Specify manually with --version"
- fi
- fi
- # Normalize version (remove 'v' prefix if present for consistency)
- VERSION="${VERSION#v}"
- log "Installing Meridian v$VERSION to $TARGET_DIR"
- # Check if already at this version
- if [[ -f "$TARGET_DIR/.meridian/.version" ]]; then
- CURRENT=$(cat "$TARGET_DIR/.meridian/.version" | tr -d 'v')
- if [[ "$CURRENT" == "$VERSION" ]]; then
- info "Already at version $VERSION. Reinstalling..."
- fi
- fi
- # Download to temp directory
- TEMP_DIR=$(mktemp -d)
- trap "rm -rf '$TEMP_DIR'" EXIT
- log "Downloading..."
- # Try different URL patterns
- DOWNLOAD_SUCCESS=false
- for url in \
- "https://github.com/$REPO/archive/refs/tags/v$VERSION.tar.gz" \
- "https://github.com/$REPO/archive/refs/tags/$VERSION.tar.gz" \
- "https://github.com/$REPO/releases/download/v$VERSION/meridian.tar.gz" \
- "https://github.com/$REPO/releases/download/$VERSION/meridian.tar.gz"
- do
- if curl -fsSL "$url" -o "$TEMP_DIR/meridian.tar.gz" 2>/dev/null; then
- DOWNLOAD_SUCCESS=true
- break
- fi
- done
- if [[ "$DOWNLOAD_SUCCESS" == false ]]; then
- error "Could not download version $VERSION. Check if version exists."
- fi
- # Extract
- log "Extracting..."
- tar -xzf "$TEMP_DIR/meridian.tar.gz" -C "$TEMP_DIR"
- # Find the extracted directory (handles different archive structures)
- # GitHub archives create: meridian-VERSION/ containing the repo
- EXTRACT_DIR=$(find "$TEMP_DIR" -maxdepth 1 -type d -name "meridian*" | head -1)
- if [[ -z "$EXTRACT_DIR" || ! -d "$EXTRACT_DIR" ]]; then
- error "Could not find extracted directory"
- fi
- # The actual Meridian scaffolding is in the .meridian/ subdirectory
- if [[ -d "$EXTRACT_DIR/meridian/.meridian" ]]; then
- SOURCE_DIR="$EXTRACT_DIR/meridian"
- elif [[ -d "$EXTRACT_DIR/.meridian" ]]; then
- SOURCE_DIR="$EXTRACT_DIR"
- else
- error "Could not find Meridian files (.meridian directory) in archive"
- fi
- is_state_file() {
- local file="$1"
- case "$file" in
- .meridian/WORKSPACE.md) return 0 ;;
- .meridian/workspace|.meridian/workspace/*) return 0 ;;
- .meridian/config.yaml) return 0 ;;
- .meridian/api-docs|.meridian/api-docs/*) return 0 ;;
- .meridian/plans|.meridian/plans/*) return 0 ;;
- .meridian/.manifest) return 0 ;;
- .meridian/.version) return 0 ;;
- esac
- return 1
- }
- # Check if this is an update or fresh install
- if [[ -f "$TARGET_DIR/$MANIFEST_FILE" ]]; then
- MODE="update"
- HAS_MANIFEST=true
- log "Existing installation detected, updating..."
- elif [[ -f "$TARGET_DIR/.meridian/.version" || -f "$TARGET_DIR/.meridian/config.yaml" ]]; then
- MODE="update"
- HAS_MANIFEST=false
- log "Existing installation detected (no manifest), updating..."
- else
- MODE="install"
- HAS_MANIFEST=false
- log "Fresh installation..."
- fi
- # If updating with manifest, delete old managed files (except state files)
- if [[ "$MODE" == "update" && "$HAS_MANIFEST" == true ]]; then
- DELETED=0
- while IFS= read -r file || [[ -n "$file" ]]; do
- [[ -z "$file" ]] && continue
- if ! is_state_file "$file" && [[ -e "$TARGET_DIR/$file" ]]; then
- rm -rf "$TARGET_DIR/$file"
- ((DELETED++)) || true
- fi
- done < "$TARGET_DIR/$MANIFEST_FILE"
- if [[ $DELETED -gt 0 ]]; then
- info "Removed $DELETED old file(s)"
- fi
- fi
- # Copy files and build manifest
- > "$TEMP_DIR/manifest.txt"
- COPIED=0
- copy_dir() {
- local src_base="$1"
- local dst_base="$2"
- local prefix="$3"
- if [[ ! -d "$src_base" ]]; then
- return
- fi
- while IFS= read -r -d '' src_file; do
- rel_path="${src_file#$src_base/}"
- full_rel="$prefix$rel_path"
- dst_file="$dst_base/$rel_path"
- # Skip state files on update
- if [[ "$MODE" == "update" ]] && is_state_file "$full_rel"; then
- continue
- fi
- # Create directory and copy file
- mkdir -p "$(dirname "$dst_file")"
- cp "$src_file" "$dst_file"
- echo "$full_rel" >> "$TEMP_DIR/manifest.txt"
- ((COPIED++)) || true
- done < <(find "$src_base" -type f -print0)
- }
- # Copy .meridian/ scaffolding only
- log "Installing files..."
- copy_dir "$SOURCE_DIR/.meridian" "$TARGET_DIR/.meridian" ".meridian/"
- info "Copied $COPIED file(s)"
- # Merge config.yaml if updating and both exist
- if [[ "$MODE" == "update" && -f "$TARGET_DIR/.meridian/config.yaml" && -f "$SOURCE_DIR/.meridian/config.yaml" ]]; then
- log "Merging config.yaml..."
- MERGE_OUTPUT=$(python3 - "$TARGET_DIR/.meridian/config.yaml" "$SOURCE_DIR/.meridian/config.yaml" << 'PYTHON_SCRIPT'
- import sys
- def parse_yaml_simple(content):
- """Simple YAML parser for flat key: value files"""
- result = {}
- for line in content.split('\n'):
- # Skip empty lines and comments
- stripped = line.strip()
- if not stripped or stripped.startswith('#'):
- continue
- if ':' in line:
- key, _, value = line.partition(':')
- key = key.strip()
- value = value.strip()
- # Remove inline comments
- if '#' in value:
- value = value.split('#')[0].strip()
- # Handle types
- if value.lower() == 'true':
- value = True
- elif value.lower() == 'false':
- value = False
- elif value.isdigit():
- value = int(value)
- result[key] = value
- return result
- def merge_configs(user_path, default_path):
- """Add missing keys from default to user config"""
- with open(user_path, 'r') as f:
- user_content = f.read()
- with open(default_path, 'r') as f:
- default_content = f.read()
- user_config = parse_yaml_simple(user_content)
- default_config = parse_yaml_simple(default_content)
- # Find keys in default that aren't in user
- new_keys = []
- for key, value in default_config.items():
- if key not in user_config:
- new_keys.append((key, value))
- if not new_keys:
- print("Config up to date")
- return
- # Append new keys to user config file
- with open(user_path, 'a') as f:
- f.write('\n# Added by Meridian v' + (sys.argv[3] if len(sys.argv) > 3 else '') + '\n')
- for key, value in new_keys:
- if isinstance(value, bool):
- value = str(value).lower()
- f.write(f'{key}: {value}\n')
- print(f"Added: {', '.join(k for k, _ in new_keys)}")
- if __name__ == '__main__':
- merge_configs(sys.argv[1], sys.argv[2])
- PYTHON_SCRIPT
- ) || true
- if [[ -n "$MERGE_OUTPUT" ]]; then
- info "$MERGE_OUTPUT"
- fi
- fi
- # Write manifest and version
- sort -u "$TEMP_DIR/manifest.txt" > "$TARGET_DIR/$MANIFEST_FILE" 2>/dev/null || true
- echo "$VERSION" > "$TARGET_DIR/.meridian/.version"
- # Make scripts executable
- log "Setting permissions..."
- find "$TARGET_DIR/.meridian/scripts" -type f \( -name "*.py" -o -name "*.sh" \) -exec chmod +x {} \; 2>/dev/null || true
- # Check if plugin is installed
- PLUGIN_INSTALLED=false
- if [[ -d "$HOME/.claude/plugins/cache/markmdev/meridian" ]]; then
- PLUGIN_INSTALLED=true
- fi
- # Success
- echo ""
- echo -e "${GREEN}Meridian v$VERSION installed successfully${NC}"
- echo ""
- echo " Location: $TARGET_DIR"
- echo " Mode: $MODE"
- echo ""
- if [[ "$MODE" == "install" ]]; then
- echo "Next steps:"
- if [[ "$PLUGIN_INSTALLED" == false ]]; then
- echo " 1. Install the plugin:"
- echo " /plugin marketplace add markmdev/claude-plugins"
- echo " /plugin install meridian@markmdev"
- echo " 2. Review .meridian/config.yaml for settings"
- echo " 3. Add docs to .meridian/docs/ with summary + read_when frontmatter"
- echo " 4. Open project in Claude Code — hooks activate automatically"
- else
- echo " 1. Review .meridian/config.yaml for settings"
- echo " 2. Add docs to .meridian/docs/ with summary + read_when frontmatter"
- echo " 3. Open project in Claude Code — hooks activate automatically"
- fi
- echo ""
- fi
- if [[ "$MODE" == "update" ]]; then
- echo "Updated .meridian/ scaffolding. State preserved:"
- echo " - WORKSPACE.md + workspace/"
- echo " - config.yaml (merged)"
- echo " - api-docs/"
- echo ""
- echo "To update hooks/agents/skills: /plugin update meridian@markmdev"
- echo ""
- fi
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.