Skip to content

saurabmishra12/model-advisor

v0.3.0MIT

Local cost-aware model planning, execution and verification through an installed Model Advisor CLI.

Model Advisor

Local model routing, per-workflow budgets and verification for Codex and Antigravity. Provides advisor_status, advisor_plan and advisor_run, plus the model-advisor skill. The default configuration uses mock providers and makes no paid API calls. Install the Python runtime before the plugin.

Install

From the source repository, with Python 3.11+ and uv:

uv tool install .
model-advisor-plugin --help

Ensure uv's tool bin directory is on the PATH seen by the desktop apps, then restart the apps. A virtual environment with pip install . also works if its scripts directory is on that PATH. The plugin does not bundle a Python runtime.

Codex, from the repository root:

codex plugin marketplace add .
codex plugin add model-advisor@model-advisor-marketplace

Antigravity App or CLI, from the repository root:

agy plugin install ./integrations/model-advisor
agy plugin list --json

Use a new chat after installation. Ask: "Use Model Advisor to check its status." In Antigravity the skill can also be invoked with /model-advisor. In Codex select Model Advisor from the plugin picker. Installation enables explicit tool use; it does not intercept every message or replace your conversation's model.

Standalone Antigravity IDE versions without plugin installation can register the same server through MCP Servers > Manage MCP Servers > View raw config:

{
  "mcpServers": {
    "model-advisor": {
      "command": "model-advisor-plugin",
      "args": ["--plugin-root", "/absolute/path/to/model-advisor/integrations/model-advisor"]
    }
  }
}

Merge the server entry into your existing configuration, preserving other servers. The IDE fallback supplies MCP tools; install the shared skill through that IDE's supported skill flow if desired.

Choose a real configuration and workspace

Set these environment variables before starting either host, or add them to its MCP server's env object. Use absolute paths and keep credentials out of Git:

export MODEL_ADVISOR_CONFIG=/absolute/path/to/advisor.json
export MODEL_ADVISOR_WORKSPACE=/absolute/path/to/existing/project

Configure provider keys using the environment variable names in advisor.json. API usage is separate from your Codex or Antigravity subscription. The engine supports OpenAI, Anthropic and HTTPS Chat Completions gateways; an Antigravity installation does not add a Gemini API adapter. The repository's examples/configure_api.py --help explains how to create a live configuration with exact model identifiers and configured prices. Invalid paths or invalid configuration stop startup; they do not silently switch to the demo.

Without overrides, the demo uses a dedicated writable workspace. Antigravity provides PLUGIN_DATA; otherwise data defaults to ${XDG_STATE_HOME:-~/.local/state}/model-advisor. Workspace-specific state is stored under workspaces/<workspace-hash>/latest.json. An optional absolute MODEL_ADVISOR_STATE selects a different state file. Installed plugin files remain read-only inputs.

MCP calls take process locks for the workspace and state file. If another session is using either, planning and execution return a busy result. Retry after that session finishes. These locks coordinate MCP sessions; direct CLI commands and unrelated programs do not participate in them.

Tasks without independent acceptance checks remain unverified. Mock accounting is simulated. Native host calls are outside the engine's budget and usage ledger. This local stdio package needs a local executor and does not provide a hosted MCP endpoint or demonstrated cost savings.

Sources

Compact execution harness (0.3.0)

Use advisor_status first to inspect mock mode, workspace and enforced limits. advisor_run and advisor_plan accept a checks array of host-owned acceptance checks. detail defaults to summary; use detail="full" to retrieve complete artifact content and ledger. Summary text truncation is explicitly marked and does not affect worker dependency context or on-disk evidence.

API workers execute a bounded dependency graph, not recursive host agents. The included skill also instructs native Codex/Antigravity agents how to delegate with explicit ownership, compact handoffs, checks and stopping conditions. Native agent calls remain outside the API engine's accounting.