Complete reference for all Massu CLI commands (npx massu init/doctor/...) and 59 workflow slash commands (/massu-*)

CLI Reference

Massu AI ships with five CLI commands for project setup and maintenance plus 59 workflow slash commands that activate inside a Claude Code session.

CLI commands run via npx massu <command> from your shell.
Slash commands run via /massu-<name> inside a Claude Code session after npx massu init deploys them.

massu init

Full project setup in one command. Detects your framework, generates configuration, registers the MCP server, installs all 16 lifecycle hooks, and deploys 59 slash commands.

Usage

bash

npx massu init

What It Does

Framework Detection — Scans package.json for TypeScript, Next.js, SvelteKit, Nuxt, Prisma, Drizzle, tRPC, GraphQL, Express, and more
Config Generation — Creates massu.config.yaml with detected framework settings
MCP Registration — Creates or merges .mcp.json to register the Massu MCP server
Hook Installation — Configures all 16 lifecycle hooks in .claude/settings.local.json
Slash Command Installation — Deploys 59 workflow commands into .claude/commands/

Output

Massu AI - Project Setup
========================

  Detected: TypeScript, Next.js, Prisma, tRPC
  Created massu.config.yaml
  Registered MCP server in .mcp.json
  Installed 16 hooks in .claude/settings.local.json
  Installed 59 slash commands in .claude/commands/
  Databases will auto-create on first session

Massu AI is ready. Start a Claude Code session to begin.

Files Created

File	Purpose
`massu.config.yaml`	Project configuration
`.mcp.json`	MCP server registration
`.claude/settings.local.json`	Hook configuration
`.claude/commands/*.md`	59 slash command definitions

massu doctor

Health check that verifies all components of a Massu AI installation are working.

Usage

bash

npx massu doctor

Checks Performed

Check	What It Verifies
Configuration	`massu.config.yaml` exists and parses correctly
MCP Server	`.mcp.json` has massu entry
Hooks Config	`.claude/settings.local.json` has hooks configured
Hook Files	All 11 compiled hook files exist
Slash Commands	`.claude/commands/` has 59 command files
Native Modules	`better-sqlite3` loads correctly
Node.js	Version >= 18
Git Repository	Git repo detected with branch info

Output

Massu AI Health Check
=====================

  ✓ Configuration      massu.config.yaml found and valid
  ✓ MCP Server         Registered in .mcp.json
  ✓ Hooks Config       16 hooks configured
  ✓ Hook Files         11/11 compiled hooks present
  ✓ Slash Commands     59/59 commands installed
  ✓ Native Modules     better-sqlite3 loads correctly
  ✓ Node.js            v20.11.0 (>= 18 required)
  ✓ Git Repository     Detected (branch: main)

Status: HEALTHY (8/8 checks passed)

Exit Codes

Code	Meaning
`0`	All checks passed
`1`	One or more checks failed

massu install-hooks

Install or update all 11 Claude Code hooks without running the full init process.

Usage

bash

npx massu install-hooks

When to Use

After updating @massu/core to a new version
If hooks were accidentally removed from .claude/settings.local.json
To re-install hooks without regenerating config or MCP registration

Output

Massu AI - Hook Installation
============================

  Installed 16 hooks in .claude/settings.local.json

Hooks will activate on your next Claude Code session.

massu install-commands

Install or update all 59 slash commands without running the full init process. By default also seeds mcpmassu* into .claude/settings.local.json so MCP tool calls skip the per-tool permission dialog.

Usage

bash

npx massu install-commands
npx massu install-commands --skip-permissions

Options

Flag	Description
`--skip-permissions`	Skip seeding the canonical `mcpmassu*` glob into `.claude/settings.local.json`'s `permissions.allow`. Use when permissions are managed by enterprise policy.

When to Use

After updating @massu/core to a new version (to get the latest command definitions)
If command files were accidentally deleted from .claude/commands/
To re-install commands without regenerating config, MCP registration, or hooks
To seed mcpmassu* into permissions.allow on a fresh install (default) — eliminates the per-tool permission dialog and propagates global defaultMode to prevent the merge-replacement trap

Output

Massu AI - Command Installation
================================

  Installed 59 slash commands in .claude/commands/
  Wrote merged permissions block to .claude/settings.local.json (use --skip-permissions to opt out).

Commands will be available in your next Claude Code session.

massu permissions

Three subcommands managing the MCP allowlist lifecycle in .claude/settings.local.json.

Usage

bash

npx massu permissions install
npx massu permissions verify
npx massu permissions check-drift

Subcommands

Subcommand	Effect	Exit codes
`install`	Seeds `mcpmassu*` into `permissions.allow` AND propagates user-global `defaultMode` (`~/.claude/settings.json`) into the project-local file. Idempotent. Preserves operator-edited values.	0
`verify`	Read-only check that all canonical MCP allowlist entries are present.	0 if clean; 1 with `missing: <entry>` per missing entry on stderr
`check-drift`	Extended diagnostic surfacing 4 drift kinds.	See exit code matrix below

`check-drift` exit code matrix

Highest-severity kind wins when multiple kinds are present:

Exit code	Drift kind	Meaning
0	(clean)	No drift detected
1	`missing-allow`	Canonical massu entries missing from `permissions.allow`
2	`invalid-default-mode`	`defaultMode` set to a value that requires `--permission-mode` launch flag (`bypassPermissions`, `auto`, `dontAsk`) — silently inert without the flag
3	`unknown-key`	Top-level setting key is not documented at `code.claude.com/docs/en/settings` (e.g., common typo `skipAutoPermissionPrompt`) — silently ignored by Claude Code
4	`strips-global-defaultmode`	Project-local `permissions` object would strip the global `defaultMode` during settings merge (empirically observed; undocumented behavior).

When to Use

Run install once per fresh project clone (or rely on automatic seeding via install-commands)
Run verify as a quick pre-flight sanity check
Run check-drift when MCP calls auto-deny silently OR when migrating between Claude Code versions

Example: detecting the merge-replacement trap

bash

$ npx massu permissions check-drift
drift[strips-global-defaultmode]: Project-local permissions object omits defaultMode while global ~/.claude/settings.json has defaultMode="auto". Per empirical observation (2026-05-14) the merge unit is the entire permissions object, so the global defaultMode is silently stripped. — remediation: Run `npx massu permissions install` to write the full merged permissions block (auto-propagates global defaultMode).
$ echo $?
4

massu changelog

Two subcommands managing release-boundary CHANGELOG generation. Shipped in 1.9.0 (plan-1.9.0-plan-token-aware-changelog-batcher).

Usage

bash

npx massu changelog generate
npx massu changelog verify

Subcommands

Subcommand	Effect	Exit codes
`generate`	Reads commit subjects since `git describe --tags --abbrev=0`, groups by `(plan-<token>)` paren-notation, pulls each plan file's `## Changelog Summary` section, and emits a Keep-a-Changelog 1.1.0-compliant entry to stdout. Operator pipes/copies into CHANGELOG.md (no forced overwrite).	0 (clean) / 2 (missing plan file or missing `## Changelog Summary` section for a referenced token)
`verify`	Read-only check that the latest CHANGELOG.md entry references every plan-token in commits since the last tag.	0 (all referenced) / 1 (`gap: <token>` per missing, on stderr)

Plan-file `## Changelog Summary` contract

Any plan with Status in the shipped subset (SHIPPED, IMPLEMENTED, COMPLETE, SUPERSEDED, APPROVED) MUST contain a ## Changelog Summary heading. The plan-status validator at scripts/massu-plan-status-validator.sh enforces this. The generator reads this section verbatim into the CHANGELOG entry body, so plan authors describe shipped behavior in one place — the plan file.

Example plan structure:

markdown

# Plan: Feature X

**Plan Token**: `plan-1.9.0-feature-x`
**Status**: SHIPPED 2026-05-14 (SHA abc1234)

---

## Changelog Summary

Plan `plan-1.9.0-feature-x` — Brief description of shipped behavior. Concrete benefit to operators + key file:line refs + structural drift-prevention notes.

---

## Other sections (Problem statement, P-items, etc.)

Pre-tag gate

scripts/pre-push-light.sh step [11/11] Plan-Token Changelog Currency fires when packages/core/package.json#version drifts from the latest git tag (release in progress). The gate BLOCKS the push if CHANGELOG.md doesn't have a matching ## [X.Y.Z] heading AND doesn't reference every plan-token in the commit range. CI mirrors this check (3-layer: pre-push + CI + drift-guard vitest).

When to Use

Run generate during /massu-release Stage D to auto-draft the CHANGELOG entry (skill integration enabled in 1.9.0)
Run verify post-edit to confirm completeness before tagging
The pre-tag gate runs automatically — no manual invocation needed

Example: generating + verifying a release entry

bash

$ npx massu changelog generate > /tmp/draft.md
$ head -3 /tmp/draft.md
## [1.9.0] - 2026-05-14

Plan `plan-1.9.0-plan-token-aware-changelog-batcher` — Release-boundary CHANGELOG batcher...

# Operator prepends draft to CHANGELOG.md, then:
$ npx massu changelog verify
All plan-tokens referenced.
$ echo $?
0

massu validate-config

Validate your massu.config.yaml without running the full health check.

Usage

bash

npx massu validate-config

What It Checks

File exists in current directory
Valid YAML syntax
Required fields present (project.name, toolPrefix, framework.type)

Output (Valid)

massu.config.yaml is valid

Output (Warnings)

massu.config.yaml parsed successfully with warnings:
  ! Missing project.name (will default to "my-project")
  ! Missing toolPrefix (will default to "massu")

Exit Codes

Code	Meaning
`0`	Config is valid (may have warnings)
`1`	Config file missing or invalid YAML

Global Options

All commands support:

Flag	Description
`--help`, `-h`	Show help message
`--version`, `-v`	Show version

MCP Server Mode

When no subcommand is provided, npx @massu/core starts the MCP server directly (for advanced use):

bash

npx @massu/core

This is handled automatically by Claude Code via .mcp.json — you don't need to run this manually.

Slash Commands

The following 59 slash commands ship with @massu/core and are deployed into .claude/commands/ by npx massu init and npx massu install-commands. Each command activates inside a Claude Code session by typing /<command-name>. Internal commands (massu-internal-*) are operator-only and intentionally excluded.

/massu-article-review

When user shares a URL, article, tweet, or post and wants analysis of how it applies to the project -- 'review this', 'what do you think of this'

/massu-audit-deps

Comprehensive dependency audit (vulnerabilities, outdated, licenses, unused, bundle size)

/massu-autoresearch

When user wants autonomous command optimization, says 'autoresearch', 'optimize this command', 'run overnight improvement loop', or wants Karpathy-style iterative prompt optimization

/massu-batch

When user wants to apply the same code-only change across multiple files in parallel — 'batch update', 'apply to all', 'migrate these files'

/massu-bearings

When user starts a new session, says 'good morning', asks 'where was I', 'what should I work on', or needs session orientation after being away

/massu-changelog

Generate changelog entries from conventional commits

/massu-checkpoint

When user wants mid-implementation verification, says 'checkpoint', 'check progress', or needs a quality gate during a multi-phase plan

/massu-ci-fix

When CI fails after push — auto-diagnoses failures, fixes, commits, and re-pushes. 'ci fix', 'fix ci', 'ci failed', 'workflow failed'

/massu-cleanup

Dead code removal — unused imports, orphaned files, dead exports, and stale references

/massu-command-health

When user asks about command quality, says 'how are my commands', 'command health', or wants to see which slash commands have quality issues

/massu-command-improve

When user wants to improve a specific command's quality score, says 'improve this command', 'fix command issues', or after command-health shows weak commands

/massu-commit

When user says 'commit', 'ready to commit', 'save my work', or has completed implementation and wants to commit changes

/massu-create-plan

When user wants to plan a feature, fix, or change before implementing -- 'create a plan', 'plan this', or describes requirements that need scoping

/massu-data

When user asks about data trends, metrics, analytics, funnel analysis, cohort comparison, entity counts, storage usage, or 'what happened' questions about the database

/massu-dead-code

When user asks about unused code, says 'find dead code', 'clean up unused', or wants to reduce codebase size by removing unreferenced exports

/massu-debug

When user reports a bug, error, 500, crash, unexpected behavior, broken feature, or pastes error logs/stack traces

/massu-deploy

Deploy the current project to Vercel

/massu-deps

Dependency audit covering security vulnerabilities, updates, and compatibility analysis

/massu-doc-gen

Generate JSDoc comments, README sections, and API docs for undocumented code

/massu-docs

Documentation sync protocol ensuring docs align with code changes and features

/massu-estimate

Effort estimation with complexity scoring, codebase impact analysis, and historical comparison

/massu-full-audit

(See command file for details.)

/massu-gap-enhancement-analyzer

When user says 'analyze gaps', 'find enhancements', 'gap analysis', or has completed a massu-loop implementation and needs to identify remaining gaps and enhancement opportunities

/massu-golden-path

When user wants full autonomous implementation: 'build this', 'implement this feature', 'golden path', or provides a plan file to execute end-to-end

/massu-guide

When a new user or contributor asks 'how does this work', 'give me a tour', 'onboarding', or needs an interactive walkthrough of the codebase

/massu-hooks

EXECUTION

/massu-hotfix

When user needs an urgent fix -- 'hotfix', 'emergency fix', 'broken and needs immediate patch'

/massu-incident

When a bug is confirmed, a production issue is found, or user reports 'this broke', 'incident', 'production error' — triggers incident documentation protocol

/massu-infra-audit

When user asks about .claude/ infrastructure health, says 'audit infra', 'check claude setup', or needs to verify references, staleness, and format compliance

/massu-learning-audit

When user says 'learning audit', 'check auto-learning', 'memory coverage', or needs to validate that incidents are being learned from and patterns are being captured

/massu-loop-playwright

When user wants browser-based testing, says 'test in browser', 'playwright audit', or needs visual/functional verification with Playwright

/massu-loop

When user wants to implement a plan autonomously — 'implement this plan', 'start the loop', 'execute', or provides a plan file to implement end-to-end

/massu-new-feature

Feature scaffolding with correct patterns pre-applied and verification gates

/massu-new-pattern

When user discovers a new pattern, says 'add this pattern', 'new pattern', or needs to formalize a recurring solution into the patterns library with approval

/massu-parity

Generic feature parity check between two systems or components

/massu-perf

When user says 'performance audit', 'slow queries', 'bundle too large', 'page is slow', or needs to identify performance bottlenecks in queries, bundle size, or render cycles

/massu-plan-audit

When user wants to create a plan AND audit it to zero gaps in one flow, says 'plan audit', 'create and audit plan', or needs the combined create-then-audit workflow

/massu-plan

When user wants to audit an existing plan for gaps -- 'audit this plan', 'review the plan', or references a plan file that needs verification

/massu-production-verify

When user says 'verify production', 'is it working', 'production check', or after a deploy to verify features are actually working in production — not just deployed

/massu-push-light

Fast pre-push verification (~90s) - patterns, security, types, hooks, tests, build

/massu-push

When user says 'push', 'push to remote', 'deploy', or wants to push committed changes to the remote repository

/massu-recap

When user says 'done for today', 'wrapping up', 'end session', 'handoff', or is about to close the terminal

/massu-refactor

Safe refactoring with behavioral equivalence, incremental transforms, and automatic rollback

/massu-release

Release preparation — version bump, changelog, full verification, tagging

/massu-review

Automated code review across 7 dimensions (patterns, security, architecture, website, AI-specific, performance, accessibility)

/massu-rule

Inspect, approve, or dismiss rule candidates emitted by the v0.2 interactive rule-approval hook. Subcommands: list, show <id>, approve <id>, dismiss <id>, recurrence.

/massu-rollback

When user says 'rollback', 'revert this', 'undo changes', 'go back', or needs to safely undo code or database changes with state preservation

/massu-scaffold-hook

When user wants to create a new Claude Code hook — scaffolds the hook script, adds to settings.json, sets up profile gating

/massu-scaffold-page

When user wants to create a new page, route, or section in the app — scaffolds the page component, layout, loading/error states, and tRPC integration

/massu-scaffold-router

When user wants to create a new tRPC router, API endpoint, or backend procedure — scaffolds router file, registers in root.ts, adds Zod schemas

/massu-security

When user says 'security audit', 'check security', 'RLS audit', 'XSS check', or needs a focused security review covering auth, secrets, injection, and OWASP top 10

/massu-simplify

When user says 'simplify', 'review my code', 'clean this up', or has finished implementation and wants quality review before commit

/massu-squirrels

When user has a tangential idea mid-task that should be parked — 'squirrel this', 'park this idea', 'remind me later about'

/massu-status

Read-only project health dashboard with 14 health checks

/massu-tdd

When user wants test-driven development, says 'TDD', 'write tests first', 'red green refactor', or needs the RED-GREEN-IMPROVE cycle

/massu-test

Intelligent test runner with failure analysis, coverage gaps, and test generation

/massu-type-mismatch-audit

When user says 'type audit', 'type mismatch', 'check types', or suspects type inconsistencies between frontend, backend, and database columns

/massu-ui-audit

When user says 'UI audit', 'UX review', 'accessibility check', 'check responsiveness', or needs a deep review of UI consistency, accessibility, and user flows

/massu-verify-playwright

When user says 'check pages', 'scan for console errors', 'verify playwright', or needs to browser-test pages for console errors and generate a fix plan

/massu-verify

When user says 'verify', 'run verification', 'check everything', or needs to run all VR-* verification checks with mandatory proof output before claiming work is complete

Source-of-truth: command files live under .claude/commands/massu-*.md in the public repo. The plan-1.7.0-cohesive-cleanup P-A-005 drift-guard test fails CI when a new external command is added without a matching H2 entry above.

CLI Reference

CLI Reference

massu init

Usage

What It Does

Output

Files Created

massu doctor

Usage

Checks Performed

Output

Exit Codes

massu install-hooks

Usage

When to Use

Output

massu install-commands

Usage

Options

When to Use

Output

massu permissions

Usage

Subcommands

check-drift exit code matrix

When to Use

Example: detecting the merge-replacement trap

massu changelog

Usage

Subcommands

Plan-file ## Changelog Summary contract

Pre-tag gate

When to Use

Example: generating + verifying a release entry

massu validate-config

Usage

What It Checks

Output (Valid)

Output (Warnings)

Exit Codes

Global Options

MCP Server Mode

Slash Commands

/massu-article-review

/massu-audit-deps

/massu-autoresearch

/massu-batch

/massu-bearings

/massu-changelog

/massu-checkpoint

/massu-ci-fix

/massu-cleanup

/massu-command-health

/massu-command-improve

/massu-commit

/massu-create-plan

/massu-data

/massu-dead-code

/massu-debug

/massu-deploy

/massu-deps

/massu-doc-gen

/massu-docs

/massu-estimate

/massu-full-audit

/massu-gap-enhancement-analyzer

/massu-golden-path

/massu-guide

/massu-hooks

/massu-hotfix

/massu-incident

/massu-infra-audit

/massu-learning-audit

/massu-loop-playwright

/massu-loop

/massu-new-feature

/massu-new-pattern

/massu-parity

/massu-perf

/massu-plan-audit

`check-drift` exit code matrix

Plan-file `## Changelog Summary` contract