Deterministic AI Agent Orchestration Framework
AgenticOS is a portable, auditable AI agent operating layer for running AI-assisted workflows safely. It provides deterministic routing, structured logging, and multi-provider support for security-conscious environments.
# Clone and install
git clone https://github.com/Pharns/AgenticOS.git
cd AgenticOS
./install.sh
# Verify installation
./scripts/aos doctor
# Run your first command
aos q "What is a buffer overflow?"- Unified CLI (
aos) — Single command for all operations - Multi-Provider Support — Claude, Codex, and Gemini
- Auto-Routing — Keyword and AI-powered profile selection
- Audit-Grade Logging — JSON logs for every execution
- Health Validation — 40+ checks with auto-fix capability
- Project Isolation — Per-project configurations
- Memory Persistence — Session continuity across invocations
# Quick questions (Gemini)
aos q "Explain SQL injection"
# Development tasks (Codex)
aos d "Fix the authentication bug"
# GRC/Compliance writing (Claude)
aos g "Draft a password policy for SOC 2"
# Auto-route based on keywords
aos auto "Write a security policy" # → grc
aos auto "Fix the login error" # → dev
# Work on a specific project
aos -p myproject d "Add input validation"AgenticOS/
├── scripts/
│ ├── aos # Unified CLI (start here)
│ ├── router # Routing engine
│ ├── agent # Execution engine
│ ├── doctor # Health validation
│ └── memory # Memory management
├── .agents/
│ ├── agents.yaml # Profile definitions
│ ├── workflows.yaml # Workflow definitions
│ ├── router_auto_rules.json
│ ├── prompts/ # System prompts
│ ├── logs/ # Execution logs
│ └── memory/ # Persistent memory
├── docs/ # Documentation
└── install.sh # Installer
| Document | Description |
|---|---|
| User Guide | Complete reference |
| Quick Start | Get started in 5 minutes |
| Core Commands | Command reference |
| Auto-Routing | Routing system details |
| Design Philosophy | Why AgenticOS works this way |
- Python 3.10+
- At least one AI provider CLI:
claude(Anthropic)codex(OpenAI)gemini(Google)
- No auto-execution — Generated code is never auto-executed
- User-triggered only — Only explicit commands run
- No secrets in repo — Credentials in
.env(gitignored) - Full audit trail — Every action logged with context
- Deterministic — Same inputs produce same behavior
AgenticOS chooses:
- Explicit contracts over intelligence
- Ordered rules over scoring
- Determinism over convenience
- Boring correctness over novelty
If behavior is unclear, AgenticOS will fail or explain — never guess.
MIT License. See LICENSE for details.