One AI that maximizes signal, eliminates noise, and finds the optimal path — across code, work, and life. Elixir/OTP + Rust TUI + Desktop Command Center. Runs locally. Open-source.
Every agent framework processes every message the same way. "Build me a REST API with auth" gets the same pipeline as "What time is it?" Same model, same context window, same latency, same cost. No understanding of what the message actually is before throwing compute at it.
We built OSA to fix this. It's the AI layer of MIOSA — an operating system for running your entire business. One agent handling everything: code, operations, communication, analysis, orchestration. The foundation is Signal Theory: every input is classified by intent, domain, and complexity before it touches the reasoning engine. The right model gets the right task. Multi-step problems get decomposed into parallel sub-agents. The agent remembers what worked and what didn't across sessions.
~154,000 lines of Elixir/OTP + Rust + SvelteKit. ~2,000 tests. Runs locally. Your data stays yours.
Codebase Breakdown
──────────────────────────────────────────
Elixir/OTP (lib/) 77,000 lines Core agent, orchestration, providers,
channels, tools, swarm, sandbox
Desktop (desktop/) 27,000 lines Command Center — Tauri + SvelteKit,
chat, agents, terminal, settings
Rust TUI (priv/rust/tui/) 20,000 lines Terminal interface, SSE client,
auth, rendering
Tests (test/) 29,000 lines ~2,000 tests across all modules
Go utilities (priv/go/) 900 lines Tokenizer, git helper, sysmon
Config 500 lines Runtime, dev, test, prod
──────────────────────────────────────────
Total ~154,000 lines
Before the agent reasons about anything, it understands what you're asking. Every input is classified into a 5-tuple that determines how it gets processed — which model handles it, what strategy to use, how much compute to spend:
S = (Mode, Genre, Type, Format, Weight)
Mode: What to do — BUILD, EXECUTE, ANALYZE, MAINTAIN, ASSIST
Genre: Speech act — DIRECT, INFORM, COMMIT, DECIDE, EXPRESS
Type: Domain — question, request, issue, scheduling, summary, report
Format: Container — message, command, document, notification
Weight: Complexity — 0.0 (trivial) → 1.0 (critical, multi-step)
"Help me build a rocket" → BUILD mode, high weight → routes to the most capable model with orchestration. "What time is it?" → ASSIST mode, low weight → fast model, direct answer, no overhead. The classifier is LLM-primary with a deterministic fallback when the LLM is unavailable. Results are cached in ETS (SHA256 key, 10-minute TTL).
The classification drives everything downstream:
Weight 0.0–0.35 → Utility tier (Haiku, GPT-3.5, 8B models) — fast, cheap
Weight 0.35–0.65 → Specialist tier (Sonnet, GPT-4o-mini, 70B) — balanced
Weight 0.65–1.0 → Elite tier (Opus, GPT-4o, Pro models) — full reasoning
A simple lookup doesn't need Opus. A complex refactor doesn't belong on Haiku. The system matches compute to complexity automatically — no manual model switching.
Complex tasks get decomposed into parallel sub-agents:
User: "Build me a REST API with auth, tests, and docs"
OSA Orchestrator:
├── Research agent — analyzing codebase
├── Builder agent — writing implementation
├── Tester agent — writing tests
└── Writer agent — writing documentation
Synthesis: 4 agents completed — files created, tests passing, docs written.
The orchestrator analyzes complexity via LLM, decomposes into dependency-aware waves, spawns sub-agents with role-specific prompts, tracks real-time progress via event bus, and synthesizes results.
# Four collaboration patterns
:parallel # All agents work simultaneously
:pipeline # Agent output feeds into next agent
:debate # Agents argue, consensus emerges
:review_loop # Build → review → fix → re-reviewMailbox-based inter-agent messaging. Dependency-aware wave execution. PACT framework (Planning → Action → Coordination → Testing) with quality gates at every phase.
Three sandbox backends for isolated code execution:
| Backend | Isolation | Use Case |
|---|---|---|
| Docker | Full OS — read-only root, CAP_DROP ALL, network isolation | Production, untrusted code |
| Wasm | wasmtime with fuel limits and restricted filesystem | Lightweight, fast startup |
| Sprites.dev | Firecracker microVMs with checkpoint/restore | Cloud sandboxes, persistent state |
Per-agent sandbox allocation via the Registry. Warm container pool for Docker. All backends implement a common Sandbox.Behaviour.
Every provider maps to three compute tiers — elite, specialist, utility:
anthropic: claude-opus-4-6 → claude-sonnet-4-6 → claude-haiku-4-5
openai: gpt-4o → gpt-4o-mini → gpt-3.5-turbo
google: gemini-2.5-pro → gemini-2.0-flash → gemini-2.0-flash-lite
groq: llama-3.3-70b → llama-3.1-70b → llama-3.1-8b-instant
ollama: [auto-detected by model size — largest→elite, smallest→utility]
...and 13 more providers
Shared OpenAICompat base for 14 providers. Native implementations for Anthropic, Google, Cohere, Replicate, and Ollama. Automatic fallback chain: if primary fails, next provider picks up. Ollama tiers are detected dynamically at boot.
export OSA_DEFAULT_PROVIDER=groq
export GROQ_API_KEY=gsk_...
# Done. OSA now uses Groq for all inference.Five modules that understand how people communicate:
| Module | What It Does |
|---|---|
| Communication Profiler | Learns each contact's style — response time, formality, topic preferences |
| Communication Coach | Scores outbound message quality before sending — clarity, tone, completeness |
| Conversation Tracker | Tracks depth from casual chat to deep strategic discussion (4 levels) |
| Proactive Monitor | Watches for silence, drift, and engagement drops — triggers alerts |
| Contact Detector | Identifies who's talking from message metadata |
Token-budgeted context assembly:
CRITICAL (unlimited): System identity, active tools
HIGH (40%): Recent conversation turns, current task state
MEDIUM (30%): Relevant memories (keyword-searched, not full dump)
LOW (remaining): Workflow context, environmental info
Three-zone compression: HOT (last 10 msgs, full fidelity) → WARM (progressive compression) → COLD (key facts only, importance-weighted).
Four-layer memory:
- Session — JSONL per-session conversation log
- Long-term — MEMORY.md across all sessions
- Episodic — ETS inverted index for keyword → session mapping
- Vault — Structured memory with 8 typed categories, fact extraction, scored observations, session lifecycle, and deterministic prompt injection (see below)
The Vault is a structured memory system that goes beyond flat files:
~/.osa/vault/
├── facts/ ├── decisions/ ├── lessons/
├── preferences/ ├── commitments/ ├── relationships/
├── projects/ ├── observations/ ├── handoffs/
└── .vault/
├── facts.jsonl # Temporal fact store (never deletes, versioned)
├── checkpoints/ # Mid-session save points
└── dirty/ # Dirty-death detection flags
| Feature | How It Works |
|---|---|
| Typed categories | 8 memory types (fact, decision, lesson, preference, commitment, relationship, project, observation) with YAML frontmatter |
| Fact extraction | ~15 regex patterns extract structured facts from free text — no LLM needed |
| Scored observations | Observations get a relevance score (0.0–1.0) that decays exponentially over time |
| Session lifecycle | Wake (detect dirty deaths) → Checkpoint (periodic save) → Sleep (create handoff doc) |
| Context profiles | 4 profiles (default/planning/incident/handoff) control what vault content enters the prompt |
| Prompt injection | Keyword matching against vault files injects relevant decisions/preferences into system prompt |
6 tools: vault_remember, vault_context, vault_wake, vault_sleep, vault_checkpoint, vault_inject
Priority-ordered hooks fire at lifecycle events:
security_check (p10) — Block dangerous tool calls
context_optimizer (p12) — Track tool load, warn on heavy usage
mcp_cache (p15) — Cache MCP schemas in persistent_term
budget_tracker (p25) — Token budget enforcement
quality_check (p30) — Output quality scoring
episodic_memory (p60) — Write JSONL episodes
vault_checkpoint (p80) — Auto-checkpoint vault every 10 tool calls
metrics_dashboard (p80) — JSONL metrics + periodic summary
...
Each hook returns {:ok, payload}, {:block, reason}, or :skip. Blocked = pipeline stops.
| Channel | Features |
|---|---|
| CLI | Built-in terminal interface |
| HTTP/REST | SDK API surface on port 8089 |
| Telegram | Webhook + polling, group support |
| Discord | Bot gateway, slash commands |
| Slack | Events API, slash commands, blocks |
| Business API, webhook verification | |
| Signal | Signal CLI bridge, group support |
| Matrix | Federation-ready, E2EE support |
| IMAP polling + SMTP sending | |
| OneBot protocol | |
| DingTalk | Robot webhook, outgoing messages |
| Feishu/Lark | Event subscriptions, card messages |
Each channel adapter handles webhook signature verification, rate limiting, and message format translation.
brew tap miosa-osa/tap
brew install osagent
osagentcurl -fsSL https://raw.githubusercontent.com/Miosa-osa/OSA/main/install.sh | sh
osagentThe installer detects OS/arch, auto-installs Rust and Elixir if missing, builds both components, and installs osa and osagent to ~/.local/bin/.
git clone https://github.com/Miosa-osa/OSA.git
cd OSA
mix setup # deps + database + compile
bin/osa # start talkingRequires Elixir 1.17+, Erlang/OTP 27+, Rust/Cargo (for TUI).
docker compose up -dThe compose file includes OSA + Ollama with healthchecks and automatic dependency ordering. The production container runs as a non-root osa user with minimal privileges.
| Command | What it does |
|---|---|
osa |
Recommended. Backend + Rust TUI in one command. Works from any directory. |
osa --dev |
Dev mode (profile isolation, port 19001) |
osa setup |
Run the setup wizard (provider, API keys) |
mix osa.chat |
Backend + built-in Elixir CLI (no TUI) |
mix osa.serve |
Backend only (for custom clients or desktop app) |
osagent |
TUI binary only (connects to running backend) |
cd desktop && npm run tauri:dev |
Command Center — desktop GUI (connects to running backend) |
First time? Just run osa. It auto-detects first run and launches the setup wizard.
# Local AI (default — free, private, no API key)
osa setup # select Ollama
# Cloud — pick any of 18 providers
osa setup # select Anthropic, OpenAI, Groq, DeepSeek, etc.
# Or set env vars directly (in ~/.osa/.env)
OSA_DEFAULT_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...OSA exposes a REST API on port 8089:
# Health check
curl http://localhost:8089/health
# Classify a message (Signal Theory 5-tuple)
curl -X POST http://localhost:8089/api/v1/classify \
-H "Content-Type: application/json" \
-d '{"message": "What is our Q3 revenue trend?"}'
# Run the full agent loop
curl -X POST http://localhost:8089/api/v1/orchestrate \
-H "Content-Type: application/json" \
-d '{"input": "Analyze our sales pipeline", "session_id": "my-session"}'
# Launch an agent swarm
curl -X POST http://localhost:8089/api/v1/swarm/launch \
-H "Content-Type: application/json" \
-d '{"task": "Review codebase for security issues", "pattern": "review_loop"}'
# List available models
curl http://localhost:8089/api/v1/models
# Stream events (SSE)
curl http://localhost:8089/api/v1/stream/my-sessionJWT authentication supported for production — set OSA_SHARED_SECRET and OSA_REQUIRE_AUTH=true. The SSE stream and HTTP client auto-refresh expired tokens transparently.
The Command Center is OSA's native desktop interface — a full visual control plane for everything the agent can do. Built with Tauri 2 + SvelteKit 2 + Svelte 5, it runs as a lightweight native app on macOS, Linux, and Windows.
| Section | What It Does |
|---|---|
| Dashboard | System health, KPIs, active agents, recent activity — all real-time from backend |
| Chat | Full conversation with markdown, code highlighting, SSE streaming, model selector, collapsible history |
| Agents | Browse the roster, see agent tiers/roles, dispatch agents to tasks |
| Models | View and switch LLM providers and models across all 3 tiers |
| Terminal | Embedded xterm.js terminal — run shell commands without leaving the app |
| Tasks | Task management and tracking |
| Memory | Browse and manage agent memory, vault entries, knowledge |
| Activity | Real-time event stream — see what the agent is doing as it happens |
| Connectors | Configure chat channels, MCP servers, webhooks |
| Usage | Token usage, budget tracking, cost breakdowns |
| Settings | Provider keys, preferences, profiles |
# Prerequisites: Node.js 18+, Rust/Cargo, system dependencies for Tauri
# See: https://v2.tauri.app/start/prerequisites/
cd desktop
npm install
# Development (hot-reload)
npm run tauri:dev
# Production build
npm run tauri:build
# Binary output: desktop/src-tauri/target/release/osa-desktopThe Command Center connects to the OSA backend on port 8089. Start the backend first (bin/osa or mix osa.serve), then launch the desktop app.
┌───────────────────────────────────────────────────────────┐
│ 12 Channels │
│ CLI │ HTTP │ Telegram │ Discord │ Slack │ WhatsApp │ ... │
└───────────────────────┬───────────────────────────────────┘
│
┌───────────────────────▼───────────────────────────────────┐
│ Hook Pipeline (priority-ordered middleware) │
│ security_check → context_optimizer → mcp_cache → ... │
└───────────────────────┬───────────────────────────────────┘
│
┌───────────────────────▼───────────────────────────────────┐
│ Signal Classifier (LLM-primary) │
│ S = (Mode, Genre, Type, Format, Weight) │
│ ETS cache │ Deterministic fallback │
└───────────────────────┬───────────────────────────────────┘
│
┌───────────────────────▼───────────────────────────────────┐
│ Two-Tier Noise Filter │
│ Tier 1: <1ms regex │ Tier 2: weight thresholds │
└───────────────────────┬───────────────────────────────────┘
│ signals only
┌───────────────────────▼───────────────────────────────────┐
│ Events.Bus (:osa_event_router) │
│ goldrush-compiled Erlang bytecode │
└───┬──────────┬──────────┬──────────┬─────────────────────┘
│ │ │ │
┌───▼───┐ ┌───▼─────┐ ┌──▼────┐ ┌──▼───────────┐
│ Agent │ │Orchest- │ │ Swarm │ │Intelligence │
│ Loop │ │rator │ │ +PACT │ │ (5 mods) │
│ │ │ │ │ │ │ │
│ Tier │ │ Roster │ │ Intel │ │ Profiler │
│ Route │ │ 31+17 │ │ Votes │ │ Coach │
└───┬───┘ └───┬─────┘ └──┬────┘ │ Tracker │
│ │ │ │ Monitor │
│ │ │ │ Detector │
│ │ │ └──────────────┘
┌─▼─────────▼──────────▼─────────────────────────────────┐
│ Shared Infrastructure │
│ Context Builder (token-budgeted, 4-tier priority) │
│ Compactor (3-zone sliding window, importance-weighted) │
│ Memory (3-store + inverted index + episodic JSONL) │
│ Vault (8-category structured memory + fact extraction)│
│ Cortex (context aggregation delegate) │
│ Scheduler (cron + heartbeat) │
│ Sandbox (Docker + Wasm + Sprites.dev) │
└────────────────────────────────────────────────────────┘
│ │ │ │
┌────▼────┐ ┌───▼─────┐ ┌──▼────┐ ┌───▼──────┐
│18 LLM │ │Skills │ │Memory │ │ OS │
│Providers│ │Registry │ │(JSONL)│ │Templates │
│ 3 tiers │ │34 tools │ │ │ │ │
└─────────┘ │91 cmds │ └───────┘ └──────────┘
└─────────┘
Every component is supervised across 4 subsystem supervisors. If any part crashes, OTP restarts just that component — no downtime, no data loss, no manual intervention. The top-level uses rest_for_one so a crash in Infrastructure tears down everything above it.
OptimalSystemAgent.Supervisor (rest_for_one)
│
├── Platform.Repo (PostgreSQL — conditional, multi-tenant)
│
├── Supervisors.Infrastructure (rest_for_one)
│ ├── SessionRegistry Process registry for agent sessions
│ ├── Events.TaskSupervisor Supervised async work
│ ├── PubSub Phoenix.PubSub core messaging
│ ├── Events.Bus goldrush-compiled event routing
│ ├── Events.DLQ Dead letter queue
│ ├── Bridge.PubSub Event fan-out bridge
│ ├── Store.Repo SQLite3 persistent storage
│ ├── Telemetry.Metrics Event-driven metrics collection
│ ├── MiosaLLM.HealthChecker Provider health + circuit breaker
│ ├── Providers.Registry 18 LLM providers, 3-tier routing
│ ├── Tools.Registry Tool dispatcher (goldrush-compiled)
│ ├── Machines Composable skill sets
│ ├── Commands 91 built-in + custom slash commands
│ ├── OS.Registry Template discovery + connection
│ └── MCP.Supervisor DynamicSupervisor for MCP servers
│
├── Supervisors.Sessions (one_for_one)
│ ├── Channels.Supervisor DynamicSupervisor — 12 channel adapters
│ ├── EventStreamRegistry Per-session SSE event streams
│ └── SessionSupervisor DynamicSupervisor — Agent Loop processes
│
├── Supervisors.AgentServices (one_for_one)
│ ├── Agent.Memory 3-store architecture + episodic JSONL
│ ├── Agent.HeartbeatState Session heartbeat tracking
│ ├── Agent.Workflow Workflow state machine
│ ├── MiosaBudget.Budget Token budget management
│ ├── Agent.TaskQueue Task queuing + prioritization
│ ├── Agent.Orchestrator Multi-agent spawning + synthesis
│ ├── Agent.Progress Real-time progress reporting
│ ├── Agent.TaskTracker Task lifecycle tracking
│ ├── Agent.Hooks Priority-ordered middleware pipeline
│ ├── Agent.Learning Pattern learning system
│ ├── MiosaKnowledge.Store Semantic knowledge graph
│ ├── Memory.KnowledgeBridge Knowledge ↔ Memory bridge
│ ├── Vault.Supervisor Structured memory (FactStore + Observer)
│ ├── Agent.Scheduler Cron + heartbeat scheduling
│ ├── Agent.Compactor 3-zone context compression
│ ├── Agent.Cortex Context aggregation delegate
│ └── Agent.ProactiveMode Autonomous proactive actions
│
├── Supervisors.Extensions (one_for_one)
│ ├── Treasury Token treasury (opt-in)
│ ├── Intelligence.Supervisor 5 communication modules
│ ├── Fleet.Supervisor Multi-instance fleet (opt-in)
│ ├── Sidecar.Manager Go/Python sidecar lifecycle
│ │ ├── Go.Tokenizer Fast tokenization sidecar
│ │ ├── Go.Git Git operations sidecar
│ │ ├── Go.Sysmon System monitoring sidecar
│ │ ├── Python.Supervisor Python execution sidecar
│ │ └── WhatsAppWeb Baileys WhatsApp bridge
│ ├── Sandbox.Supervisor Docker + Wasm + Sprites.dev (opt-in)
│ ├── Wallet Payment integration (opt-in)
│ ├── System.Updater OTA update checker (opt-in)
│ └── Platform.AMQP RabbitMQ publisher (opt-in)
│
├── Channels.Starter Deferred channel boot
└── Bandit HTTP REST API on port 8089
Drop a markdown file in ~/.osa/skills/your-skill/SKILL.md:
---
name: data-analyzer
description: Analyze datasets and produce insights
tools:
- file_read
- shell_execute
---
## Instructions
When asked to analyze data:
1. Read the file to understand its structure
2. Use shell commands to run analysis
3. Produce a summary with key findingsAvailable immediately — no restart, no rebuild.
defmodule MyApp.Skills.Calculator do
@behaviour OptimalSystemAgent.Skills.Behaviour
@impl true
def name, do: "calculator"
@impl true
def description, do: "Evaluate a math expression"
@impl true
def parameters do
%{"type" => "object",
"properties" => %{
"expression" => %{"type" => "string"}
}, "required" => ["expression"]}
end
@impl true
def execute(%{"expression" => expr}) do
{result, _} = Code.eval_string(expr)
{:ok, "#{result}"}
end
end
# Register at runtime:
OptimalSystemAgent.Skills.Registry.register(MyApp.Skills.Calculator)// ~/.osa/mcp.json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
}
}MCP tools are auto-discovered and available alongside built-in skills.
OSA is grounded in four principles from communication and systems theory:
- Shannon (Channel Capacity): Every channel has finite capacity. Match compute to complexity — don't burn your best model on trivial tasks.
- Ashby (Requisite Variety): The system must match the variety of its inputs — 18 providers, 12 channels, unlimited skills, 5 reasoning strategies.
- Beer (Viable System Model): Five operational modes (Build, Assist, Analyze, Execute, Maintain) mirror the five subsystems every viable organization needs.
- Wiener (Feedback Loops): Every action produces feedback. The agent learns across sessions — memory, knowledge graph, pattern recognition, context aggregation.
Research: Signal Theory: The Architecture of Optimal Intent Encoding in Communication Systems (Luna, 2026)
OSA is the intelligence layer of the MIOSA platform:
| Setup | What You Get |
|---|---|
| OSA standalone | Full AI agent in your terminal — chat, automate, orchestrate |
| OSA + BusinessOS | Proactive business assistant with CRM, scheduling, revenue alerts |
| OSA + ContentOS | Content operations agent — drafting, scheduling, engagement analysis |
| OSA + Custom Template | Build your own OS template. OSA handles the intelligence. |
| MIOSA Cloud | Managed instances with enterprise governance and 99.9% uptime |
| Doc | What It Covers |
|---|---|
| Documentation Index | Full docs map — 312 docs across all subsystems |
| Architecture | Ecosystem map, supervision tree, module organization |
| Agent Loop | Core reasoning engine, strategies, context builder |
| Memory & Knowledge | 5-layer memory, knowledge graph, SPARQL, OWL reasoning |
| Orchestration | Multi-agent decomposition, waves, swarms, PACT |
| Tools | 34 built-in tools, middleware pipeline, custom tools |
| LLM Providers | 18 providers, circuit breaker, tier routing |
| HTTP API | Every endpoint, auth, SSE, error codes |
| CLI Reference | All slash commands organized by category |
| Features | Recipes, skills, hooks, voice, proactive mode, tasks |
| Deployment | Docker, systemd, Nginx, production checklist |
Built by Roberto H. Luna and the MIOSA team.
We prefer skills over code changes. Write a SKILL.md, share it with the community. See CONTRIBUTING.md.
Apache 2.0 — See LICENSE.
Built by MIOSA. Grounded in Signal Theory. Powered by the BEAM.
