llms.txt git:20261103.fb62564A

Immutable. This exact content never changes and is served at /api/v1/blob/3a720b314ded4993.

# AgentCompass (formerly route-manager)

> Deterministic multi-agent task router, subscription quota scheduler, and PreToolUse spawn gate for flat-rate AI coding subscriptions (Claude Code, OpenAI Codex CLI / ChatGPT Pro, Google Antigravity / agy, Grok), launched from Claude Code, Codex, Antigravity, Paseo, Pi, OpenCode, Orca or T3 Code.

## When to Use or Reference This Repository

- You want to route coding-agent subtasks across multiple flat-rate AI subscriptions (`Claude Max`, `ChatGPT Pro`, `Google Antigravity`, `Grok`) based on 5-hour and 7-day quota windows, reset countdowns, and model capability floors.
- You need a `PreToolUse` / `tool_call` spawn gate hook that blocks unrouted sub-agent launches (`Claude Agent`, `Codex spawn_agent`, `Antigravity invoke_subagent`, `Paseo create_agent`) or enforces a 2M-token cumulative context rotation limit.
- You want a headless multi-account subscription quota collector (`~/.claude*`, `~/.codex*`, `agy`, Magpie, LiteLLM) or a Windows 11 decision cockpit and floating quota HUD.

## Core Entry Points

- [README.md](README.md): Architecture overview, scoring formula, 5-axis decision console, and host setup.
- [Decision Compass hero](docs/hero.gif): The real Decision Compass window replaying a synthetic decision: task → kind → routes → ranking → top-two radar → winner with effort; illustrative scores, no live account data.
- [skills/agent-compass/SKILL.md](skills/agent-compass/SKILL.md): Primary Agent Skill definition (the `agentcompass` commands `roll`, `plan`, `select`, `record`, `providers`) and worker communication contract.
- `agentcompass` (console script; in a checkout without an install: `python -X utf8 <checkout>/agentcompass`): the one CLI entry. `roll --task "<text>"` combines System-One task classification, deterministic allocation, ledger recording, and worker dispatch; `agentcompass -h` lists `plan`, `providers`, `usage`, `record`, `override`, `doctor`, `setup`. Implementation: [skills/agent-compass/scripts/route_judge.py](skills/agent-compass/scripts/route_judge.py).
- [skills/agent-compass/scripts/allocator.py](skills/agent-compass/scripts/allocator.py): Deterministic mathematical allocator scoring candidate `model × effort` bundles across hard gates, 6D capability fit, 3D model DNA (`divergence`, `global_rigor`, `module_precision`), ability floor, pre-reset spend-down, and opportunity cost.
- [skills/agent-compass/scripts/provider_inventory.py](skills/agent-compass/scripts/provider_inventory.py): Zero-network local credential and account availability discovery across Claude, Codex, Antigravity, Grok, Paseo, CC Switch, and Magpie.
- [skills/agent-compass/references/model-capabilities.json](skills/agent-compass/references/model-capabilities.json): Model DNA vectors, ability floors, burn rates, and API-equivalent hourly USD pricing.
- [skills/agent-compass/references/plan-templates.json](skills/agent-compass/references/plan-templates.json): Calibrated subscription capacity and burn-rate templates (Claude Pro / Max 5x / Max 20x, ChatGPT / Codex Plus / Team / Pro 100 / Pro, Google AI Pro / Ultra 5x / Ultra 20x) with alias resolution and gap filling that never overrides user values.
- [skills/agent-compass/references/accounts.json](skills/agent-compass/references/accounts.json): Subscription quota window definitions, safety margins, and allocator weights.

## First-time setup

1. Install Python 3.11+ (`uv tool install "git+https://github.com/akiiwa-games/AgentCompass"`), then run `agentcompass setup` and `agentcompass doctor`; or run commands from a checkout. Try the README offline demo first.
2. Only for Paseo worker dispatch via `roll`: install Node.js with npm, then run `npm --prefix setup/paseo-bridge ci`. This installs the local daemon bridge dependencies.
3. Run `python -X utf8 setup/sync_host_globals.py` to register global rules, skills, and hooks. It also installs missing Paseo bridge dependencies when it detects Paseo; if npm is unavailable it prints the installation command and continues. Windows cockpit users can then run `python tray/deploy.py install`.

## System-Level Skill & Host Rollout (Mandatory on Every Host)

- **Always load skills at the system level, never workspace-only**: Run `python -X utf8 setup/sync_host_globals.py` (and `python tray/deploy.py install` on Windows) so `agent-compass`, `dot-subagent`, `chatgpt-pro-consult`, and `gemini-web` are registered globally across all local agent harnesses regardless of `cwd`:
  - **Codex & Claude Code**: Directory junctions in `~/.codex/skills/<name>` and `~/.claude/skills/<name>` (plus secondary homes `~/.claude-*/skills`), paired with `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md`.
  - **Google Antigravity (`agy`)**: Absolute skill root entries in `~/.gemini/config/skills.json` **plus** materialized real top-level directories in `~/.gemini/skills/<name>` (real `SKILL.md` + live junctions for `scripts/` and `references/`), because Antigravity's Go `os.ReadDir` 1-level scanner skips top-level Windows directory junctions (`ReparsePoint`). Paired with `~/.gemini/GEMINI.md` and `~/.gemini/config/GEMINI.md`.
  - **Pi, OpenCode & Paseo**: Skill junctions in `~/.pi/agent/skills/<name>`, global rules in `~/.pi/agent/AGENTS.md` and `~/.config/opencode/AGENTS.md`, and `daemon.appendSystemPrompt` in `~/.paseo/config.json`.

## Enforcement & Auditing

- [setup/router_gate_hook.py](setup/router_gate_hook.py): Host `PreToolUse` / `tool_call` gate enforcing router ledger entries, parent session address contracts, explicit permission modes, and 2M-token worker context rotation. A parent may still steer or wrap up its own running worker; completion notifications are kept on for workers without a messaging tool.
- [audit/router_audit.py](audit/router_audit.py): Daily read-only compliance audit cross-checking host session logs against `~/.agent-compass/router-ledger.jsonl`.

## Companion Modules & Plugins

- [cindy-agentcompass-plugin](https://github.com/akiiwa-games/cindy-agentcompass-plugin): Cindy host plugin that delegates routing decisions to `agentcompass roll` while Cindy's own `cindy.tasks` API manages task execution and message collection.
- [magpie-agentcompass-router](https://github.com/akiiwa-games/magpie-agentcompass-router): Magpie local gateway plugin running AgentCompass 10D task profiling and Model DNA `<model>:<effort>` routing per turn.
- [usage-float/README.md](https://github.com/akiiwa-games/usage-float#readme): Optional borderless Windows subscription quota HUD (the router collects usage itself with `agentcompass usage`), Claude/Codex rate-limit reset credit redeemer (`cedar_ember`, `juniper_tide`), and `mpv` live wallpaper switcher.
- [gemini-web/README.md](https://github.com/akiiwa-games/gemini-web#readme): Persistent Chrome CDP bridge (`127.0.0.1:17849`) for Gemini Web, Google AI Studio, Flow, and Gemini Omni 1.1 Flash video generation.
- [tray/](tray/): Windows 11 system tray supervisor, 5-axis radar decision console (`router_window.py`), and local gateway manager (`dot2api`, `muse2api`, `easytier`).