MAUDE - Metrics Analysis & User Development Engine

MAUDE is a personal instrumentation system for analyzing Claude Code sessions to identify flow patterns and reduce friction over time.

Installation

As NPM Package (Recommended)

npm install -g @heyzk/maude

From Source

git clone https://github.com/zk/maude.git
cd maude
npm install
npm run build

Development

# Run in development mode with hot reload
npm run dev

# Run type checking
npm run typecheck

# Run tests
npm test

# Build for production
npm run build

Technology Stack

• Language: TypeScript
• Runtime: Node.js
• Build Tool: esbuild (fast bundler with native TypeScript support)
• Type Checking: TypeScript Compiler (tsc --noEmit)
• Testing: Jest with ts-jest
• Development: tsx for TypeScript execution
• UI Framework: Ink (React for CLI)

Usage

Interactive TUI (Terminal User Interface)

After installation, run:

maude

This launches an interactive interface where you can:

• Browse all Claude Code sessions
• View session details and metrics
• Generate comprehensive reports
• Copy logs to clipboard
• Navigate with keyboard shortcuts

Command Line Tools

The package also includes CLI tools for scripting:

# List sessions in JSON format
./bin/llm-tool list

# Generate report for a session
./bin/llm-tool report-create <session-path> [output-path]

# Query report data
./bin/llm-tool report-query <report-file> <jq-path>

# Convert report to markdown
./bin/llm-tool report-to-markdown <report-file> [output-file]

# Analyze interventions
./bin/llm-tool analyze-interventions <report-file> [output-file]

Session File Format

MAUDE reads Claude Code session files in JSONL format (.jsonl), where each line is a JSON object representing a message. Sessions are typically stored in ~/.claude/projects/[project-name]/[session-id].jsonl.

Build System

MAUDE uses a modern TypeScript build pipeline optimized for CLI applications:

• esbuild: Bundles TypeScript directly to JavaScript (10-100x faster than tsc)
• TypeScript: Used for type checking only (tsc --noEmit), not compilation
• Separate Workers: Report generation runs in separate worker processes to avoid blocking the UI
• Single Output: All production code bundles to dist/cli/ for simplicity

This architecture provides:

• Fast builds (< 1 second)
• Full TypeScript type safety
• Clean production distribution
• Simple path resolution (no dual build confusion)

Deployment

Publishing to NPM

1. Update version:

   npm version patch  # or minor/major

2. Build and test:

   npm run clean
   npm run build
   npm test

3. Test locally:

   # Test global installation
   npm install -g .
   maude --version
      
   # Test package contents
   npm pack --dry-run

4. Publish:

   npm publish

Release Process

The prepublishOnly script automatically:

1. Cleans previous builds
2. Runs type checking
3. Bundles with esbuild

Package Structure

The published package includes:

• dist/cli/index.js - Main CLI entry point (with shebang)
• dist/cli/workers/ - Separate worker processes
• README.md - Documentation
• LICENSE - MIT license

Documentation

Detailed documentation is available in the docs/ directory.