mason-context 0.1.0 → 0.2.0

package/README.md

@@ -1,154 +1,116 @@
-# Mason
+# Mason – the context builder for LLMs 👷
 
-A context engineering tool that helps LLMs understand your codebase. Mason handles the expensive parts — aggregating git history, selecting architecturally important files, mapping test coverage, and persisting project knowledge across sessions — so the LLM can focus on interpretation.
+Mason gives LLMs a persistent map of your codebase so they stop exploring from scratch every session.
 
-Works as an **MCP server** (for Claude Code, Cursor, etc.) or as a **standalone CLI** with any LLM provider.
+**The problem:** Every time an LLM starts a new conversation about your code, it greps, reads files, and pieces together the architecture — burning tokens on context it already understood yesterday. On a 164-file project, answering "what features does this app have?" requires reading 8+ files across multiple tool calls.
 
-## Quick start
-
-```bash
-npx mason-ai setup    # registers Mason with Claude Code
-```
-
-Restart Claude Code, then ask: "use mason to analyze this project and generate a CLAUDE.md."
+**Mason's fix:** A concept map that persists across sessions. One tool call returns a feature-to-file lookup table — the LLM knows exactly where to look, without exploring.
 
-## Install
+**Measured result** ([deepeval](https://github.com/confident-ai/deepeval), Claude Sonnet, 164-file KMP project):
 
-```bash
-npm install -g mason-ai
-```
-
-## Usage
+| Question | With Mason | Without Mason | Token saving |
+|---|---|---|---|
+| List all features | 10,258 tok | 31,346 tok | **67%** |
+| Trace data flow | 12,010 tok | 15,258 tok | **21%** |
+| Compare platforms | 10,897 tok | 19,353 tok | **44%** |
+| Onboarding flow | 10,271 tok | 11,432 tok | **10%** |
+| **Average** | | | **36%** |
 
-### As an MCP server (recommended)
+Same answer quality (0.9/1.0 on all tests, both paths). Reproduce: [bench/](bench/).
 
-One-command setup for Claude Code:
-
-```bash
-mason setup                            # registers with Claude Code (user scope)
-mason setup --scope project            # project-scoped instead
-```
-
-Or manually:
+## Quick start
 
 ```bash
-claude mcp add mason -- npx mason-ai mcp
+claude mcp add mason --scope user -- npx mason-context mcp
 ```
 
-Then ask Claude to generate a CLAUDE.md — it will call Mason's tools automatically.
+Restart Claude Code, then ask: *"use mason to analyze this project and create a snapshot."*
 
-Mason exposes 9 tools via MCP:
+That's it — Mason will analyze your codebase and create a concept map. Next session, it loads the map instead of re-exploring everything.
 
-| Tool | What it does |
-|---|---|
-| `full_analysis` | All-in-one: git stats + project structure + code samples + test map + snapshot |
-| `get_snapshot` | Load persistent project snapshot (auto-detects staleness) |
-| `save_snapshot` | Save file summaries for future sessions (no API key needed) |
-| `configure_project` | Customize sampling — add patterns, always-include files, ignore paths |
-| `analyze_project` | Git history stats (commit patterns, stale dirs, hot files) |
-| `get_code_samples` | Smart file previews — config, entry points, architectural patterns, tests |
-| `get_file_content` | Read any file in full (drill-down after previewing) |
-| `get_project_structure` | Directory tree with file counts and extension breakdown |
-| `get_test_map` | Map test files to source files by name matching |
-
-### Persistent snapshots
-
-Mason persists its understanding of your project across conversations, saving thousands of tokens per session.
-
-**Via MCP (no API key needed):**
+## How it works
 
-Ask your AI assistant to "create a mason snapshot for this project." It will analyze the codebase, summarize key files, and call `save_snapshot` to persist. Next session, it loads the snapshot via `get_snapshot` instead of re-reading everything. If the snapshot is stale (files changed since last update), Mason tells the LLM exactly which files to re-read.
+### Concept map
 
-**Via CLI (requires LLM provider):**
+Mason's core feature. It persists a feature-to-file map in `.mason/snapshot.json` that survives across conversations. When the LLM needs to understand your project, it reads this map instead of grepping through your entire codebase:
 
-```bash
-mason set-llm gemini AIza-xxx          # configure a provider
-mason snapshot ~/my-project            # generate snapshot
-mason snapshot --install-hook          # auto-update on every commit
+```json
+{
+  "features": {
+    "home screen": {
+      "files": ["HomeScreen.kt", "HomeViewModel.kt", "GetWeatherDataUseCase.kt"]
+    }
+  },
+  "flows": {
+    "weather fetch": {
+      "chain": ["HomeViewModel.kt", "WeatherRepositoryImpl.kt", "WeatherServiceImpl.kt"]
+    }
+  }
+}
 ```
 
-### As a standalone CLI
+The map is generated by the LLM itself — Mason provides the analysis tools, and the LLM interprets your code to decide what the features and flows are. This means the map captures architectural understanding, not just file listings.
 
-Configure an LLM provider once:
+Create one by asking your AI assistant to *"create a mason snapshot"*, or via CLI:
 
 ```bash
-mason set-llm claude sk-ant-xxx        # Anthropic
-mason set-llm gemini AIza-xxx          # Google (free tier available)
-mason set-llm openai sk-xxx            # OpenAI
-mason set-llm ollama                   # Local, no API key needed
+mason set-llm gemini          # configure a provider (no API key needed)
+mason snapshot ~/my-project   # generate concept map
+mason snapshot --install-hook # auto-update on every commit
 ```
 
-Then generate:
+### Change impact analysis
 
-```bash
-mason generate                         # current directory
-mason generate ~/my-project            # specific directory
-mason generate --model claude-haiku-4-5-20251001  # override model
-```
+Before editing a file, Mason can tell you what else might be affected. It combines three signals that would each require multiple tool calls to gather manually:
 
-### Just analyze (no LLM needed)
+- **Co-change history** — files that historically change together in git commits
+- **References** — files that import or mention the target by name
+- **Related tests** — test files paired to the target by naming convention
 
 ```bash
-mason analyze                          # print git history findings
+mason impact WeatherRepository.kt -d ~/my-project
 ```
 
-## How it works
-
-Mason's philosophy: **the LLM is smart, Mason is fast.** Instead of trying to understand your code (badly, with regex), Mason does what LLMs can't do cheaply:
+Also available as the `get_impact` MCP tool — ask your assistant *"what would be affected if I changed WeatherRepository?"*
 
-1. **Aggregate stats** across hundreds of commits — stale directories, hot files, commit conventions
-2. **Select the right files** — architecturally important files the LLM should read, based on naming patterns (ViewModel, Repository, Service, Module, UseCase, etc.)
-3. **Pair interfaces with implementations** — surfaces both `WeatherRepository.kt` and `WeatherRepositoryImpl.kt`
-4. **Include module build files** — so the LLM can infer the dependency graph itself
-5. **Map tests to source** — structural test coverage analysis
-6. **Persist knowledge** — snapshot summaries survive across conversations, eliminating cold-start token waste
+### Git history analysis
 
-The LLM does all the interpretation — identifying conventions, understanding patterns, writing rules. Mason just makes sure it sees the right files and remembers what it learned.
+Mason aggregates hundreds of commits into actionable stats: which files change most often (hot files you should be careful with), which directories haven't been touched in months (potentially stale code), and what commit conventions the team follows. This is the kind of analysis that would take dozens of `git log` calls to compute manually.
 
-## Smart file sampling
+```bash
+mason analyze ~/my-project
+```
 
-Mason doesn't dump your whole repo. It picks ~25 files across these categories:
+## MCP tools
 
-- **Config files** — build configs, linter configs, version catalogs
-- **Module build files** — subdirectory build files that reveal dependency graphs
-- **Entry points** — main files, app entry points
-- **Hot files** — most frequently changed in the last 3 months (from git)
-- **Architectural files** — ViewModels, Repositories, Services, DI Modules, UseCases, Mappers, Controllers, Middleware
-- **Both interfaces and implementations** — `*Repository.*` and `*RepositoryImpl.*`
-- **Test examples** — diverse across languages (JVM, Swift, Python, Go, etc.)
-- **Directory representatives** — one source file per top-level directory for breadth
+Mason exposes 6 tools via the Model Context Protocol. Any MCP-compatible client (Claude Code, Cursor, etc.) can use them:
 
-All files are returned as previews (~60 lines) with metadata. The LLM can request full content of any file it wants to dig into.
+| Tool | What it does |
+|---|---|
+| `get_snapshot` | Load the concept map — maps features/flows to files |
+| `save_snapshot` | Persist the concept map for future sessions |
+| `get_impact` | Change impact: co-change history, references, related tests |
+| `analyze_project` | Git history: commit patterns, hot files, stale dirs |
+| `full_analysis` | All-in-one first visit: git stats + structure + code samples + test map |
+| `get_code_samples` | Smart file previews selected by architectural role |
 
-### Custom patterns
+## CLI usage
 
-Mason's built-in patterns won't catch everything. If your project uses different naming conventions (e.g., `*Gateway*` instead of `*Repository*`, `*Bloc*` instead of `*ViewModel*`), configure it per-project:
+Mason also works as a standalone CLI for generating CLAUDE.md files and running analysis without an MCP client. Configure an LLM provider once, then use any command:
 
-```json
-// .mason/config.json
-{
-  "patterns": ["**/*Gateway.*", "**/*Bloc.*", "**/*Cubit.*"],
-  "alwaysInclude": ["src/core/config.ts", "lib/injection.dart"],
-  "ignore": ["**/fixtures/**", "**/mocks/**"]
-}
+```bash
+mason set-llm claude|gemini|ollama|openai  # configure provider
+mason generate                # analyze codebase + LLM -> CLAUDE.md
+mason analyze                 # git stats only (no LLM needed)
+mason impact File.kt          # change impact analysis
+mason snapshot                # create/update concept map
 ```
 
-Or let the LLM configure it via the `configure_project` MCP tool when it notices the sampler missed important files.
+Most providers work without an API key — `claude`, `gemini`, and `ollama` all use their respective CLIs directly.
 
 ## Language support
 
-Mason is completely language-agnostic. It works with any project that has source files and a git history:
-
-- TypeScript/JavaScript (React, Node, etc.)
-- Kotlin (Android, KMP, server)
-- Java (Spring, Android)
-- Python (Django, FastAPI, etc.)
-- Go
-- Rust
-- Swift (iOS, SwiftUI)
-- Ruby, C#, C++, Dart, and more
-
-No language-specific parsing — the architectural file selection works by naming conventions that are common across ecosystems.
+Mason is completely language-agnostic. It uses file naming patterns and git history rather than language-specific parsing, so it works with any project that has source files and a git repository — TypeScript, Kotlin, Python, Go, Rust, Swift, Java, C#, Dart, and more.
 
 ## License