Metadata-Version: 2.4
Name: omnimancer-cli
Version: 0.2.6
Summary: A unified command-line interface for multiple AI language models
Author-email: Kellan Strong <kellan@jite.ai>
License: MIT
Project-URL: Homepage, https://github.com/nvasion/omnimancer
Project-URL: Repository, https://github.com/nvasion/omnimancer
Project-URL: Issues, https://github.com/nvasion/omnimancer/issues
Keywords: ai,cli,chat,openai,claude,language-model
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: certifi>=2023.0.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: html2text>=2020.1.16
Requires-Dist: jsonschema>=4.17.0
Requires-Dist: readability-lxml>=0.8.1
Requires-Dist: PyYAML>=6.0.0
Requires-Dist: toml>=0.10.2
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Omnimancer

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

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

# Output formats
omn -p "summarize this repo"                                # plain text (default)
omn -p "summarize this repo" --output-format json           # structured JSON
omn -p "summarize this" --output-format stream-json         # streaming JSON

# Auto-approve all tool operations (CI/scripts)
omn -p "fix the failing tests" --dangerously-skip-permissions

# Verbose output / explicit config file
omn -p "audit the security module" --verbose --config ~/.omnimancer/config.json
```

The `--provider`, `--model`, and `--base-url` flags are **session overrides**: they
modify the in-memory config for this run only and are never written back to disk.

Headless mode with `--output-format json` emits a single structured result
object — including the tool calls the agent made along the way:

```json
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "result": "Here's the refactored code...",
  "session_id": "…",
  "model": "claude-sonnet-4-20250514",
  "num_turns": 3,
  "tool_calls": [
    {"name": "file_read", "arguments": {"path": "src/auth.py"}, "error": null},
    {"name": "file_write", "arguments": {"path": "src/auth.py"}, "error": null}
  ],
  "usage": {"input_tokens": 1523, "output_tokens": 892, "total_cost_usd": 0.04},
  "total_cost_usd": 0.04,
  "stop_reason": "end_turn"
}
```

On failure it stays valid JSON (stdout), with the error and any tool calls made:

```json
{"type": "result", "subtype": "error", "is_error": true, "error": "…", "tool_calls": [...]}
```

For a live, line-by-line stream of what the agent is doing (assistant text,
each `tool_use`, each `tool_result`, then the final `result`), use
`--output-format stream-json`.

### Interactive mode

```bash
omn                                  # start interactive REPL
omn --provider openai                # start with a specific provider (session-only)
omn --no-approval                    # skip approval prompts
omn --dangerously-skip-permissions   # auto-approve all tool operations
```

Interactive mode gives you a REPL with streaming responses, token/cost display, and agent capabilities:

```
>>> 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 |
| 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 <provider> [model]` | Switch provider or model |
| `/models [filter]` | List available models (alias: `/model`) |
| `/providers` | List all providers with status |
| `/agent on\|off\|status` | Toggle agent mode |
| `/subagents [run <name> <task>]` | List or run scoped child agents |
| `/config show\|get\|set` | View or modify configuration |
| `/config set-provider <name> [--api-key …] [--base-url …] [--model …]` | Create/update a provider |
| `/config remove-provider <name>` | Remove a provider |
| `/hooks [list\|on\|off\|add\|remove]` | Manage lifecycle hooks |
| `/permissions [list\|on\|off\|allow\|deny\|ask\|remove]` | Manage permission rules |
| `/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\|<name> [key=value …]]` | List and render MCP prompts |
| `/mcp [status\|reload\|connect\|disconnect\|health] [server]` | MCP server management |
| `/add-model <name> <provider> [description]` | Register a custom model |
| `/remove-model <name> <provider>` | 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 <provider>`:

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

### Environment variable overrides

Environment variables take precedence over the saved config and are applied at
runtime only (never written back to disk). This makes them ideal for CI and for
testing endpoints without touching `config.json`.

```bash
# Conventional API keys
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export OPENROUTER_API_KEY="sk-or-..."
export DIGITALOCEAN_INFERENCE_KEY="..."

# Per-provider overrides: OMNIMANCER_<PROVIDER>_{API_KEY,BASE_URL,MODEL}
export OMNIMANCER_OPENAI_BASE_URL="http://localhost:1234/v1"
export OMNIMANCER_DIGITALOCEAN_MODEL="llama3.3-70b-instruct"

# Pick the default provider for this run
export OMNIMANCER_DEFAULT_PROVIDER="digitalocean"
omn
```

You can also override the endpoint for a single headless run with `--base-url`:

```bash
omn -p "summarize README.md" --provider openai --base-url http://localhost:1234/v1
omn -p "explain this repo" --provider digitalocean --model llama3.3-70b-instruct
```

### Provider-specific setup

**Claude (Anthropic):**
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
# Models: claude-sonnet-4, claude-opus-4, claude-3-5-sonnet
```

**OpenAI:**
```bash
export OPENAI_API_KEY="sk-..."
# Models: gpt-4o, gpt-4-turbo, gpt-3.5-turbo
```

**Google Gemini:**
```bash
export GOOGLE_API_KEY="..."
# Models: gemini-1.5-pro, gemini-1.5-flash
```

**AWS Bedrock:**
```bash
# Uses AWS credentials (env vars, ~/.aws/credentials, or IAM role)
export AWS_DEFAULT_REGION="us-east-1"
# Models: anthropic.claude-3-5-sonnet, amazon.titan
```

**OpenRouter:**
```bash
export OPENROUTER_API_KEY="sk-or-..."
# Models: anthropic/claude-3.5-sonnet, openai/gpt-4o, and 100+ more
```

**DigitalOcean inference (OpenAI-compatible):**
```bash
export DIGITALOCEAN_INFERENCE_KEY="..."
# Default endpoint: https://inference.do-ai.run/v1
# Models: llama3.3-70b-instruct, llama3-8b-instruct, openai-gpt-4o
# Override the endpoint if needed:
export OMNIMANCER_DIGITALOCEAN_BASE_URL="https://inference.do-ai.run/v1"
```

**Ollama (local, no API key):**
```bash
ollama serve
ollama pull llama3.1
omn
>>> /switch ollama llama3.1
```

**Azure OpenAI:**
```bash
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
```

## Architecture

```
omnimancer/
├── cli/                    # CLI interface (modular)
│   ├── interface.py       # Core REPL loop, streaming integration
│   ├── headless.py        # -p pipeline mode (text/json/stream-json)
│   ├── command_dispatch.py # Slash command handlers
│   ├── agent_loop.py      # Marker-based agent workflow
│   ├── tool_handler.py    # Native tool call execution
│   ├── subagent.py        # Scoped child agent runner
│   ├── system_prompts.py  # Prompt building
│   ├── display.py         # Terminal output & token status
│   └── completion.py      # Tab completion
├── core/                   # Engine & business logic
│   ├── engine.py          # Provider abstraction & streaming delegation
│   ├── agent_engine.py    # Autonomous agent capabilities
│   ├── agent_managers.py  # Executor/web/MCP/approval manager facades
│   ├── hooks.py           # Lifecycle hooks manager
│   ├── models.py          # Data models (ChatResponse, StreamEvent, etc.)
│   ├── agent/             # File ops, approval, tool definitions
│   └── security/          # Permission rules, path validation, sandboxing
├── providers/              # 13+ AI provider implementations
│   ├── base.py            # Provider interface (streaming fallback)
│   ├── claude.py          # Anthropic (native streaming & tool calling)
│   ├── openai.py          # OpenAI (native tool calling)
│   └── ...
├── ui/                     # Terminal UI components
│   └── streaming_display.py # Rich Live streaming display
└── mcp/                    # Model Context Protocol (official mcp SDK)
    ├── client.py          # Per-server lifecycle (stdio/SSE/HTTP)
    └── manager.py         # Multi-server orchestration
```

### Streaming architecture

Streaming uses async generators that flow through the full stack:

```
Provider (SSE parsing) → Engine (delegation) → Interface (display routing)
                                                  ↓
                                          StreamingDisplay (Rich Live panel)
```

Each layer yields `StreamEvent` objects. Providers that don't implement real streaming get an automatic fallback in `BaseProvider` that wraps the full response in the same event format, so the UI code works identically for all providers.

## Development

```bash
git clone https://gitlab.com/jite-ai/omnimancer
cd omnimancer
pip install -e ".[dev]"
pytest tests/ -v
```

Tests follow TDD. 1,460 tests across providers, CLI, streaming, agent operations, hooks, permissions, MCP, and integration scenarios (including a real MCP stdio server exercised end-to-end).

## License

MIT
