Zeus

# ⚡ Zeus — your one-stop tool to control your computer **Zeus is a local AI agent orchestrator with a real UI.** Install once, run `zeus start`, and you get a fast, terminal-inspired web app — on your laptop *and* your phone — where AI agents can actually *do things on your machine*: read and write files, run commands, drive a real browser, search the web, manage tasks, run scheduled jobs, and orchestrate teams of sub-agents. One tool for everything you need to control your computer. Everything lives in `~/.zeus`. No cloud account, no telemetry, no lock-in — your agents, skills, memory, and workspaces are plain human-editable files on your own disk. ```bash ./install.sh # one-time setup zeus start # launch the server + open the web UI ``` --- <img width="1798" height="940" alt="Screenshot 2026-06-24 at 20 29 52" src="https://github.com/user-attachments/assets/d03897d8-2460-4ec6-be28-8c2f162efa8c" /> --- ## Why Zeus is different Most agent projects are a **library or a terminal loop**. Zeus is a **complete application**: - **It has a real, beautiful UI** — a vanilla-JS, no-build web app with a command palette, theming, live streaming, and inline HTML/SVG previews. Not a CLI you squint at. - **It runs on your phone.** The UI is an installable PWA with a mobile-first nav, and `zeus start --tailscale` puts it on your private tailnet so you can drive your computer's agents from anywhere — securely, never exposed to the public internet. - **Agents control the whole machine, with a UI for it.** Files, shell, a dedicated automated **Chromium** the agent drives by vision, web search, an embedded terminal, a file explorer, a code editor, git — all in one place. - **It's an orchestrator, not just an agent.** Sub-agent delegation (with per-sub-agent stop), recurring **workflows**, scheduled jobs, MCP servers, to-dos, dashboards, widgets, timers, and a layered, self-curating **memory** system. - **Bring any model.** Anthropic, OpenAI, Groq, Google Gemini, OpenRouter, AWS Bedrock — *or* fully local models via the built-in **BYO Model** app (a self-contained Ollama that installs entirely inside `~/.zeus`). - **Self-contained integrations.** Need private web search or a managed browser? Zeus installs SearXNG, Chromium, and Ollama *inside* `~/.zeus` — nothing touches your system. --- ## Features ### The `zeus` command `zeus start` · `stop` · `status` · `restart` · `logs -f` · `open` · `reset`. Runs a detached local server (uvicorn on `127.0.0.1:8756`) and opens the UI. `zeus reset` wipes `~/.zeus` and starts factory-fresh (asks first). ### Works on web **and** mobile - One-URL web UI at `http://127.0.0.1:8756`, served `no-store` so edits show up on reload. - **Installable PWA** with an offline page, app-launcher nav, and a touch-friendly mobile layout (centered popups, big tap targets, no horizontal scroll). - **Tailscale built in:** `zeus start --tailscale` serves the app on your tailnet (`https://<machine>.ts.net`) so your phone — logged into the same tailnet — can install and use Zeus from anywhere. Private by default. ### Bring your own model - **Cloud:** Anthropic (API key), OpenAI, Groq, Google Gemini, OpenRouter, AWS Bedrock — paste a key and go. One model switcher, with per-model type badges (multimodal / text / tools) and editable context windows. - **Local — the BYO Model app:** browse the full Ollama library, favorite the models you like, pull any model (with live progress + a stop button), and run them fully on-device. The Ollama binary *and* weights live entirely under `~/.zeus/ollama` on a private port — your system stays untouched. Vision models (e.g. `qwen3-vl`, `llava`) can see image attachments. ### Agents, sub-agents & skills - Build specialized **agents** with their own prompt, tools, model, and permission mode. - Agents **delegate to sub-agents** (configurable depth) and you can **stop a single sub-agent** from the live dock while the parent keeps working. - A **skills** library the agent loads on demand; agents can even author new skills and sub-agents. ### A computer the agent can actually use - Built-in tools: **Read / Write / Edit / Bash / Glob / Grep**, web search + fetch, and a vision-driven **browser** (a dedicated Chromium the agent clicks/types/scrolls by looking at screenshots). - A real embedded **terminal** (PTY + xterm.js), **file explorer**, **code editor**, and **git** panel. - **Permission modes** — `default` (approve risky actions), `plan` (read-only), `acceptEdits`, `autopilot` — plus lifecycle **hooks** for PreToolUse / PostToolUse / Stop / UserPromptSubmit. ### Automate everything - **Workflows:** multi-step agent pipelines on a **cron schedule**, on demand, or after every chat. - **To-dos & stickies**, **timers & alarms**, **world clocks**, live **widgets & dashboards**, desktop **push notifications**, and a built-in **location** tool. - **MCP servers** (stdio + HTTP/SSE) merge their tools into your agents. ### Memory that stays sharp - Layered context — **Soul / Steering / User / Project** — loaded into every turn and prompt-cached so it's nearly free. - **Model-driven curation:** a model periodically de-duplicates and prunes memory itself, keeping a small, high-signal core. Project memory follows your working directory; volatile state (which tools/models are connected) is never stored. - **Smart context management:** dynamic per-model context windows, prompt caching, accurate token accounting, and in-turn compaction that clears stale tool outputs so long agentic runs don't blow past the window. ### Self-contained integrations SearXNG (private metasearch), a managed Chromium, and Ollama — each installs and runs **entirely inside `~/.zeus`**, controllable from Settings → Integrations. Nothing is installed system-wide. ### And more A live performance monitor, themeable UI, a ⌘K command palette, per-tab working directories, multiple workspaces, image/PDF attachments, and spec-driven development tooling. --- ## Quick start ```bash ./install.sh # creates backend/.venv, installs deps, symlinks `zeus` onto PATH zeus start # start + open the UI at http://127.0.0.1:8756 zeus start --tailscale # also serve on your tailnet (use it from your phone) ``` Then open the UI, connect a provider (or install a local model in **BYO Model**), and start chatting. Backend changes need `zeus restart`; the frontend is no-build — just reload. **Requirements:** Python 3.11+ and macOS/Linux. State lives in `~/.zeus` (override with `ZEUS_HOME`). --- ## Contributing Zeus is early, vibe-coded, and very much open to help. See **[CONTRIBUTING.md](CONTRIBUTING.md)** to get started, browse the **[open issues](https://github.com/shreyasks094/Zeus/issues)** (look for `good first issue` and `help wanted`), and please be kind — see the **[Code of Conduct](CODE_OF_CONDUCT.md)**. Found a security problem? See **[SECURITY.md](SECURITY.md)** (report privately, not in a public issue). The most useful things right now: **test a model provider** ([#2](https://github.com/shreyasks094/Zeus/issues/2)) and **test on your platform** — Linux, Windows/WSL, newer Python, iPhone. --- ## Acknowledgements Huge thanks and inspiration to **PewDiePie's Odysseus**, **openclaw**, and **hermes** — projects that showed what personal, local-first AI agents can be. Zeus took the spark and ran in its own direction: a full app you can hold in your hand. And enormous thanks to the open tools Zeus stands on: - **[Ollama](https://ollama.com)** — local models, installed and run entirely inside `~/.zeus`. - **[SearXNG](https://github.com/searxng/searxng)** — private metasearch, self-hosted in `~/.zeus`. - **[Chromium](https://www.chromium.org)** — the dedicated browser the agent drives by vision. - **[FastAPI](https://fastapi.tiangolo.com)** & **[xterm.js](https://xtermjs.org)** — the backend and the embedded terminal. - And every model provider Zeus connects to — **Anthropic, OpenAI, Groq, Google Gemini, OpenRouter, AWS Bedrock**. Zeus was **vibe coded with passion** — built for the joy of it. ⚡