<div align="center">
# mvtk
**AI-optimized developer toolkit — structured JSONL output for every dev workflow**
[](https://crates.io/crates/mvtk)
[](https://docs.rs/mvtk)
[](https://www.rust-lang.org)
[](https://github.com/scalecode-solutions/mvToolkit/actions)
[](LICENSE)
[](https://crates.io/crates/mvtk)
</div>
---
`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
```bash
cargo install mvtk
```
Or grab a pre-built binary from [Releases](https://github.com/scalecode-solutions/mvToolkit/releases).
---
## Commands
| `mvtk grep` | Parallel regex search — context lines, tally, unique, symbol context, diff-filter |
| `mvtk read` | Read files as numbered JSONL lines — `--fn`, `--outline`, `--from`/`--to` block extraction |
| `mvtk tree` | Directory tree as JSONL entries with sizes, timestamps, language stats |
| `mvtk diff` | Parse `git diff` into structured hunk + file_changed records |
| `mvtk changes` | Semantic diff — which *functions* changed, not which lines |
| `mvtk ctx` | What does this file import? Who imports it? |
| `mvtk blame` | Per-line `git blame` as JSONL with author, commit, timestamp |
| `mvtk symbols` | Extract all function/struct/class/type declarations across a codebase |
| `mvtk metrics` | LOC, function counts, complexity, blank/comment ratios per file |
| `mvtk deps` | Import/dependency graph — edges, kinds (std/external/internal) |
| `mvtk todos` | Find TODO/FIXME/HACK/UNWRAP/SAFETY comments with optional blame |
| `mvtk refs` | Find every call site / usage of a symbol |
| `mvtk stash` | Structured `git stash list` with timestamps and affected files |
| `mvtk test` | Run tests (Go/Rust/Node) and emit structured pass/fail records |
| `mvtk lint` | Run `cargo clippy`, `eslint`, or `ruff` — emit structured diagnostics |
---
## Quick Start
### Search
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
--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.
```jsonl
{"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.
```toml
[dependencies]
mvtk = "1.0"
```
```rust
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.
```bash
# 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:
| ANSI escape codes | Everywhere | Never |
| Pagination | `less` by default | None |
| Token budgets | Not a concept | `--max-tokens` |
| Structured output | Rarely | Always JSONL |
| Binary file noise | Silently included | Auto-excluded |
| Context windows | Not a concern | First-class |
| Language-aware extraction | grep doesn't know functions | `--fn`, `--outline`, `--from`/`--to` |
---
## License
[Non-Commercial Copyleft License](LICENSE) — free for personal and open-source use. Modifications must be shared and credit the original author. Commercial use requires a separate agreement.
---
<div align="center">
Built by <a href="https://github.com/scalecode-solutions">Scalecode Solutions</a>
</div>