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.