mm

Mastermind

A Claude Code plugin for tracking progress across multiple projects via session analysis.

What It Does

Mastermind analyzes your Claude Code conversation history and generates structured reports. It helps you:

• Track what you've done across multiple projects
• Remember decisions and their rationale
• Surface patterns in how you work
• Maintain context when switching between projects

All data is stored as markdown files—works great with Obsidian or any text editor.

Prerequisites

• Claude Code installed
• jq for JSON processing: brew install jq (macOS) or apt install jq (Linux)

Installation

From GitHub

# Clone the repository
git clone https://github.com/mconcat/mastermind
cd mastermind

# Install the plugin
/plugin install mm@mastermind

For Development

# Load plugin for current session only
claude --plugin ./path/to/mastermind

Quick Start

# 1. Initialize your vault (stores all mastermind data)
/mm:init ~/Documents/vault

# 2. Register projects to track
/mm:add my-webapp ~/projects/my-webapp
/mm:add rust-lib ~/projects/rust-lib

# 3. Sync your Claude Code session history
/mm:sync

# 4. View project status
/mm:overview

Commands

Command	Description
/mm:init <vault-path>	Initialize a new vault
/mm:add <name> <path>	Register a project to monitor
/mm:sync [project]	Analyze new sessions, generate reports
/mm:overview	Dashboard of all monitored projects
/mm:status <project>	Deep dive on one project
/mm:plan [project]	Create or update project spec
/mm:daily	Generate cross-project daily digest

All commands work from any directory.

Vault Structure

After running /mm:init, your vault contains:

vault/
├── config.yaml                     # Project registry
├── state/
│   └── sync-state.yaml             # Sync tracking
├── projects/
│   └── my-webapp/
│       ├── spec.md                 # Project specification
│       ├── status.md               # Current state summary
│       └── sessions/
│           ├── 2026-01-15-implementing-auth.md
│           └── 2026-01-16-fixing-token-refresh.md
└── daily/
    └── 2026-01-16.md               # Daily digest

Session reports use a YYYY-MM-DD-title.md naming convention for easy sorting and discovery.

Session Reports

Reports are generated automatically from your Claude Code conversations. Each report captures:

• Summary: What the session accomplished
• Decisions: Technical choices and rationale
• Issues & Fixes: Problems encountered and solutions
• Learnings: Insights for future work
• Unfinished Work: What's left to do

Reports are written as readable narratives, not rigid templates.

Example Report

# Implementing JWT Authentication

**Project**: my-webapp
**Date**: 2026-01-15
**Session ID**: `a1b2c3d4-...`

This session focused on adding JWT-based authentication. The implementation
went smoothly until token refresh became an issue—users were getting logged
out on page refresh.

**The fix**: Store refresh tokens in httpOnly cookies instead of localStorage.
This prevents XSS attacks while maintaining session persistence.

**Learnings**:
- Auth state lives in AuthContext provider
- Browser dev tools network tab is essential for debugging auth flows

Workflow

1. Work normally with Claude Code on your projects
2. Sync periodically: Run /mm:sync at the end of work sessions
3. Review reports: Check projects/*/sessions/ for insights
4. Update specs: Use /mm:plan when project direction changes
5. Daily digest: Run /mm:daily for cross-project summary

Configuration

Vault Location

Stored in ~/.claude/mastermind.local.md:

# Mastermind Configuration
vault: ~/Documents/vault

Project Registry

In your vault's config.yaml:

projects:
  my-webapp:
    path: ~/projects/my-webapp
    description: React web application
  rust-lib:
    path: ~/projects/rust-lib
    description: Data processing library

How It Works

1. Claude Code stores your conversations in ~/.claude/projects/
2. /mm:sync discovers new sessions and filters them to essential content
3. Analyzer agents read each session and generate narrative reports
4. Reports are saved to your vault with timestamps and descriptive titles
5. State tracking ensures only new content is processed on subsequent syncs

Tips

• Sync regularly: Run /mm:sync at the end of each work session
• Keep specs updated: Your spec is the source of truth for project direction
• Read your reports: They often surface patterns you didn't notice while working
• Use with Obsidian: The vault is just markdown—link between reports freely

License

MIT