Self-improving, multi-agent AI coding assistant with natural language understanding, autonomous role execution, persistent memory, and governed security.
Getting Started | NLA | ARA | Skills | Web UI | AEGIS Governance | Documentation | Contributing
v10.0.0 -- Orion Agent is under active development. Core features are functional and tested (1,348 passing tests). The Autonomous Role Architecture (ARA) is complete with 37 CLI commands, 106+ API endpoints, Skills system, and a full React Web UI. We welcome feedback and bug reports via GitHub Issues.
Orion is an AI coding assistant that goes beyond simple code generation. It combines:
- Natural Language Architecture (NLA) -- Intent classification, clarification detection, and adaptive prompt engineering
- Autonomous Role Architecture (ARA) -- Background task execution with configurable roles, AEGIS-gated promotion, and daemon management
- Multi-Agent Deliberation -- Three specialized agents deliberate on every task
- Persistent Memory -- Learns and remembers across sessions, projects, and time
- AEGIS Governance -- Hardened security gate that prevents unsafe operations
- Slim Persona System -- Tiered prompt engineering (50–120 tokens) matched to intent complexity
Unlike single-shot AI tools, Orion develops understanding of your codebase, your patterns, and your preferences over time.
Orion understands what you mean, not just what you type:
| Component | Purpose |
|---|---|
| ExemplarBank | 200+ seed exemplars for intent matching with cosine similarity |
| IntentClassifier | Embedding + keyword hybrid classification (coding, question, conversational) |
| ClarificationDetector | Detects ambiguous requests and generates targeted follow-up questions |
| BriefBuilder | Converts natural language into structured TaskBrief objects |
| RequestAnalyzer | Full pipeline: classify → clarify → brief → route |
| EnglishFoundation | Linguistic pre-processing (contractions, negation, entity extraction) |
| LearningBridge | Feedback loop: user ratings → new exemplars → improved classification |
Orion can work autonomously in the background with configurable roles (28 modules, 671+ ARA tests):
| Component | Purpose |
|---|---|
| RoleProfile | YAML-based role configuration with 3-tier authority, confidence thresholds, competencies, risk tolerance |
| AegisGate | Pre-promotion security: secret scanning, write limits, scope checks, auth |
| SessionEngine | State machine with heartbeat, cost tracking, and 5 stop conditions |
| GoalEngine | LLM-powered task DAG decomposition with action validation |
| ExecutionLoop | Sequential task runner with confidence gating and checkpointing |
| TaskExecutor | File generation/editing in sandbox with context-aware LLM calls |
| PromotionManager | Sandbox branch creation, file diff, conflict detection, git-tagged promote/reject/undo |
| GoalQueue | Multi-goal FIFO queue with priority interrupts, dependencies, and reorder |
| MorningDashboard | 7-section CLI TUI: overview, approvals, tasks, files, budget, AEGIS, actions |
| PromptGuard | 12-pattern prompt injection defence with sanitization |
| AuditLog | HMAC-SHA256 hash chain, append-only JSONL, tamper detection |
| KeychainStore | OS-native credential storage (Windows/macOS) with encrypted fallback |
| UserIsolation | Multi-user OS-user scoping, per-user containers and branches |
| SkillLibrary | AgentSkills-compatible SKILL.md system with CRUD, integrity verification, and role assignment |
| SkillGuard | 22+ pattern security scanner with NFKC normalization and evasion hardening |
| Daemon + CLI | Background process with 37 commands including setup wizard |
| Notifications | Email (SMTP), webhook, and desktop toast delivery with rate limiting |
| REST + WebSocket API | 106+ endpoints for web UI integration and real-time updates |
Starter roles included: game-developer, night-coder, researcher, devops-runner, full-auto
Orion uses the AgentSkills open standard for extensible agent capabilities (8 bundled skills, 145 tests):
| Component | Purpose |
|---|---|
| SKILL.md Format | YAML frontmatter + markdown instructions, compatible with Claude Code and Windsurf |
| SkillLibrary | Central registry with CRUD, import, rescan, role resolution, integrity verification (SHA-256) |
| SkillGuard | Security scanner: 22+ patterns, NFKC normalization, prompt injection detection |
| Skill Groups | Organize skills into assignable groups with role mapping |
| 8 Bundled Skills | code-review, write-tests, write-documentation, deploy-to-staging, docker-setup, git-workflow, debug-issue, refactor-safely |
A full-featured React (Next.js) dashboard for managing ARA sessions:
| Feature | Description |
|---|---|
| Dashboard | Stats grid, status hero, activity feed, task queue, progress ring |
| Consent Gates | Approve/reject with GitHub-PR-style diff viewer (file tree + unified diffs) |
| New Session | Start work sessions from the UI with role selection and goal input |
| Job Roles | Create, edit, delete roles with scope/auth/description |
| Skills | Browse, create, delete skills; assign/unassign to roles; security scan |
| Chat | WebSocket chat sidebar connected to Orion's full NLA pipeline |
| Settings | ARA settings, API keys, workspace configuration |
| Notifications | Real-time notification badge with unread count |
Every request flows through three specialized agents:
| Agent | Role | Responsibility |
|---|---|---|
| Builder | Creator | Generates code solutions using your chosen LLM |
| Reviewer | Critic | Analyzes Builder's output for correctness, quality, and edge cases |
| Governor | Authority | Makes final decisions using memory, quality gates, and governance rules |
This "Table of Three" approach catches errors that single-agent systems miss.
Orion remembers -- not just within a conversation, but across your entire development history:
| Tier | Storage | Duration | Purpose |
|---|---|---|---|
| Session | RAM | Current session | Immediate context and conversation state |
| Project | JSON | Days to weeks | Workspace patterns, decisions, and preferences |
| Institutional | SQLite | Months to years | Cross-project wisdom and proven patterns |
AEGIS (Autonomous Execution Governance and Integrity System) is Orion's security core:
- Workspace Confinement -- Cannot operate outside your project directory
- Mode Enforcement -- Graduated permissions (safe -> pro -> project)
- Action Validation -- Every file operation is checked before execution
- External Access Control -- Network operations require explicit approval
- Shell Injection Prevention -- Blocks dangerous command patterns
Orion learns from every interaction:
- You rate responses (1-5 stars)
- Good patterns (4-5) are stored as success templates
- Bad patterns (1-2) are stored as anti-patterns to avoid
- Evolution tracking monitors improvement over time
| Feature | Orion |
|---|---|
| Natural language understanding | NLA: intent classification, clarification, adaptive prompts |
| Autonomous background tasks | ARA: roles, daemon, checkpoints, drift detection, recovery |
| Web UI | Full React dashboard with consent gates, diff viewer, session management |
| Skills system | AgentSkills-compatible SKILL.md, 8 bundled, SkillGuard security |
| Multi-agent deliberation | 3 specialized agents (Builder, Reviewer, Governor) |
| Persistent memory | 3 tiers (session, project, institutional) |
| Learns from feedback | Evolves based on your approval/rejection patterns |
| Governance/safety gate | AEGIS -- hardened security invariants |
| Edit validation | Pre-write confidence scoring + auto-recovery |
| LLM providers | 11 providers including local Ollama |
| Self-hosted | Runs entirely on your machine |
| Open source | AGPL-3.0 |
# Basic installation
pip install orion-agent
# With all integrations
pip install orion-agent[all]orion> /workspace /path/to/your/project
Workspace set: /path/to/your/project
> /mode pro
Mode set: pro (read + write with approval)
> Explain what the main function does
[Orion analyzes your code and provides explanation]
> Add error handling to the database connection
[Orion proposes changes, waits for your approval]
# Set your API key
/settings key openai sk-your-key-here
# Choose your model
/settings model gpt-4o
# Or use local Ollama (free)
/settings provider ollama
/settings model llama3AEGIS is what makes Orion safe for production use. It's a pure-function security gate with six invariants:
- Workspace Confinement -- All file operations must stay within the workspace
- Mode Enforcement -- Actions must be permitted by the current mode
- Action Scope -- Only approved operation types are allowed
- Risk Validation -- High-risk operations require human confirmation
- Command Execution -- Shell commands are validated for safety
- External Access -- Network operations follow read/write approval rules
AEGIS cannot be bypassed, disabled, or reconfigured by AI agents.
Complete AEGIS documentation ->
Orion connects to 79+ external services:
| Category | Count | Examples |
|---|---|---|
| LLM Providers | 11 | OpenAI, Anthropic, Google, Ollama, Groq, Mistral, Cohere |
| Voice TTS | 8 | ElevenLabs, OpenAI TTS, Edge-TTS, Piper |
| Voice STT | 6 | Whisper, Vosk, Deepgram, AssemblyAI |
| Image Generation | 8 | DALL-E 3, Stability AI, Midjourney, Replicate |
| Messaging | 15 | Slack, Discord, Telegram, Teams, WhatsApp |
| Dev Tools | 10+ | GitHub, GitLab, Jira, Linear, Notion |
Complete integration catalog ->
| Document | Description |
|---|---|
| Getting Started | Quick start guide for new users |
| Installation | Detailed installation instructions |
| User Guide | Complete user documentation |
| CLI Reference | All commands and options |
| API Reference | REST and WebSocket API |
| Architecture | System design deep-dive |
| AEGIS | Governance system documentation |
| Memory System | Three-tier memory explained |
| Security | Security model and practices |
| Deployment | Production deployment guide |
| FAQ | Frequently asked questions |
┌─────────────────────────────────────────────────────────────────┐
│ USER INTERFACES │
│ ┌─────────┐ ┌───────────┐ ┌───────────┐ ┌──────────────┐ │
│ │ CLI │ │ Web UI │ │ WebSocket │ │ ARA Daemon │ │
│ │ (REPL) │ │ (Next.js) │ │ (realtime)│ │ (background) │ │
│ └────┬────┘ └─────┬─────┘ └─────┬─────┘ └──────┬───────┘ │
└───────┼─────────────┼──────────────┼───────────────┼───────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ FastAPI Server (10 route modules, 106+ endpoints) │
│ REST API │ WebSocket │ CORS │ Auth │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐
│ NLA Pipeline │ │ ARA Engine │ │ Skills System │
│ ExemplarBank │ │ Sessions │ │ SkillLibrary │
│ IntentClassify │ │ Daemon │ │ SkillGuard (22+) │
│ BriefBuilder │ │ TaskExecutor │ │ 8 bundled skills │
│ FastPath/ToT │ │ Promotion │ │ SKILL.md format │
└────────┬────────┘ │ GoalQueue │ └─────────────────────┘
│ │ Dashboard │
▼ └────────┬────────┘
┌─────────────────────────────┼───────────────────────────────────┐
│ AEGIS GOVERNANCE GATE │
│ Workspace Confinement │ Secret Scanning │ Write Limits │
│ Mode Enforcement │ Risk Validation │ Auth (PIN/TOTP) │
│ PromptGuard │ AuditLog (HMAC) │ KeychainStore │
└───────────────────────────┬─────────────────────────────────────┘
│
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ LLM Layer │ │ Memory │ │ Integrations │
│ (11 provs) │ │ (3-tier) │ │ 79 connectors │
│ + Ollama │ │ Institutional │ │ LLM, voice, │
│ │ │ Teaching │ │ image, msg, dev │
└─────────────┘ └─────────────────┘ └─────────────────┘
Complete architecture documentation ->
src/orion/
├── cli/ # Interactive REPL and commands
├── core/
│ ├── agents/ # Builder, Reviewer, Governor, Table of Three, FastPath
│ ├── understanding/ # NLA: intent, clarification, brief, analyzer, english
│ ├── memory/ # Three-tier memory engine + institutional memory + teaching
│ ├── learning/ # Evolution engine, feedback, patterns, learning bridge
│ ├── editing/ # Edit validator, format selector, git safety
│ ├── context/ # Repo map (tree-sitter), Python AST, code quality
│ ├── governance/ # AEGIS safety gate, execution authority
│ ├── llm/ # Provider routing, model config, slim persona prompts
│ └── production/ # Health probes, metrics, shutdown, logging
├── ara/ # Autonomous Role Architecture (28 modules)
│ ├── role_profile # YAML role configuration + 3-tier authority + 5 starter templates
│ ├── auth # PIN + TOTP authentication
│ ├── aegis_gate # Pre-promotion security gate
│ ├── session # State machine with heartbeat + cost tracking
│ ├── goal_engine # LLM-powered task DAG decomposition
│ ├── execution # Sequential task runner with checkpointing
│ ├── task_executor # Context-aware file generation/editing in sandbox
│ ├── daemon # Background process + IPC control
│ ├── daemon_launcher# Session launcher from pending state
│ ├── cli_commands # 37 commands: work/status/review/promote/skills/roles/setup/...
│ ├── promotion # Sandbox → workspace merge with git tags + undo
│ ├── dashboard # Morning Dashboard TUI (7 sections) + pending review detection
│ ├── goal_queue # Multi-goal FIFO queue with priority interrupts
│ ├── prompt_guard # Prompt injection defence (12 patterns)
│ ├── audit_log # HMAC-SHA256 hash chain tamper-proof log
│ ├── keychain # OS-native credential storage
│ ├── user_isolation # Multi-user OS-user scoping
│ ├── notifications # Email, webhook, desktop providers
│ ├── feedback_store # Outcome recording + confidence calibration
│ ├── skill # Skill + SkillGroup dataclasses, SKILL.md parser, validation
│ ├── skill_guard # SkillGuard security scanner (22+ patterns, NFKC hardening)
│ ├── skill_library # Central skill registry with CRUD, import, integrity verification
│ ├── ollama_provider# Local LLM integration for task execution
│ ├── checkpoint # Git-based session snapshots
│ ├── drift_monitor # External workspace change detection
│ ├── recovery # Failure handling + retry policy
│ └── lifecycle # Session cleanup + health reporting
├── api/ # FastAPI REST + WebSocket server (10 route modules, 106+ endpoints)
│ └── routes/ # ara, auth, chat, gdpr, health, models, platforms, settings, tools, training
├── integrations/ # 79 connectors (LLM, voice, image, messaging, ...)
├── security/ # Encrypted store, Docker sandbox, secret scanner
└── plugins/ # Plugin lifecycle API (8 hooks)
orion-web/ # React (Next.js) Web UI
├── src/app/
│ ├── page.tsx # Home page
│ ├── ara/page.tsx # ARA Dashboard (consent gates, diff viewer, sessions, roles, skills)
│ ├── chat/page.tsx # Chat interface
│ ├── aegis/page.tsx # AEGIS governance info
│ └── settings/page.tsx # Full settings panel
└── src/components/ # ChatInterface, SettingsPanel, AegisApprovalModal
# Backend
git clone https://github.com/phoenixlink-cloud/orion-agent.git
cd orion-agent
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
pytest # 1,348 tests
# API Server
uvicorn orion.api.server:app --port 8001
# Web UI
cd orion-web
npm install
npm run dev # http://localhost:3000We welcome contributions! Please read our guidelines first:
- CONTRIBUTING.md -- How to contribute
- CLA.md -- Contributor License Agreement (required)
- COPYRIGHT.md -- Ownership and IP terms
- CODE_OF_CONDUCT.md -- Community guidelines
Note: All contributions require a signed CLA before code can be merged.
Copyright (C) 2025 Phoenix Link (Pty) Ltd. All Rights Reserved.
Orion Agent is dual-licensed:
| License | Use Case | Requirements |
|---|---|---|
| AGPL-3.0 | Open source, personal use, AGPL-compatible projects | Copyleft -- share modifications under AGPL-3.0 |
| Commercial | Proprietary software, SaaS, enterprise | Contact Phoenix Link for licensing |
Using Orion in a commercial product or SaaS? Contact info@phoenixlink.co.za
Orion is free and open-source. If it has benefited you and you'd like to see continued development, please consider making a voluntary financial contribution.
| Tier | Amount | Description | Link |
|---|---|---|---|
| One-Time Support | R400 | Supports ongoing development, documentation, and testing of Orion Agent and governed AI tooling. |  |
| Development Sponsor | R1,500 | Supports feature development, performance improvements, integrations, and security hardening. |  |
| Infrastructure Sponsor | R8,000 | Helps fund infrastructure, CI/CD pipelines, security audits, and long-term sustainability. |  |
This is a voluntary contribution, not a purchase. See FUNDING.md for full details.
Other ways to help: Star the repo | Report bugs | Improve docs | Contribute code
| Purpose | Contact |
|---|---|
| General inquiries, licensing, partnerships | info@phoenixlink.co.za |
| Technical support | support@phoenixlink.co.za |
Website: phoenixlink.co.za
Built by Phoenix Link (Pty) Ltd
Governed AI for the real world.