Signal Theory-optimized proactive AI agent. Local-first. Open source. BEAM-powered.
curl -fsSL https://raw.githubusercontent.com/Miosa-osa/OSA/main/install.sh | bash
osaOne command installs. One command runs. First run walks you through setup.
OSA is the intelligence layer of MIOSA — a local-first, open-source AI agent built on Elixir/OTP. It runs on your machine, owns your data, and connects to any LLM provider you choose.
Every agent framework processes every message the same way. OSA does not. Before any message reaches the reasoning engine, a Signal Classifier decodes its intent, domain, and complexity. Simple tasks go to fast, cheap models. Complex multi-step tasks get decomposed into parallel sub-agents with the right models for each step. The agent learns from every session.
The theoretical foundation is Signal Theory — a framework for maximizing signal-to-noise ratio in AI communication, grounded in Shannon, Ashby, Beer, and Wiener.
User Input
│
├─ Message Queue (300ms debounce batching)
│
├─ UserPromptSubmit Hook (can modify/block)
│
├─ Budget + Turn Limit Check
│
├─ Prompt Injection Guard (3-tier detection)
│
├─ Context Compaction Pipeline
│ ├─ Micro-compact (no LLM — truncate old tool results)
│ ├─ Strip tool args → Merge consecutive → Summarize warm zone
│ ├─ Structured 8-section compression (iterative, preserves details)
│ ├─ Context collapse (413 recovery — withhold large results)
│ └─ Post-compact restore (re-inject files, tasks, workspace)
│
├─ Pre-Directives (explore, delegation, task creation nudges)
│
├─ Genre Routing (low-signal → short-circuit, skip full loop)
│
├─ Context Build (cached static base + dynamic per-request)
│ ├─ Async memory prefetch (fires parallel while context builds)
│ ├─ Effort-aware thinking config (low/medium/high/max)
│ ├─ Agent message injection (inter-agent communication)
│ └─ Iteration budget tracking
│
├─ LLM Streaming Call
│ ├─ Streaming tool execution (tools fire MID-STREAM)
│ ├─ Fallback model chain (auto-switch on rate limit/failure)
│ └─ Max output token recovery (bump + retry on truncation)
│
├─ Tool Execution
│ ├─ Concurrency-aware dispatch (parallel safe, sequential unsafe)
│ ├─ Permission check (tiers + pattern rules + interactive prompt)
│ ├─ Pre-hooks (security, spend guard, MCP cache)
│ ├─ Tool result persistence (large → disk with reference)
│ ├─ Diff generation (unified diff for file operations)
│ ├─ Post-hooks (cost, telemetry, learning, episodic)
│ └─ Doom loop detection (halt on repeated failures)
│
├─ Behavioral Nudges (read-before-write, code-in-text, verification)
│
├─ Stop Hooks (can override response or force continuation)
│
└─ Post-Response
├─ Output guardrail (scrub system prompt leaks)
├─ Post-response hooks (transcript, auto-memory, session save)
├─ Telemetry recording
└─ SSE broadcast to all connected clients
┌─────────────────────────────────────────────────────────────────────┐
│ Channels: Rust TUI │ Desktop (Tauri) │ HTTP/SSE │ Telegram │ ... │
├─────────────────────────────────────────────────────────────────────┤
│ Signal Classifier: S = (Mode, Genre, Type, Format, Weight) │
├─────────────────────────────────────────────────────────────────────┤
│ Events.Bus (Goldrush compiled BEAM bytecode dispatch) │
├──────────┬──────────┬───────────┬──────────┬────────────────────────┤
│ Agent │ Orchest- │ Swarm │ Scheduler│ Healing Orchestrator │
│ Loop │ rator │ (4 modes)│ (cron) │ (self-repair) │
│ (ReAct) │ (14 roles│ │ │ │
│ │ bg/fork/│ Teams + │ │ Speculative Executor │
│ │ worktree│ NervSys │ │ │
├──────────┴──────────┴───────────┴──────────┴────────────────────────┤
│ Context │ Compactor │ Memory │ Settings │ Hooks │ Permissions │
│ Builder │ (6-step) │ (SQLite │ Cascade │ (25 │ (pattern │
│ │ │ +ETS │ (4-layer)│ events,│ rules, │
│ │ │ +FTS5) │ │ 4 types│ interactive) │
├──────────┴───────────┴─────────┴──────────┴─────────┴───────────────┤
│ 7 Providers │ 47 Tools │ Telemetry │ Credential Pool │ Soul│
│ + Fallback │ (deferred)│ (per-tool) │ (key rotation) │ │
└───────────────┴────────────┴─────────────┴───────────────────┴─────┘
Runtime: Elixir 1.17+ / Erlang OTP 27+ | HTTP: Bandit | DB: SQLite + ETS + persistent_term | Events: Goldrush | HTTP Client: Req
Every input is classified into a 5-tuple before it reaches the reasoning engine:
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 category: question, request, issue, scheduling, summary
Format — Container: message, command, document, notification
Weight — Complexity: 0.0 (trivial) → 1.0 (critical, multi-step)
The classifier is LLM-primary with a deterministic regex fallback. Results are cached in ETS (SHA256 key, 10-minute TTL). This is what makes tier routing possible.
7 providers, 3 tiers, weight-based dispatch:
| Weight Range | Tier | Use Case |
|---|---|---|
| 0.00–0.35 | Utility | Fast, cheap — greetings, lookups, summaries |
| 0.35–0.65 | Specialist | Balanced — code tasks, analysis, writing |
| 0.65–1.00 | Elite | Full reasoning — architecture, orchestration, novel problems |
| Provider | Notes |
|---|---|
| Ollama Local | Runs on your machine — fully private, no API cost |
| Ollama Cloud | Fast cloud inference, no GPU required |
| Anthropic | Claude Opus, Sonnet, Haiku |
| OpenAI | GPT-4o, GPT-4o-mini, o-series |
| OpenRouter | 200+ models behind a single API key |
| MIOSA | Fully managed Optimal agent endpoint |
| Custom | Any OpenAI-compatible endpoint |
14 specialized agent roles. Explore → Plan → Execute protocol:
User: "Build a REST API with auth, tests, and docs"
OSA:
├── Explorer agent — scans codebase (read-only, fast)
├── Planner agent — designs architecture + implementation plan
├── Backend agent — writes API + auth middleware
├── Tester agent — writes test suite
└── Doc-writer agent — writes documentation
Sub-agents share a task list and communicate via ETS-backed mailboxes.
:parallel # All agents work simultaneously, results merged
:pipeline # Each agent's output feeds the next
:debate # Agents argue positions, consensus emerges
:review_loop # Build → review → fix → re-review (iteration budget enforced)Swarms use ETS-backed team coordination: shared task lists, per-agent mailboxes, scratchpads, and configurable iteration limits.
| Category | Tools |
|---|---|
| File | file_read, file_write, file_edit, file_glob, file_grep, dir_list, multi_file_edit |
| System | shell_execute, git, download, repl (Python/Elixir/Node) |
| Web | web_search, web_fetch |
| Memory | memory_save, memory_recall, session_search (FTS5 full-text) |
| Agent | delegate (background/fork/worktree), send_message, message_agent, list_agents, team_tasks, task_stop, task_output |
| Skills | create_skill, list_skills |
| Code | code_symbols, computer_use (macOS/Linux/Docker/SSH) |
| Config | config, cron (create/list/delete/trigger), tool_search |
| Advanced | mixture_of_agents (multi-LLM ensemble), verify_loop, spawn_conversation, peer_review, cross_team_query |
| Other | task_write, ask_user, create_agent |
Tools support deferred loading — rarely-used tools excluded from prompt, discoverable via tool_search. Large results auto-persisted to disk.
Soul system: IDENTITY.md, USER.md, and SOUL.md are loaded at boot and interpolated into every LLM call. The setup wizard collects your name and agent name on first run. The agent knows who it is and who you are from conversation one.
Memory layers:
| Layer | Backend | Notes |
|---|---|---|
| Long-term | SQLite + ETS | Relevance scoring: keyword match + signal weight + recency |
| Episodic | ETS | Per-session event tracking, capped at 1000 events |
| Skills | File system | Patterns with occurrence >= 5 auto-generate skill files (SICA) |
SICA Learning cycle: See → Introspect → Capture → Adapt. The agent observes what works across sessions and converts recurring patterns into reusable skills automatically.
CRITICAL (unlimited) — System identity, active tool schemas
HIGH (40%) — Recent conversation turns, current task state
MEDIUM (30%) — Relevant memories (keyword-searched from SQLite/ETS)
LOW (remaining) — Workflow context, environmental metadata
Three-zone compression:
- HOT — last 10 messages, full fidelity
- WARM — older turns, progressively summarized
- COLD — oldest content reduced to key facts only
Control your desktop directly from the agent. Platform adapters for:
| Platform | Method |
|---|---|
| macOS | Accessibility API — click, type, screenshot, scroll |
| Linux X11 | xdotool + xclip — full desktop control |
| Docker | Container-isolated desktop interaction |
| Remote SSH | Control machines over SSH tunnels |
The agent can take screenshots, click elements, type text, press keys, scroll, and interact with any GUI application.
| Channel | Notes |
|---|---|
| Elixir CLI | Primary REPL — 25 commands, streaming, task display, diff view, Ctrl+R search, multi-line input |
| Rust TUI | Full terminal UI — onboarding wizard, model picker, sessions, command palette |
| Desktop GUI | Tauri 2 + SvelteKit 5 — chat, agents, tasks, memory, signals, settings, usage tracking |
| HTTP/SSE API | Port 9089, JWT auth, 20+ route modules, real-time SSE streaming |
| Telegram | Long-polling, typing indicators, markdown conversion |
| Discord | Webhook mode, token validation |
| Slack | Webhook + HMAC-SHA256 request verification |
25 lifecycle events. 4 hook types:
| Type | Description |
|---|---|
| Function | Elixir functions — built-in (security, budget, telemetry, learning) |
| HTTP Webhook | POST JSON to external URLs on any event |
| Shell Command | Run bash commands with payload interpolation |
| Agent | Spawn a subagent in response to an event |
Events: pre_tool_use, post_tool_use, post_tool_use_failure, user_prompt_submit, pre_compact, post_compact, session_start, session_end, pre_response, post_response, subagent_start, subagent_stop, file_changed, permission_request, stop, and more.
Configure via ~/.osa/settings.json:
{
"hooks": {
"post_tool_use": [
{"type": "http", "url": "https://example.com/webhook"},
{"type": "shell", "command": "echo '{{tool_name}} done' >> /tmp/osa.log"}
]
}
}Control thinking depth and iteration budget:
| Level | Thinking | Iterations | Use Case |
|---|---|---|---|
/effort low |
1K tokens | 10 | Quick answers, fast mode |
/effort medium |
5K tokens | 30 | Balanced (default) |
/effort high |
10K tokens | 50 | Deep reasoning |
/effort max |
32K tokens | 100 | Maximum analysis |
Cron jobs (CRONS.json) and event-driven triggers (TRIGGERS.json) configured in ~/.osa/. HEARTBEAT.md defines a recurring proactive checklist the agent runs on a schedule.
curl -fsSL https://raw.githubusercontent.com/Miosa-osa/OSA/main/install.sh | bashAuto-installs Elixir, Erlang, and Rust if missing. Symlinks osa to your PATH.
Homebrew: brew tap miosa-osa/tap && brew install osagent
Docker: docker compose up -d
osaFirst run detects your setup and offers:
- Quick Start — auto-detect providers and go
- Manual Setup — choose provider, enter API key or OAuth sign-in, pick model
- Skip — configure later with
/setupor~/.osa/.env
Supported providers: Ollama (local/free), Anthropic (OAuth or API key), OpenAI, Groq, OpenRouter, Together, DeepSeek.
osa Start (backend + TUI)
osa setup Re-run setup wizard
osa serve Headless backend (HTTP API on :9089)
osa update Pull latest + recompile
osa doctor Health checks
osa version Print version
Type /help inside the REPL:
/help /clear /compact /model /status /cost /context /memory /tools /skills
/agents /sessions /tasks /plan /doctor /export /version /coordinator /effort
/fast /permissions /hooks /metrics /setup /login /logout /channels /exit
mix osa.run "Fix the auth bug" # text output
mix osa.run --format json "Explain this code" # structured JSON
echo "Build an API" | mix osa.run --format stream-json # streaming NDJSONmix osa.chat --resume cli_abc123 # Resume specific session
mix osa.chat --continue # Resume most recentAll runtime config lives in ~/.osa/.env, generated by the setup wizard:
OSA_DEFAULT_PROVIDER=ollama
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=nemotron-3-super
OSA_USER_NAME=Roberto
OSA_AGENT_NAME=OSAWorkspace: ~/.osa/
~/.osa/
├── .env # Provider config (generated by wizard)
├── settings.json # User settings (effort, permissions, hooks)
├── permissions.json # Tool permission rules (allow/deny with glob patterns)
├── oauth.json # OAuth credentials (auto-refreshed)
├── IDENTITY.md # Agent personality
├── USER.md # User profile
├── SOUL.md # Agent values
├── agents/ # Custom agent roles (AGENT.md files)
├── skills/ # Custom skills (SKILL.md files, hot-reload)
├── sessions/ # Saved session state (for resume)
├── exports/ # Exported conversations
├── workspace/ # Agent file workspace
├── tool-results/ # Large tool output persistence
├── worktrees/ # Git worktree isolation
├── agent-memory/ # Per-agent persistent memory
└── prompts/ # System prompt overrides
Settings cascade: user (~/.osa/settings.json) < project (.osa/settings.json) < local (.osa/settings.local.json) < session
lib/optimal_system_agent/ # 200+ Elixir modules
agent/ # ReAct loop, context, memory, effort, worktree, compactor, hooks
agent/loop/ # Core loop: react_loop, tool_executor, streaming_tool_executor,
# context_collapse, tool_result_storage, llm_client, guardrails
channels/cli/ # CLI: commands (25), permissions, spinner, renderer, line_editor,
# message_queue, diff_renderer, agent_tree, task_display
channels/http/ # HTTP API: 20+ route modules, SSE streaming, auth, rate limiter
events/ # Bus (Goldrush compiled BEAM bytecode), PubSub, DLQ
providers/ # 7 providers + fallback chain + credential pool
tools/builtins/ # 47 built-in tools, schema validation, deferred loading
memory/ # Store (SQLite + ETS), auto_extract, SICA learning, FTS5 search
telemetry/ # Per-tool and per-provider execution metrics
swarm/ # Parallel, pipeline, debate, review_loop coordinators
budget/ # Token cost tracking, treasury
signal/ # Signal classifier, noise filter
store/ # Ecto repo, schemas, migrations (SQLite + PostgreSQL)
supervisors/ # OTP supervision trees
priv/
rust/tui/ # Rust TUI (ratatui + crossterm)
prompts/ # System prompt templates
agents/ # Agent role definitions
skills/ # Built-in skills (hot-loadable)
swarms/ # Swarm pattern presets
desktop/ # Command Center — Tauri 2 + SvelteKit 5
Drop a markdown file anywhere under ~/.osa/skills/:
---
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 findingsSkills are available immediately — no restart, no recompile. The Skills Registry hot-reloads on file change.
Recurring behavior patterns (occurrence >= 5) are auto-promoted to skills by the SICA engine.
mix test # Full suite (1730 tests)
mix test test/tools/ # Tool tests only
mix test test/providers/ # Provider tests only
mix test test/signal/ # Signal classification tests
mix test test/swarm/ # Swarm pattern tests| Area | Status | Notes |
|---|---|---|
| Events/Signal tests | Aligning | Core rewritten, tests being updated |
| Agent strategy tests | Evaluating | Mixed test failures under review |
| Swarm HTTP routing | Partial | Works via delegate tool; HTTP endpoint pending |
| Permission system | Wiring | TUI UI done, backend endpoint pending |
| Sandbox isolation | Planned | Docker/Wasm backends |
| Additional channels | Planned | WhatsApp, Signal, Matrix, Email |
| Vault (structured memory) | Planned | 8-category typed memory with fact extraction |
OSA is grounded in four principles from information and systems theory:
- Shannon (Channel Capacity) — Every channel has finite capacity. Match compute to complexity. Don't run your best model on trivial tasks.
- Ashby (Requisite Variety) — The system must match the variety of inputs it receives. OSA must handle every signal type, not just the common ones.
- Beer (Viable System Model) — Five operational modes mirror the five subsystems every viable organization needs. Structure enables autonomy.
- Wiener (Feedback Loops) — Every action produces feedback. The agent learns what works and adapts across sessions.
Research paper: Signal Theory: The Architecture of Optimal Intent Encoding — Luna, MIOSA Research, 2026.
OSA is the intelligence layer of the MIOSA platform:
| Configuration | What You Get |
|---|---|
| OSA standalone | Full AI agent in your terminal, on your hardware |
| OSA + BusinessOS | Proactive business assistant with CRM, scheduling, revenue alerts |
| OSA + Custom Template | Build your own OS template; OSA provides the intelligence layer |
| MIOSA Cloud | Managed instances with enterprise governance |
Skills over code changes. Write a SKILL.md, share it with the community. See CONTRIBUTING.md for the full process.
Apache 2.0 — See LICENSE.
Built by Roberto H. Luna and the MIOSA team. Grounded in Signal Theory. Powered by the BEAM.
This repository is indexed with CodeGraphContext — an interactive code graph that maps functions, modules, call chains, and relationships across the entire codebase.
# Install CGC
uv tool install codegraphcontext
# Index this repository
cgc index .
# Launch the interactive visualizer (opens in browser)
cgc visualizeThis opens an interactive graph at http://localhost:8000/playground where you can:
- Search for any function, module, or class
- Trace call chains — who calls what, and how deep
- Detect dead code — unused functions and modules
- Analyze complexity — cyclomatic complexity per function
- Inspect relationships — imports, inheritance, method calls
# Find callers of a function
cgc analyze callers function_name
# Find dead code
cgc analyze dead-code
# Complexity analysis
cgc analyze complexity
# Raw Cypher query
cgc query "MATCH (f:Function) RETURN f.name LIMIT 20"- Python 3.10+
- uv (recommended) or pip