mvtk

AI-optimized developer toolkit — structured JSONL output for every dev workflow

mvtk is a command-line toolkit built for AI agents and developers who need machine-readable, structured output — not ANSI color codes, not paginators, not noise. Every record is a JSON Line. Every command respects a token budget. Every result is parseable, composable, and consistent.

Think of it as the Unix toolkit reimagined for the age of LLMs: grep, cat, git diff, blame, tree — but all speaking JSONL.

Install

cargo install mvtk

Or grab a pre-built binary from Releases.

Commands

Quick Start

Search

# Find all TODO comments with surrounding context
mvtk grep 'TODO' src/ --symbol-context

# Count how often each error type appears
mvtk grep 'Error' . --type rs --tally

# Show only lines changed since HEAD
mvtk grep 'handleAuth' . --diff --type go

# Block extraction between two patterns
mvtk grep --from '^## Installation' --to '^## ' README.md

Read

# Read with line numbers
mvtk read src/main.rs

# Extract a function (parser-based)
mvtk read src/lib.rs --fn run

# Extract any block by regex (works in ANY language)
mvtk read handler.swift --from 'func stopSharing' --to '^\}'

# Extract a markdown section
mvtk read roadmap.md --from '^## Phase 3' --to '^## Phase 4' --to-exclusive

# Read outline of symbols only (no content)
mvtk read src/ --outline

Understand a codebase

# What does auth.go import, and who imports it?
mvtk ctx auth.go

# What symbols changed in the last commit?
mvtk changes HEAD~1

# Show largest files by function count
mvtk metrics src/ --sort fns --format markdown

# Show the dependency graph
mvtk deps . --type rs --edges

AI-friendly flags

Every command supports:

--max-tokens 4000    # hard cap — never blow your context window
--no-stats           # suppress summary record
--format compact     # file:line:content — minimum tokens

Output Format

All output is JSON Lines — one record per line, no color, no paging.

{"type":"match","file":"src/main.rs","line":42,"col":5,"content":"    run(opts)?;","pattern":"run"}
{"type":"fn","file":"src/lib.rs","name":"run","signature":"pub fn run(opts: &Opts)","start_line":10,"end_line":45,"lines":[...]}
{"type":"block","file":"README.md","from_pattern":"^## Install","to_pattern":"^## ","start_line":12,"end_line":18,"lines":[...]}
{"type":"summary","files_searched":12,"matched":3,"elapsed_ms":14,"truncated":false}

Record types: match · fn · block · outline · line · hunk · file_changed · symbol · metric · dep · todo · ref · blame · stash · test · lint · import · importer · change · summary · warning · error

Library Usage

mvtk is also a library crate. Every subcommand is independently callable — no clap, no I/O assumptions.

[dependencies]
mvtk = "1.0"

use mvtk::cmd::read::{ReadOpts, run};
use mvtk::cmd::grep::{GrepOpts, run as grep_run};
use mvtk::output::Emitter;

// Read a file as JSONL records
let opts = ReadOpts {
    files: vec!["src/main.rs".into()],
    fn_name: Some("handle_request".into()),
    ..Default::default()
};
let mut em = Emitter::capturing(8192); // 8192 token budget
run(&opts, &mut em)?;
let records = em.into_records(); // Vec<serde_json::Value>

// Extract a block by regex
let opts = ReadOpts {
    files: vec!["config.toml".into()],
    from: Some(r"\[database\]".into()),
    to: Some(r"^\[".into()),
    to_exclusive: true,
    ..Default::default()
};

Module map:

mvtk::cmd::grep      — parallel search
mvtk::cmd::read      — file reader + block extractor
mvtk::cmd::tree      — directory walker
mvtk::cmd::diff      — git diff parser
mvtk::cmd::changes   — semantic diff
mvtk::cmd::ctx       — import graph
mvtk::cmd::blame     — git blame
mvtk::cmd::symbols   — symbol extractor
mvtk::cmd::metrics   — LOC/complexity
mvtk::cmd::deps      — dependency graph
mvtk::cmd::todos     — comment scanner
mvtk::cmd::refs      — usage finder
mvtk::cmd::stash     — stash lister
mvtk::cmd::test      — test runner
mvtk::cmd::lint      — linter bridge
mvtk::output         — Emitter<W>, record types
mvtk::symbol         — language-agnostic outline
mvtk::util           — walkers, git helpers, token counting

mvtk read --from/--to

The universal fallback when --fn can't parse your language.

# Swift (parser doesn't cover methods)
mvtk read file.swift --from 'func stopSharing' --to '^\}'

# Python class method
mvtk read service.py --from 'def handle_request' --to '^    def \|^class '

# Markdown section (exclusive: don't include the next header)
mvtk read roadmap.md --from '^## Phase 3' --to '^## ' --to-exclusive

# TOML config block
mvtk read config.toml --from '\[database\]' --to '^\['

# All matching blocks in one file
mvtk read handlers_test.go --from 'func Test' --to '^\}' --all

Rules:

• --from only → start at match, read to EOF
• --to only → read from line 1 until match
• Both → first --from, then first --to after it (both inclusive)
• --to-exclusive → exclude the --to line itself
• --all → return every block in the file
• No match → warning record + exit 1

Why mvtk?

Standard tools weren't designed for AI consumers:

License

Non-Commercial Copyleft License — free for personal and open-source use. Modifications must be shared and credit the original author. Commercial use requires a separate agreement.