✦ Orion

An agent in your terminal — build software, run research, orchestrate operations.

Orion is a terminal-native AI agent. By default it's a strong general engineer — it edits files, runs commands, debugs, tests, automates, and orchestrates subagents. Two commands unlock specialized capabilities: /research (a scientific-intelligence system for world modeling, simulation, and mathematical analysis) and /security (defensive audit & hardening). Models are abstracted behind intelligence tiers (low → godmode), and everything stays under your control through a permission system enforced in the agent loop — not in a prompt.

npm install -g @omida/orion
orion

Highlights

| | | |---|---| | One agent, specialized capabilities | ◇ general (default) · /research world models & simulation · /security defensive audit — history carries across | | Intelligence tiers | /intelligence low\|medium\|high\|godmode routes to the right model for the job; models rebranded as Orion. Any provider underneath: OpenRouter, Anthropic, or any OpenAI-compatible endpoint (local Ollama / LM Studio / vLLM, keyless) | | Code intelligence | Multi-language symbol index: repo_map, code_symbols, code_definition (go-to-def), code_references (find-refs) across TS/JS, Python, Go, Rust, and more | | Agent fleet | Launch background jobs (fleet_run) that run detached and unattended, optionally in isolated git worktrees; monitor them via fleet_status, orion fleet, or the web dashboard | | Compounding memory | Semantic long-term memory across sessions — Orion recalls relevant facts, preferences, and decisions automatically, learns from /reflect, and you browse it via orion memory or the web viewer | | Constellation ontology | A built-in Palantir-style knowledge graph — model a domain as typed objects, links, and actions; query, traverse, semantic-search, and visualize it as an interactive graph | | Skills | Drop .orion/skills/<name>/SKILL.md files to teach Orion your workflows; loaded on demand | | Real safety | Permission modes (ask / auto / yolo) + per-tool policies, workspace trust prompts, unified diffs in approvals, checkpointed mutations with /undo, hard read-only plan mode | | MCP | Model Context Protocol servers over stdio or streamable HTTP; their tools join the agent's toolset under the same permission gates | | Subagents | Parallel spawn_agent delegation, custom agent definitions in markdown, optional git-worktree isolation | | Every surface | Interactive TUI · headless -p for scripts and pipes · orion serve HTTP/SSE API | | Durable context | ORION.md project memory (AGENTS.md-compatible), rules dirs, auto-compaction against real context limits, resumable sessions | | Real web search | LangSearch API by default when configured — hybrid keyword+vector search with summaries, no scraping rate limits — with an automatic DuckDuckGo fallback |

Quick start

npm install -g @omida/orion
export OPENROUTER_API_KEY=sk-or-...    # or run `orion` and use /login
export LANGSEARCH_API_KEY=sk-...        # optional — powers web_search (free tier at langsearch.com)
orion

Then just talk to it. Useful moves from day one:

❯ /init                        analyze the repo and write ORION.md
❯ fix the failing test in @src/api/users.test.ts
❯ ! npm test                   run a command yourself; output is shared with the agent
❯ /plan                        hard read-only mode for safe exploration
❯ /undo                        revert everything the last run changed

The three modes

◇ General — the default. A strong senior engineer and operator: orients in the repo, makes minimal idiomatic diffs, runs the project's tests/build to verify, debugs root causes, runs background jobs, orchestrates parallel subagents, and states blast radius before anything destructive. (This merges what used to be separate "build" and "ops" modes.)

◈ Research (/research) — a scientific intelligence for hard quantitative work: world modeling, simulation, and mathematical analysis. Frames problems precisely, states assumptions, builds explicit models, and computes with real code (numpy/scipy — matrices, ODEs, Monte Carlo, optimization) instead of guessing.

It's backed by a real experiment engine: the agent writes a simulation that reads params from $ORION_PARAMS and writes a metrics.json + figures into $ORION_RUN_DIR, then runs it with the run_experiment tool. Every run is recorded reproducibly (command, params, metrics, artifacts) in research/experiments.jsonl; list_experiments compares runs for ablation analysis, and orion serve's web UI has an Experiments viewer that renders each run's metrics and figures inline.

⛨ Security (/security) — a defensive security engineer: threat-models, audits code for real vulnerabilities grounded in path:line, prioritizes by exploitability × impact, writes the fix and the regression test, and hardens defaults. Scoped to authorized, defensive, educational use.

Intelligence

Models are abstracted as Orion tiers, routed by /intelligence:

| tier | model | ~$/M in·out | |---|---|---| | low | deepseek-v4-flash | $0.09 / $0.18 | | medium (default) | deepseek-v4-pro | $0.44 / $0.87 | | high | glm-5.2 | $0.57 / $1.80 | | godmode | claude-sonnet-5 | $2 / $10 (opt-in) |

Override the model behind any tier in config (intelligenceModels), or pin a raw model with /model <id>.

Interfaces

Terminal UI

orion — streaming chat with slash-command palette, live model picker with prices, message queueing while the agent works, @file attachments, ! shell passthrough, input history, mode-colored status bar with live token/cost tracking and permission-mode badges. Tool activity shows change stats and timings (✓ edit_file(web.ts) +154 -36 · 1.2s), a live run timer ticks while the agent works, an always-on activity line shows exactly what's happening (⠸ composing write_file… 2.4k chars), and every run ends with a summary (✦ done in 1m 23s · 3 turns · 6 tools · 12k tok · $0.02); tune the detail with /verbosity quiet|normal|verbose. On startup Orion checks npm for updates and offers to install them (autoUpdateCheck: false to disable, /update to run manually).

Headless

orion -p "explain the build failure"          # print result, exit
cat error.log | orion -p "diagnose"           # piped stdin becomes context
orion --mode research --plan -p "..."         # read-only research run
orion --yolo -p "apply the codemod"           # auto-approve (use with care)
orion -c                                      # resume latest session here

Gated tools (writes, shell, MCP) are denied by default in headless runs — --yolo opts in.

HTTP server + web client

orion serve --port 4300 --auth mytoken

Open http://127.0.0.1:4300/ for a built-in web chat client (streaming, tool activity, timers). POST /v1/chat streams agent events over SSE; sessions are shared with the TUI. The web client also has an Experiments viewer and a live Fleet dashboard. See docs/server.md for the full API.

Agent fleet

orion fleet run "review PR #42 and post findings"   # launch a background job (waits, streams)
orion fleet list                                     # all jobs + status
orion fleet watch <id>                               # stream a job's log

Inside a chat, Orion can launch jobs itself with fleet_run (unattended, auto-approved; use isolation: "worktree" to keep changes off the main tree) and check them with fleet_status. The orion serve web UI has a live Fleet dashboard to launch, watch, and cancel jobs.

Compounding memory

Orion has semantic long-term memory that spans sessions. Relevant memories are recalled into context automatically at the start of each task, so it remembers your preferences, decisions, and project facts without being reminded. It saves durable learnings with the remember tool (typed as fact / preference / decision / insight / code, scoped to the project or global), and /reflect extracts learnings from the current session.

orion memory list                 # browse what Orion has learned
orion memory search "deploy"      # semantic search
orion memory stats

Embeddings default to a fast, dependency-free local embedder (zero config). Point embeddings.model at any OpenAI-compatible embeddings endpoint for deeper semantic recall. Browse and prune memory in the orion serve web viewer.

Safety model

• Workspace trust: the first time you run Orion in a directory it asks whether you trust it (remembered per directory; subdirectories inherit). Untrusted headless runs are noted on stderr.
• Permission modes — switch live with /permissions or start with --auto / --yolo:
  • ask (default): writes, shell, and MCP tools each require approval
  • auto: file edits auto-approved; shell and MCP still ask
  • yolo: every prompt bypassed (explicit deny rules still honored)
• Every tool belongs to a permission class (read / write / execute / network / mcp); policies are allow, ask, or deny, resolved most-specific-first and enforced in the loop.
• Approval prompts show the real unified diff or command before anything runs; approve once, for the session, or decline — declines are fed back to the model as guidance.
• Every file mutation is checkpointed first-touch-per-run; /undo reverts a whole run, and the log survives restarts.
• Post-edit diagnostics: after every file edit, Orion runs fast syntax/type checks (tsc/node/python/JSON) and feeds problems straight back to the model so it self-corrects immediately (diagnostics: false to disable).
• Cost budgets: set maxCostPerSession (USD) and the agent warns at 80% and stops at the limit.
• /plan removes mutation tools from the toolset entirely — read-only by construction.
• hooks.preTool lets your own script veto any tool call.

Configuration

Global ~/.config/orion/config.json, per-project .orion/settings.json. Full reference: docs/configuration.md.

{
  // Omit "model"/"modes" entirely to use the cost-optimized per-mode presets.
  "modes": { "research": { "model": "deepseek/deepseek-v4-pro" } },
  "permissions": { "execute": "allow", "mcp__github": "allow" },
  "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } },
  "hooks": { "postTool": "echo $ORION_TOOL >> .orion/audit.log" }
}

Extensibility lives in your repo:

| Path | Purpose | |---|---| | ORION.md / AGENTS.md | project memory, loaded every conversation (/init writes it; the remember tool appends) | | .orion/rules/*.md | always-loaded rules | | .orion/commands/*.md | custom slash commands ($ARGUMENTS substitution) | | .orion/agents/*.md | custom subagent definitions — own prompt, toolset, model | | .orion/skills/<name>/SKILL.md | skills: capability packs loaded on demand (frontmatter name, description; /skills lists) |

Development

npm install
npm run typecheck     # strict tsc
npm test              # vitest: loop, tools, permissions, providers, MCP, server
npm run build         # tsup → dist/cli.js
ORION_MOCK=1 orion    # deterministic offline provider for UI/loop work

Documentation

Full docs live in docs/:

• Configuration reference · Capabilities & intelligence · Tools reference · Server & web client
• Subsystems: Constellation (ontology) · Research engine · Code intelligence · Agent fleet · Memory
• Design notes · Changelog

Roadmap

LSP-aware diagnostics · WebSocket transport and web client · GitHub automation · MCP HTTP transport · release automation

License

MIT