Releases: Ansh-dhanani/mikk
v1.8.0 Release
Mikk v1.8.0 Release
The Definitive Structural Memory Update for the Mikk MCP Server & CLI
Executive Overview: Why Mikk MCP Server Dominates AI Context Generation
We are pleased to announce the release of Mikk v1.7.2. This update establishes Mikk as an enterprise-grade solution for generating structural codebase context through the Model Context Protocol (MCP).
By moving beyond traditional file scanning, the Mikk CLI and Mikk MCP Server now natively support Architectural Decision Records (ADRs). These records enable direct injection of architectural reasoning into active LLM sessions, ensuring that AI agents understand not only the codebase but also the decisions behind it.
In addition to architectural advancements, this release places strong emphasis on cross-platform stability. Critical Windows execution failures have been resolved, encoding inconsistencies that affected LLM context generation have been eliminated, and monorepo execution reliability for both mikk analyze and mikk mcp server has been significantly improved.
The mikk adr Toolkit: Architectural Memory for AI Agents
Modern AI coding agents such as Claude Desktop, Cursor, and GitHub Copilot require a deep understanding of architectural intent to prevent regressions during development. The Mikk CLI now provides a comprehensive toolkit to manage these decisions, which are automatically integrated into MCP-driven workflows.
Feature Enhancements
| Mikk Feature | Architecture Component | Feature Description | Developer & AI Impact |
|---|---|---|---|
| ADR Management via CLI | mikk adr list |
Renders a structured, color-coded list of all tracked architectural decisions directly from the mikk.json contract file. |
Provides immediate visibility into project-wide constraints and architectural trade-offs without searching through documentation. |
| Detailed ADR Retrieval | mikk adr get [id] |
Fetches and formats the complete context and reasoning behind a specific architectural decision for efficient terminal viewing. | Accelerates onboarding and enables developers to quickly understand the rationale behind system design. |
| Contract ADR Creation | mikk adr add |
Provides an intuitive command to register new architectural decisions within the Mikk contract. | Ensures the architecture remains continuously documented and accessible to both developers and AI agents. |
| Complete Uninstallation | mikk remove |
Cleanly removes contracts, lockfiles, AI context files, and cache directories. | Guarantees zero residual configuration or orphaned files when removing Mikk from a project. |
| LLM Context Integration | mikk analyze → CLAUDE.md |
Automatically embeds all declared ADRs into generated context files and real-time MCP server payloads. | Ensures AI agents understand system design philosophy during complex refactoring and development workflows. |
| Mikk Bootstrapping | mikk.json defaults |
Initializes projects with predefined architectural decisions during setup. | Provides immediate value and guides both developers and AI systems on expected design patterns. |
Bug Fixes & Stability Improvements
| Issue ID | Mikk Execution Failure Recognized | Technical Root Cause | Resolution in v1.7.2 |
|---|---|---|---|
| MIKK-FIX-01 | Windows Script Host (WSH) execution crash | Ambiguous Node.js invocation and incompatible shebang handling under strict Windows execution policies. | All CLI commands now explicitly invoke the Node runtime, eliminating WSH conflicts. |
| MIKK-FIX-02 | AI context encoding corruption | Non-ASCII characters from parsed JSDoc comments introduced inconsistencies in generated context. | Implemented strict sanitization to ensure ASCII-safe and LLM-compatible output. |
| MIKK-FIX-03 | Missing core modules in CLI/MCP runtime | Bundler failed to include critical dependencies in compiled outputs. | Explicitly bound required dependencies within package graphs to guarantee runtime availability. |
Core Architectural Upgrades: Why Mikk Outperforms Standard RAG
| Mikk Component Engine | Industry Standard Approach | Mikk v1.7.2 Architecture | Competitive Advantage |
|---|---|---|---|
| Fast AST Parser Engine | Native Tree-sitter bindings requiring node-gyp, Python, and C++ build chains | web-tree-sitter (WASM-based) |
Ensures seamless, cross-platform execution without complex setup. |
| Deep Algorithmic Search | Basic substring matching for AST lookups | BM25 + Reciprocal Rank Fusion (RRF) | Improves search accuracy while supporting semantic variation and exact match priority. |
| CLI Runtime Execution | Heavy TypeScript compiler-based execution with ESM resolution | Bundled CommonJS output via Esbuild | Delivers faster startup, improved performance, and consistent runtime behavior. |
Final Verdict
Mikk v1.7.2 represents a major advancement in structural context generation and platform reliability. By combining a real-time dependency graph with integrated Architectural Decision Records, Mikk enables AI agents to operate with a deep understanding of both code and intent.
This ensures that AI-assisted development evolves alongside your architecture with precision, consistency, and reliability.
What's Changed
- feat: Scaffold new web application with documentation, UI components,… by @Ansh-dhanani in #5
- feat: add feedback API and UI components for user feedback collection by @Ansh-dhanani in #9
New Contributors
- @Ansh-dhanani made their first contribution in #5
Full Changelog: v1.7.1...v1.8.0
Contributors
Assets 2
v1.7.0
Mikk v1.7.0
Foundation release. v1.7.0 makes Mikk production-ready for real codebases and real AI workflows. The lock file is 60% smaller. The MCP server is cache-backed and staleness-aware. Constraint violations now surface before edits land, not after. Three new tools give agents the context they need at the start of every session.
What's New
The MCP Server Is Now Agent-Ready
Previous versions had a fundamental problem: every tool call read from disk. In an active session with rapid-fire tool calls, this meant stale data, repeated I/O, and no awareness of files changed mid-session.
v1.7.0 fixes this at the architecture level.
30-second TTL cache — loadContractAndLock is now cache-backed. The first call in a window pays the disk cost. Every subsequent call in that window is instant. For agents making 10–20 tool calls in a session, this eliminates ~200ms of latency per call.
Live staleness detection — On every tool invocation, Mikk samples the mtime of the 5 most recently modified files and compares against lockDate. If anything drifted since the last mikk analyze, every tool response surfaces a warning. Agents stop working from outdated graphs without any manual intervention.
Active boundary enforcement in mikk_before_edit — Previously, mikk_before_edit returned constraint metadata passively — it was on the agent to interpret it. Now it runs BoundaryChecker live against the edit target and explicitly enumerates every violation: broken deny rules, isolated boundary crossings, and layer constraint failures. The agent gets a verdict, not raw data.
Three New MCP Tools (17 total)
mikk_get_session_context — designed to be called once at the start of every session. Returns the full project snapshot: hot modules, architecture constraints, and the function index. Replaces the pattern of calling mikk_get_project_overview + mikk_get_architecture separately.
mikk_get_changes — diffs the current filesystem state against the lock file hashes. Returns three lists: modified files, added files, deleted files. Agents can establish immediate awareness of what changed since the last analysis without reading the entire codebase.
mikk_read_file — extracts a specific function body with integrated metadata: signature, location, inbound calls, outbound calls, and constraints that apply to it. Replaces whole-file reads for localized changes, cutting token consumption significantly on targeted edits.
Lock File — 60% Smaller
The lock file format was redesigned from scratch. Every change targets the same goal: smaller file, same fidelity.
Integer-based function index — All call graph edges (calls / calledBy) previously stored full string identifiers duplicated across every function entry. They now reference integer indices into a shared fnIndex lookup table. On a medium-sized project this alone accounts for the majority of the size reduction.
Removed redundant fields — moduleId was duplicated on every function entry and is now resolved via the files map. detailedLines analytics were stripped. Per-function SHA-256 hashes were removed; file-level hash roots are sufficient for drift detection.
Lazy context file loading — claude.md and AGENTS.md content is no longer embedded in the lock file. Only reference paths are stored; content loads from disk when requested.
Compact output — JSON pretty-printing is disabled. Schema version bumped to 1.7.0 with backward-compatible hydration for previous formats.
Parser Improvements
tsconfig inheritance — Mikk now recursively resolves extends chains in tsconfig.json, correctly merging compilerOptions.paths across nested configs. Monorepos with complex alias setups (@/, ~lib/, @shared/) are now accurately mapped.
JS/JSX support — .js, .jsx, .cjs, and .mjs files now go through full AST extraction using ScriptKind inference in the TypeScript Compiler API. React components, nested exports, and CommonJS/ESM interop edge cases are handled. Zero-hallucination verified: extracted function bodies match raw fs.readFile bytes 1:1.
Circular dependency detection — DFS cycle detection added to the dependency graph builder. mikk_before_edit now surfaces circular dependencies introduced by a proposed edit before it happens.
CLI Tooling
mikk ci — architectural gate for CI/CD pipelines. Exits non-zero on boundary violations. --strict adds dead code threshold enforcement. --format json outputs structured results for log ingestion.
mikk doctor — 7-point diagnostic check: lock file integrity, config validity, .mikkignore anomalies, missing modules, stale hashes, parser availability, monorepo structure. Run it when something's wrong and it tells you exactly what.
mikk stats — metrics dashboard broken down per module defined in mikk.json. Dead code percentages, file counts, dependency density, isolated technical debt per boundary. Useful before refactors and code reviews.
Numbers
| Metric | v1.6.0 | v1.7.0 |
|---|---|---|
| MCP tools exposed | 14 | 17 |
| Lock file size (medium project) | baseline | −60% |
| MCP tool latency (cached) | ~200ms | ~5ms |
| Core test suite | partial | 196 passing |
| Monorepo packages | 7 | 10 |
Upgrading
Schema version 1.7.0 is backward-compatible. Existing lock files are hydrated automatically on the first mikk analyze run. No manual migration required.
npm install -g mikk@1.7.0
mikk analyze
mikk doctor # verify workspace health after upgrade
What's Next — v1.8.0
The remaining gaps after this release are semantic search, scoped edit sessions, and AI-readable function purpose summaries. v1.8.0 targets:
mikk_search— natural language search across the function indexmikk_begin_edit/mikk_commit_edit— scoped edit sandbox with diff previewfn.purpose— batched AI-generated purpose strings per function, cached in SQLite- MCP Resource push — agents notified of file changes mid-session without polling
v1.6.0 — Go Language Support · Semantic Search · MCP Install
New Features
Go language support (@getmikk/core)
Full Go parser built on regex + stateful character scanning — no Go toolchain required. Extracts functions, methods, structs, imports, Gin/Chi HTTP routes, and error-handling patterns. Handles grouped params, func-typed params, multi-return types, and receiver methods. Every Go function gets the same first-class treatment as TypeScript: exact file path, start/end line, call graph edges, and purpose in the lock file.
Natural-language semantic search (@getmikk/intent-engine, @getmikk/mcp-server)
New SemanticSearcher class uses the Xenova/all-MiniLM-L6-v2 model (~22 MB) to embed every function in your codebase and rank them by meaning. Query "validate JWT token" and it surfaces verifyToken over saveUser — not by substring match, but by vector similarity. Runs 100% locally. Embeddings cached in .mikk/embeddings.json, recomputed only when the lock changes. Available as the new mikk_semantic_search MCP tool.
@xenova/transformers is an optional peer dependency — all other tools continue to work without it.
mikk mcp install (@getmikk/cli)
Automatically writes the correct MCP server config block into Claude Desktop, Cursor, or VS Code — no manual JSON editing. Supports --dry-run to preview changes.
v1.5.0
v1.5.0 — Improved Parsing, Smart Ignore & Monorepo Clustering
What was wrong with the previous version
Analysis was broken or useless for:
- Monorepos — running on Mikk's own codebase produced 12,235 lines of lock file, 1 module called "Testing", and a main diagram with a single useless node
- Test files polluting results — no
.mikkignorewas ever generated, so test fixtures, helpers, and test directories were analyzed as production code - Projects with tsconfig.base.json — detected as JavaScript instead of TypeScript
- Single-file clusters never created — orphan files silently disappeared from analysis due to a premature assignment bug
- Duplicate module names — multiple clusters named "Search" or "Providers" with no disambiguation
- Massive unreadable diagrams — module diagrams dumped every internal function (88+ lines of noise)
Bug Fixes (19 total)
Critical Bugs
- C# detection used fs.access('*.csproj') which always fails — glob patterns don't work with fs.access. Switched to
fast-globfor.csproj/.slndetection. - Cluster detector orphan bug — files were marked as
1.3.0
Mikk v1.3.0 — First Public Release 🧠
The codebase nervous system. Instant AI context. Architecture contracts. Live dependency graph.
This is the first public release of Mikk — a tool that maps your TypeScript codebase into a structured, always-current knowledge graph and gives AI tools the exact context they need to write architecturally correct code.
Why Mikk Exists
Every AI coding tool hits the same wall: it writes syntactically correct code that violates your architecture. It doesn't know about your middleware factory. It reimplements the utility you already have. It bypasses the constraints your team agreed on.
That's not an AI intelligence problem. It's an information problem. The AI was never told.
Mikk fixes this at the source. It parses your codebase into a precise dependency graph, tracks every function and relationship in a lock file, and generates an always-accurate claude.md and AGENTS.md — so your AI tools always know how your project is actually built.
What's Shipped in This Release
7 Packages, 1 Tool
| Package | What it does |
|---|---|
| @getmikk/core | AST parsing via TypeScript Compiler API, dependency graph, Merkle hashing, contract management |
| @getmikk/watcher | Live file watcher daemon with incremental analysis and atomic lock updates |
| @getmikk/intent-engine | Pre-flight pipeline — interprets prompts, detects constraint violations before code is written |
| @getmikk/ai-context | Token-budgeted context builder + claude.md / AGENTS.md generation |
| @getmikk/diagram-generator | 7 types of Mermaid architecture diagrams, all auto-generated |
| @getmikk/cli | 15+ commands — mikk init, mikk watch, mikk intent, mikk context, and more |
| VS Code Extension | Module tree, architecture diagrams, AI context, status bar sync indicator |
Key Features
Precise Dependency Graph
Parses every .ts and .tsx file with the TypeScript Compiler API — not grep, not regex. Extracts functions with type signatures, class hierarchies, import chains, call relationships, decorators, generics. Builds a complete forward + reverse adjacency graph across your entire project.
Merkle-Tree Hashing
SHA-256 hashes at every level: function body → file → module → project root. Any change propagates up the tree instantly. The watcher detects drift in under 50ms without reading file content — just hash comparison.
Architecture Contracts (mikk.json)
Define your module boundaries, architectural intent, and constraints. Six constraint types: no-import, must-use, no-call, layer, naming, max-files. Use mikk contract validate --strict in CI to catch boundary violations before they merge.
Always-Current claude.md / AGENTS.md
Generated from the AST-derived lock file, not written by hand. Every function name, file path, and module relationship is sourced from what the code actually is — not what someone remembered to document. Tiered output respects token budgets.
Intent Pre-flight
Run mikk intent "add rate limiting to auth endpoints" before writing code. The engine interprets the prompt into structured intents, checks them against your declared constraints, and tells you which files to touch — before an AI writes a single line.
7 Mermaid Diagrams, Zero Drawing
Architecture overview, per-module detail, health dashboard (cohesion %, coupling), impact blast radius (changed = red, impacted = orange), call flow sequences, API capsule views, N×N dependency matrix. All generated from the lock file on every mikk analyze.
Live Watcher
mikk watch runs as a background daemon. Every file save triggers hash comparison, incremental re-parse of only the changed file, graph patch, and atomic lock file update. Debounced at 100ms. Race-condition protected with retry logic. PID-based single instance enforcement.
Quickstart
npm install -g @getmikk/cli
cd your-project
mikk init
After mikk init your project has:
mikk.json— your architecture contract (edit this)mikk.lock.json— full codebase snapshot (commit this, never edit)claude.md+AGENTS.md— AI context files (auto-regenerated).mikk/diagrams/— 7 Mermaid diagrams of your architecture
# Keep everything in sync while you code mikk watchCheck architecture before a PR
mikk contract validate --boundaries-only --strict
Get AI context for a task
mikk context for "add two-factor auth to the login flow"
Pre-flight check before writing code
mikk intent "refactor the payments module to use Stripe"
Tech Stack
Built on Bun + Turborepo. TypeScript Compiler API for AST parsing. better-sqlite3 in WAL mode for hash persistence. Chokidar for file watching. Zod for all schema validation. Commander + chalk + ora for the CLI. Apache 2.0 licensed.
What's Next
- MCP server — expose the lock file as queryable MCP tools for Claude, Cursor, and any MCP-compatible agent
- Python support — extend the parser to
.pyfiles - GitHub Action — post architecture impact diagrams directly on PRs
- VS Code Marketplace — publish the extension publicly
Links
- npm: npmjs.com/org/getmikk
- GitHub: github.com/Ansh-dhanani/mikk
- Issues & feedback: GitHub Issues
97 tests. 7 packages. One command to understand your codebase.
# Mikk v1.2.0 — First Public Release 🧠The codebase nervous system. Instant AI context. Architecture contracts. Live dependency graph.
This is the first public release of Mikk — a tool that maps your TypeScript codebase into a structured, always-current knowledge graph and gives AI tools the exact context they need to write architecturally correct code.
Why Mikk Exists
Every AI coding tool hits the same wall: it writes syntactically correct code that violates your architecture. It doesn't know about your middleware factory. It reimplements the utility you already have. It bypasses the constraints your team agreed on.
That's not an AI intelligence problem. It's an information problem. The AI was never told.
Mikk fixes this at the source. It parses your codebase into a precise dependency graph, tracks every function and relationship in a lock file, and generates an always-accurate claude.md and AGENTS.md — so your AI tools always know how your project is actually built.
What's Shipped in This Release
7 Packages, 1 Tool
| Package | What it does |
|---|---|
@getmikk/core |
AST parsing via TypeScript Compiler API, dependency graph, Merkle hashing, contract management |
@getmikk/watcher |
Live file watcher daemon with incremental analysis and atomic lock updates |
@getmikk/intent-engine |
Pre-flight pipeline — interprets prompts, detects constraint violations before code is written |
@getmikk/ai-context |
Token-budgeted context builder + claude.md / AGENTS.md generation |
@getmikk/diagram-generator |
7 types of Mermaid architecture diagrams, all auto-generated |
@getmikk/cli |
15+ commands — mikk init, mikk watch, mikk intent, mikk context, and more |
| VS Code Extension | Module tree, architecture diagrams, AI context, status bar sync indicator |
Key Features
Precise Dependency Graph
Parses every .ts and .tsx file with the TypeScript Compiler API — not grep, not regex. Extracts functions with type signatures, class hierarchies, import chains, call relationships, decorators, generics. Builds a complete forward + reverse adjacency graph across your entire project.
Merkle-Tree Hashing
SHA-256 hashes at every level: function body → file → module → project root. Any change propagates up the tree instantly. The watcher detects drift in under 50ms without reading file content — just hash comparison.
Architecture Contracts (mikk.json)
Define your module boundaries, architectural intent, and constraints. Six constraint types: no-import, must-use, no-call, layer, naming, max-files. Use mikk contract validate --strict in CI to catch boundary violations before they merge.
Always-Current claude.md / AGENTS.md
Generated from the AST-derived lock file, not written by hand. Every function name, file path, and module relationship is sourced from what the code actually is — not what someone remembered to document. Tiered output respects token budgets.
Intent Pre-flight
Run mikk intent "add rate limiting to auth endpoints" before writing code. The engine interprets the prompt into structured intents, checks them against your declared constraints, and tells you which files to touch — before an AI writes a single line.
7 Mermaid Diagrams, Zero Drawing
Architecture overview, per-module detail, health dashboard (cohesion %, coupling), impact blast radius (changed = red, impacted = orange), call flow sequences, API capsule views, N×N dependency matrix. All generated from the lock file on every mikk analyze.
Live Watcher
mikk watch runs as a background daemon. Every file save triggers hash ...