Skip to main content
Glama

⭐ Sea-Star

A private, local-first AI agent with a MacOS menubar cockpit that lives in your Obsidian vault. One-click's ease. Nothing leaves your house.

Version License: MIT Python 3.11+


— The Sea Star, 20th n 3rd, Dogpatch, SF, Ca, USA This cute snack also thanks Tom's drydock around the corner. As it was.

A sea star holds on tight to its rock and doesn't let go. Sea-Star does the same with your notes — and helps you find the right one.


At a glance

  • 🏠 Local by default — the reasoning runs on your machine, against your model. No cloud, no telemetry, no account.

  • 🗂️ Your vault is the memory — it reads Obsidian notes directly and answers with citations back to them.

  • 🔌 MCP both ways — it's a server and a client, so it drops into Osaurus, Claude Desktop, Cursor or TRAE, and can borrow other MCP servers as its own tools.

  • ⚙️ Runtime-agnostic — any OpenAI-compatible endpoint works unchanged: Osaurus, Ollama, LM Studio, llama.cpp, MLX, vLLM, Unsloth Studio.

  • 🖱️ Two front doors — a terminal-first CLI, and a native macOS menu-bar app that wraps the same engine. Anything you can click, you can also type.


Related MCP server: obsidian-local-mcp

Documentation

🚧 SeaStar (Work in Progress)

Note: SeaStar is currently under active pre-alpha development. It is not yet ready for production use, and code architecture is subject to rapid change.

One page for wherever you're starting from. Start at the docs index if you're unsure.

I want to…

Read

Understand what this is, in plain English (no jargon)

docs/start-here.md

Run it day to day — by clicking or by typing

docs/use-the-app.md

Connect Sea-Star to Osaurus / Claude Desktop / Cursor / TRAE

docs/connect.md

See every command, tool, setting and runtime

docs/reference.md

Know how it actually works — architecture, the capability ladder, privacy

docs/TECHNICAL.md

Fix something that's broken

docs/troubleshooting.md

Know the rules the code must keep

docs/foundation.md

The landing page is a single static file — site/index.html, open it in a browser. The palette, the type and the voice rules live in docs/brand.md.


The problem

Right now you get to pick two of three:

  • Powerful local Harnesses (Opencode, Buzz, custom stacks) — but configuring them is a weekend of YAML and silent failures.

  • One-click agents (the frontier products) — but they're cloud, proprietary, and they read your notes.

  • Your Obsidian vault as the brain — but wiring Obsidian + a local model + an agent loop together is left as an exercise for the reader.

Sea-Star is an AI Cockpit and the missing third option: the zero-config, fully-local agent that treats your Obsidian vault as first-class memory, runs on whatever local model you already have, and plugs into whatever MCP host you already use.

What it is

Sea-Star is an MCP server that is also an MCP client. That sounds odd, but it's deliberate:

  • As an MCP server, it exposes one simple tool (ask_seastar) to any host — Claude Desktop, Cursor, TRAE, whatever. That tool runs a full local agent loop.

  • As an MCP client, it consumes other MCP servers — including the existing Obsidian ones — as its own tools.

The reasoning happens on your machine, against your model. The host is just a window.

Why it stays sovereign

Sea-Star talks to any OpenAI-compatible local inference endpoint. That means it works, unchanged, with:

Runtime

Where it's usually found (a hint, not a lease)

Osaurus

http://localhost:1337/v1

Ollama

http://localhost:11434/v1

LM Studio

http://localhost:1234/v1

llama.cpp (llama-server)

http://localhost:8080/v1

MLX (mlx_lm.server)

http://localhost:8080/v1

oMLX

http://localhost:8000/v1

vLLM

http://localhost:8000/v1

Unsloth Studio

http://localhost:8888/v1

Runtime-agnostic by contract. You never touch this layer again.

A default port is where a runtime is usually observed listening — it is not exclusive, and it is not permanent. Two runtimes may ship the same default, and an app update can move one onto another's port (oMLX has claimed 1337 on at least one machine after a self-update). sea-star doctor probes the endpoints and names what is actually answering where — trust its report over any table.

The focused setup: Osaurus + Unsloth Studio

I built Sea-star after thinking it would be cool for an Osaurus (my fave harness that week ) agent.. just to hop over to Unsloth studio and do some fine tuning It is runtime-agnostic on purpose — but if you want the specific pairing that inspired it, this is the one: Osaurus for the agent layer, Unsloth Studio for the model-and-skills layer, Sea-Star for the memory.

The two are complementary by nature. Osaurus is a Mac-native agent harness — it runs agents, loads skills, and speaks MCP both ways. Unsloth Studio is a model workbench — it runs and fine-tunes models and exposes an OpenAI-compatible API. Osaurus brings the doing; Unsloth brings the thinking; neither one knows about your notes. Sea-Star is the third leg: it gives them a shared, private memory in your Obsidian vault.

┌────────────────────┐   MCP    ┌──────────────┐   OpenAI-compatible   ┌──────────────────┐
│  Osaurus (agents)  │ ───────▶ │   Sea-Star   │ ────────────────────▶ │ Unsloth Studio   │
│  skills, memory    │ ◀─────── │  (memory)    │ ◀──────────────────── │ (local models)   │
└────────────────────┘          └──────┬───────┘                       └──────────────────┘
                                       │
                                       ▼
                              ┌──────────────────┐
                              │  Obsidian vault  │
                              └──────────────────┘

The recipe (three moves):

  1. Start the engine. In Unsloth Studio, launch the local server and copy its OpenAI-compatible base URL (the same kind of URL as Ollama's …:11434/v1).

  2. Point Sea-Star at it. Put that URL and the model name in your seastar.toml under [inference] — see Configuration below. That's the whole "Unsloth is the brain" step.

  3. Point Osaurus at Sea-Star. Add Sea-Star as an MCP server in Osaurus (the same command / args block you'd add to Claude Desktop). Osaurus now has your vault as memory; its agents can ask Sea-Star what you already know.

Menu labels drift between versions of both apps — the concept is what matters: Unsloth serves an OpenAI-compatible endpoint, Sea-Star consumes it, Osaurus calls Sea-Star. If either app exposes a compatible endpoint, this works unchanged.

And if you'd rather use a different harness tomorrow — Buzz, Opencode Desktop, Deepseek Harness MacOS (omarchy soon .. ) — nothing above changes. That flexibility is the point.

Zero-download shortcut (macOS 26+). Osaurus ships AFM. Run osaurus serve, then sea-star doctor: doctor probes the OpenAI-compatible endpoints and reports the runtime that is actually answering, on the port it actually took — for example Runtime: osaurus -> http://127.0.0.1:1337/v1. Where another runtime got the port first, doctor names that one instead; the port in any table is only a hint. Two legs instead of three, and nothing to download.

Install

Two ways in. Pick whichever suits you — neither one is the "advanced" one.

Terminal (available now)

# Zero-install from source, if you have uv (recommended):
uvx --from git+https://github.com/Roqett/Sea-Star sea-star serve

# Or clone and run it locally:
git clone https://github.com/Roqett/Sea-Star
cd Sea-Star
uv sync
uv run sea-star serve

pip install seastar-mcp lands with the first PyPI release. Until then, the uvx --from git+... form above is the one-liner to use.

App (built, still being refined)

A native macOS menu-bar app — no terminal at all — wraps this same engine, so nothing you set up here changes when you use it. It shows what is actually running on your machine, in two readings of the same four facts, and it never claims more than it can prove. The terminal track above stays exactly as useful as it is today.

This is 0.1.0 and it is not released yet. The repository is currently private.

Two ways to run it

The same engine, two front doors. The app is the everyday reading; the terminal does everything the app does, and is how you debug it. Every action maps both ways:

What you want to do

App

Terminal

Detect vault / runtime / model

Detects on launch

uv run sea-star doctor

Machine-readable status

Feeds the cockpit

uv run sea-star doctor --json

Start the MCP server

Start / Refresh in the panel

uv run sea-star serve

Create seastar.toml

Choose folder in-app

uv run sea-star init

Ask the vault a question

Ask your agent

uv run sea-star ask "…"

Switch vault / harness / model

The rows, in Facts or Path

SEASTAR_* env or seastar.toml

Read the logs

The Logs panel

~/Library/Logs/Sea-Star/sea-star.log

Keep the engine green

—

uv run ruff check . && uv run pytest

The app never hides a capability: anything you can click, you can also type.

Quickstart

# 1. Point Sea-Star at your Obsidian vault
sea-star init --vault "~/Documents/MyVault"

# 2. Check that it can see a local model
sea-star doctor

# 3. Run it as an MCP server (stdio)
sea-star serve

Then add it to your MCP host of choice:

{
  "mcpServers": {
    "sea-star": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Roqett/Sea-Star", "sea-star", "serve"]
    }
  }
}

Ask your host: "Ask Sea-Star what I decided about the vineyard irrigation project." Sea-Star searches your vault, reasons locally, and answers with citations to your own notes.

How you use it

Sea-Star has three ways to use it. Use any one on its own; they compose.

Way 1 — Ask your folder of notes from the terminal (the fastest way to feel it)

No host, no config file, no JSON. If a local model is running, this works:

sea-star ask "What did I decide about the vineyard irrigation project?"

Sea-Star searches your vault, reads the matching notes, asks your local model, and prints the answer with [[wikilinks]] back to the notes it used:

The Grenache bottling run is booked for the second week of February, and you should
order more corks before the McLaren Vale crush starts.

Sources: [[Cellar Notes]]

That citation is the whole point. It isn't a chatbot guessing — it's your notes answering, and you can click straight through to the source.

The 60-second smoke test

# 1. Is a vault and a model in reach?
sea-star doctor
Vault:    /Users/you/Documents/MyVault
Notes:    128
Runtime:  osaurus -> http://127.0.0.1:1337/v1
Model:    foundation
Available: foundation
Bridged MCP servers: none
Ready.

If it says Ready, you're done. If it says No local inference server answered, start your runtime (see the recipe above) or point Sea-Star at one in seastar.toml.

# 2. Ask something only your notes know
sea-star ask "Summarise what I wrote about <a real thing in your vault>"

If step 2 returns a cited answer, the vault, the model, and the agent loop are all proven. That's the test.

Way 2 — Put Sea-Star behind your agent harness (MCP server)

This is the "Osaurus gets your memory" move. Register Sea-Star as an MCP server:

{
  "mcpServers": {
    "sea-star": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Roqett/Sea-Star", "sea-star", "serve"]
    }
  }
}
  • Osaurus — Settings › Tools › Connections › add the block above. Osaurus then exposes one tool, ask_seastar, to its agents.

  • Opencode Desktop / Cursor / TRAE work — the same block, in the app's mcpServers config.

Now any agent in the host can ask "what do I already know about X?" and get your vault's answer, locally.

The full walkthrough — exact menu paths, config file locations, and the instruction to give the host's agents — lives in docs/connect.md.

Way 3 — Let Sea-Star borrow other MCP servers (MCP client)

Sea-Star can consume other MCP servers and offer their tools to your model. In seastar.toml:

[[mcp.servers]]
name = "obsidian"
command = "npx"
args = ["-y", "obsidian-mcp", "/Users/you/Documents/MyVault"]

Restart, and Sea-Star's agent loop can call obsidian__* tools alongside its own vault tools. That's how you give the agent more to work with. If a server offers dozens of tools, trim the menu with include / exclude (see Configuration) — the agent chooses better from a short list.

Which do I start with?

Start with Way 1 (sea-star ask) — it's the honest test. Then wire Way 2 into Osaurus, and add Way 3 only when you want a second tool source.

Configuration

Sea-Star is zero-config by default: it auto-detects common local runtimes and finds your Obsidian vault straight from Obsidian's own obsidian.json, so for most people sea-star serve just works with no setup at all.

If you want to pin things down, sea-star init --vault <path> writes a seastar.toml into your vault. Sea-Star also reads ./seastar.toml from the working directory and ~/.config/seastar/config.toml. Resolution order is: explicit path → SEASTAR_* environment variables → config file → autodetection → a loud failure.

# <your-vault>/seastar.toml
vault = "/Users/you/Documents/MyVault"

[inference]
# Leave base_url empty to let Sea-Star autodetect a local runtime on startup.
base_url = "http://127.0.0.1:11434/v1"   # any OpenAI-compatible endpoint
model = "qwen2.5:7b-instruct"
api_key = "seastar-local"                # local runtimes ignore this
max_steps = 8
temperature = 0.2

# Consume other MCP servers (e.g. an Obsidian MCP) as Sea-Star's own tools.
[[mcp.servers]]
name = "obsidian"
command = "npx"
args = ["-y", "obsidian-mcp", "/Users/you/Documents/MyVault"]
# Optional tool allowlist. Empty (or absent) means "every tool the server offers".
# Set it and only these tools reach the agent.
include = ["search_notes", "read_note"]
# Optional denylist. Always wins, even over `include`.
exclude = ["delete_note"]

Heads up: a seastar.toml can hold a real api_key. If your vault is under version control or cloud sync, add seastar.toml to your .gitignore so it doesn't get committed or shared.

How it works

┌──────────────────┐        MCP (stdio)         ┌─────────────────────────────┐
│  Your MCP host   │  ───────────────────────▶  │           SEA-STAR          │
│ (Claude/Cursor)  │   ask_seastar(question)    │  ┌───────────────────────┐  │
└──────────────────┘  ◀───────────────────────  │  │     agent loop        │  │
                                                 │  │  plan → tool → answer │  │
                                                 │  └──────────┬────────────┘  │
                                                 │             │               │
        ┌────────────────────────────────────────┼─────────────┼───────────────┘
        │                                        │             │
        ▼                                        ▼             ▼
┌────────────────┐                    ┌──────────────────┐  ┌──────────────────┐
│ Local model    │                    │  Obsidian vault  │  │  other MCP       │
│ (any OpenAI-   │                    │  (your notes,    │  │  servers you     │
│  compatible)   │                    │   as memory)     │  │  configure       │
└────────────────┘                    └──────────────────┘  └──────────────────┘
        ▲
        │  everything above this line runs on YOUR machine
   ─────┴───────────────────────── no cloud. no telemetry. ──────────────────────

Project layout

src/sea_star/
  cli.py           # `sea-star init | doctor | serve | ask`
  config.py        # config + runtime probing + vault autodetection
  inference.py     # the one path to a model; OpenAI-compatible
  vault.py         # the only module that touches vault files
  tools.py         # tool registry + built-in vault tools
  agent.py         # the bounded agent loop (plan -> tool -> answer)
  mcp_server.py    # exposes ask_seastar, vault_*, machine_report
  mcp_client.py    # consumes other MCP servers as its own tools
  recon.py         # one-shot reads of this machine's process/socket tables
  harnesses.py     # harness discovery + the rung each one reached
  connections.py   # records which process spawned serve (stdio attachment)
  providers.py     # what a harness *declares* it gets models from
  register.py      # the ask-once store at ~/.seastar/register.json
  agents.py        # agent roster reading
macapp/            # the native macOS menu-bar cockpit (AppKit + SwiftUI)
  SeaStar/
    App/           # the AppKit shell: status item, popover, app menu
    Views/         # cockpit, graph, panel, settings, onboarding
    Models/        # the decoded bridge report
    Services/      # engine invocation, server lifecycle, logs, updates
    Support/       # palette, strings, links
    Shaders/       # the caustic shimmer

docs/TECHNICAL.md explains the architecture, the capability ladder that decides what Sea-Star is allowed to claim, and the known debt.

Roadmap

  • Runtime-agnostic inference adapter

  • Native macOS menu-bar cockpit

  • Vault search / read / write with citations

  • Agent loop + MCP server + MCP client

  • Semantic (embedding) recall over the vault

  • .mcpb one-click Desktop Extension

  • "Which local models actually work with MCP" conformance table

  • Omarchy port — run on Arch Linux + Hyprland. The Python engine should carry over unchanged; the GUI is a rewrite (the SwiftUI cockpit becomes a Linux-native shell).

The name

There's a bar called The Sea Star at 20th n 3rd, in the Dogpatch district of San Francisco. I stone's throw from the birthplace of GPT some 30 years later. The Builder spent some time there ( with a qwirky Grey timberwolf)..a long time ago. The Sea-stars in South Australia 's Spencer Gulf are just as colourful and EVERY single one : TOTALLY unique

That's the spirit. A sea star holds on tight to its rock and doesn't let go. Those arms (or legs ) are independent, but connected : Sea-Star does the same with your notes and lets you know the big picture.

Contributing

Issues and PRs welcome — especially conformance reports ("Sea-Star worked with model X on runtime Y"). This project is designed to be maintained.

License

MIT © Roqett / Up Periscope


Built by an Oz winemaker who as a lad bought a Sinclair Spectrum 16K (but only got as far as trying to copy "blue Monday ' in BASIC )..timewarp to pulling the pin after vintage 2025, upgraded to a M4pro Mini 64GB, and relearnt to build. an Indy-dev build is a lot like a mini vintage. Learnt in public.

On the advice of the late Hunter S. Thompson — who said he hated recommending drugs, alcohol, or insanity to anyone... but admitted they'd always worked for him — we took the parts worth keeping: no dangerous drugs, only high-quality alcohol, no propellant weapons. Mostly Swift, Python, sometimes Rust, mainly Swift.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Turns your Obsidian vault into an MCP-enabled workspace with tools for reading/writing notes, managing folders, running semantic searches, and maintaining long-term memory—all while keeping data local to your vault.
      280,944 npm
      159
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that wraps the Obsidian CLI to give AI assistants direct access to read, edit, and manage notes within an Obsidian vault. It enables advanced operations such as frontmatter property management, context-aware searching, and the execution of internal Obsidian commands.
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that exposes a local Obsidian vault as persistent, searchable memory for AI agents, with hybrid retrieval, reranker, and PDF support.
      34
      638 npm
      36
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to read and search your Obsidian vault through a local MCP server, keeping everything private and local.
      Apache 2.0