📦

Mikk

Name: Mikk
Rating: 1.5

No description available

0 installs

Trust: 30 — Low

Devtools

Ask AI about Mikk

I know everything about Mikk. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

Mikk

Your AI doesn't understand your codebase. Mikk fixes that.

The codebase nervous system — parses your architecture, maps every dependency,
and delivers the exact context your AI needs. Zero cloud. Zero config. Zero hallucination.

The Problem

You copy 4,000 lines of source code into Claude. It generates a component that imports from utils/auth — a path that doesn't exist. Your BoundaryChecker lives in src/core/contract/, not where the LLM guessed. You spend 20 minutes fixing import paths, broken calls, and layer violations in AI-generated code.

LLMs write great code — for codebases they've never seen. They don't know your module boundaries. They can't trace your dependency graph. They have no idea that touching login.ts breaks 14 downstream functions across 3 packages. They get a flat paste of files and hallucinate the rest.

Mikk gives your AI the architecture it's missing.

One command. Your entire codebase — parsed, graphed, hashed, and served as structured, token-budgeted context. Locally. In milliseconds.

90 files

_{of scattered source code
your AI has to index}

→

1 file

_{mikk.lock.json
~12,900 lines · full structure}

+

493 lines

_{claude.md / AGENTS.md
architectural context}

Mikk's algorithm parses your entire codebase and generates mikk.lock.json — a single structured file (~12,900 lines) containing every function signature, every dependency edge, every call graph, every module assignment, and every Merkle hash. Instead of your AI crawling through 90+ scattered source files, it reads one file with the full architecture. On top of that, Mikk generates claude.md and AGENTS.md — distilled to 493 lines of tiered context that fits in any AI's context window.

Why Mikk is Fast

Most dev tools scan your project and call it a day. Mikk was engineered from the ground up for speed at scale.

Technique	What it does	Why it matters
Merkle-tree hashing	SHA-256 at function → file → module → root	One hash comparison = full drift detection. No diffing.
Incremental analysis	Only re-parses changed files on `watch`	100-file change in a 10k-file project? Only those 100 get touched.
BFS graph tracing	Walks the dependency graph from seed nodes	Context is traced, not brute-forced. O(reachable) not O(codebase).
Token budgeting	Greedy knapsack packing by relevance score	AI gets max signal per token. No wasted context window.
SQLite WAL mode	Hash store uses Write-Ahead Logging	Concurrent reads during writes. No lock contention on watch.
Atomic lock file writes	Temp file → rename on every update	Zero chance of corrupted `mikk.lock.json`, even on crash.
PID-based singleton	Watcher daemon enforces single instance	No duplicate watchers eating CPU.
Debounced batching	File changes are batched within a window	Save 20 files at once? One re-analysis, not twenty.
Turborepo caching	Build artifacts cached across packages	Rebuild only what changed in the monorepo.
Two-pass graph construction	Nodes first, then edges in a single sweep	O(n) graph build, forward + reverse adjacency maps for O(1) lookups.

What Mikk Actually Does

npm install -g @getmikk/cli && cd my-project && mikk init

In ~3 seconds, Mikk:

Parses every TypeScript file via the TS Compiler API — real AST, not regex
Builds a full dependency graph (two-pass: nodes then edges, O(1) adjacency lookups)
Clusters files into logical modules via greedy agglomeration
Hashes everything with Merkle-tree SHA-256 (function → file → module → root)
Detects HTTP routes (Express, Koa, Hono) with method, path, handler, and middleware chain
Generates mikk.json (your architecture contract) + mikk.lock.json (full codebase snapshot)
Generates Mermaid architecture diagrams in .mikk/diagrams/
Outputs claude.md and AGENTS.md — ready-to-use AI context files

No cloud. No API keys. No telemetry. Everything stays on your machine.

Features

AI Context Builder

Graph-traced, token-budgeted context payloads. BFS walks your call graph from seed functions, scores by relevance, and packs the optimal context within your token limit. No more dumping your whole repo into a prompt.

Impact Analysis

See what breaks before you change it. BFS backward walk traces the full blast radius of any file — every upstream caller, every downstream dependency — in milliseconds.

Intent Pre-flight

Describe what you want to build in plain English. Mikk parses it into structured intents, checks against 6 constraint types, detects conflicts, and suggests an implementation plan — before a single line is written.

Strict Contracts

Define module boundaries in mikk.json. CI fails if an import violates your architecture. Supports no-import, must-use, no-call, layer, naming, and max-files constraints.

MCP Server

Expose your architecture to Claude, Cursor, VS Code Copilot — any MCP-compatible AI assistant. 12 tools, 3 resources, one command: mikk mcp.

Merkle-Tree Drift Detection

SHA-256 hashes at every level: function → file → module → root. One hash comparison = full codebase drift check. Persisted in SQLite with WAL mode for zero-contention reads.

Live Watcher

Incremental, debounced file watching with atomic lock file writes and PID-based singleton enforcement. Your architecture map stays in sync as you code — zero manual re-analysis.

Full AST Parsing

TypeScript Compiler API extracts functions, classes, generics, imports (with tsconfig alias resolution), decorators, and type parameters. Not regex — real compiler-grade parsing. Go files are parsed with regex + stateful scanning (no Go toolchain needed). Every function gets its exact file path, start line, and end line stored in the lock file.

Supported languages: TypeScript/TSX · Go

Precise Code Location

Every context result, impact report, and function detail includes the exact file + line range + actual source body. Your AI isn't told "the auth module handles login" — it's told "validateToken() is at src/auth/login.ts:42–78 and here is the full code block."

Architecture Decision Records

Document architectural decisions (ADRs) directly in mikk.json. Every AI context query surfaces relevant decisions alongside the code — so your AI knows why a constraint exists, not just that it does.

Real-World Use Cases

"I need to add rate limiting to all API routes"

mikk context for "Add rate limiting to API endpoints"

Mikk finds every route handler, traces their middleware chains, identifies the right insertion points, and packages it all into a context payload your LLM can act on immediately.

"What breaks if I refactor the auth module?"

mikk context impact src/auth/login.ts

Get the full blast radius — every function that calls into auth, every module that depends on it, and a Mermaid diagram showing the impact zone.

"Is this change architecturally safe?"

mikk intent "Move user validation into a shared utils module"

Mikk checks your intent against all contract constraints, warns about layer violations, and tells you exactly which files will be affected — before you write any code.

"My AI keeps hallucinating import paths"

mikk mcp

Connect Mikk as an MCP server. Now Claude/Cursor/Copilot can call mikk_before_edit before every change — getting the real exported API, real constraints, and real blast radius. When it calls mikk_get_function_detail, it gets the exact file path, start line, end line, and full source body — no guessing.

"I need to point my AI to the exact code block to change"

mikk context for "fix the token refresh logic"

Mikk doesn't just return a module name. It returns the exact function, its file path, its start and end line numbers, and the actual source code block — ready to be passed directly to your AI as precise, actionable context.

"New developer just joined — how do they understand the codebase?"

mikk init

Auto-generates claude.md and AGENTS.md with a tiered architecture summary — modules, entry points, key functions, constraints. New devs (and their AI assistants) get full context instantly.

Quick Start

Install

npm install -g @getmikk/cli

Initialize

cd my-project
mikk init

Explore

# Re-analyze after structural changes
mikk analyze

# See what changed since last analysis
mikk diff

# Ask your architecture a question
mikk context query "How does authentication work?"

# See the blast radius of a change
mikk context impact src/auth/login.ts

# Get AI context for a coding task
mikk context for "Add caching to the database layer"

# Pre-flight check a refactoring idea
mikk intent "Extract shared validation into a utils module"

# Generate architecture diagrams
mikk visualize all

# Visualize a specific module
mikk visualize module auth

# Visualize impact of current changes
mikk visualize impact

# Validate contracts in CI
mikk contract validate --boundaries-only --strict

# Start MCP server for AI assistants
mikk mcp

# Live watch mode
mikk watch

Connect to Your AI Tools

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "mikk": {
      "command": "npx",
      "args": ["-y", "@getmikk/mcp-server", "/path/to/your/project"]
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "mikk": {
      "command": "npx",
      "args": ["-y", "@getmikk/mcp-server", "/path/to/your/project"]
    }
  }
}

VS Code Copilot

.vscode/settings.json:

{
  "mcp.servers": {
    "mikk": {
      "command": "npx",
      "args": ["-y", "@getmikk/mcp-server", "/path/to/your/project"]
    }
  }
}

All 12 MCP Tools

Tool	What it does
`mikk_get_project_overview`	Modules, function counts, tech stack, constraints
`mikk_query_context`	Ask an architecture question — returns graph-traced context
`mikk_impact_analysis`	Blast radius of changing a specific file
`mikk_before_edit`	Pre-edit check — exported functions at risk, constraints, blast radius
`mikk_find_usages`	Every function that calls a specific function
`mikk_list_modules`	All declared modules with file/function counts
`mikk_get_module_detail`	Functions, files, exported API, internal call graph for a module
`mikk_get_function_detail`	Params, return type, call graph, exact file + start/end line + full source body for a function
`mikk_search_functions`	Substring search across all function names
`mikk_semantic_search`	Natural-language search — find functions by meaning via local vector embeddings (Xenova/all-MiniLM-L6-v2). E.g. "validate JWT token" ranks `verifyToken` highest. Requires `@xenova/transformers` (optional).
`mikk_get_constraints`	All architectural constraints and design decisions
`mikk_get_file`	Read raw source of any project file
`mikk_get_routes`	Detected HTTP routes (Express / Koa / Hono)

Resources: mikk://contract · mikk://lock · mikk://context

Contract Management

# Generate initial contract from auto-detected clusters
mikk contract generate

# Validate against the contract (CI mode)
mikk contract validate --boundaries-only --strict

# Show all cross-module dependencies
mikk contract show-boundaries

# Update the lock file after changes
mikk contract update

Constraint Types

Constraint	Description
`no-import`	Module must not import from specified modules
`must-use`	Module must use specified dependencies
`no-call`	Functions must not call specified targets
`layer`	Enforces layered architecture (can only import from lower layers)
`naming`	Enforces naming patterns via regex
`max-files`	Limits files per module

How It Works

 Parse ──→ Graph ──→ Cluster ──→ Hash ──→ Contract ──→ Context ──→ Serve
  │          │          │          │          │            │          │
  TS AST    Dep Graph  Module    Merkle    mikk.json    Token-     MCP
  Parser    Builder    Detection SHA-256   Validator    Budgeted   Server

Deep Dive: The Full Pipeline

1. Parse — Understand Your Code

Mikk uses the TypeScript Compiler API to parse every .ts/.tsx file into structured data:

Functions — name, params with types, return type, exact start + end line, internal calls, async/generator flags, decorators, type parameters
Classes — methods, properties, inheritance chains, decorators, with per-method line ranges
Interfaces, type aliases, enums, const declarations
Imports — named, default, namespace, type-only, with full resolution (tsconfig aliases, index files, extension inference)

2. Graph — Map Every Dependency

Two-pass GraphBuilder construction:

Nodes — One per file, function, class, and generic declaration
Edges — Import edges, function call edges, class containment, implements relationships

Result: a complete DependencyGraph with forward + reverse adjacency maps for O(1) traversal.

3. Hash — Detect Drift Instantly

Merkle-tree SHA-256 at every level:

function hash → file hash → module hash → root hash

One root hash comparison tells you if anything changed. Persisted in SQLite (WAL mode) for fast incremental checks.

4. Contract — Define Your Architecture

{
  "modules": {
    "auth": {
      "intent": "Handle user authentication and session management",
      "include": ["src/auth/**"],
      "publicApi": ["login", "logout", "validateToken"],
      "constraints": {
        "no-import": ["payments"],
        "layer": 1
      }
    }
  }
}

6 constraint types: no-import · must-use · no-call · layer · naming · max-files

Supports Architecture Decision Records (ADRs) in your contract:

{
  "decisions": [
    {
      "id": "ADR-001",
      "title": "Use JWT for stateless authentication",
      "date": "2024-01-15",
      "status": "accepted"
    }
  ]
}

5. AI Context — Surgical Precision

Seed — Match task keywords against the lock file
Walk — BFS trace the call graph outward from seeds
Score — Proximity + keyword + entry-point bonuses
Budget — Greedily fill token budget with highest-scoring functions
Format — XML tags (Claude) or plain text (generic)

6. Intent Pre-flight — Think Before You Code

Interpret — Parse prompt into structured intents (action + target + confidence)
Detect — Check against all 6 constraint types + boundary rules
Suggest — Affected files, new files, and impact estimate

7. MCP Server — Let AI See Your Architecture

12 tools + 3 resources exposed via the Model Context Protocol. Zero config. Works with Claude Desktop, Cursor, VS Code, and any MCP-compatible client.

Includes automatic HTTP route detection for Express, Koa, and Hono — method, path, handler function, middleware chain, file, and line number are all extracted and exposed via mikk_get_routes.

Packages

Mikk is a Turborepo monorepo with 8 packages:

Package	Description
`@getmikk/core`	Foundation — AST parsing, dependency graph, Merkle hashing, contract management, boundary checker, cluster detection
`@getmikk/cli`	CLI — 15+ commands for init, analyze, diff, watch, contracts, context, intent, diagrams
`@getmikk/ai-context`	AI context builder — BFS graph tracing, token budgeting, `claude.md`/`AGENTS.md` generation
`@getmikk/intent-engine`	Intent pre-flight — NL prompt parsing, conflict detection (6 rule types), implementation suggestions
`@getmikk/diagram-generator`	Diagram engine — Mermaid.js architecture diagrams
`@getmikk/mcp-server`	MCP server — 12 tools, 3 resources for AI assistants
`@getmikk/watcher`	File watcher daemon — debounced, incremental, atomic updates
`@getmikk/vscode-extension`	VS Code extension — module tree view, architecture diagrams panel, AI context generation, impact analysis, and status bar sync indicator

Apps:

App	Description
`apps/web`	Web Dashboard & Contract Generator — browser-based UI for exploring your architecture
`apps/registry`	Package registry — central index for published Mikk contracts

Package Dependency Graph

@getmikk/core              ← Foundation (no internal deps)
    ↑
@getmikk/intent-engine     ← depends on core
    ↑
@getmikk/ai-context        ← depends on core + intent-engine
@getmikk/diagram-generator ← depends on core
@getmikk/watcher           ← depends on core
@getmikk/mcp-server        ← depends on core + ai-context + intent-engine
    ↑
@getmikk/cli               ← depends on core + ai-context + diagram-generator + intent-engine + mcp-server
@getmikk/vscode-extension  ← depends on core + diagram-generator + ai-context

Project Structure

After running mikk init, your project gets:

my-project/
├── mikk.json              ← Architecture contract (you own this)
├── mikk.lock.json         ← Full codebase snapshot (auto-generated)
├── claude.md              ← AI context for Claude
├── AGENTS.md              ← AI context for Codex/agents
└── .mikk/
    ├── diagrams/          ← Auto-generated Mermaid diagrams
    ├── hashes.db          ← SQLite Merkle hash store (WAL mode)
    └── watcher.pid        ← Daemon PID (singleton enforced)

Development

git clone https://github.com/Ansh-dhanani/mikk.git
cd mikk
bun install
bun run build
bun run test    # 97 tests across 10 packages

Tech Stack

Tool	Purpose
Bun	Runtime & package manager
Turborepo	Monorepo build orchestration
TypeScript	Language (strict mode)
TypeScript Compiler API	AST parsing
Zod	Schema validation
better-sqlite3	Hash persistence (WAL mode)
Chokidar	File watching
Commander	CLI framework
@modelcontextprotocol/sdk	MCP server protocol
esbuild	Bundling

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

# Branch from main → make changes → test → PR
bun run test && bun run lint

Documentation

Resource	Description
User Guide	Complete walkthrough of all features
@getmikk/core	AST parsing, graph building, hashing, contracts
@getmikk/cli	All CLI commands reference
@getmikk/ai-context	AI context builder internals
@getmikk/intent-engine	Intent pre-flight system
@getmikk/diagram-generator	Mermaid diagram generation
@getmikk/mcp-server	MCP server setup & tools
@getmikk/watcher	File watcher daemon
VS Code Extension	Extension features & usage

Apache-2.0 — see LICENSE

Stop feeding your AI blind. Give it Mikk.

npm install -g @getmikk/cli && mikk init