All releases

Matcha CLI · 0.04

Matcha CLI 0.04

Released

The CLI-side groundwork for editor integration, more ways to work with Skills, MCP, and model context windows, and a smoother day in the terminal for input, background tasks, and long sessions.

This release also fixes a config-directory regression and several Provider availability problems. Still local, with your own API key. Model requests still go to the Provider you choose.

Editor integration

  • These are protocol capabilities the CLI offers to editor clients over ACP / stdio. The IDE plugin has not shipped, and a client turns on each surface only as negotiated.
  • Isolated Chat: the CLI copies the allowed text files into a separate workspace. The agent reads and writes only inside that copy, and the editor can get changes against a fixed baseline. Creating a copy never edits the original project.
  • The editor can receive the agent's questions, options, and plan approvals. A cancelled, rejected, invalid, or expired reply is never treated as approval, and never starts another turn on its own.
  • Isolated sessions can be listed, paginated, searched by title or summary, renamed, branched, and deleted. Deleting removes only the managed copy, never your original project files.
  • An idle session can switch model, reasoning effort, and the permitted permission modes. A restored isolated session starts again from Ask.
  • Text changes can be previewed, applied after confirmation, queried, and undone, for additions, edits, and deletions. Before applying or undoing, the CLI re-checks the source and file contents, and a file you have kept editing is not overwritten. Multi-file operations are not atomic as a whole; results are reported per file.
  • A dropped connection does not resend the last message. Failed restores, busy sessions, and invalid sessions return clear errors.

Skills and instruction profiles

  • An editor can read a local definition catalog: the name, description, source, availability, and rejection reason of Skills, instruction profiles, and sub-agent personas. The catalog never returns definition bodies, raw configuration, or credentials.
  • The catalog reuses the CLI's discovery and precedence rules across project, user, configured paths, and allowed local plugins. .matcha comes first, and older directories stay read-only compatible.
  • When you invoke a Skill explicitly, the CLI checks the definition version and source before expanding it. An unknown slash command does not quietly become ordinary prompt text.
  • An idle session can select an additional instruction profile, added on the next turn. The choice survives a restore, and must be made again if the definition is edited, removed, or disabled. A profile does not replace the system prompt, Provider, tools, permissions, or workspace scope.

Providers and model choice

  • New /context-window. When the current model declares several context windows, you can pick one mid-session. /model can also choose the window first, then the reasoning effort. Models with a single window do not show the option.
  • The reasoning-effort menu uses the options and recommended value from the model catalog, and config aliases inherit the matching menu.
  • New matcha auth status --json lets an editor read the current Provider, credential source, and whether it can be configured. The output contains no API key, key suffix, or endpoint URL, and does not mean the credential has been verified.
  • New or improved per-model request-size limits, rate-limit retry thresholds, Responses API reasoning_summary, and mTLS client certificate settings. What is actually supported depends on the Provider and API.
  • Fixed an explicit chat_completions setting being overridden by a model of the same name, and concurrent launches overwriting each other's model catalog cache.

MCP and local extensions

  • An editor can manage local stdio MCP: see the source, enabled state, observed process and tool state, and diagnostics, and explicitly add, edit, remove, enable, disable, restart, and run doctor. Reading the state never starts a server, calls a tool, or refreshes authentication.
  • Edits need an idle session, the latest config version, and confirmation. Project-level writes still require workspace trust. Enabling does not start a server, and a successful save is not a successful connection; each is reported separately.
  • MCP environment credentials are entered with matcha mcp credentials through hidden terminal input. Cancelling commits nothing, and the config snapshot never exposes command arguments, environment values, URLs, headers, or OAuth material.
  • HTTP MCP can use bearer_token_file. The token file is re-read on every request, so credentials can be rotated.
  • MCP in ordinary sessions supports multi-turn questions and structured JSON tool results, and tells the server to stop work on cancel or timeout. When a built-in tool and an MCP tool share a name, the built-in tool wins.
  • Fixed local plugin hooks needing an extra reload in a new session, MCP settings in an agent definition being overridden by ordinary config, and the model still using the old list after a Skill refresh.

Agents, long tasks, and worktrees

  • New matcha worktree create [name] [--ref REF] creates a managed worktree first, so you can enter it or start a session yourself. matcha -p accepts --worktree.
  • Sub-agents can inherit the parent model, configurable in /settings. Allowed local custom agent definitions can be used to create sub-agents explicitly.
  • An interjection can interrupt a sub-agent's long wait, and the UI separates interjections, queued messages, and steering more clearly. The main agent answers the interjection first, then returns to the original task.
  • Background shell commands appear as task rows with live output, and a resumed session brings background task state back. Fixed duplicate reminders, foreground commands reported as background tasks, and wrong cancel state after closing a session.
  • Context compaction keeps recent messages and references to earlier images. Compaction that fails on a rate limit can be retried, and the extra text for /compact reaches the compaction backend. Long-session cleanup keeps compaction checkpoints that are still referenced, reducing the chance of missing history on restore or rewind.
  • When several parallel tools edit the same file, they run in order. Other tools with no conflict keep running concurrently.

Terminal experience

  • New terminal theme, which uses the terminal's own foreground color and a transparent background. /theme search recognizes aliases such as transparent, dark, and system.
  • Ctrl+P opens the command palette straight from the welcome screen. Tab moves among the prompt, scrollback, and dock, and Ctrl+G shows or hides the dock. The welcome prompt grows with multi-line input.
  • /btw recognizes a side question mid-message and keeps any images attached to it.
  • Better up/down movement after a soft wrap, focus after editing a queued message, and cursor position after retrieving a draft.
  • Fixed pasting the wrong image, an input method submitting an old clipboard image, and images lost after a fullscreen redraw or history recall. An attachment that cannot be sent now tells you.
  • File-edit diffs show real line numbers, and permission prompts expand the pending edit automatically. Long command arguments wrap, and plan comments can be deleted directly.
  • Better display of Markdown table links, heading colors, Swift highlighting, and complex Mermaid diagrams. Syntax highlighting of large files uses less memory.
  • The /memory panel can search note text and looks better in narrow terminals.
  • Fewer redundant redraws in tmux and on an idle Dashboard, with better responsiveness when scrolling, refreshing background tasks, or when terminal output blocks.

Behavior changes

  • Esc no longer cancels a running turn, and the interface now points to Ctrl+C. When matcha -p is interrupted, it finishes the session cleanly and returns the matching exit code.
  • Scheduled /loop tasks now always run in the background and no longer insert timed turns into the current conversation.
  • The Auto permission mode shows as Auto-review in the TUI. Entering and leaving plan mode keeps showing and restoring the previous permission state.
  • The source toolchain moves to Rust 1.94.0.

Fixes made before release

  • Config-directory regression: after the upstream sync, runtime config reads, and writes such as mcp add, Provider selection, and saved settings, briefly went to the old directory and ignored ~/.matcha/config.toml and MATCHA_HOME. Fixed: current config is read and written only under MATCHA_HOME or ~/.matcha, and the old directory is used only for one-time copy migration, never written or deleted. Project-level mcp add writes to .matcha/config.toml.
  • Provider availability (present in 0.03): headless -p, ACP, and the TUI used to reject keys set up through matcha login or the official environment variables for OpenAI, Anthropic, Google, and OpenAI-compatible Providers, and keyless Ollama and LM Studio, saying no Provider was configured. They now agree with the credentials inference actually uses.
  • Provider-level keys (present in 0.03): api_key / env_key under [model_providers.<id>], including custom OpenAI-compatible Providers and xAI, are now used for catalog-model inference, with the same credential the catalog request uses. A [model.<id>] credential still wins. When a non-xAI Provider is selected, XAI_API_KEY in the environment is no longer probed, broadcast, or sent.
  • xAI inference address (present in 0.03): when xAI is selected by key, MATCHA_MODELS_BASE_URL and MATCHA_XAI_API_BASE_URL now take effect, and requests no longer fall back to the public xAI address. An explicit [model_providers.xai] base_url still wins.
  • Headless exit code (present in 0.03): when a tool needs approval and -p cannot ask, the turn now ends with exit code 1 and names the tool on stderr. The output format is unchanged.
  • Session title model (present in 0.03): when xAI is not selected and session_summary_model is not set, session titles use the current session model, and no longer send an xAI model ID to another Provider.
  • matcha trace and matcha setup now say plainly that upload and managed configuration are unavailable in this build. The model is no longer offered feedback-sending or image and video generation tools.

Upgrading from an older version

  • An official install of 0.03 can run matcha update --check to see this release, then install it with matcha update, or with /update in the TUI followed by confirmation. Matcha never downloads or installs on its own.
  • Your data stays in ~/.matcha (or MATCHA_HOME). Linux, Windows, and macOS Intel remain best effort, and this release adds no new platform support claim.