New mcp object in knosh.json declares MCP (Model Context Protocol) servers. A local server is type: "local" with a command (argv array) or commandLine (a single string, tokenized POSIX-style); a remote server is type: "remote" with a required url and optional headers, connected over MCP Streamable HTTP. Both types share enabled (default true), timeout (seconds, default 5), and required (default false). The deprecated HTTP+SSE transport and OAuth are not supported.
A remote server's headers value that is exactly{env:NAME} is resolved from the NAME environment variable at connect time, so a bearer token never has to be written into knosh.json.
Every enabled MCP server is spawned and handshaken before a prompt, kdocs, or file-defined command run starts, and every process Knosh started is terminated when the run finishes. required controls whether a failed server is a stderr warning or an aborted run.
Each server's tools are discovered and merged into the agent's registry, namespaced as <serverHandle>_<toolName> so they can never collide with a built-in. See MCP tools.
New mcp: block in agent frontmatter overrides the global enabled state of MCP servers per agent, keyed by exact server handle or glob, with exact-beats-glob and last-matching-glob-wins precedence.
New list-mcp command lists all configured servers, annotating disabled ones and showing an environment-variable or header count only — never names or values. --agent <id> shows each server's global state alongside its effective state for that agent.
New add-mcp command writes an entry under mcp without hand-editing the file. Server type is inferred, never declared: --url makes it remote, argv or --commandLine makes it local. Also supports --env, --header, --timeoutSeconds, --required, --disabled, --global, and --force.
New mcp-info <name> command prints one server's details, then actually connects — handshake, tool discovery, disconnect — to confirm reachability. It never executes a discovered tool. Unlike a real run, every startup failure is reported and the command exits 1.
Per-tool permission patterns can now be written relative to the working directory (e.g. "src/*": "allow"), so one agent file works unchanged across every project it is used in. A pattern beginning * or ? is used verbatim (keeping a bare "*" base rule matching every path); a pattern beginning /, ~, or $HOME is already anchored; every other pattern is resolved against the working directory. ~/$HOME are now also expanded in per-tool patterns.
Closed a .. traversal bypass in per-tool permission pattern matching: a pattern was matched against the raw path string the model supplied, so a path like src/../secrets.txt could satisfy an allow rule scoped to src/* even though it resolved outside that directory. Per-tool patterns and received paths are now both resolved and normalized before matching, using the same primitive the external_directory containment check already uses.
Config file merging now goes one level below the top-level key for mcp, toolLimits, and webFetch, instead of the local file's object replacing the global one wholesale. mcp merges per server handle, and a local entry naming only enabled overlays the global entry — the supported way to disable a globally-declared server from a project file.
Refreshed dependencies, including Koog to 1.2.0 and Kotlin to 2.4.10.
A new --benchmark flag on prompt, kdocs, and file-defined commands prints a metrics summary to stderr after the run, showing token consumption, LLM call count, tool call count, and elapsed time. The summary appears only when stderr is an interactive terminal, and token counts are omitted when the provider returns no usage metadata.
A live status line is shown on stderr while an agent runs in an interactive terminal. It is omitted when iterations run in parallel.
New defaultAgentId field in knosh.json sets a project-wide fallback agent, making --agentId optional.
New toolLimits object makes the maximum size of tool responses configurable: globMaxFiles, grepMaxMatches, textReadMaxBytes, and webFetchMaxBytes, plus grepMaxLineLength and grepTimeoutMillis bounding the grep tool's regex matching.
prompt is now the default command, so knosh "summarize this" is equivalent to knosh prompt "summarize this". Running knosh with no arguments still prints root help.
New webFetch object configures the SSRF egress policy for the web-fetch tool.
Knosh now warns on stderr at startup if a config file or its parent directory is writable by other users on the system. The check is advisory only.
Hardened the grep tool against pathological caller-supplied regexes (ReDoS). A search that exceeds its time budget returns partial results with a note rather than hanging.
Closed a path-traversal gap in filesystem-tool permission checks: .. segments in a tool's path argument could previously reach files outside the intended boundary. The external_directory boundary is now containment-based. Symlink canonicalization remains a documented follow-up.
Hardened the web-fetch tool against SSRF, re-checking every redirect hop against the same policy. See Security / SSRF.
Breaking:knosh kdocs --parallel is now an integer-valued option (--parallel N) instead of a boolean flag. Valid range is [1, 32]; the default when omitted is 1.
init command to write a default knosh.json config file, with --global for ~/.config/knosh/knosh.json. init --global also creates an empty agents/ directory.
list-agents command to list available agents in the configured agents directory.
kdocs command to iterate over supplied source files and update their KDoc comments using an LLM.
prompt command to run a one-shot LLM prompt using a named agent.
Agent configuration via Markdown files with YAML frontmatter (model, temperature, tool permissions, system prompt).
Twelve built-in tools covering filesystem navigation, file I/O, and web access.
Support for multiple LLM providers via Koog: Anthropic, Mistral, OpenAI, and Ollama.
Per-agent and per-command temperature overrides via --temperature.
--max-iterations option to cap the number of LLM tool-call cycles per run.
Retry policy for transient LLM and network errors, including Ollama-specific retries.
Tool-call logging with optional full-content logging via --log-full-tool-calls, and --log-full-prompts for debugging.
Rich terminal output via Mordant (Markdown rendering in TTY; plain text elsewhere).
Global and project-local knosh.jsonconfig with optional per-provider API keys.