# 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.

[![npm](https://img.shields.io/npm/v/omnius.svg)](https://www.npmjs.com/package/omnius)
[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-CC--BY--NC--4.0-blue.svg)](LICENSE)

## Install

```bash
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:

```bash
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

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

```text
/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](docs/getting-started/install.md), [First run](docs/getting-started/first-run.md), [Model providers](docs/getting-started/model-providers.md) |
| Terminal workflows | [TUI workflows](docs/guides/tui-workflows.md), [Slash commands](docs/reference/slash-commands.md) |
| REST daemon | [REST reference](docs/reference/rest-api.md), [REST quickref](docs/rest/QUICKREF.md), [OpenAPI source](docs/rest/openapi-source.md) |
| Realtime voice chat | [Realtime guide](docs/guides/realtime.md) |
| Sponsor and COHERE mesh | [Sponsor and COHERE guide](docs/guides/sponsor-and-cohere.md) |
| Telegram bridge | [Telegram guide](docs/guides/telegram.md) |
| Media generation | [Media guide](docs/guides/media-generation.md) |
| Operations | [Runtime hygiene](docs/operations/runtime-hygiene.md), [Security and remote access](docs/operations/security-and-remote-access.md) |
| Architecture | [Architecture overview](docs/architecture/overview.md) |
| Agent-explorable docs | [Agent memory docs index](docs/agent-memory/INDEX.md) |

## 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:

```bash
omnius serve
```

Useful entrypoints:

```text
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:

```bash
OMNIUS_REST_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](docs/reference/rest-api.md) for the maintained endpoint inventory. The canonical machine contract is generated from [packages/cli/src/api/openapi.ts](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:

```text
/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

```bash
pnpm install
pnpm -r build
pnpm docs:check
```

Focused checks used for the docs skill surface:

```bash
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/`.

```bash
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 --prefer-online --cache-min=0 --registry https://registry.npmjs.org/
NPM_CONFIG_CACHE=$(pwd)/.npm-cache npm publish --access public --prefer-online --cache-min=0 --registry https://registry.npmjs.org/
```

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](LICENSE) for non-commercial use. Commercial use, redistribution, hosted services, and enterprise deployment require a commercial license.
