Suggests a terminal command based on the user's request

Executes a terminal command and captures its output. Runs silently by default (no visible block). Pass show_in_wave=true only when you want the user to watch the command run in a visible Wave Terminal block — e.g. a build, install, or multi-step process. For 5 consecutive commands, leave show_in_wave unset so they all run quietly without cluttering Wave.

Executes a command and automatically waits for and returns its output. Preferred for quick commands that don't need a visible terminal tab. Use open_terminal_tab only for long-running processes like builds or servers.

Preview a command without executing it

Retrieve the output of a previously executed command

Execute a pipeline of commands with conditional logic (stop/continue/warn on failure)

Execute a command with real-time output streaming - ideal for long-running builds

Save a command template with variables for reuse

Execute a saved command template with variable substitution

List all saved command templates

List recent commands from history with status, duration, and exit codes

Run health check on configuration, database, terminal, and recent error rates

Copy text to the macOS system clipboard

Read the current contents of the macOS system clipboard

Toggle macOS notification preferences for command completion alerts

Get current terminal environment context including git branch, active venv, node version, docker status, and working directory

Execute a command and return structured parsed output (supports git status, git log, docker ps, test results, ls -la, and JSON)

Capture a snapshot of the current shell environment variables with a named label

Compare two environment snapshots and show additions, removals, and changes

Save current project context as a named workspace profile (directory, commands, env vars, terminal preference)

Load a saved workspace profile to restore project context

List all saved workspace profiles

Delete a saved workspace profile

Open a new named terminal tab. ONLY use for long-running commands that need their own visible tab (builds, installs, servers, cloning repos). For quick commands, prefer execute_command or execute_with_auto_retrieve instead. If a session already exists, use send_to_session to reuse it.

Send a command to an existing named terminal session, reusing its tab. Always prefer this over opening a new tab when a relevant session already exists. Use list_sessions first to check for available sessions.

List all active terminal sessions. Check this before opening new tabs to avoid creating duplicates. Reuse existing sessions with send_to_session whenever possible.

Close a named terminal session and optionally close its tab. Use to clean up sessions that are no longer needed. Pass close_tab: true to also close the terminal tab.

Remove stale terminal sessions that have been inactive. Use periodically to clean up accumulated tabs. Sessions inactive longer than inactive_minutes (default: 30) are removed. Set close_tabs to true to also close the terminal tabs.

Set up a file system watcher that triggers a command when files change

Remove an active file system watcher

List all active file system watchers

Execute a command on a remote host via SSH (key-based authentication only)

Save an SSH connection profile for quick reuse

List all saved SSH connection profiles

Delete a saved SSH connection profile

Check if a command is interactive (requires TTY/stdin) before executing it. Returns safety level: safe, cautious, interactive, or blocked with suggestions for non-interactive alternatives

Read Wave Terminal settings from ~/.waveterm/settings.json. Optionally filter by namespace prefix (e.g. 'ai', 'term', 'window', 'app').

List all custom widgets configured in Wave Terminal (from ~/.waveterm/widgets.json).

List all AI model presets configured in Wave Terminal (from ~/.waveterm/aipresets.json).

List all tab background definitions in Wave Terminal (from ~/.waveterm/backgrounds.json).

Update a single Wave Terminal setting in settings.json. First call returns a confirmation; pass approved=true to execute. Examples of keys: 'ai:model', 'term:theme', 'term:fontsize', 'app:tabbar'.

Create a new custom widget in Wave Terminal (writes to ~/.waveterm/widgets.json). First call returns a confirmation; pass approved=true to execute.

Update an existing Wave Terminal widget. First call returns a confirmation; pass approved=true to execute.

Remove a custom widget from Wave Terminal. First call returns a confirmation; pass approved=true to execute.

Create or update a Wave Terminal AI model preset in ~/.waveterm/aipresets.json. First call returns a confirmation; pass approved=true to execute.

Set the Wave Terminal theme (writes 'term:theme' to settings.json). First call returns a confirmation; pass approved=true to execute.

Update Wave Terminal window or terminal appearance settings (writes to settings.json). First call returns a confirmation; pass approved=true to execute. Supported: font_size, font_family, transparency, tab_bar, ctrl_v_paste, confirm_quit, mac_option_is_meta, bell_sound, bell_indicator, default_new_block.

Check whether the Seashell Helper block is connected. Shows which tool tier is available.

Connect the MCP server to the Seashell Helper block running inside Wave Terminal. The helper must already be running (open the Seashell Helper widget in Wave first).

List all Wave Terminal workspaces with their IDs, names, icons, and colours. Requires the Seashell Helper block to be running.

List blocks in Wave Terminal, optionally filtered by workspace, tab, or view type. Requires the Seashell Helper block.

Create a new block in Wave Terminal. First call returns a confirmation; pass approved=true to execute. Requires the Seashell Helper block.

Delete a block from Wave Terminal. First call returns a confirmation; pass approved=true to execute. Requires the Seashell Helper block.

Get terminal scrollback content from a Wave block. Requires the Seashell Helper block.

Run a command in a new Wave Terminal block. First call returns a confirmation; pass approved=true to execute. Requires the Seashell Helper block.

Open a file in a Wave Terminal preview block. Requires the Seashell Helper block.

Open a file for editing in Wave Terminal. First call returns a confirmation; pass approved=true to execute. Requires the Seashell Helper block.

List all Wave Terminal secret keys (Tier C — requires approved=true and a non-empty reason). Requires the Seashell Helper.

Set a Wave Terminal secret (Tier C — requires approved=true and a non-empty reason). Requires the Seashell Helper.

Read a Wave Terminal secret (Tier C — requires approved=true and a non-empty reason). The plaintext value is withheld unless SEASHELL_ALLOW_SECRET_READ=1. Requires the Seashell Helper.

Delete a Wave Terminal secret (Tier C — requires approved=true and a non-empty reason). Requires the Seashell Helper.

Add a Fish shell widget to the Wave widget bar (convenience wrapper around wave_create_widget). First call returns a confirmation; pass approved=true to execute.

Bootstrap a Wave tab with a project-specific block layout. Templates: general, python-dev, node-dev, swift-dev. First call returns a confirmation; pass approved=true to execute. Requires the Seashell Helper.

Drain unread notes the user left for Claude via the seashell-msg shell command. Aggregates across the global inbox (~/.seashell/inbox.jsonl) AND every registered project inbox (.seashell-inbox/inbox.jsonl in each project root). Each note carries a timestamp, working directory, project label, and (optionally) attachments + a reply_token. Read messages are archived. Call this when the user's chat message is brief or implies they were elsewhere (e.g. "?", "continue", "check inbox"). If any returned message has a reply_token, you should answer via reply_to_user.

Cheap peek across the global inbox + every registered project inbox. Returns total unread count, age of the oldest message, and a per-project breakdown. Call before read_user_inbox if you only want to know whether anything is waiting.

Browse archived messages across all inboxes (global + every registered project). Sorted most-recent-first.

Post a reply to a user inbox message. Use this when a message returned by read_user_inbox had a reply_token — that means the user invoked seashell-ask and is blocking on your answer. The reply is written to the appropriate replies.jsonl (global or per-project) and seashell-ask picks it up within ~1 second. If the user just left a note via seashell-msg (no reply_token), no reply call is needed — answer in chat normally.

Browse the OUTBOUND history — replies you've previously sent via reply_to_user. Aggregates across the global inbox and every registered project's replies.jsonl. Use this to answer questions like "what was the last thing you said in this project?" or "what did you tell me about X?" without needing to manually open the file. Sorted most-recent-first.

Read the most recent N turns of a Claude Code session's transcript, without resuming it. Use this when the user asks 'what's the status of project X?' or 'what did we last talk about in ?' — you read the actual transcript instead of relying on memory. Resolution: pass project (fuzzy name) and Seashell follows the project's .seashell-inbox/primary-session.txt pointer (or falls back to the largest .jsonl in that project's Claude Code dir). Or pass session_id (full UUID or prefix) for direct lookup. Returns formatted user/assistant turns; tool calls are flagged with [used: <tool>] and thinking blocks with [thought]. Long messages auto-truncate.