Installation

npm install -g @getmikk/cli

bun add -g @getmikk/cli

Core Commands

`mikk init`

Full codebase scan. Parses all source files via OXC (TS/JS) and Tree-sitter (other languages), builds the dependency graph, detects modules, writes all artifacts.

mikk init
mikk init --force    # re-initialize even if mikk.json already exists
mikk init --strict-parsing

--strict-parsing fails initialization if parser/read/import-resolution diagnostics are detected.

What gets generated:

mikk.json — architecture contract with auto-detected modules
mikk.lock.json — full codebase snapshot
claude.md + AGENTS.md — tiered AI context files

`mikk analyze`

Re-analyze and update all generated files. Incremental by default — only re-parses files whose content hash changed.

mikk analyze
mikk analyze --full    # force full re-parse (ignore hashes)
mikk analyze --strict-parsing

mikk analyze surfaces parse diagnostics with reason counts when files fall back to empty parsed output. Use --strict-parsing to make diagnostics a hard failure.

After mikk analyze completes, the MCP server's cache is busted on the next tool call — the server detects the updated mikk.lock.json mtime immediately.

`mikk watch`

Start the live file watcher daemon. Keeps mikk.lock.json in sync as you edit.

mikk watch
mikk watch --debounce 500    # debounce delay in ms (default: 100)
mikk watch --obsidian        # also regenerate Obsidian vault on graph updates

The watcher enforces single-instance via PID file — starting mikk watch twice reuses the existing process. Changes under 15 files trigger incremental re-analysis. Changes ≥ 15 files trigger a full re-analysis. All lock writes are atomic: temp file → rename. Zero corruption on crash.

--obsidian flag: When a graph:updated event fires, the watcher spawns node scripts/mikk-to-obsidian.mjs --all-fns to regenerate the Obsidian vault in mikk-vault/. The vault contains one note per file, function, class, type, route, variable, and property — all interlinked as wikilinks.

If the sync script exits non-zero, the first line of stderr is shown:

→ Obsidian vault sync failed: Cannot read lock: ENOENT

`mikk diff`

Show what changed since the last analysis.

mikk diff

Added:    src/auth/two-factor.ts
Modified: src/auth/login.ts
Deleted:  src/auth/legacy-auth.ts

3 files changed (1 added, 1 modified, 1 deleted)

`mikk ci`

CI gate — validates architecture and exits non-zero on violations.

mikk ci                   # check constraint violations
mikk ci --strict          # also enforce dead code threshold
mikk ci --format json     # structured JSON output for log ingestion

Use mikk ci in automated pipelines. It is designed for non-interactive environments and always produces machine-readable exit codes.

Context Commands

`mikk context for`

Build an AI context payload for a task description.

mikk context for "How does authentication work?"
mikk context for "Refactor the payments module" --tokens 8000
mikk context for "Fix the session bug" --provider claude --hops 3

Prop

Type

`mikk context impact`

Show the full blast radius of changing a file.

mikk context impact src/auth/login.ts
mikk context impact src/auth/login.ts --depth 5

`mikk context query`

Answer an architecture question using the dependency graph.

mikk context query "Who calls parseToken?"
mikk context query "What does src/api/routes.ts depend on?"

Contract Commands

`mikk contract validate`

Validate the current codebase against all constraints in mikk.json.

mikk contract validate
mikk contract validate --strict              # exit 1 on any violation
mikk contract validate --boundaries-only     # check only no-import / layer rules

`mikk contract show-boundaries`

Show the current cross-module dependency map — useful for writing constraint rules.

mikk contract show-boundaries

Intent Commands

`mikk intent`

Validate a plain-English plan against your architecture before writing any code.

mikk intent "Add a caching layer to the auth module"
mikk intent "Extract shared validation into utils" --verbose
mikk intent "Move user service to shared module" --json

The intent engine:

Parses the prompt into structured intents (action + target + confidence)
Checks against all 6 constraint types
Detects boundary violations
Returns approved: true/false with affected files and new files required

Architectural Decision Records (ADRs)

mikk adr list                                                    # list all decisions
mikk adr get ADR-001                                             # full details for a decision
mikk adr add --id "use-jwt" --title "Stateless JWT" --reason "No session storage needed"
mikk adr rm use-jwt                                              # remove a decision

ADRs are stored in mikk.json and surface automatically in every mikk_query_context response. The Intent Understanding component also reads ADRs to detect planned migrations — if an ADR mentions a module and contains "migration" or "deprecat", changes to that module are classified as intentional.

Dead Code

mikk dead-code                    # show all unreferenced functions
mikk dead-code --module auth      # filter to a specific module

Exemptions applied automatically: exported symbols, entry-point names, route handlers, test functions, constructors, and functions transitively called by any exported function in the same file.

MCP Commands

Start the MCP server (stdio transport).

mikk mcp
mikk mcp --project /absolute/path/to/project

Auto-install into your AI tool.

mikk mcp install                     # auto-detect installed tools
mikk mcp install --tool claude       # Claude Desktop
mikk mcp install --tool cursor       # Cursor
mikk mcp install --tool vscode       # VS Code Copilot
mikk mcp install --tool windsurf     # Windsurf
mikk mcp install --dry-run           # preview without writing

Stats & Diagnostics