Hormuz

Hormuz is a customer-local model router for existing coding clients. Its entry points are a terminal CLI and a skills-only plugin that calls the same setup, status and disconnect implementation. Coding clients retain their editor, tools, permissions and agent loop.

The approved workflow is connect → submit a coding-client request through the router → inspect result/status → disconnect. See scope and implementation order and specification #523.

The current source implements destination ownership, automatic route admission, hard local-only enforcement and recoverable Codex CLI connection lifetime. Routine tests use disposable clients and model endpoints. Real llama.cpp/model quality, subscription eligibility, installed-platform support and plugin distribution remain separate qualification work. The plugin bundles setup, status, troubleshooting and disconnect instructions over the CLI. MCP is optional if a concrete integration needs it.

A pinned Codex → llama.cpp profile now records real local tool execution, incremental streaming, cancellation and restoration. Its supplied-script case passed; autonomous repair and strict answer formatting failed. That historical run used manual work binding; the router now supports automatic conversation binding for the recognized native HTTP envelope.

An optional managed llama.cpp profile now starts and stops one engine from existing verified runtime/model files through the same connection commands. It verifies bundled libraries as well as the launcher, preserves external engines, and keeps cleanup pending until its owned lease is released. Verified acquisition now previews and explicitly downloads the existing pinned experimental runtime/model into a private generation. Model selection and coding qualification remain separate.

Shared local setup now generates the local-only configuration from existing verified engine/model files and connects through that same owner. The CLI and plugin use client setup codex; repeated setup reuses the configuration and active generation, and preserves edited files. The installed router remains a prerequisite. Setup now creates a private local caller credential and configures Codex's command-backed authentication without manual token exports. See local credential setup.

Opt-in shadow routing records a local model's routing recommendation alongside the actual attempt. Shared setup accepts --shadow-router; recommendations preserve existing routing, local-only policy and conversation affinity.

Local coding qualification now gates automatic coding admission on a pinned, predeclared campaign of actual edits, independent checks and normal completion. The bundled experiment remains unqualified for automatic coding. Engine health and shadow advice do not grant that qualification.

Install in your agent

The plugin manifests and shared CLI implementation are included in this source. Installation remains subject to each coding client's plugin support and review.

Codex

codex plugin marketplace add Xpounder-com/hormuz
codex plugin add hormuz@hormuz

Use a CLI with codex plugin add (checked on 0.160.0). Alternatively, after adding the marketplace, select Hormuz in your client's plugin browser and install it.

Gemini CLI

gemini extensions install https://github.com/Xpounder-com/hormuz

Restart the Gemini CLI session after installation.

GitHub Copilot CLI

copilot plugin marketplace add Xpounder-com/hormuz
copilot plugin install hormuz@hormuz

Claude Code

claude plugin marketplace add Xpounder-com/hormuz
claude plugin install hormuz@hormuz

Inside Claude Code, the equivalent commands start with /plugin instead of claude plugin. Start a new session or reload plugins after installation.

Cursor, OpenCode and other skill-capable agents

Use the open Agent Skills installer (requires Node.js/npm). Choose your agent when prompted:

npx skills add Xpounder-com/hormuz --skill hormuz

Or select it explicitly with --agent cursor or --agent opencode.

After installation, ask: “Use Hormuz to set up local-only routing for Codex.” The skill checks the installed router, client version and route qualification before using shared setup. Plugin installation installs instructions; the router runtime and a qualified local model are separate prerequisites. The implemented persistent connection supports Codex CLI 0.147.0 and the 0.160.0 single-agent HTTP profile. Other agents can use the skill to manage that connection; their own inference-routing adapters are not implemented. See installation, updates, removal and compatibility.

Source evaluation

Use Python 3.11 or later in a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install .
python -m hormuz --help
python -m unittest tests.test_execution_destination_workflow tests.test_connected_client_lifetime_workflow

Installation may download Python dependencies. Tests require loopback access; they use temporary files and processes with synthetic credentials. They do not contact external model providers or change your active coding-client settings.

For deliberate setup, copy config.example.json to hormuz.json, set the environment token named by its local identity, and review:

hormuz --config hormuz.json client connect codex --dry-run
hormuz --config hormuz.json client connect codex
hormuz client status codex
hormuz client disconnect codex

The example is deliberately unqualified and blocks inference until a real local route has been qualified. It does not install a model or claim a known-good runtime. See admission, connection lifetime and support.

Product limits

Local-only blocks every intercepted model path from cloud execution, including helpers. It does not control unrelated coding-client tools, plugins or network connections. Automatic mode considers only eligible qualified local routes; unknown evidence uses an explicitly permitted baseline or blocks. Continuing tool and provider state retains destination affinity.

Codex subscription access is not established by login or these tests. There is no automatic fallback to billable API usage. Unknown costs remain unknown.

Inspect cloud authorization readiness before changing settings with hormuz --config hormuz.json client cloud-readiness codex. The opt-in native Codex catalog adds separate gateway/native authentication for discovery; native inference remains blocked. The read-only receipt distinguishes declared API access from the two separately authorized ChatGPT plan paths and reports their remaining blockers.

Optional local history adds encrypted, redacted text review and spending estimates on your device. Collection starts disabled; hormuz --config hormuz.json history enable opts in for future intercepted requests. Use history list, history show, history insights, history export, history delete and history disable to control retained data. No training or cloud upload is part of this feature; exports are explicitly decrypted files.

The 2.0 development line retires standalone apps, hosted/enterprise front doors, billing and PostgreSQL deployment support. Migration and rollback describe the breaking changes. Existing releases, local user data and cloud resources are not deleted by this repository cleanup. Operational resource cleanup remains open.

Use CONTRIBUTING.md, SUPPORT.md, SECURITY.md and CODE_OF_CONDUCT.md.

Plugin capabilities

The skills-only plugin now offers focused diagnosis, observed request explanations, bounded local model probes, advisory recommendations, privacy/budget staging, usage insights and safe restoration. See the capability contract and command workflow for coverage and limits.