# Omnimancer

> A unified CLI for multiple AI language models with AWS Bedrock integration, MCP support, and autonomous agent capabilities. Access 13+ AI providers (Claude, OpenAI, Gemini, Bedrock, and more) through one interface with secure file operations, approval workflows, and agent-driven automation.

- **Type:** MCP server
- **Install:** `agentstack add mcp-nvasion-omnimancer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [nvasion](https://agentstack.voostack.com/s/nvasion)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [nvasion](https://github.com/nvasion)
- **Source:** https://github.com/nvasion/omnimancer
- **Website:** https://factory-nexus.ai/packages/omnimancer

## Install

```sh
agentstack add mcp-nvasion-omnimancer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

A multi-model coding agent for the terminal. One tool, any LLM.

Omnimancer works like `claude -p` but isn't locked to a single provider. Point it at Claude, OpenAI, Gemini, Bedrock, Ollama, or any of 13+ supported backends and get a coding agent that reads files, writes code, runs commands, and iterates autonomously — with streaming responses, token/cost tracking, and structured JSON output for pipeline integration.

Beyond the basics, it ships with:

- **MCP support** (stdio, SSE, and HTTP transports) for tools, resources, and prompts
- **Lifecycle hooks** — run shell commands on message/tool events, with blocking veto power
- **Permission rules** — declarative allow/deny/ask rules per tool with regex matchers
- **Subagents** — scoped child agents with their own prompt, tool whitelist, and model
- **Layered security** — approval workflow, sensitive-path protection, and project-boundary enforcement
- **Named endpoint aliases** — run several OpenAI-compatible endpoints (vLLM, llama.cpp, LM Studio) side by side as first-class providers, keyless if the endpoint is
- **Modern input layer** — prompt_toolkit prompt with multiline editing, fuzzy `@file` mentions with content injection, live completion for providers/models, Ctrl-R history search
- **Prompt enhancement** — `e:` prefix or `/enhance` rewrites your draft with a configurable small model before sending (PromptFoundry meta-prompts)
- **Session approval modes** — `/accept edits|all` (or Shift+Tab) for claude-code-style auto-accept, always below your permission rules

## Install

```bash
pip install omnimancer-cli
```

## Usage

### Headless (pipeline mode)

```bash
# Single prompt, JSON output — like claude -p
omn -p "refactor auth.py to use dependency injection"

# Pipe context in
cat error.log | omn -p "diagnose this crash and suggest a fix"

# Use a specific provider and model.
# Note: the prompt must come right after -p; put other flags after it.
omn -p "write tests for src/api/routes.py" --provider claude --model claude-sonnet-4
omn -p "explain this codebase" --provider openai --model gpt-4o
omn -p "review this diff" --provider ollama >> read src/main.py and add error handling
[text streams in real-time as the model generates]
  tokens: 1523 in / 892 out | ~$0.0134

>>> /switch openai gpt-4o
>>> now review what we just changed
[switches to OpenAI, continues conversation]
```

### Streaming responses

Responses stream token-by-token as the model generates, so you see output immediately instead of waiting for the full response. After each response, a token/cost summary is displayed.

Streaming is automatic for providers that support it. Other providers fall back to displaying the full response once complete — no configuration needed.

| Provider | Streaming |
|----------|:---------:|
| Claude (Anthropic) | Yes |
| OpenAI / openai-compatible / DigitalOcean | Yes (SSE, incl. tool-call deltas) |
| All others | Fallback (full response) |

Streaming works in both regular chat and agent mode (tool calling flow). The display uses a live-updating terminal panel that refreshes at 15fps.

### Agent mode

When agent mode is enabled (`/agent on`), the AI can autonomously:

- **Read and write files** with approval workflow
- **Execute shell commands** with security validation
- **Search codebases** with fuzzy file matching (70% similarity threshold)
- **Make HTTP requests** for API testing
- **Call MCP tools** from connected MCP servers

All destructive operations require explicit approval (or are governed by your [permission rules](#permission-rules)). Reads and searches are auto-approved.

Providers that support native tool calling (Claude, OpenAI, Gemini) use structured function calls. Others fall back to operation markers parsed from the response text.

```
>>> /agent on
>>> fix the failing test in tests/test_auth.py
[agent reads test file, reads source, edits code, runs pytest, iterates]
  tokens: 4210 in / 1893 out | ~$0.0412
```

### Subagents

Subagents are scoped child agents with their own system prompt, tool whitelist, model override, and iteration cap. Each run uses an isolated conversation context, so a subagent never pollutes your main session — and its errors are caught and reported instead of crashing the REPL.

Define them in `config.json`:

```json
"subagents": {
  "reviewer": {
    "description": "Reviews code for bugs and style issues",
    "prompt": "You are a meticulous code reviewer...",
    "tools": ["Read", "Grep", "Bash"],
    "model": null,
    "max_iterations": 10
  }
}
```

Tool names match the agent's toolset (`Read`, `Write`, `Edit`, `Bash`, `Glob`, `Grep`, `WebFetch`). `tools: null` inherits all tools; `model: null` inherits the session model.

```
>>> /subagents                          # list configured subagents
>>> /subagents run reviewer check src/auth.py for security issues
```

## Supported Providers

| Provider | Tool Calling | Streaming | Notes |
|----------|:---:|:---:|-------|
| **Claude** (Anthropic) | Yes | Yes | Primary target. Best coding performance. |
| **OpenAI** | Yes | Fallback | GPT-4o, o1, etc. |
| **Gemini** (Google) | Yes | Fallback | Large context window. |
| **AWS Bedrock** | Yes | Fallback | Claude/Titan via AWS. |
| **Ollama** | No | Fallback | Local models. No API key needed. |
| **xAI** (Grok) | Yes | Fallback | |
| **Mistral** | No | Fallback | |
| **Perplexity** | No | Fallback | Web search built-in. |
| **Azure OpenAI** | Yes | Fallback | Enterprise Azure deployment. |
| **Vertex AI** | Yes | Fallback | Google Cloud deployment. |
| **OpenRouter** | No | Fallback | Access to 100+ models. |
| **DigitalOcean** | No | Fallback | OpenAI-compatible GenAI inference. Custom endpoint supported. |
| **Cohere** | No | Fallback | |

"Fallback" means the provider works but sends the full response at once instead of streaming token-by-token. The UI handles both modes transparently.

## Commands

| Command | Description |
|---------|-------------|
| `/help [command]` | Show help (optionally for a specific command) |
| `/quit` | Exit (also: `/exit`, Ctrl+D) |
| `/clear` | Clear terminal screen |
| `/switch  [model]` | Switch provider or model (uncataloged models are registered on the fly) |
| `/models [filter]` | List available models; `/models refresh [provider]` pulls live catalogs |
| `/model` | Interactive model picker for the current provider |
| `/providers` | List all providers with status |
| `/agent on\|off\|status` | Toggle agent mode |
| `/subagents [run  ]` | List or run scoped child agents |
| `/config show\|get\|set` | View or modify configuration |
| `/config set-provider  [--api-key …] [--base-url …] [--model …]` | Create/update a provider |
| `/config remove-provider ` | Remove a provider |
| `/hooks [list\|on\|off\|add\|remove]` | Manage lifecycle hooks |
| `/permissions [list\|on\|off\|allow\|deny\|ask\|remove]` | Manage permission rules |
| `/accept [edits\|all\|off]` | Session approval mode (Shift+Tab cycles it at the prompt) |
| `/enhance [chat\|code\|image\|research] ` | Rewrite a draft prompt with the enhancement model, confirm, send (the `e:` message prefix does it inline) |
| `/save [name]` | Save conversation |
| `/load [name]` | Load conversation |
| `/list` | List saved conversations |
| `/history [recent\|search\|clear\|export\|stats]` | Manage conversation history |
| `/tools` | Show available MCP tools |
| `/prompts [list\| [key=value …]]` | List and render MCP prompts |
| `/mcp [status\|reload\|connect\|disconnect\|health] [server]` | MCP server management |
| `/add-model   [description]` | Register a custom model |
| `/remove-model  ` | Unregister a custom model |
| `/list-custom-models` | List registered custom models |
| `/status` | System status |

You can also define your own slash commands: drop `.json` or `.py` command
definitions into `~/.omnimancer/commands/` and they're loaded at startup.

## MCP servers

Omnimancer's MCP layer is built on the official [`mcp` SDK](https://pypi.org/project/mcp/) and supports three transports — **stdio** (local subprocess), **SSE**, and **streamable HTTP** (remote) — and three MCP features: **tools** (exposed to the agent and listed via `/tools`), **resources**, and **prompts** (listed and rendered via `/prompts`).

Configure servers in `config.json`:

```json
"mcp": {
  "enabled": true,
  "servers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"],
      "env": {},
      "enabled": true,
      "auto_approve": ["read_file"],
      "timeout": 30
    },
    "remote-api": {
      "transport": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {"Authorization": "Bearer ..."},
      "enabled": true
    }
  }
}
```

Stdio servers need `command` (plus optional `args`/`env`); SSE and HTTP servers need `url` (plus optional `headers` — e.g. a bearer token for authenticated servers). `auto_approve` lists tool names that skip the approval prompt for that server.

Manage servers at runtime with `/mcp status`, `/mcp connect [server]`, `/mcp disconnect [server]`, `/mcp reload [server]`, and `/mcp health [server]`.

MCP is optional: if the `mcp` package isn't installed, everything else still works — connecting to a server just tells you to `pip install mcp`.

## Hooks

Hooks run shell commands at lifecycle events — for logging, notifications, linting, or policy enforcement. Four events are available:

| Event | Fires | Can block? |
|-------|-------|:---:|
| `pre_send_message` | Before a message is sent to the provider | Yes |
| `post_send_message` | After a successful provider response | No |
| `tool_use_request` | Before an agent tool/operation runs | Yes |
| `post_tool` | After a tool/operation completes | No |

A **blocking** hook vetoes the action if it exits non-zero (or times out). Hooks receive the event payload as JSON on stdin, plus `OMNIMANCER_HOOK_*` environment variables (`OMNIMANCER_HOOK_EVENT`, `OMNIMANCER_HOOK_MESSAGE`, …) for shell one-liners. Hook errors never crash the app.

Manage from the CLI:

```
>>> /hooks                                   # list configured hooks
>>> /hooks add post_tool notify --timeout 10 notify-send "tool ran"
>>> /hooks add tool_use_request guard --matcher "rm -rf" --blocking exit 1
>>> /hooks remove post_tool notify
>>> /hooks off                               # disable all hooks globally
```

`--matcher` is a regex tested against the event's target (message text, file path, command) — the hook only fires on a match. Hooks are stored in `config.json` under `hooks`:

```json
"hooks": {
  "enabled": true,
  "tool_use_request": [
    {"name": "guard", "command": "exit 1", "matcher": "rm -rf", "blocking": true, "timeout": 30}
  ]
}
```

## Permission rules

Permission rules decide what the agent may do before the approval prompt is ever shown. Each rule matches a tool (an operation type like `file_write`, `command_execute`, `web_request` — or `*` for any) plus an optional regex on the target (file path, command, URL).

Precedence: **deny > ask > allow > default** (normal approval workflow).

```
>>> /permissions                             # list rules
>>> /permissions deny command_execute "rm -rf"
>>> /permissions ask file_write ".*prod.*"
>>> /permissions allow file_write "\.env$"   # authorize project-local .env writes
>>> /permissions remove deny 1               # remove rule by index
>>> /permissions off                         # disable rules globally
```

- `deny` rules refuse without prompting.
- `ask` rules force a prompt even if the operation was previously "remembered" as approved.
- `allow` rules auto-approve — and also authorize writes to sensitive-named files (like `.env`) inside the project.

Rules live in `config.json` under `permissions` (`always_deny` / `always_ask` / `always_allow` lists).

## Security model

Three layers govern every agent operation, in order:

1. **Permission rules** — your declarative deny/ask/allow rules (above).
2. **Approval workflow** — interactive y/n with diff preview; approvals can be "remembered" per session.
3. **Low-level security gate** — path and command validation that runs regardless of approval.

The security gate distinguishes:

- **Hard-restricted paths** — never writable, even with approval: system directories (`/etc`, `/sys`, `/proc`, `/boot`, `/usr/bin`, …), `~/.ssh`, `~/.aws/credentials`, `~/.config/gcloud`.
- **Sensitive name patterns** — denied by default but overridable by explicit approval or an `always_allow` rule: `.env*`, `*secret*`, `*key*`, `*token*`, `*password*`, `*credentials*`, `*.db`/`*.sqlite*`.
- **Project boundary** — writes must stay inside the directory `omn` was launched from (or a temp dir).

Plus: command whitelist/blacklist, sandboxed execution, read-before-write logic, and automatic backups of existing files before modification.

## Configuration

### API keys

The simplest setup is environment variables:

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."
export XAI_API_KEY="..."
omn
```

### Config file

Config is stored in `~/.omnimancer/config.json` (API keys are encrypted at rest).
You can edit it directly or, more conveniently, configure everything from the CLI:

```bash
omn
# Configure a provider in one step (api key is encrypted before storage)
>>> /config set-provider claude --api-key sk-ant-...
>>> /config set-provider openai --api-key sk-... --model gpt-4o
>>> /config set-provider openrouter --api-key sk-or-... --model anthropic/claude-3.5-sonnet

# Set or change individual fields
>>> /config set providers.openai.base_url https://my-proxy.example.com/v1
>>> /config set providers.openai.max_tokens 8192
>>> /config set default_provider claude

# Inspect / clean up
>>> /config show
>>> /config get default_provider
>>> /config remove-provider openai
```

### Multiple endpoints

Each of these is just a provider you can point anywhere via `base_url`, so you can run
several endpoints side by side and switch between them with `/switch `:

| Endpoint | Provider name | Default base URL |
|----------|---------------|------------------|
| Claude (direct) | `claude` | `https://api.anthropic.com/v1` |
| OpenAI | `openai` | `https://api.openai.com/v1` |
| OpenRouter | `openrouter` | `https://openrouter.ai/api/v1` |
| DigitalOcean inference | `digitalocean` | `https://inference.do-ai.run/v1` |

Any OpenAI-compatible service (local proxy, gateway, self-hosted model) works by
overriding `base_url` on the `openai` provider.

### Self-hosted endpoints as named providers

Any number of OpenAI-compatible endpoints (vLLM, llama.cpp server, LM Studio, proxies) can be configured side by side under names you choose. `provider_type` picks the implementation; the entry name is yours:

```bash
>>> /config set-provider gateway --type openai-compatible \
        --base-url http://vllm-gateway.internal:8888/v1 --model qwen3-coder-30b
>>> /config set-provider local --type openai-compatible \
        --base-url http://localhost:8000/v1 --model qwen3-coder-30b
>>> /switch local
```

The `openai-compatible` type is keyless by default (`auth_type: "none"`), takes its model catalog from the endpoint's `/v1/models` (including each model's served context size — see `/models refresh`), and raises timeout errors with a cold-start hint since self-hosted gateways may load a model on first request. Set `providers..timeout` generously for such endpoints (e.g. `360`).

### Prompt enhancement (optional)

`/enhance` and the `e:` message prefix rewrite a draft prompt with a dedicated model before sending, using the [PromptFoundry](https://github.com/gitshipdone/promptfoundry) meta-prompts (same author; that repo is the canonical source for the prompt texts and is being prepared for public release).

The feature is **opt-in**: it activates only when your config carries an `enhancement` block. Without one, `e:` is not intercepted and `/enhance` points you here.

```json
"enhancement"

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [nvasion](https://github.com/nvasion)
- **Source:** [nvasion/omnimancer](https://github.com/nvasion/omnimancer)
- **License:** MIT
- **Homepage:** https://factory-nexus.ai/packages/omnimancer

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-nvasion-omnimancer
- Seller: https://agentstack.voostack.com/s/nvasion
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.