Your terminal, available to your agents.

Chau7 exposes a local MCP server for terminal control, telemetry, runtime inspection and repository metadata.

Stable interface

Download links serve stable v0.5.1 for macOS. The Rust/GPUI 0.6.0-rc.1 candidate is unreleased. Release status and migration plan.

The v0.5.1 registry declares 34 tools and 3 static resources. Resources are separate from tools; individual run resources are also readable by URI.

Read the tool and resource definitions

Tool directory

Search or group the tools. Each entry explains what it returns or changes, its control boundary, and a small input example.

All 34 tools are listed below. Open an entry for its purpose, boundary, and example.

Telemetry history

Look up recorded runs and sessions. These tools read history; they do not discover live tabs.

run_getGet one telemetry run by ID.Read only

Returns the stored summary for a single run.

Boundary: The result may contain repository and provider metadata.

Example parameters

{
  "run_id": "<run-id>"
}

run_listList telemetry runs with optional filters.Read only

Filter by repository, session, provider, parent run, dates, or tags; use limit and offset to page through results.

Boundary: This is recorded telemetry, not live tab discovery.

Example parameters

{
  "repo_path": "/path/to/repo",
  "limit": 10
}

run_tool_callsRead the tool calls recorded for a run.Read only

Returns the run's tool-call history.

Boundary: Tool names, arguments, or results can contain project data.

Example parameters

{
  "run_id": "<run-id>"
}

run_transcriptRead the full conversation transcript for a run.Read only

Returns the recorded conversation turns for one run.

Boundary: Transcripts can include prompts and agent responses. Treat returned text as potentially sensitive.

Example parameters

{
  "run_id": "<run-id>"
}

run_tagSet tags on a telemetry run.Updates tags

Writes the supplied tag list to the selected run.

Boundary: Changes telemetry metadata; it does not execute a terminal command.

Example parameters

{
  "run_id": "<run-id>",
  "tags": [
    "reviewed"
  ]
}

run_latest_for_repoFind the most recent run for a repository.Read only

Optionally narrow the lookup to a provider.

Boundary: Returns recorded history, not a live terminal session.

Example parameters

{
  "repo_path": "/path/to/repo",
  "provider": "Claude Code"
}

session_listList telemetry-backed AI sessions and run counts.Read only

Optionally filter by repository or active telemetry sessions.

Boundary: This is a telemetry/history view. Use tab_list and tab_status to discover live tabs.

Example parameters

{
  "repo_path": "/path/to/repo",
  "active_only": true
}

session_currentRead currently active telemetry-backed sessions.Read only

Returns the current session view derived from available telemetry.

Boundary: Not the authoritative live tab list; use tab_list and tab_status for control.

Example parameters

{}

Runtime state & diagnostics

Inspect current Chau7 state or subscribe to changes on this MCP connection.

chau7_runtime_infoInspect Chau7 build and process identity.Read only

Returns version, build metadata, process ID, launch time, and observability schema version.

Boundary: The documented payload is runtime identity, not a credentials interface.

Example parameters

{}

chau7_mcp_session_infoInspect MCP startup diagnostics for this connection.Read only

Returns client/server identity, bridge and socket paths, negotiated protocol, startup status, and error class.

Boundary: Diagnostics include local filesystem paths; the documented payload excludes secrets.

Example parameters

{}

chau7_runtime_eventsRead recent Chau7 and AI lifecycle events.Read only

Filter recent events by Unix timestamp and result limit; events include stable IDs and timestamps.

Boundary: Event messages and scopes can reveal activity or project context.

Example parameters

{
  "limit": 50
}

chau7_timer_inventoryInspect Chau7-owned timers and display links.Read only

Returns timer IDs, kinds, subsystems, queues, cadence, and active state.

Boundary: Diagnostic inventory only; it does not change timer state.

Example parameters

{}

chau7_state_snapshotRead one aggregated Chau7 state snapshot.Read only

Combines runtime identity, live tabs, pending approvals, repository event summaries, telemetry, timers, and a monotonic change sequence.

Boundary: The snapshot can include workspace and session information visible to the connected client.

Example parameters

{}

chau7_subscribeOpen a live state feed on this MCP connection.Opens feed

Optionally select topics, replay changes from a cursor, and set heartbeat timing. Later deltas arrive as JSON-RPC notifications.

Boundary: Changes the connection's subscription state and streams requested state; it is not an app-setting change.

Example parameters

{
  "topics": [
    "tab-state",
    "approval-state"
  ],
  "heartbeat_interval_ms": 15000
}

chau7_unsubscribeStop a state feed on this MCP connection.Stops feed

Stop the current subscription, optionally identifying it by subscription ID.

Boundary: Ends this connection's feed; it does not close Chau7 or alter the underlying tabs.

Example parameters

{
  "subscription_id": "<subscription-id>"
}

Tabs & agents

Discover tabs, create MCP tabs, and perform explicitly scoped terminal actions.

tab_listList live Chau7 tabs across windows.Read only

Use this as the primary live discovery call before addressing a tab.

Boundary: Lists tabs without sending input or changing ownership.

Example parameters

{}

tab_createCreate a new terminal tab in Chau7.Creates tab

Choose a working directory and optional target window. The returned tab ID can be passed to later tab calls.

Boundary: Creates a local shell tab. The optional Require Approval setting applies to new-tab creation and is off by default.

Example parameters

{
  "directory": "/path/to/repo",
  "window_id": 0
}

tab_request_controlRequest control of an existing user-opened tab.Requires approval

Pass a tab ID from tab_list. Chau7 presents a local confirmation before granting control.

Boundary: Always requires explicit confirmation in Chau7; the request itself does not inject terminal input.

Example parameters

{
  "tab_id": "<tab-id>"
}

tab_release_controlRevoke MCP control of a tab.Releases control

The tab remains open, but later mutating calls require a new grant.

Boundary: Revokes the process-local control grant without closing the tab.

Example parameters

{
  "tab_id": "<mcp-tab-id>"
}

tab_execRun a shell command in an MCP-controlled tab.Runs command

Commands can be queued while the shell starts. Readiness fields or tab_wait_ready can coordinate prompt-ready execution.

Boundary: Runs with the local user's environment in an MCP-controlled or explicitly authorized tab. Command permission rules still apply; this is not a shell sandbox.

Example parameters

{
  "tab_id": "<mcp-tab-id>",
  "command": "pwd"
}

tab_statusRead a tab's current status and control/readiness fields.Read only

Use it to understand a tab before sending input or waiting for readiness.

Boundary: Returns status; it does not start a process or grant control.

Example parameters

{
  "tab_id": "<tab-id>"
}

tab_wait_readyWait for an MCP-controlled tab to accept execution.Waits, no write

Set a timeout in milliseconds to wait for deterministic command acceptance.

Boundary: Waits for readiness; it does not grant permission or submit a command.

Example parameters

{
  "tab_id": "<mcp-tab-id>",
  "timeout_ms": 10000
}

tab_send_inputSend raw text to a terminal tab.Terminal input

Sends the supplied text as terminal input; use tab_press_key or tab_submit_prompt when a key press is required.

Boundary: Can change or submit shell input. Mutating tab tools are limited to MCP-controlled or explicitly authorized tabs.

Example parameters

{
  "tab_id": "<mcp-tab-id>",
  "input": "git status"
}

tab_press_keySend a key press to a terminal tab.Terminal input

Supports named keys and optional modifiers for interactive terminal applications.

Boundary: A key can submit or alter a command. Mutating tab tools are limited to MCP-controlled or explicitly authorized tabs.

Example parameters

{
  "tab_id": "<mcp-tab-id>",
  "key": "escape"
}

tab_submit_promptSubmit the current prompt in an interactive terminal.Submits prompt

Sends Enter to the selected tab, such as to submit a queued task to a running agent.

Boundary: Submits whatever is currently at the prompt. Mutating tab tools are limited to MCP-controlled or explicitly authorized tabs.

Example parameters

{
  "tab_id": "<mcp-tab-id>"
}

tab_closeClose an MCP-controlled tab.Closes tab

A running process prevents normal closure unless force is explicitly set.

Boundary: Closing a tab interrupts its session; force=true can close it while processes are running.

Example parameters

{
  "tab_id": "<mcp-tab-id>"
}

tab_outputRead recent terminal output from a tab.Read only

Read the scrollback buffer by default, or select the ANSI-stripped PTY log for full output including alternate-screen content.

Boundary: Terminal output can contain prompts, commands, credentials, or other project data.

Example parameters

{
  "tab_id": "<mcp-tab-id>",
  "lines": 50
}

agent_launchLaunch one or more coding agents in fresh Chau7 tabs.Starts agent

Starts a local CLI, waits for readiness, and can optionally submit a task prompt. The result reports per-agent launch checks.

Boundary: Starts local processes and may submit a prompt. Launched agents have the permissions of their local environment; the MCP tool is not a sandbox.

Example parameters

{
  "directory": "/path/to/repo",
  "agent_command": "claude",
  "count": 1
}

tab_set_ctoSet a tab's Command Token Optimization override.Changes tab setting

Choose default, forceOn, or forceOff for the selected tab.

Boundary: Updates the per-tab CTO override.

Example parameters

{
  "tab_id": "<mcp-tab-id>",
  "override": "default"
}

tab_renameSet or clear a tab's custom title.Changes tab setting

Pass an empty title to remove the custom title.

Boundary: Changes tab display metadata; it does not rename a repository or process.

Example parameters

{
  "tab_id": "<mcp-tab-id>",
  "title": "Build log"
}

Repository context

Read or update Chau7's local notes and event summaries for a repository.

repo_get_metadataRead Chau7 metadata for a repository.Read only

Returns the saved description, labels, favorite files, and frequent commands.

Boundary: May reveal local project notes and paths.

Example parameters

{
  "repo_path": "/path/to/repo"
}

repo_set_metadataUpdate Chau7 metadata for a repository.Updates repo metadata

Only the provided description, labels, or favorite-file fields are changed.

Boundary: Writes local repository metadata; it does not edit files in the repository.

Example parameters

{
  "repo_path": "/path/to/repo",
  "labels": [
    "website"
  ]
}

repo_frequent_commandsRead frequently used commands for a repository.Read only

Returns commands sorted by frecency and can be limited to a requested number.

Boundary: Command history can reveal project workflows or sensitive command text.

Example parameters

{
  "repo_path": "/path/to/repo",
  "limit": 10
}

repo_get_eventsRead recent AI tool events scoped to a repository.Read only

Optionally filter by tab, event type, tool/provider, producer, or session.

Boundary: Event messages can contain project context; messages are truncated by default.

Example parameters

{
  "repo_path": "/path/to/repo",
  "limit": 20,
  "truncate_messages": true
}

Telemetry resources

chau7://telemetry/runs
chau7://telemetry/sessions
chau7://telemetry/sessions/current
Dynamic run reads: chau7://telemetry/runs/<run_id>

Local transport and registration

The server uses an owner-only Unix socket. A bundled bridge exposes the MCP stdio transport used by supported clients. Integration code supports Claude Code, Codex, Cursor, Windsurf and Gemini CLI; registration depends on client configuration, app settings and helper availability. Inspect the resulting client configuration if a server does not appear.

Local transport does not constrain what a client does with returned output. A connected AI client may send the terminal content it reads to its configured provider.

Control and approvals

Terminal mutation uses control claims and command permission policies. The optional Require Approval setting applies to new-tab creation and is off by default. Requesting control of an existing user tab always asks for explicit consent. Command allow/deny rules and protected input are separate controls. Tab limits apply according to configuration. Inspect MCP control and approval settings before granting terminal control. The separate Permission Center describes macOS access such as protected paths and notifications. Local socket permissions reduce access; they do not make every same-user client trustworthy.

Approval gates · Tab limits · Controlled tab indicators

Questions and answers

Can any script send arbitrary JSON-RPC commands?

Use the documented MCP tools through a compatible client and bridge. Chau7 also has a separate, narrower scripting socket; it is not interchangeable with MCP.

Does every AI session have complete telemetry?

No. Available fields depend on provider transcripts, hooks, attribution and proxy routing. Missing measurements should not be read as zero usage.