License: MIT Python 3.10+ FastAPI 3 Agents 16 Skills v0.2.0 Status: Stable dev.to article

# Agentic OS (agentic-os) ๐Ÿง  โ€” Multi-Agent Orchestration Platform A locally-hosted operating system for AI agents โ€” an open-source GitHub repository โ€” that coordinates **opencode**, **Hermes Agent**, and **Gemini CLI** into a unified dashboard with persistent memory, cron scheduling, skill execution, cost analytics, and disaster recovery. > **Why Agentic OS?** Most agent tools work in isolation โ€” a terminal for coding, a separate chat for research, another for memory. Agentic OS is the **control plane** that unifies them: one dashboard, one memory layer, one scheduler, one skill hub. Three agents, infinite capabilities. --- ## โœจ Features | Category | Features | |----------|----------| | **๐Ÿค– 3-Agent Engine** | opencode (code/DevOps), Hermes (memory/scheduling), Gemini (research/analysis) with intelligent routing | | **๐Ÿงฉ 16+ Skills** | Executable skill packs with eval scoring, learnings, and score history per run | | **๐Ÿง  Persistent Memory** | SQLite FTS5 + `brain/` folder โ€” shared context read by all agents at session start | | **โฑ Cron Scheduler** | APScheduler-powered jobs โ€” heartbeat, memory consolidation, daily standup, DevOps audit | | **๐Ÿ’ฐ Cost Analytics** | Track spending per provider, model, agent. Free-tier alerts prevent surprise bills | | **๐Ÿ“‹ Audit Trail** | Every action logged โ€” chat, skill runs, settings changes, backups | | **๐Ÿ’พ One-Click Backup** | Full tar.gz snapshot of all configs, skills, brain, agents, prompts | | **๐Ÿ“ Prompt Library** | 10 reusable templates โ€” code review, system audit, project plan, brainstorm, and more | | **๐Ÿ“ Standards System** | Discover and inject coding conventions across your project | | **๐Ÿ”Œ Plugin Registry** | Marketplace-style plugin management (extensible via skills) | | **๐ŸŽจ Dark/Light Theme** | GitHub-style dark mode + clean light theme, toggle from sidebar | | **โšก Zero API Costs** | Built for free tiers โ€” Gemini Flash, OpenRouter free models, local opencode | | **๐Ÿ“‹ Kanban Board** | Visual task management โ€” drag-and-drop columns, priority/status filtering, block/unblock, detail view | | **๐ŸŽฏ Goals** | Project targets with progress tracking, auto-syncs to `brain/active-projects.md` | | **๐Ÿ““ Journal** | Daily markdown entries stored as `brain/journal/YYYY-MM-DD.md` with full-text search | | **โค๏ธ Agent Health** | Real-time monitoring of opencode, Hermes, and Gemini CLI availability | | **๐Ÿงญ Smart Router** | Keyword-based task routing with confidence scoring โ€” suggests best agent for any task | | **๐Ÿ“Š Learning Analytics** | Skill evaluation scores, performance trends, and historical charts | | **๐ŸŽฌ Session Replay** | Browse and replay past opencode sessions from the dashboard | --- ## ๐Ÿ— Architecture ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ AGENTIC OS DASHBOARD โ”‚ โ”‚ FastAPI + Tailwind SPA โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€-โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” | โ”‚ โ”‚ opencode โ”‚ โ”‚ Hermes โ”‚ โ”‚ Gemini CLI โ”‚ โ”‚ โ”‚ โ”‚ (Code/DevOps)โ”‚ โ”‚ (Memory/Schedโ”‚ โ”‚ (Research/Analy) โ”‚ โ”‚ โ”‚ โ”‚ File Ops) โ”‚ โ”‚ /Channels) โ”‚ โ”‚ โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€-โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ | โ”‚ โ”‚ โ”‚ โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ โ”‚ โ”‚ 7 CORE LAYERS (Stacked) โ”‚ โ”‚ โ”‚ โ”‚ Layer 7: Identity / Persona / Constitution โ”‚ โ”‚ โ”‚ โ”‚ Layer 6: Self-Evolution + Capability Manager โ”‚ โ”‚ โ”‚ โ”‚ Layer 5: Scheduler + Awareness + Health Guardian โ”‚ โ”‚ โ”‚ โ”‚ Layer 4: Memory Graph + Memory Consolidation โ”‚ โ”‚ โ”‚ โ”‚ Layer 3: Skills Hub + Eval + Learnings Loop โ”‚ โ”‚ โ”‚ โ”‚ Layer 2: Business Brain + Context Folders โ”‚ โ”‚ โ”‚ โ”‚ Layer 1: Agent Router + Standards + Profiles โ”‚ โ”‚ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ``` ### Agent Responsibilities | Agent | Role | Default Model | Provider | Cost | |-------|------|---------------|----------|------| | **opencode** | Code generation, DevOps, file operations | deepseek-v4-flash-free | opencode-zen | **$0** | | **Hermes Agent** | Persistent memory, scheduling, messaging | Owl Alpha (1M ctx) | OpenRouter | **$0** | | **Gemini CLI** | Web research, multi-modal analysis | gemini-2.5-flash | Google OAuth | **$0** | ### Routing Rules - **Code/DevOps task?** โ†’ opencode - **Memory/Channel/Schedule?** โ†’ Hermes Agent - **Research/Analysis?** โ†’ Gemini CLI - **Complex multi-step?** โ†’ Chain: Gemini researches โ†’ opencode implements โ†’ Hermes monitors/schedules --- ## ๐Ÿš€ Quick Start ### Linux/macOS ```bash git clone https://github.com/zumayaaustin-creator/agentic-os.git cd agentic-os chmod +x install.sh && ./install.sh ./start.sh # Open http://127.0.0.1:8080 ``` ### Windows PowerShell ```powershell git clone https://github.com/zumayaaustin-creator/agentic-os.git cd agentic-os .\install.ps1 .\start.ps1 # Open http://127.0.0.1:8080 ``` --- ## ๐Ÿ“‹ Prerequisites ### Linux/macOS | Tool | Required? | Install | |------|-----------|---------| | Python 3.10+ | โœ… Required | Install from your package manager or [python.org](https://www.python.org/downloads/). Verify with `python3 --version`. | | Node.js 18+ | โš  For opencode and Gemini CLI | `curl -fsSL https://deb.nodesource.com/setup_20.x \| sudo bash - && sudo apt install -y nodejs` | | opencode | โš  For code tasks | `npm install -g @opencode/cli` | | Hermes Agent | โš  For memory/scheduling | Follow the upstream Hermes Agent documentation. If native Windows support is unavailable, use WSL for Hermes. | | Gemini CLI | โš  For Google AI | `npm install -g @google/gemini-cli` | > โš  = Optional โ€” the dashboard starts and core pages work without all agent CLIs installed. Agent-specific chat, routing, health, and skill execution features will show offline or warning status until the relevant CLI is installed and authenticated. ### Windows | Tool | Required? | Install | Verify / Next Step | |------|-----------|---------|--------------------| | Python 3.10+ | โœ… Required | Install from [python.org/downloads/windows](https://www.python.org/downloads/windows/) and enable **โ€œAdd python.exe to PATHโ€** during setup. | `python --version` | | Node.js 18+ | โš  For opencode and Gemini CLI | Install from [nodejs.org](https://nodejs.org/). | `node --version` and `npm --version` | | opencode | โš  For code tasks | `npm install -g @opencode/cli` | Confirm the CLI is available in a new terminal session. | | Gemini CLI | โš  For Google AI | `npm install -g @google/gemini-cli` | Run `gemini auth login` and complete OAuth in the browser. | | Hermes Agent | โš  For memory/scheduling | Windows support must be verified separately if the upstream installer remains Bash-only. | Check the upstream Hermes Agent install docs before relying on native Windows support. | > โš  = Optional โ€” the dashboard works with any subset of installed agents. The PowerShell launchers resolve Python in this order: `py -3.10`, `py -3`, then `python`. For manual commands, prefer `python -m pip install -r requirements.txt` and `python server.py --port 8080` so the same interpreter runs both dependency installation and the server. > **PowerShell execution policy:** if you use PowerShell scripts, allow local scripts for your user with `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`, or run a single installer invocation with `powershell -ExecutionPolicy Bypass -File .\install.ps1`. --- ## ๐Ÿ”ง Configuration ### Hermes (OpenRouter) ```bash # Set your OpenRouter API key echo 'OPENROUTER_API_KEY=sk-or-v1-your-key-here' > ~/.hermes/.env ``` ### Gemini CLI (Google OAuth) ```bash gemini auth login # Complete OAuth in browser โ€” tokens saved to ~/.gemini/oauth_creds.json ``` ### Dashboard Settings Edit `data/settings.json`: ```json { "dashboard": { "port": 8080 }, "theme": "dark", "agents": { "opencode": true, "hermes": true, "gemini": true } } ``` --- ## ๐Ÿ“ Project Structure ``` agentic-os/ โ”œโ”€โ”€ server.py # FastAPI backend (REST API) โ”œโ”€โ”€ requirements.txt # Python dependencies โ”œโ”€โ”€ install.sh / install.ps1 # Platform installers โ”œโ”€โ”€ start.sh # Launch dashboard โ”œโ”€โ”€ backup.sh / restore.sh # Unix disaster recovery โ”œโ”€โ”€ backup.ps1 / restore.ps1 # Windows disaster recovery โ”‚ โ”œโ”€โ”€ dashboard/ # Web frontend (SPA) โ”‚ โ”œโ”€โ”€ index.html # Entry point + sidebar โ”‚ โ”œโ”€โ”€ app.js # SPA router + theme/sidebar toggle โ”‚ โ”œโ”€โ”€ api.js # API client (all endpoints) โ”‚ โ”œโ”€โ”€ styles.css # Full dark/light theme CSS โ”‚ โ”œโ”€โ”€ utils.js # Shared utilities โ”‚ โ””โ”€โ”€ pages/ # 20 page modules (13 original + 7 v0.2.0) โ”‚ โ”œโ”€โ”€ dashboard.js # Overview with stats โ”‚ โ”œโ”€โ”€ skills.js # Skill grid/list/detail โ”‚ โ”œโ”€โ”€ memory.js # Brain file editor โ”‚ โ”œโ”€โ”€ chat.js # Multi-agent chat โ”‚ โ”œโ”€โ”€ scheduler.js # Cron job manager โ”‚ โ”œโ”€โ”€ audit.js # Activity trail โ”‚ โ”œโ”€โ”€ cost.js # Cost analytics charts โ”‚ โ”œโ”€โ”€ plugins.js # Plugin marketplace โ”‚ โ”œโ”€โ”€ backups.js # Backup/restore UI โ”‚ โ”œโ”€โ”€ prompts.js # Template library โ”‚ โ”œโ”€โ”€ standards.js # Code conventions โ”‚ โ”œโ”€โ”€ settings.js # Config editor โ”‚ โ”œโ”€โ”€ setup-wizard.js # Guided setup โ”‚ โ”œโ”€โ”€ kanban.js # โ–ธ Kanban Board (v0.2.0) โ”‚ โ”œโ”€โ”€ goals.js # โ–ธ Goals (v0.2.0) โ”‚ โ”œโ”€โ”€ journal.js # โ–ธ Journal (v0.2.0) โ”‚ โ”œโ”€โ”€ agent-health.js # โ–ธ Agent Health (v0.2.0) โ”‚ โ”œโ”€โ”€ smart-router.js # โ–ธ Smart Router (v0.2.0) โ”‚ โ”œโ”€โ”€ learning-analytics.js # โ–ธ Learning Analytics (v0.2.0) โ”‚ โ””โ”€โ”€ session-replay.js # โ–ธ Session Replay (v0.2.0) โ”‚ โ”œโ”€โ”€ brain/ # Shared context (all agents read) โ”‚ โ”œโ”€โ”€ business-brain.md # Current project context โ”‚ โ”œโ”€โ”€ memory.md # Accumulated knowledge โ”‚ โ”œโ”€โ”€ recent-decisions.md โ”‚ โ”œโ”€โ”€ active-projects.md โ”‚ โ”œโ”€โ”€ identity.md โ”‚ โ”œโ”€โ”€ constitution.md โ”‚ โ””โ”€โ”€ journal/ # Daily markdown entries (YYYY-MM-DD.md) โ”‚ โ”œโ”€โ”€ skills/ # 16 executable skills โ”‚ โ”œโ”€โ”€ devops-audit/ # GCP/CloudMart infra audit โ”‚ โ”œโ”€โ”€ heartbeat/ # 5-min health check โ”‚ โ”œโ”€โ”€ content-draft/ # Blog/newsletter writing โ”‚ โ”œโ”€โ”€ code-review/ # PR review checklist โ”‚ โ”œโ”€โ”€ research-synthesis/ # Gemini research aggregator โ”‚ โ”œโ”€โ”€ daily-standup/ # Morning briefing โ”‚ โ”œโ”€โ”€ meeting-minutes/ # Notes processor โ”‚ โ”œโ”€โ”€ project-planner/ # Step-by-step plans โ”‚ โ”œโ”€โ”€ brainstorming/ # Socratic design โ”‚ โ”œโ”€โ”€ systematic-debug/ # 4-phase root cause โ”‚ โ”œโ”€โ”€ memory-consolidation/ # Weekly synthesis โ”‚ โ”œโ”€โ”€ backup-skill/ # Snapshot creator โ”‚ โ”œโ”€โ”€ cost-analytics/ # Multi-provider cost โ”‚ โ”œโ”€โ”€ tdd-cycle/ # Red-green-refactor โ”‚ โ”œโ”€โ”€ goal-planner/ # Goal โ†’ steps โ”‚ โ””โ”€โ”€ _template/ # Starter template โ”‚ โ”œโ”€โ”€ agents/ # Per-agent configs โ”œโ”€โ”€ scheduler/jobs/ # Cron job definitions โ”œโ”€โ”€ registry/ # Plugin marketplace โ”œโ”€โ”€ standards/ # Discover/inject conventions โ”œโ”€โ”€ prompts/ # 10 reusable templates โ”œโ”€โ”€ data/ # Runtime data (agent-routes.json tracked; settings/cost/chat gitignored) โ”œโ”€โ”€ audit/ # Activity log (gitignored) โ””โ”€โ”€ backups/ # Snapshots (gitignored) ``` --- ## ๐Ÿ†• What's New in v0.2.0 | Feature | Description | |---------|-------------| | **๐Ÿ“‹ Kanban Board** | Visual task management with 6 columns (triage โ†’ todo โ†’ ready โ†’ in_progress โ†’ blocked โ†’ done), drag-and-drop, priority labels, filtering, and detail modals with complete/block/unblock actions | | **๐ŸŽฏ Goals** | Create and track project targets with progress bars, categories, and target dates. Auto-syncs to `brain/active-projects.md` for agent awareness | | **๐Ÿ““ Journal** | Daily markdown journal entries stored as `brain/journal/YYYY-MM-DD.md`. Full-text search, day streak tracking, word count | | **โค๏ธ Agent Health** | Real-time dashboard showing online/offline status for all 3 agents (opencode, Hermes, Gemini CLI). Auto-refresh every 5 seconds | | **๐Ÿงญ Smart Router** | Keyword-based routing engine โ€” type a task description and get an AI-suggested agent with confidence score. Manual override available | | **๐Ÿ“Š Learning Analytics** | Skill evaluation scores, performance trends, and per-skill detail breakdowns with mini bar charts | | **๐ŸŽฌ Session Replay** | Browse and replay past opencode sessions directly from the dashboard. View message content and timestamps | ### UI Modernization - **Glass morphism cards** with subtle backdrop blur - **Glow borders** and gradient accents on interactive elements - **Skeleton loaders** with shimmer animation for async content - **Empty states** with icons and contextual messages - **All CSS additions are zero-breaking** โ€” existing 13 pages and 28 endpoints unchanged --- ## ๐ŸŽฎ Usage ### AI Chat Select an agent from the sidebar โ†’ type your message โ†’ get response. | Agent | Best for | Example | |-------|----------|---------| | **opencode** | "Check system status", "Deploy to GKE" | Code + terminal automation | | **Hermes** | "What did I work on recently?", "Schedule a daily backup" | Memory recall, scheduling | | **Gemini** | "Research latest AI agent trends", "Analyze this image" | Web research, multi-modal | ### Skills Browse 16 skills from Skills Hub โ†’ click Run โ†’ monitor eval scores over time. ### Scheduler Create cron jobs: heartbeat (5 min), memory consolidation (weekly), daily standup, DevOps audit. ### Cost Analytics Track spending per provider/model/agent. Free-tier alerts warn when nearing limits. ### Disaster Recovery Create and restore local snapshots of `brain/`, `skills/`, `agents/`, `data/`, `registry/`, `standards/`, and `prompts/`. User-specific `data/settings.json` is excluded from backups. **Unix/macOS/Linux** ```bash ./backup.sh ./restore.sh ``` **Windows PowerShell** ```powershell .\backup.ps1 .\restore.ps1 ``` Run the restore command without a backup file to list available backups. ### Kanban Board (v0.2.0) Drag tasks across columns, filter by priority/category, click to view details. Block tasks when blocked, mark complete when done. ### Goals (v0.2.0) Create goals with categories and target dates. Progress tracked via +25% increments. Completed goals auto-sync to brain context. ### Journal (v0.2.0) Write daily entries with markdown support. Auto-saves after 2 seconds. Search across all entries from the dashboard. ### Smart Router (v0.2.0) Describe a task in plain English โ€” the router analyzes keywords and suggests the best agent. Route manually or let AI decide. ### Agent Health (v0.2.0) Monitor online status of all 3 agents in real time with 5-second auto-refresh. Health checks are filesystem-based (no subprocess calls). ### Learning Analytics (v0.2.0) View evaluation scores for all 16 skills. Trends chart shows score progression over time. Top skills ranked by performance. ### Session Replay (v0.2.0) Browse opencode session logs by date and size. Click "Replay" to view all messages in a chat-like interface. --- ## ๐Ÿ“Š Comparison: Agentic OS vs Claude Agent OS (Julian Goldie) | Feature | Claude Agent OS (Video) | Agentic OS (This Project) | |---------|------------------------|---------------------------| | **Core Agents** | Claude + OpenClaw + Hermes | opencode + Hermes + Gemini CLI | | **Cost** | $20/mo (Claude subscription) | **$0 โ€” all free tiers** | | **Stack** | Next.js + Tailwind | FastAPI + vanilla JS SPA | | **Architecture** | 4 layers | **7 layers** | | **Skills System** | Plugin marketplace (2,000+ from Hermes) | 16 curated skills + eval scoring + learnings | | **Memory** | Obsidian vault (external) | Built-in brain/ + SQLite FTS5 | | **Scheduler** | Not shown | APScheduler cron jobs | | **Cost Tracking** | Not shown | Built-in per-provider analytics | | **Backup/Restore** | Not shown | One-click Unix tar.gz and Windows zip snapshots | | **Audit Trail** | Not shown | Full activity log | | **Standards System** | Not shown | Discover/inject conventions | | **Client Timeout** | Not shown | 200s AbortController | | **Kanban Board** | Yes | **Yes โ€” built-in** with drag-and-drop, priority, block/unblock, filters | | **Open Source** | No (tutorial only) | **MIT License** | --- ## ๐Ÿงช Tested On - **OS**: Linux (Ubuntu 22.04+), macOS; Windows dashboard setup supported via PowerShell, with Hermes best used through WSL if native support is unavailable - **Python**: 3.10, 3.11, 3.12 - **Browsers**: Chrome, Firefox, Edge - **Agents**: opencode v0.8+, Hermes Agent v1.0+, Gemini CLI v1.0+ --- ## ๐Ÿค Contributing 1. Fork the repo 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add amazing feature'`) 4. Push (`git push origin feature/amazing-feature`) 5. Open a Pull Request See `data/agent-routes.json` for routing rules and `skills/_template/` for creating new skills. --- ## ๐Ÿ“„ License MIT License โ€” free to use, modify, and distribute. ---

Agentic OS โ€” Built with โค๏ธ by zumayaaustin-creator

๐Ÿ“– Read the dev.to article ยท Report Bug ยท Discussions ยท GitHub