# SoloOS

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

![An AI agent plans the week: tasks, sticky notes and agenda events appear live in the UI](docs/demo.gif)

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

Needs **Node 20.19+** (or 22.12+) — `node -v` to check. Nothing else.

```bash
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

```bash
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](SECURITY.md).

## License

MIT