Seashell

SeaShell

Talk to Claude from any terminal block. Get answers back. Resume any past Claude Code session by name.

An MCP server + shell toolkit that bridges Wave Terminal, Claude Desktop, and Claude Code — turning multi-tab terminal work into seamless AI-collaborative coding.

[Quick start](#quick-start) · [Installation](#installation) · [Commands](#commands-youll-use-every-day) · [Limitations](#limitations) · [FAQ](#faq)

---

What it is

SeaShell is a Model Context Protocol server (Swift) plus a small set of shell commands that together give you three things:

1. Cross-terminal asynchronous messages. Leave a note for Claude from any Wave Terminal block; pick up the answer in another. seashell-msg, seashell-ask.
2. Resume any Claude Code session by name. Walk away from a deep coding session in Claude Desktop's Code mode last night, open Wave this morning, type hey continue with — same conversation, same memory. hey, seashell-sessions.
3. Optional autonomous responses via a daemon. Without you ever touching a chat, a small daemon spawns claude -p in the right project directory and answers your inbox. Uses your Claude subscription — no API key.

All three compose. You can mix-and-match.

✨ Marquee feature: hey continue with

$ hey continue with myapp

🔄 Resuming session a1b2c3d4 (project: myapp)...

> What's the latest update on the auth refactor?

We finished extracting the AuthService. Tests pass. Next is wiring it
into the API layer — I have a draft in routes/auth.py on line 142.
Want me to walk through it?

That's a fresh terminal. Same conversation history as last night's Claude Desktop Code-mode session. Full project memory. Fuzzy matching — hey continue with ma works too.

Each project has a pinned primary session at /.seashell-inbox/primary-session.txt, so hey continue with always lands you in the same conversation — even if you've spawned multiple parallel sessions for the same repo. The pin is set automatically the first time you seashell-init (largest existing session wins) or on the first claude startup in that directory. Re-pin any session anytime with seashell-sessions promote .

Quick start

# 1. Build
git clone https://github.com/M-Pineapple/seashell ~/Github/seashell
cd ~/Github/seashell && ./build.sh

# 2. Register the MCP server with Claude Desktop AND/OR Claude Code CLI
#    (Desktop config edit OR `claude mcp add --scope user seashell ...`)

# 3. Sign in to your Claude subscription via the CLI
claude auth login

# 4. (Optional but highly recommended) Install the example bundle
cd ~/Github/seashell/examples/wave-config && ./install.sh
seashell-setup-hooks   # wire SessionStart + PostToolUse into ~/.claude/settings.json

# 5. Try it
hey continue with           # resumes that project's latest session
hey what's the latest in ?       # async question via inbox

Installation

1. Install Wave Terminal

Download Wave Terminal and launch it once.

2. Install Claude Desktop and/or Claude Code CLI

You'll want at least one of:

• Claude Desktop — the GUI app from claude.ai/download. Use this for general chat. The "Code" mode here persists sessions to disk and IS resumable from SeaShell.
• Claude Code CLI — install via npm: npm install -g @anthropic-ai/claude-code. This is what hey continue with actually invokes (via claude --resume ).

Most users want both.

3. Build SeaShell

git clone https://github.com/M-Pineapple/seashell ~/Github/seashell
cd ~/Github/seashell
./build.sh

build.sh produces .build/release/seashell (~16 MB).

4. Register the MCP server with Claude

You need to register SeaShell with whichever Claude clients you use. They're separate registrations.

a) Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "seashell": {
      "command": "/absolute/path/to/seashell/.build/release/seashell",
      "args": ["--port", "9876"]
    }
  }
}

Restart Claude Desktop. The 60+ SeaShell tools appear in the available-tools list.

b) Claude Code CLI

claude mcp add --scope user seashell \
    /absolute/path/to/seashell/.build/release/seashell -- --port 9879

The different port (9879) avoids a clash if you run both Desktop and CLI invocations in parallel. --scope user means the registration is global — visible from any directory.

5. Sign in to your Claude subscription

claude auth login

This opens a browser for OAuth into your Claude.ai account. No API key needed — claude -p (and the optional daemon) draws from your Pro/Max subscription via this auth.

6. (Optional but recommended) Install the example bundle

cd ~/Github/seashell/examples/wave-config
./install.sh

This snapshots your existing fish + Wave configs to ~/.seashell-backups//, then installs:

• ~/.local/bin/seashell-msg, seashell-ask, seashell-init
• ~/.local/bin/hey, seashell-sessions, seashell-setup-hooks
• ~/.local/bin/seashell-session-start, seashell-post-tool-use (Claude Code hooks)
• ~/.config/fish/ (a working fish config with NL routing, atuin, fastfetch, theme-sync)
• ~/.config/fastfetch/config.jsonc
• ~/Library/LaunchAgents/dev.seashell.theme-sync.plist (auto light/dark for Wave)

7. (Optional) Wire the Claude Code hooks

seashell-setup-hooks

Adds two entries to ~/.claude/settings.json:

• SessionStart hook — registers each interactive claude REPL in ~/.seashell/sessions/.json with project label and Wave block ID
• PostToolUse hook — appends every tool call to ~/.seashell/sessions//activity.log and updates a "current file" pointer when Claude does Edit/Write

The hooks only fire for interactive TTY sessions (a real claude REPL inside a Wave block). They do NOT fire for claude -p invocations. SeaShell's seashell-sessions command works regardless because it falls back to scanning ~/.claude/projects/.

8. (Optional) Install the autonomous daemon

cd ~/Github/seashell/examples/seashell-daemon
./install.sh

The daemon polls every project's inbox every 5 seconds. When something lands, it spawns claude -p from that project's directory to read and respond. Uses your Claude subscription via the CLI auth from step 5.

See [examples/seashell-daemon/README.md](examples/seashell-daemon/README.md) for details.

Commands you'll use every day

hey — natural-language entry point

hey continue with myapp                        # resume project's latest session
hey resume ma                                  # fuzzy match (initials work)
hey let's work on the seashell project        # natural language continuation
hey what's the next thing on the refactor?    # routes to inbox (waits for reply)
swift build 2>&1 | hey "fix these errors"     # pipe + ask

If the first words look like a session-resume intent (continue, resume, let's work on, go back to, pick up), hey runs claude --resume . Otherwise it falls through to seashell-ask.

seashell-sessions — see your Claude Code sessions

seashell-sessions                  # list everything
seashell-sessions latest     # print the most recent session id matching 
seashell-sessions primary    # print the project's pinned primary session id
                                   #   (falls back to latest if none pinned)
seashell-sessions promote          # pin most-recent session as primary for $PWD
seashell-sessions promote      # pin a specific session (project inferred from its cwd)
seashell-sessions show         # full metadata for one session
seashell-sessions resolve    # fuzzy-match and print the best id

Reads from THREE sources:

• ~/.seashell/sessions/ — hook-registered sessions (★ marker in list)
• ~/.claude/projects//.jsonl — filesystem-discovered (every session, every project)
• ~/Library/Application Support/Claude/claude-code-sessions///local_*.json — Claude Desktop's session wrappers, which contribute Desktop's user-friendly titles and archived flag

This three-source read means fuzzy matching works against Desktop titles too: hey continue with the current trader pro will find a session titled Current Trader Pro Development Session in Desktop, even if its on-disk cwd basename (e.g. Github) wouldn't match. Archived sessions get an A marker in list and are excluded from fuzzy matching by default — so a long-archived experiment can't be resurrected by accident.

The pinned primary session lives at /.seashell-inbox/primary-session.txt and is what hey continue with resumes.

seashell-msg — leave Claude a note

seashell-msg "compare the test output to what we discussed"
swift build 2>&1 | seashell-msg "fix these errors"
seashell-msg --file /tmp/build.log "investigate this"
seashell-msg --global "skip cwd routing"

Auto-routes to the nearest .seashell-inbox/ ancestor; falls back to ~/.seashell/inbox.jsonl.

seashell-ask — blocking question

seashell-ask "what's the status of the refactoring?"      # blocks up to 600s
seashell-ask --timeout 60 "did the build pass?"           # custom timeout
seashell-ask --no-wait "post and exit"                    # fire-and-forget with reply token

Posts a message with a reply_token, polls for a matching reply in replies.jsonl, prints when found.

seashell-mirror-mcp — keep CLI and Desktop MCP servers in sync

seashell-mirror-mcp --dry-run     # preview what would be added (env values redacted)
seashell-mirror-mcp --list        # just print the diff
seashell-mirror-mcp               # apply: clone Desktop MCP entries to the CLI (additive)
seashell-mirror-mcp --update      # force re-sync EVERY Desktop server (picks up rotated tokens,
                                  # env-var changes, command edits). Removes + re-adds each entry.
                                  # Doesn't touch CLI-only servers (e.g. seashell).

Claude Desktop and Claude Code CLI use separate config files for MCP server registration (claude_desktop_config.json vs ~/.claude.json), even though they share the same session .jsonl storage. So a session resumed via hey continue with may be missing tools that Desktop has — e.g. you can ask Claude about Trello in Desktop but the resumed CLI session has no Trello MCP. This script mirrors Desktop → CLI (additive only, never removes), making the tool surface match. Idempotent and safe to re-run whenever you add a new server in Desktop.

Dry-run output redacts env values for keys that look like secrets (anything matching the components KEY, TOKEN, SECRET, PASSWORD, API, AUTH, CREDENTIAL, PAT). The actual claude mcp add calls use the real values from your Desktop config.

seashell-init — register a project

cd ~/Github/your-project
seashell-init

Creates .seashell-inbox/, registers the project in ~/.seashell/projects.jsonl, writes (or extends) CLAUDE.md with an inbox hint.

MCP tools surface (60+ tools)

Grouped by tier. Used by Claude (in Desktop, in claude REPLs, in the daemon) — not typed by you.

Inbox (Tier A — safe)

• read_user_inbox, inbox_count, inbox_history, reply_to_user, read_my_replies

Cross-session peeking (Tier A — safe)

• read_session_transcript — read the most recent N turns of any project's primary session (or any session by id) without resuming it. Lets Claude Desktop answer "what's the status of project X?" by quoting the actual transcript instead of guessing.

Direct Wave config (Tier A read / Tier B write)

• wave_get_settings, wave_set_setting, wave_get_widgets, wave_create_widget, wave_update_widget, wave_delete_widget, wave_get_ai_presets, wave_set_ai_preset, wave_set_theme, wave_set_appearance, wave_get_backgrounds

Wave helper-block tools (Tier A read / Tier B write)

• wave_list_workspaces, wave_list_blocks, wave_get_scrollback, wave_get_block_meta, wave_set_block_meta, wave_create_block, wave_delete_block, wave_run_in_block, wave_view_file, wave_edit_file

Wave secrets (Tier C — explicit approval required)

• wave_secret_list, wave_secret_set, wave_secret_get, wave_secret_delete

Command execution

• execute_command, execute_with_auto_retrieve, execute_with_streaming, execute_pipeline, get_command_output, list_recent_commands

Templates, profiles, environment

• save_template, run_template, list_templates, save_workspace_profile, load_workspace_profile, list_workspace_profiles, get_environment_context, capture_environment, diff_environment

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full tier table.

Limitations

These aren't bugs — they're architectural realities worth knowing up front.

| Limitation | Why | |---|---| | You can't target a specific Claude Desktop chat with seashell-msg / seashell-ask. The MCP server is shared across all Desktop chats — there's no chat ID exposed to MCP. | Claude Desktop's MCP integration runs one shared MCP server per config entry, with no per-chat identifier. The workaround: use the daemon (project-scoped Claude per inbox) or use hey continue with to resume a Claude Code session instead. | | Continuity works only for Claude Code sessions. Claude Desktop's "Chat" mode and "Co-work" mode aren't resumable. Claude Desktop's "Code" mode IS — it persists to the same ~/.claude/projects/ storage as the CLI. | Chat and Co-work transcripts are internal to Desktop. Code mode shares the open .jsonl format with the CLI. Use Code mode if you want cross-day, cross-client continuity. | | Hooks (SessionStart, PostToolUse) fire only for interactive TTY sessions. They do NOT fire for claude -p invocations. | This is a Claude Code behavior we accept. SeaShell's seashell-sessions falls back to scanning ~/.claude/projects/ so resume-by-name works regardless. The activity log + side blocks only populate during interactive sessions. | | Side blocks (activity tail + live code preview) only spawn from inside Wave Terminal. They use wsh createblock which requires WAVETERM_JWT. | The hook checks for the env var before invoking wsh. When you start claude outside Wave (e.g. plain Terminal.app), the side blocks are silently skipped; everything else still works. | | The autonomous daemon's claude -p sessions don't update Claude Desktop's open chat in real time. | Claude Desktop holds its own in-memory state. New turns appended to the .jsonl from claude --resume -p only become visible after Desktop refreshes/reopens the session. If you have a session open AND the daemon writes to it concurrently, last-write-wins on the file. Pick one or the other to be "live". | | High-volume use can hit Claude.ai subscription rate limits. | The daemon batches one claude -p per project per polling cycle (default 5 s). For typical use this stays under limits. For heavy workloads, increase SEASHELL_DAEMON_POLL. | | No cross-machine sync of inbox or session registry. | All state lives under ~/.seashell/ and ~/.claude/projects/. You could symlink these into iCloud Drive but it's untested. |

FAQ

Why didn't my SessionStart hook fire?

Hooks fire only for interactive TTY sessions. If you started Claude with claude -p "..." (non-interactive) or piped stdin into claude, the hook is skipped. Run claude normally inside a Wave Terminal block to trigger it.

What's the difference between Claude Desktop "Code" mode and Claude Code CLI?

They use the same conversation file format (~/.claude/projects//.jsonl). Either can read/write a session. So you can:

• Start in Desktop Code mode, resume in Wave with `hey continue with

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: M-Pineapple
• Source: M-Pineapple/seashell
• License: MIT
• Homepage: https://github.com/M-Pineapple/seashell

Install and usage instructions live in the source repository linked above.