SeaStar
by Roqett
README.md
<div align="center">
<img src="assets/sea-star.png" alt="Sea-Star" width="280">
# ⭐ 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.
[](CHANGELOG.md)
[](LICENSE)
[](https://www.python.org/)
</div>
***
> — 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.
<!--
SCREENSHOT PLACEHOLDERS
The repo has no app screenshots yet, and no claim is made here that has not been
measured. When they are captured, drop them in below with alt text that says what
the image actually shows. Capture guide:
./script/build_and_run.sh run # build + launch the cockpit
screencapture -x -C /tmp/shot.png # -C includes the cursor
click the menu-bar star to open the popover
Three worth having, in this order:
1. Graph mode — the starfield, Sea-Star at the centre, lit wires (~626x786)
2. Facts mode — the four rows + Working now (~340 wide)
3. Path mode — the same facts as connected cards
-->
***
## 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.
***
## 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](docs/README.md)** if you're unsure.
| I want to… | Read |
| ------------------------------------------------------------ | -------------------------------------------------- |
| Understand what this is, in plain English (no jargon) | [docs/start-here.md](docs/start-here.md) |
| Run it day to day — by clicking or by typing | [docs/use-the-app.md](docs/use-the-app.md) |
| Connect Sea-Star to Osaurus / Claude Desktop / Cursor / TRAE | [docs/connect.md](docs/connect.md) |
| See every command, tool, setting and runtime | [docs/reference.md](docs/reference.md) |
| Know how it actually works — architecture, the capability ladder, privacy | [docs/TECHNICAL.md](docs/TECHNICAL.md) |
| Fix something that's broken | [docs/troubleshooting.md](docs/troubleshooting.md) |
| Know the rules the code must keep | [docs/foundation.md](docs/foundation.md) |
The landing page is a single static file — [`site/index.html`](site/index.html), open
it in a browser. The palette, the type and the voice rules live in
**[docs/brand.md](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)
```bash
# 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
```bash
# 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:
```json
{
"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:
```bash
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
```bash
# 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`.
```bash
# 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:
```json
{
"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](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`:
```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.
```toml
# <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](docs/TECHNICAL.md)** explains the architecture, the capability
ladder that decides what Sea-Star is allowed to claim, and the known debt.
## Roadmap
- [x] Runtime-agnostic inference adapter
- [x] Native macOS menu-bar cockpit
- [x] Vault search / read / write with citations
- [x] 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.*