yourOS

Your personal AI operating system. A local web app that gives you a workspace with AI chat, background agents, task management, and more. Built on ostk.

yourOS adds a persistent workspace on top of Claude Code. Your tasks, agents, and chat history carry across sessions, and your connected tools work together in one conversation instead of in separate tabs. Claude Code powers the AI. yourOS gives it memory and context.

yourOS runs entirely on your computer. You open it in your browser at localhost, no account or login needed. All your data lives in ~/.youros/ and never leaves your machine unless you connect an integration like Gmail or Slack, in which case those requests go directly from your machine to the provider. yourOS is not a cloud service.

Icons and fonts are loaded from Google Fonts (fonts.googleapis.com, fonts.gstatic.com). If your network blocks those hosts, the UI will still work but icons will render as text labels. See Troubleshooting below.

You need Python 3.9 or newer, Node 18 or newer, and git. Installing yourOS does not require Homebrew. yourOS runs on macOS and Linux.

git clone https://github.com/torimeyer/youros.git ~/youros
cd ~/youros
./install.sh

Python and Node come pre-installed on recent macOS, or you can download them from python.org and nodejs.org.

When you spawn Claude Code Task-tool subagents, yourOS can register them on its Agents page so you have one place to see all your in-flight AI work. By default this only happens inside the yourOS repo itself. If you want it elsewhere, you have three options — pick any or none:

All three point at the same hook file at ~/.youros/hooks/register-agent.sh, which install.sh stages automatically.

First install the basic tools with your system package manager. Pick the line for your Linux.

Ubuntu or Debian:

sudo apt-get update
sudo apt-get install -y git curl ca-certificates python3 python3-venv python3-pip nodejs npm

Fedora:

sudo dnf install -y git curl ca-certificates python3 python3-pip nodejs npm

Arch:

sudo pacman -Sy --noconfirm git curl ca-certificates python python-pip nodejs npm

Then clone and run the installer:

git clone https://github.com/torimeyer/youros.git ~/youros
cd ~/youros
./install.sh

If your distribution ships an older Node, install a newer one with nvm first:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 20

For contributors who already have a GitHub SSH key set up: git clone git@github.com:torimeyer/youros.git ~/youros

cd ~/youros
./update.sh

Your settings, chats, tasks, and labels live in ~/.youros/ (separate from the repo) and are never touched by updates. You can also verify this by running ls -la ~/.youros/ before and after.

./uninstall.sh

Stops running yourOS processes and removes what install.sh put in the repo: api/.venv, app/node_modules, app/dist, .mcp.json, and the myos / myos-update shell aliases. Keeps ~/.youros/ (your tasks, chats, settings), ostk, and the localhost cert trust — so re-running ./install.sh brings you right back.

To truly reset to a clean slate (useful when testing a fresh install):

./uninstall.sh --purge

Also removes ~/.youros/ (DESTROYS ALL USER DATA), stops the ostk daemon, removes ~/.local/bin/ostk and ~/.cache/ostk, and removes the localhost cert from the macOS login Keychain. Prompts before each destructive step — add --yes to skip prompts.

The repo directory is never deleted. Remove it yourself with rm -rf <path> when you're done.

./start.sh

Or from anywhere after install:

myos

Your browser will open to https://localhost:8000.

For development (Vite hot reload on app/ source), use the two-terminal setup instead:

scripts/dev-backend.sh      # backend on https://127.0.0.1:8000
scripts/dev-frontend.sh     # Vite on https://localhost:3010

./stop.sh

./start.sh and scripts/dev-backend.sh both run a watchdog that restarts uvicorn on crash, so Ctrl+C alone can leave yourOS running in the background. stop.sh kills the watchdog first, then uvicorn on port 8000 and Vite on port 3010.

If stop.sh isn't available, the manual equivalent is:

pkill -9 -f backend_watchdog.sh
lsof -ti tcp:8000 | xargs kill 2>/dev/null
lsof -ti tcp:3010 | xargs kill 2>/dev/null

The setup wizard walks you through:

1. Enter your name
2. Name your OS (e.g. "MadisonOS", "AlexOS")
3. Pick a theme
4. Connect your AI provider (Anthropic or Google Gemini)
5. Turn a task you have been putting off into a plan

You can explore the dashboard, tasks, and ideas without an API key. Chat and agents need one.

• Dashboard - home screen with smart focus card, day summary, session diff, quick launch, and labels
• Chat - talk to Claude or Gemini with tool access. Multiple chat tabs. Resizable panel. GIF search, emoji reactions, image paste.
• Tasks - create and manage work items with priorities. Labels for organization. Dependencies (blocks/needs). Task briefings. Health check for duplicates and missing info. Attributed commits.
• Activity - chronological feed of everything that happened, filtered by category (tasks, agents, ideas, system)
• Agents - spawn background AI agents. Permission requests (approve/deny). Delegation view for handing off tasks. Agent templates.
• Ideas - capture thoughts quickly. AI-powered clustering. Convert ideas into tasks.
• Files - browse your workspace with in-app file preview
• Timeline - visual view of tasks over time
• Cost Tracking - budget and spending by model and agent
• Settings - theme, accent color, default LLM, Google sign-in, MCP servers (ostk-managed and manual), feature toggles, export/import config
• What's New - release notes with badge for unseen updates
• Search - Cmd+K searches across all tasks and ideas by topic, plus quick commands

yourOS covers the full ostk surface area:

yourOS runs on your laptop. Your data stays there. For a full breakdown of what is stored where, what leaves the machine and when, and how to revoke a connected tool's access: PRIVACY.md.

If you have gcloud auth application-default login set up, Gemini calls automatically route through Vertex AI. No API key required.

To use Gemini through your Google account:

1. Create a project at console.cloud.google.com
2. Go to APIs and Services, then Credentials
3. Create an OAuth 2.0 Client ID (Web application)
4. Add redirect URI: http://localhost:8000/api/auth/google/callback
5. Copy client ID and secret into api/.env (see api/.env.example)

Connect Jira and Confluence in Settings > Atlassian. yourOS uses OAuth, no password needed. Full setup instructions, permission details, and troubleshooting: docs/integrations/atlassian.md.

If you connected before May 2026: Disconnect and reconnect once. Atlassian deprecated the old permission names used in earlier versions of yourOS, and newer API endpoints reject tokens that only carry them. The reconnect takes about 30 seconds and is a one-time step.

yourOS ships a lightweight git pre-commit hook that runs pytest, vitest, and tsc -b only on the files you staged. It catches broken tests at the commit that introduces them, instead of letting them pile up until release day. A typical commit stays under 30 seconds because only the relevant tests run.

Install once:

scripts/install-git-hooks.sh

Check status or uninstall:

scripts/install-git-hooks.sh --status
scripts/install-git-hooks.sh --uninstall

Bypass for a single commit (use sparingly):

git commit --no-verify

If you already have a local pre-commit hook, the installer preserves it as .git/hooks/pre-commit.local and runs it first, so nothing you had before is lost.

Run scripts/youros-doctor.sh for a guided diagnostic with fix commands. See docs/recovery.md for the full recovery guide (check health, save your setup, restore it).

Icons render as text labels ("home", "checklist", "drag_indicator", etc.) The Material Symbols font failed to load. Usually a stale browser cache after an update — hard refresh with Cmd+Shift+R (Mac) or Ctrl+Shift+R (Linux). If it persists, rebuild the frontend: cd app && npm run build, then restart. If your browser's DevTools console shows Content-Security-Policy errors for fonts.googleapis.com, pull the latest — this was fixed by allowing Google Fonts in the CSP.

localhost:8000 still responds after you close the terminal start.sh runs a watchdog that respawns uvicorn on crash, so the app can keep running after you Ctrl+C. Use ./stop.sh to shut down cleanly.

Port 8000 is already in use Another process (often a leftover yourOS from a previous session) is holding it. Run ./stop.sh. If that doesn't clear it, lsof -nP -iTCP:8000 -sTCP:LISTEN shows what's there.

401 on /api/calendar/events in the browser console Expected until you finish Google Sign-In. See "Google Sign-In Setup" above.

Corporate network or VPN blocks Google Fonts Icons show as text because fonts.googleapis.com / fonts.gstatic.com are unreachable. The app is otherwise fully functional. If you need icons offline, open an issue — bundling the font locally is possible but not currently shipped.

Open roadmap.html in your browser to see the three-year plan.

The product is called yourOS on every screen you see. Under the hood, engineering keeps the old myos name in identifiers that would break or lose data if changed:

• ~/.youros/ — the user data directory (renaming moves no data and risks orphaning 200MB+ of history)
• MYOS_* environment variables — 36 of them; renaming requires coordinated operator changes
• youros-backend / youros-frontend PM2 process names and PID files
• com.youros.ostk-watchdog launchd plist (installed at ~/Library/LaunchAgents/)
• myos. localStorage key prefixes — renaming clears browser state
• /api/health returns {"service":"myos-api"} — e2e smoke tests grep this string
• BACKEND_SESSION_PREFIX = "myos-api-" — names ostk session directories

These stay myos until there is a migration path for each. The split is intentional: user-facing = yourOS, engineering internals = myos.