jdx/hk v1.55.0

v1.55.0: Agent-native hk

on GitHub

This release turns hk into a first-class tool for coding agents, adding an MCP server, an interactive dashboard, structured and machine-readable output, command effect safety, normalized diagnostics with SARIF export, and one-command integration snippets for popular agents and editors. It also adds a Kingfisher secret-scanner builtin and fixes a couple of file-selection and command-composition bugs.

Highlights

• A complete agent-native workflow: drive hk from anywhere with --cd/--files0-from, get machine-readable results via --format json|jsonl, gate risky steps with --safe, export findings as SARIF, and expose everything to agents over MCP with a live dashboard.
• New hk agent command tree prints ready-to-paste instruction, hook, and MCP setup snippets for Codex, Claude Code, Claude Desktop, and VS Code.

Added

• MCP server for coding agents (@jdx) #1169. hk mcp [--root <path>] starts a STDIO-only Model Context Protocol server built on the official Rust MCP SDK. Agents can inspect projects, read effect-aware execution plans, run all-or-nothing safe checks and fixes, poll run lifecycle, cancel runs, and page through logs and captured diffs. Tools are constrained to canonical startup roots plus client-provided roots, with one active run per root and bounded output/run retention. There is no HTTP listener, hosted service, auth system, or unrestricted shell tool.

  hk mcp --root /path/to/project

• Interactive MCP dashboard (@jdx) #1170. A self-contained Preact dashboard is embedded as an MCP App resource, showing live overall and per-step activity, timing, diagnostics, searchable logs, and diffs, with cancel, rerun, and explicitly confirmed safe-fix actions. Hosts without UI support fall back to structured content plus text.

• Coding-agent integration snippets (@jdx) #1171. A read-only hk agent command prints instruction, hook, and MCP setup snippets for Codex, Claude Code, Claude Desktop, and VS Code. Generators only print to stdout — they never install hooks or edit host configuration. A new /agents documentation page describes the safe agent workflow, the dashboard, and ChatGPT Desktop tunneling.

  hk agent mcp codex      # print MCP config snippet for Codex
  hk agent hooks vscode   # print a VS Code hook snippet

• Agent-friendly execution scoping (@jdx) #1162. A global --cd <DIRECTORY> re-executes hk in the chosen project without mutating process cwd, and --files0-from <PATH|-> selects an exact NUL-delimited file list from a file or stdin. --files0-from conflicts with positional files, --all, --glob, --pr, ref ranges, --staged, and --unstaged; pre-push and post-rewrite reject - since those hooks read the Git hook protocol from stdin.

• Structured execution results (@jdx) #1163. A new --format human|json|jsonl flag (default human) makes hook runs emit versioned machine-readable results. json writes a single run_result document with per-step status, timing, output, and skip reasons; jsonl streams ordered lifecycle events (run_started, run_planned, step_started/step_completed, run_completed). Structured formats own stdout; progress, logs, and tracing move to stderr. The existing --json flag continues to work.

• Command effect safety with --safe (@jdx) #1166. Step commands can now declare a read, write, or destructive effect via CommandSpec (for shell, OS-specific, and argv commands). Passing --safe runs an all-or-nothing preflight that permits read/write steps and rejects destructive and unknown-effect steps before anything runs. Legacy string commands are treated as unknown effect and only require an explicit CommandSpec when --safe is used. Declared effects appear in execution plans and structured results.

• Effect classification for all builtins (@jdx) #1167. Every command across the builtin catalog (236 command fields over 144 modules) now declares an effect: read for typical linters and format checks, write for fixers and checks that compile, sync, or populate caches. No builtins are marked destructive, so builtins work under --safe out of the box. Overriding a builtin command with a bare string correctly downgrades it to unknown effect rather than inheriting the builtin's claim.

• Normalized diagnostics and SARIF export (@jdx) #1168. Steps can opt into structured diagnostics with diagnostic_format (sarif, cargo-json, eslint-json, gcc) and optional diagnostic_tool. Output is parsed into a shared diagnostic model (severity, path, range, rule, help URL, optional fix), deduplicated, and preserved alongside raw output in JSON/JSONL results. A new --sarif <PATH> flag exports a standard SARIF 2.1.0 report from check, fix, run, and hook commands regardless of the selected output format. Malformed input surfaces a parse warning and never drops the raw command output.

• Kingfisher secret-scanner builtin (@thoroc) #1160. Adds a builtin for MongoDB's Kingfisher secret scanner, installable through mise.

Fixed

• Structured commands accept argv prefixes (@jdx) #1175. After the builtin argv migration, configs that inherited a builtin and supplied a string prefix stopped loading. prefix now accepts either a shell string (for shell commands) or an explicit argv list, so structured commands and argv builtins like Builtins.ruff can run through launchers such as mise x -- without losing argument boundaries. Argv prefixes reject file-list placeholders and can be inherited by groups; cross-mode combinations are rejected. Closes discussion #1174.

  ["ruff"] = (Builtins.ruff) {
    prefix = List("mise", "x", "--")
  }

• Deleted paths excluded from ref-scoped checks (@jdx) #1177. The libgit2 backend used Path::exists() to distinguish live from deleted paths, so on case-insensitive filesystems the old spelling of a case-only rename was passed to steps alongside the new one. Deleted diff deltas are now skipped, matching the shell-Git backend's --diff-filter behavior. Fixes discussion #1176.

New Contributors

• @thoroc made their first contribution in #1160

Full Changelog: v1.54.1...v1.55.0

💚 Sponsor hk

hk is maintained by @jdx, an open source developer for entire.io, the title sponsor of the jdx.dev open source tools including mise, aube, and more. Work on hk is funded by sponsorships.

If hk has sped up your pre-commit loop or made linting feel less painful, please consider sponsoring at jdx.dev. Sponsorships are what keep hk moving and the project independent.