npm package: @heyzk/maude
Description: Interactive TUI for analyzing Claude Code sessions to identify flow patterns and reduce friction over time.
Author: zk
Latest version: 0.2.0

# 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)

```bash
npm install -g @heyzk/maude
```

### From Source

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

### Development

```bash
# 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:
```bash
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:

```bash
# 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**:
   ```bash
   npm version patch  # or minor/major
   ```

2. **Build and test**:
   ```bash
   npm run clean
   npm run build
   npm test
   ```

3. **Test locally**:
   ```bash
   # Test global installation
   npm install -g .
   maude --version
   
   # Test package contents
   npm pack --dry-run
   ```

4. **Publish**:
   ```bash
   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.