09. Automation and Editor Integration
Leader processes
Inspect or stop the **local** shared assistant backend. Leaders are optional. They are not a workspace hub, and they do not expose your workspace to an official cloud.
What a leader is
A leader is a long-lived Matcha process on this machine. The TUI or matcha agent stdio can attach to it so several clients share one assistant (one socket, one tool runtime) instead of each starting a full process.
By default leader mode is **off**. You turn it on with --leader on matcha agent, or [cli] use_leader in ~/.matcha/config.toml. --no-leader always wins. A requested sandbox profile that is not off also refuses leader mode so tools stay in-process.
The Unix socket defaults to ~/.matcha/leader.sock (lock file leader.lock, log leader.log). Override with --leader-socket PATH or MATCHA_LEADER_SOCKET (legacy GROK_LEADER_SOCKET is read-only compatible).
Two command families
Easy to mix up:
| Command | What it is |
|---|---|
matcha agent leader | **Run** as the shared leader process. |
matcha leader list / info / kill | **Manage** leaders that are already running. |
matcha leader management:
| Subcommand | Effect |
|---|---|
list | Print discovered leaders (--json for a machine-readable array). |
info | Details for one leader. Pass --pid from list; without it, the default production environment target is used. --json available. |
kill | Stop **all** discovered live Matcha leaders. There is no --pid on kill. Stale locks for PIDs that are not Matcha processes are removed. |
list with no candidates prints No leader candidates found. kill in that case prints the same idea to stderr and exits successfully.
info that cannot use the control channel still prints the descriptor and warns that detailed info is unavailable.
When you need these commands
Use them when a follower will not connect, after an upgrade that left an old leader, or when you want to confirm a socket path before attaching an editor. You do not need a leader for ordinary TUI use or for matcha -p.
Inspect and stop
See what is running:
matcha leader list
matcha leader list --jsonInspect one process:
matcha leader info --pid 12345
matcha leader info --pid 12345 --jsonStop every live leader this command can verify as a Matcha process:
matcha leader killStart a leader yourself (advanced; most users let a follower spawn one when --leader is set):
matcha agent leader--no-exit-on-disconnect keeps that process after the last client leaves. --relay-on-demand only exists for a product WebSocket relay; that relay is disabled. --no-auto-update is a compatibility no-op.
Attach a stdio client
matcha agent --always-approve --leader stdioWhat is unavailable
Workspace hub exposure is disabled. The CLI subcommand matcha workspace (start, pause, resume, stop, restart, status) is **hidden**. It is not a local dashboard and not a substitute for matcha worktree or /dashboard.
Product relay is also off: a leader in this build serves **local** clients over IPC only. For parallel local work, use /dashboard and matcha worktree, not matcha workspace.