Omnius

Omnius is a local-first agentic coding runtime: terminal UI, autonomous coding loop, REST daemon, model router, memory layer, media tools, Telegram bridge, and peer-to-peer inference mesh in one CLI.

It is designed for open-weight and user-controlled models first, while still routing cleanly through Ollama, vLLM, OpenAI-compatible endpoints, OpenRouter, Groq, Chutes, sponsor peers, COHERE peers, and other configured providers.

Install

npm install -g omnius
omnius

Requirements:

• Node.js 22 or newer
• npm 10 or newer for published CLI use
• pnpm 9 or newer for workspace development
• A local model or configured remote endpoint

Start the REST daemon:

omnius serve

The daemon defaults to http://127.0.0.1:11435. Open the interactive API docs at http://127.0.0.1:11435/docs.

What Omnius Does

• Runs autonomous coding tasks, edits files, executes tools, tests changes, and iterates on failures.
• Provides a dense terminal UI for model selection, endpoint routing, task control, shell output, voice, sponsors, Telegram, and system telemetry.
• Exposes a REST daemon with OpenAI/Ollama-compatible inference, agentic task execution, memory, skills, tools, MCP, events, voice, projects, and governance endpoints.
• Routes models through local, cloud, sponsor, and peer-to-peer endpoints without assuming local Ollama is the only source.
• Supports realtime spoken conversation for ASR/TTS clients through /realtime and REST realtime: true.
• Supports image, video, sound, music, TTS, ASR, voice clone references, Telegram media workflows, and sponsor-provided media generation.
• Keeps project runtime state in .omnius/, which is intentionally ignored by git.

Common Workflows

omnius "inspect this repo and summarize the main entrypoints"
omnius serve

/help                 command help
/model                select or inspect the active model
/endpoint             select or configure local, cloud, sponsor, or peer endpoints
/realtime             toggle short ASR/TTS-oriented conversation mode
/broker               inspect model broker, RAM/VRAM thresholds, and loaded models
/sponsor              expose local or upstream capacity to peers
/cohere               participate in distributed COHERE inference
/telegram             configure or toggle the Telegram bridge
/skills               list explorable skills and docs memories
/pause                pause after the current turn boundary
/stop                 interrupt the active run
/resume               resume saved state

Current Feature Areas

| Area | What to read | | --- | --- | | Install and setup | Install, First run, Model providers | | Terminal workflows | TUI workflows, Slash commands | | REST daemon | REST reference, REST quickref, OpenAPI source | | Realtime voice chat | Realtime guide | | Sponsor and COHERE mesh | Sponsor and COHERE guide | | Telegram bridge | Telegram guide | | Media generation | Media guide | | Operations | Runtime hygiene, Security and remote access | | Architecture | Architecture overview | | Agent-explorable docs | Agent memory docs index |

Recent Highlights

• /realtime and REST realtime: true provide short, natural, SOUL.md-aware conversation for ASR/TTS clients.
• Endpoint setup and sponsor setup aggregate models from all enabled endpoints, including external OpenAI-compatible routers.
• /sponsor can expose text inference and media generation for image, video, sound, and music with per-modality limits.
• Sponsor and COHERE status surfaces now use shared telemetry concepts: concurrency, request rate, daily tokens, peer usage, model usage, and remote system metrics.
• The TUI reports token production rate as t/s, supports Shift+Enter multiline input, and renders dynamic shell output inside bounded Unicode cards.
• Telegram state is scoped by user and group, supports durable reply preferences, and feeds raw platform/tool failures back into the agent loop.
• Ollama pool cleanup now accounts for process groups and orphan runner processes that can keep VRAM pinned.
• REST documentation is available both as human docs and as Omnius-discoverable docs skills.

REST API

Start:

omnius serve

Useful entrypoints:

GET  /docs
GET  /openapi.json
POST /v1/chat
POST /v1/chat/completions
POST /v1/run
GET  /v1/events
GET  /v1/skills
POST /v1/tools/{name}/call
WS   /v1/voicechat/ws

For shared deployments, use bearer keys:

OMNIUS_API_KEYS="read-key:read:grafana,run-key:run:ci:60:100000:3,admin-key:admin:ops" omnius serve

See docs/reference/rest-api.md for the maintained endpoint inventory. The canonical machine contract is generated from packages/cli/src/api/openapi.ts.

Agent-Explorable Documentation

Omnius discovers project-local docs skills from .aiwg/addons/*/skills. The docs bundles in this repo expose high-signal entrypoints for agents:

/skills omnius docs
skill_execute name="omnius-docs"
skill_execute name="omnius-rest-docs"
skill_extract name="omnius-realtime-docs" query="How does realtime REST mode work?"

The intended pattern is index first, targeted document second, not loading the whole manual into the active context.

Development

pnpm install
pnpm -r build
pnpm docs:check

Focused checks used for the docs skill surface:

pnpm --filter @omnius/execution exec vitest run tests/skill-discovery.test.ts
pnpm --filter omnius exec vitest run tests/realtime-mode.test.ts tests/command-registry.test.ts

Publishing

Publish only from publish/.

cd omnius
pnpm -r clean || true
find . -name 'tsconfig.tsbuildinfo' -not -path '*/node_modules/*' -delete
pnpm -r build
node scripts/build-publish.mjs
cd publish
mkdir -p .npm-cache
NPM_CONFIG_CACHE=$(pwd)/.npm-cache npm pack
NPM_CONFIG_CACHE=$(pwd)/.npm-cache npm publish --access public

Before publishing, verify README.md, package.json, dist/index.js, and dist/launcher.cjs are in the tarball, and that package.json includes readmeFilename: "README.md" plus a string readme.

License

Omnius is released under CC-BY-NC-4.0 for non-commercial use. Commercial use, redistribution, hosted services, and enterprise deployment require a commercial license.