SoloOS

A full-stack dashboard where the AI agent is a first-class user.

Tasks, floating notes, and a weekly agenda — every feature exists twice: a human UI, and an MCP tool your AI agent can call. The GIF above is real: npm run demo replays it on your machine — a scripted MCP client plays the agent and plans the week while the UI updates live.

🚧 Early days. Full docs and the story are coming with v0.1.

Quickstart

git clone https://github.com/outoftheweed/soloos && cd soloos
npm install
npm run dev

That's it — no database to set up. SoloOS boots an embedded Postgres (PGlite) persisted to ./data. Open http://localhost:3000.

Optional: npm run seed for demo data, .env to plug a real Postgres (Neon, Supabase…) via DATABASE_URL.

Connect your agent

npm run mcp:config

Prints ready-to-paste config for Claude Code / Claude Desktop. The MCP endpoint lives at http://localhost:3000/mcp.

The 13 tools

Domain	Tools
Tasks	list_tasks · create_task · update_task · complete_task · delete_task
Floating notes	list_floating_notes · create_floating_note · update_floating_note · archive_floating_note
Agenda	get_agenda_week · add_agenda_event · remove_agenda_event · set_agenda_goals

How it fits together

Two first-class users, one server, one database:

        you                       your agent
         │                            │
   ┌─────▼──────┐              ┌──────▼──────┐
   │  React UI  │              │  MCP tools  │
   │ (polls 2s) │              │  (13, HTTP) │
   └─────┬──────┘              └──────┬──────┘
         │ tRPC                       │ /mcp
   ┌─────▼────────────────────────────▼─────┐
   │       Express — one port (3000)        │
   └───────────────────┬────────────────────┘
                       │ Drizzle
              ┌────────▼─────────┐
              │  PGlite (./data) │
              │  or DATABASE_URL │
              └──────────────────┘

The UI polls every 2 seconds — that's why the agent's writes appear on screen while they happen. No websockets, no magic, easy to fork.

Stack

React 19 · Vite · tRPC · Drizzle · PGlite/Postgres · Express · MCP (streamable HTTP)

Security

An agent that writes to your dashboard deserves a straight answer: localhost-only by default, write tools gated behind MCP_SECRET, archives instead of deletes where it matters. The details — including the honest limits — are in SECURITY.md.

License

MIT