Mason – the context builder for LLMs 👷

Mason gives LLMs a persistent map of your codebase so they stop exploring from scratch every session.

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.

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.

Measured result (deepeval, Claude Sonnet, 164-file KMP project):

Same answer quality (0.9/1.0 on all tests, both paths). Reproduce: bench/.

Quick start

claude mcp add mason --scope user -- npx -p mason-context mason-mcp

Restart Claude Code, then ask: "use mason to analyze this project and create a snapshot."

That's it — Mason will analyze your codebase and create a concept map. Next session, it loads the map instead of re-exploring everything.

How it works

Concept map

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:

{
  "features": {
    "home screen": {
      "files": ["HomeScreen.kt", "HomeViewModel.kt", "GetWeatherDataUseCase.kt"]
    }
  },
  "flows": {
    "weather fetch": {
      "chain": ["HomeViewModel.kt", "WeatherRepositoryImpl.kt", "WeatherServiceImpl.kt"]
    }
  }
}

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.

Create one by asking your AI assistant to "create a mason snapshot", or via CLI:

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

Change impact analysis

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:

• 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

mason impact WeatherRepository.kt -d ~/my-project

Also available as the get_impact MCP tool — ask your assistant "what would be affected if I changed WeatherRepository?"

Git history analysis

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 i

... View full README on GitHub