# 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/modimihir07/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/modimihir07/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 # 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.
### 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 tar.gz 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.
---
