Introduction
Mikk gives AI agents a live, structural map of your codebase — dependency graph, module boundaries, call chains, constraint rules, safety gates, and drift detection. 100% local. Zero cloud.
Your AI doesn't understand your codebase. Mikk fixes that.
Mikk parses your entire project via OXC (Rust-backed, significantly faster than the TS Compiler API), builds a bidirectional dependency graph, hashes everything with Merkle-tree SHA-256, enforces architectural contracts, and serves structured intelligence through an MCP server that Claude, Cursor, and VS Code Copilot call directly. Everything stays on your machine.
What is Mikk?
LLMs write great code — for codebases they've never seen. They don't know your module boundaries, can't trace your dependency graph, and have no idea that touching auth/login.ts breaks 14 downstream functions across 3 packages.
Mikk fixes that by giving AI assistants real architectural intelligence — not guesses, not file pastes, not embeddings alone. A live, symbol-level dependency graph with enforced constraints, pre-edit safety gates, quantitative risk scoring, and auto-correction of common mistakes.
What Mikk Produces in One Command
mikk initFor high-assurance environments, use mikk init --strict-parsing and mikk analyze --strict-parsing to fail fast on parser diagnostics.
mikk.json— your architecture contract: modules, constraints, ADRs, policiesmikk.lock.json— full codebase snapshot: every function, class, generic, import, call edge, and hashclaude.md/AGENTS.md— tiered, token-budgeted AI context files (auto-regenerated onmikk analyze)
The Mikk Pipeline
| Step | Package | What happens |
|---|---|---|
| Parse | @getmikk/core | OXC extracts every symbol: functions, classes, generics, imports, exports, call graph, routes, variables |
| Graph | @getmikk/core | Two-pass O(n) graph: nodes first, edges second. Forward + reverse adjacency maps |
| Hash | @getmikk/core | Merkle SHA-256: function → file → module → root. One hash = full drift detection |
| Lock | @getmikk/core | mikk.lock.json written — compact integer-indexed format, ~60% smaller than raw source |
| Serve | @getmikk/mcp-server | 41 MCP tools + 3 resources. Cache busted immediately after mikk analyze. ~5ms per call |
| Watch | @getmikk/watcher | Chokidar daemon — incremental re-analysis, atomic writes, single-instance PID guard |
| Obsidian | obsidian-plugin | mikk watch --obsidian generates a live Markdown vault + 3D graph view in Obsidian |
| Safety | @getmikk/intent-engine | Pre-edit validation: intent analysis, 6 safety gates, auto-correction, decision engine |
Token Efficiency
Mikk uses fewer tokens than manual file reading by serving distilled API boundaries instead of raw files. A full agent session typically uses fewer than 5,000 tokens total — versus 50,000+ for naive file-pasting approaches.
Intent Engine & Safety Gates
Every edit is validated before it lands. The Intent Engine runs six gates automatically:
| Gate | Blocks when |
|---|---|
RISK_SCORE | Risk score ≥ 90, or exceeds maxRiskScore policy |
IMPACT_SCALE | More functions affected than maxImpactNodes policy |
PROTECTED_MODULE | A protected module is touched (never bypassable) |
BREAKING_CHANGE | Exported API changed without BREAKING: commit marker |
TEST_COVERAGE | High-risk changes with no test file modifications |
DOCUMENTATION | Significant API changes with no doc file updates |
The Decision Engine evaluates the full impact and returns APPROVED, WARNING, or BLOCKED.
The Auto-Correction Engine detects broken references, missing imports, and boundary violations — and fixes them automatically where safe.
Configure all thresholds in mikk.json under policies.
Packages
| Package | Description |
|---|---|
@getmikk/core | OXC parser, dependency graph, Merkle hashing, BM25 search, boundary checker, risk/confidence engines |
@getmikk/cli | 20+ CLI commands |
@getmikk/mcp-server | 41 MCP tools + 3 resources, lock-file-mtime cache invalidation |
@getmikk/ai-context | BFS context builder, token budgeting, strict mode, claude.md generation |
@getmikk/intent-engine | Pre-edit validation, 6 safety gates, decision engine, auto-correction, intent understanding |
@getmikk/watcher | Incremental watcher daemon, atomic writes |
@getmikk/vscode-extension | Module tree, status bar, impact analysis, MCP integration |
obsidian-plugin | 3D interactive graph — modules, files, functions, classes, generics, call edges |
Known Limitations
| Area | Issue |
|---|---|
get_routes | Next.js file-system routes not parsed (Express-style only) |
find_by_signature | Non-functional for custom signature strings — use find_function |
secrets_scan | High false-positive rate on template literals — use severity: "high" |
find_by_location | Requires exact line number, no range matching |
| Python/Go call graphs | Less complete than TS/JS — import resolution via tree-sitter is planned |
Next Steps
Interactive Playground
Try all 41 MCP tools with live examples. See exactly what Mikk returns for each command.
3D Codebase Explorer
Interactive 3D graph visualization of your codebase with AI chat. Free models powered by OpenRouter.
Installation & Quick Start
Get Mikk running in your project in under 3 minutes.
Core Concepts
The Mesh, Merkle hashing, AI Context Builder, Intent Engine, and Safety Gates.
Was this page helpful?