# Claudeos

> ⚡ Open-source agent operating system — Claude as the kernel, every AI tool as a process, one shared memory

- **Type:** MCP server
- **Install:** `agentstack add mcp-rishavraj20-claudeos`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [RishavRaj20](https://agentstack.voostack.com/s/rishavraj20)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [RishavRaj20](https://github.com/RishavRaj20)
- **Source:** https://github.com/RishavRaj20/claudeos
- **Website:** https://rishavraj20.github.io/claudeos/

## Install

```sh
agentstack add mcp-rishavraj20-claudeos
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ⚡ ClaudeOS

**The open-source agent operating system.**

*Claude is the kernel. Every AI tool is a process. All agents share one memory.*

[](LICENSE)
[](https://nodejs.org)
[](#quick-start)
[](#contributing)

`one daemon` · `many agents` · `shared memory` · `MCP drivers`

---

## 🧠 What is this?

Every AI agent today lives in its own silo — Claude Code doesn't know what Gemini CLI did, your local Ollama model can't see what Codex wrote, and nothing remembers anything across tools.

**ClaudeOS treats your AI tools like an operating system treats processes:**

| OS concept | ClaudeOS |
|---|---|
| 🧬 **Kernel / scheduler** | A daemon that routes every task to the right backend via configurable rules |
| ⚙️ **Processes** | Existing CLI agents (Claude Code, Gemini CLI, Codex) wrapped as first-class providers — nothing reimplemented |
| 🔌 **Drivers** | Capabilities plug in as [MCP](https://modelcontextprotocol.io) servers — filesystem, browser, email, anything |
| 💾 **Shared memory** | SQLite index + markdown vault (`~/.claudeos/`) that **every agent reads and writes** — Obsidian-compatible |

### The demo that matters

```
$ claudeos run "write a one-line python script to reverse a string"
[claude-code] ✓  print(input()[::-1])          ← Claude Code wrote this

$ claudeos run "what script did the coding agent write earlier?" --provider ollama
[ollama / llama3.2] ✓  print(input()[::-1])    ← a LOCAL model recalled it
```

Two different AI backends. One memory. That's the point.

---

## 🚀 Quick start

**Requirements:** Node ≥ 23.6 (runs TypeScript natively — no build step). Optional: [Ollama](https://ollama.com) for local models, an `ANTHROPIC_API_KEY` for the direct API, Claude Code / Gemini CLI / Codex for agent processes.

```bash
git clone https://github.com/RishavRaj20/claudeos && cd claudeos
npm install
cp claudeos.config.example.json claudeos.config.json   # edit to taste
node src/cli.ts start                                  # daemon on :7777
```

Then, in another terminal:

```bash
node src/cli.ts run "explain CRDTs in 3 lines"          # auto-routed
node src/cli.ts run "summarize X" --provider ollama     # explicit + local
node src/cli.ts run "fix the bug in utils.py"           # → routes to claude-code
node src/cli.ts providers                               # who's alive?
node src/cli.ts runs                                    # task history
node src/cli.ts recall "that thing from yesterday"      # preview memory
node src/cli.ts mcp                                     # list drivers + tools
```

---

## ✨ Features

- **🎯 Smart routing** — regex rules map prompts to providers (`"fix the bug"` → Claude Code, `"summarize"` → local llama); first match wins, falls back to your default
- **🔋 Three provider types, one interface**
  - `claude` — Anthropic API (streaming, adaptive thinking, server-side refusal fallbacks)
  - `ollama` — any local model, fully offline and private
  - `cli` — wrap *any* CLI agent as a subprocess with a `{prompt}` template
- **🔌 MCP driver model** — declare servers in config (Claude Desktop format); the daemon connects at boot, discovers tools, hands them to the kernel model's agentic loop, and exposes direct calls:
  ```bash
  claudeos mcp call filesystem__read_text_file '{"path": "README.md"}'
  ```
- **🧠 Semantic memory injection** — every task automatically receives the most relevant past runs inside a `` block, whoever produced them. Ranking is by embedding similarity (local `nomic-embed-text` via Ollama — fully private, no API), with keyword+recency fallback when Ollama is off. Past runs are auto-embedded at daemon startup.
- **📓 Human-readable memory** — every run is a markdown file with frontmatter; point Obsidian at `~/.claudeos/memory/` and browse your agents' entire history
- **📥 Driver registry** — `claudeos mcp registry` lists 9 curated drivers (fetch, github, puppeteer, sqlite, ...); `claudeos mcp install ` writes the config for you
- **⏱ Async tasks + live events** — `claudeos run "..." --async` returns instantly; follow with `claudeos task ` or stream every task's lifecycle over WebSocket with `claudeos watch`
- **🔗 Multi-step pipelines** — chain providers into workflows where each step's output feeds the next via `{input}` / `{prev}` / `{stepname}` templates:
  ```
  $ claudeos pipeline build "a python function is_palindrome(s)"
  ── research   [ollama] ✓        outline from a local model
  ── implement  [claude-code] ✓   def is_palindrome(s): ...
  ── verify     [claude-code] ✓   LGTM
  ```
- **🌐 Local HTTP + WS API** — `GET /status`, `GET /mcp`, `POST /run`, `POST /tasks`, `ws://:7777/ws`; the CLI is just a client, so any UI can attach (Tauri desktop app coming in phase 2)
- **📦 Zero build step** — modern Node runs the TypeScript directly; one runtime dependency worth naming (`@anthropic-ai/sdk`) plus the MCP SDK

---

## 🏗 Architecture

```
                ┌──────────────────────────────┐
   CLI ───────▶ │   daemon  (HTTP :7777)       │ ◀─────── UI (phase 2)
                │    └─ scheduler ("kernel")   │
                └───────┬──────────┬───────────┘
                        │ routes   │ persists
          ┌─────────────┼──────────┼──────────────┐
          ▼             ▼          │              ▼
    Claude API      Ollama         │         CLI agents
    (opus 5 +       (llama,        │         (claude-code,
     MCP tools)      granite...)   │          gemini, codex)
          │                        ▼
          │                 ~/.claudeos/
          └─ MCP drivers     ├─ claudeos.db    SQLite index (searchable)
             (filesystem,    └─ memory/*.md    markdown vault (Obsidian-ready)
              browser, ...)
```

## 🖥 Desktop app (phase 2)

A native [Tauri](https://tauri.app) dashboard lives in [desktop/](desktop/) — provider and MCP driver health, a run console (auto-route, pick a provider, or run a whole pipeline), live WebSocket event feed, and run history. It's a thin client over the daemon's API, so keep `claudeos start` running.

```bash
cd desktop
npm install
npm run tauri dev     # requires Rust (rustup.rs)
```

## ⚙️ Configuration

Everything lives in `claudeos.config.json` (gitignored — copy [claudeos.config.example.json](claudeos.config.example.json)):

```jsonc
{
  "defaultProvider": "claude",
  "providers": {
    "claude":      { "type": "claude", "model": "claude-opus-5" },
    "ollama":      { "type": "ollama", "model": "llama3.2" },
    "claude-code": { "type": "cli", "command": "claude", "args": ["-p", "{prompt}"] }
  },
  "routing": [
    { "match": "\\b(code|refactor|implement|debug)\\b", "provider": "claude-code" },
    { "match": "\\b(summarize|translate|classify)\\b",  "provider": "ollama" }
  ],
  "memory":     { "inject": true, "maxEntries": 3 },
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"] }
  }
}
```

---

## 🗺 Roadmap

- [x] Daemon + CLI + provider abstraction (Claude API / Ollama / wrapped CLI agents)
- [x] Regex task routing with fallback
- [x] MCP client — capability drivers, exposed to the kernel model's agentic loop
- [x] Memory injection — cross-agent knowledge sharing on every task
- [x] `claudeos mcp install ` — one-command driver registry (9 curated MCP servers)
- [x] Async tasks + WebSocket streaming — `run --async`, `claudeos task`, `claudeos watch`
- [x] Embedding-based recall — semantic memory search via local Ollama embeddings (`nomic-embed-text`), with keyword fallback when Ollama is offline
- [x] Multi-step pipelines — research → implement → verify chains across providers, defined in config, streamed step-by-step over WebSocket
- [x] **Phase 2 (started):** Tauri desktop app (`desktop/`) — native dashboard over the daemon's HTTP/WS API: provider + MCP health, run console with auto-route/provider/pipeline selection, live event feed, run history
- [x] Phase 2 continued: live async runs in the UI (WebSocket-fed output), memory vault browser, in-app config editor, packaged `.app`/`.dmg` builds (`npm run tauri build`)
- [x] Per-token streaming — all three provider types stream deltas over WebSocket (`task.delta`); the desktop app renders output live with a cursor
- [ ] Phase 2 next: driver install from the UI, notifications, signed builds

## 🤝 Contributing

This project is young and moving fast — perfect time to jump in. Open an issue, grab a roadmap item, or add a provider for your favorite agent (it's ~60 lines: implement `available()` and `run()` in [src/providers/](src/providers/types.ts)).

Inspired by [OpenHuman](https://github.com/tinyhumansai/openhuman) — ClaudeOS bets on orchestrating the agents you already use rather than replacing them.

## 📄 License

[Apache-2.0](LICENSE)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [RishavRaj20](https://github.com/RishavRaj20)
- **Source:** [RishavRaj20/claudeos](https://github.com/RishavRaj20/claudeos)
- **License:** Apache-2.0
- **Homepage:** https://rishavraj20.github.io/claudeos/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-rishavraj20-claudeos
- Seller: https://agentstack.voostack.com/s/rishavraj20
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.