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 · Installation · Commands · Limitations · 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:

Cross-terminal asynchronous messages. Leave a note for Claude from any Wave Terminal block; pick up the answer in another. seashell-msg, seashell-ask.
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 <project> — same conversation, same memory. hey, seashell-sessions.
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 <project>`

$ 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 <project>/.seashell-inbox/primary-session.txt, so hey continue with <project> 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 <id>.

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 <some-project>          # resumes that project's latest session
hey what's the latest in <project>?       # 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 <id>).

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/<timestamp>/, 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/<id>.json with project label and Wave block ID
PostToolUse hook — appends every tool call to ~/.seashell/sessions/<id>/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 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 <id>. Otherwise it falls through to seashell-ask.

`seashell-sessions` — see your Claude Code sessions

seashell-sessions                  # list everything
seashell-sessions latest <name>    # print the most recent session id matching <name>
seashell-sessions primary <name>   # 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 <id>     # pin a specific session (project inferred from its cwd)
seashell-sessions show <id>        # full metadata for one session
seashell-sessions resolve <name>   # fuzzy-match and print the best id

Reads from THREE sources:

~/.seashell/sessions/ — hook-registered sessions (★ marker in list)
~/.claude/projects/<encoded-cwd>/<id>.jsonl — filesystem-discovered (every session, every project)
~/Library/Application Support/Claude/claude-code-sessions/<account>/<bridge>/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 <project>/.seashell-inbox/primary-session.txt and is what hey continue with <project> 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 <project> 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 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 <project>` 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/<encoded-cwd>/<uuid>.jsonl). Either can read/write a session. So you can:

Start in Desktop Code mode, resume in Wave with hey continue with <project> ✅
Start in claude REPL inside Wave, view in Desktop's Code mode sidebar later ✅
Bounce back and forth across clients on the same conversation ✅

You cannot resume Desktop "Chat" or "Co-work" mode sessions — those are stored elsewhere and aren't exposed.

Why two MCP server registrations (one for Desktop, one for CLI)?

Claude Desktop and Claude Code CLI maintain separate MCP configurations. Desktop reads ~/Library/Application Support/Claude/claude_desktop_config.json; CLI reads ~/.claude.json. We register on different ports (9876 vs 9879) so they don't collide if both spawn SeaShell at once.

What's the difference between `seashell-msg` and `hey`?

seashell-msg "..." always posts to the inbox (fire-and-forget).
seashell-ask "..." posts and blocks waiting for a reply.
hey ... is smarter: if the prompt looks like a session-resume request, it claude --resumes; otherwise it acts like seashell-ask.

Think of hey as the user-friendly umbrella; seashell-msg/seashell-ask are the lower-level primitives.

Does the daemon cost money?

The daemon spawns claude -p which uses your Claude.ai subscription (Pro or Max), not the API. No per-token billing. You hit your subscription rate limits, not your wallet. If you don't have a subscription, the daemon won't work — install Claude Code from claude.ai.

Can I use this without Wave Terminal?

Mostly yes. The MCP tools work in any client. The shell commands (hey, seashell-msg, etc.) work in any terminal. The side blocks (activity tail + live code preview) require Wave's wsh createblock — they silently no-op if run outside Wave.

What happens if I start two `claude` REPLs in the same project directory?

Each gets its own UUID, its own .jsonl file, its own conversation. They're independent. hey continue with <project> resumes the most recently active one.

How do I make my Wave Terminal command run autonomously without me checking back?

Install the daemon (step 8). Then any seashell-ask from any block will get answered by claude -p within ~5 seconds, no chat needed.

How do I uninstall?

# Daemon
launchctl unload ~/Library/LaunchAgents/dev.seashell.daemon.plist
rm ~/Library/LaunchAgents/dev.seashell.daemon.plist
rm ~/.local/bin/seashell-daemon

# Theme sync
launchctl unload ~/Library/LaunchAgents/dev.seashell.theme-sync.plist
rm ~/Library/LaunchAgents/dev.seashell.theme-sync.plist

# Shell commands and hooks
rm ~/.local/bin/seashell-* ~/.local/bin/hey

# Hooks from Claude config (manual edit)
# Open ~/.claude/settings.json and remove the SeaShell entries from the "hooks" key

# State
rm -rf ~/.seashell

# MCP server registrations (manual)
# Remove "seashell" entry from ~/Library/Application Support/Claude/claude_desktop_config.json
# claude mcp remove seashell

# Restore old fish config
mv ~/.config/fish ~/.config/fish.removed
mv ~/.seashell-backups/<timestamp>/fish ~/.config/fish

How can I see what the daemon is doing right now?

tail -f /tmp/seashell-daemon.log

You'll see every poll cycle, every spawned claude -p, and Claude's response timing.

Can the daemon talk to itself? (i.e. infinite loop)

The daemon's claude -p is restricted to four tools: inbox_count, inbox_history, read_user_inbox, reply_to_user. It can't post new inbox messages — only consume and reply.

What do I do if my hook fired wrong / something broke / I want to reset?

Delete ~/.seashell/sessions/<bad-id>/ and ~/.seashell/sessions/<bad-id>.json. The next interactive claude will register fresh. Your ~/.claude/projects/ history is preserved.

Why is my inbox showing messages I didn't send?

Most likely your claude -p (e.g. from the daemon) called read_user_inbox and it returned messages from a different cwd's inbox. SeaShell aggregates inboxes across all known projects + global by default. Use inbox_count to see the per-project breakdown.

Where do I report bugs?

Open an issue at github.com/M-Pineapple/seashell/issues.

Architecture & docs

docs/ARCHITECTURE.md — System overview, layers, MCP tool surface, Wave object model
docs/INBOX.md — Storage layout, routing rules, daemon architecture, troubleshooting
docs/WAVE_INTEGRATION.md — How SeaShell talks to Wave: wsh, WAVETERM_JWT, RPC mechanism
docs/HELPER_PROTOCOL.md — Wire protocol between the external server and the in-Wave helper

Project layout

seashell/
├── README.md                       ← you are here
├── LICENSE                         ← MIT
├── Package.swift                   ← Swift package manifest
├── build.sh / clean.sh             ← build scripts
├── setup.sh                        ← post-clone bootstrap
│
├── Sources/
│   ├── Seashell/                   ← MCP server, tool handlers, Wave adapter
│   │   ├── InboxHandlers.swift     ← inbox tools (read/count/history/reply/read_my_replies)
│   │   └── …                       ← 30+ other handler files
│   └── ConfigManager/              ← standalone config-management binary
├── Tests/SeashellTests/
│
├── helper/seashell-helper          ← in-Wave Python helper (TCP proxy to wsh)
├── config/                         ← Claude Desktop config template
├── docs/                           ← architecture, INBOX, integration, helper protocol
├── prompts/                        ← AI-assisted configuration prompts
│
└── examples/
    ├── wave-config/
    │   ├── bin/                    ← shell commands: hey, seashell-msg/ask/init/sessions/setup-hooks
    │   ├── hooks/                  ← Claude Code SessionStart + PostToolUse scripts
    │   ├── fish/                   ← starter fish stack
    │   ├── fastfetch/              ← system-info banner config
    │   ├── wave/                   ← Wave widgets/settings templates
    │   ├── theme-sync/             ← auto light/dark switcher
    │   └── install.sh              ← installs all the above into your $HOME
    └── seashell-daemon/            ← autonomous inbox responder via claude -p

Acknowledgments

Wave Terminal — the terminal SeaShell is built around. Open-source, block-based, deeply scriptable.
Anthropic — for the Model Context Protocol, Claude Desktop, and Claude Code CLI.
fish shell, atuin, starship, zoxide, fastfetch — small tools that make the example config worth running.
Ollama + the Qwen team — for the local LLM that powers the optional natural-language fish layer.

License

MIT — see LICENSE.

Built with 🐚 by Pineapple 🍍

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
Sources		Sources
Tests/SeashellTests		Tests/SeashellTests
assets		assets
config		config
docs		docs
examples		examples
helper		helper
prompts		prompts
.gitignore		.gitignore
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
build.sh		build.sh
clean.sh		clean.sh
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation

SeaShell

What it is

✨ Marquee feature: hey continue with <project>

Quick start

Installation

1. Install Wave Terminal

2. Install Claude Desktop and/or Claude Code CLI

3. Build SeaShell

4. Register the MCP server with Claude

a) Claude Desktop

b) Claude Code CLI

5. Sign in to your Claude subscription

6. (Optional but recommended) Install the example bundle

7. (Optional) Wire the Claude Code hooks

8. (Optional) Install the autonomous daemon

Commands you'll use every day

hey — natural-language entry point

seashell-sessions — see your Claude Code sessions

seashell-msg — leave Claude a note

seashell-ask — blocking question

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

seashell-init — register a project

MCP tools surface (60+ tools)

Inbox (Tier A — safe)

Cross-session peeking (Tier A — safe)

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

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

Wave secrets (Tier C — explicit approval required)

Command execution

Templates, profiles, environment

Limitations

FAQ

Why didn't my SessionStart hook fire?

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

Why two MCP server registrations (one for Desktop, one for CLI)?

What's the difference between seashell-msg and hey?

Does the daemon cost money?

Can I use this without Wave Terminal?

What happens if I start two claude REPLs in the same project directory?

How do I make my Wave Terminal command run autonomously without me checking back?

How do I uninstall?

How can I see what the daemon is doing right now?

Can the daemon talk to itself? (i.e. infinite loop)

What do I do if my hook fired wrong / something broke / I want to reset?

Why is my inbox showing messages I didn't send?

Where do I report bugs?

Architecture & docs

Project layout

Acknowledgments

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 18

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

✨ Marquee feature: `hey continue with <project>`

`hey` — natural-language entry point

`seashell-sessions` — see your Claude Code sessions

`seashell-msg` — leave Claude a note

`seashell-ask` — blocking question

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

`seashell-init` — register a project

What's the difference between `seashell-msg` and `hey`?

What happens if I start two `claude` REPLs in the same project directory?

Packages