Installation

Massu AI installs with one command. It automatically detects your framework, creates your configuration, registers the MCP server, installs all 11 lifecycle hooks, and deploys 31 slash commands.

Prerequisites

Before you begin, make sure you have:

Node.js 18+ -- Check with node --version
Claude Code CLI -- Installed and authenticated. See Claude Code documentation for setup.
A Git repository -- Massu AI uses git for branch detection and session tracking

Step 1: Install the Package

bash

npm install @massu/core

Step 2: Initialize Massu AI

Run the init command in your project root:

bash

npx massu init

This single command does everything:

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

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

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

Here's what massu init does automatically:

Framework Detection -- Scans your 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 11 lifecycle hooks in .claude/settings.local.json
Slash Command Installation -- Deploys 31 workflow commands into .claude/commands/

Step 3: Start Using Massu AI

Start a Claude Code session:

bash

claude

On the first session, you'll see:

=== MASSU AI: Active ===
Session memory, code intelligence, and governance are now active.
11 hooks monitoring this session. 31 slash commands available.
Type "massu_sync" to index your codebase.
=== END MASSU ===

Then index your codebase:

> Use massu_sync to rebuild indexes

Verify Installation

Run the health check at any time:

bash

npx massu doctor

Expected output:

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

  ✓ Configuration      massu.config.yaml found and valid
  ✓ MCP Server         Registered in .mcp.json
  ✓ Hooks Config       11 hooks configured
  ✓ Hook Files         11/11 compiled hooks present
  ✓ Slash Commands     31/31 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)

What Gets Installed

The 11 Lifecycle Hooks

Hook	Event	Purpose
`session-start`	SessionStart	Injects prior context, failed attempts, and session summaries
`session-end`	Stop	Generates session summary, captures conversation turns
`post-tool-use`	PostToolUse	Classifies tool calls into observations, detects patterns
`user-prompt`	UserPromptSubmit	Records prompts, auto-detects plan file references
`pre-compact`	PreCompact	Snapshots session state before context compaction
`pre-delete-check`	PreToolUse	Checks sentinel impact before file deletion
`post-edit-context`	PostToolUse	Surfaces applicable rules after editing files
`security-gate`	PreToolUse	Blocks dangerous bash commands and protected file writes
`cost-tracker`	PostToolUse	Estimates and tracks token costs per tool call
`quality-event`	PostToolUse	Detects test failures, type errors, and build failures
`intent-suggester`	UserPromptSubmit	Suggests relevant slash commands based on your prompt

Files Created

your-project/
  massu.config.yaml              # Project configuration (auto-generated)
  .mcp.json                      # MCP server registration (auto-generated)
  .claude/
    settings.local.json          # Hook configuration (auto-generated)
    commands/                    # 31 slash commands (auto-generated)
      massu-plan.md
      massu-loop.md
      massu-commit.md
      ...                        # 28 more command files
    session-state/
      CURRENT.md                 # Auto-generated session state
  .massu/                        # Created on first session
    memory.db                    # Cross-session memory database
    data.db                      # Import edges, feature registry

Other Commands

Install or update hooks only

bash

npx massu install-hooks

Install or update slash commands only

bash

npx massu install-commands

Re-deploys all 31 slash commands into .claude/commands/ without running the full init process. Useful after updating @massu/core to get the latest command definitions.

Validate your configuration

bash

npx massu validate-config

Troubleshooting

MCP Server Not Found

Verify the package is installed: npm list @massu/core
Check the MCP configuration: cat .mcp.json
Re-run: npx massu init

Hooks Not Running

Run the health check: npx massu doctor
Check hooks are configured: cat .claude/settings.local.json
Re-install hooks: npx massu install-hooks

No Tools Available

Verify config exists: ls massu.config.yaml
Validate config: npx massu validate-config
Check MCP server logs for errors

Database Errors

Massu AI creates its SQLite databases automatically on first use. If you see database errors:

Check write permissions in the .massu/ directory
Ensure better-sqlite3 native module loads: node -e "require('better-sqlite3')"
Rebuild native modules: npm rebuild better-sqlite3

Next Steps

Now that Massu AI is installed, follow the Quick Start Guide for a hands-on tutorial, or dive into the Configuration Reference to customize Massu AI for your project.