agroute 0.1.0__tar.gz

agroute-0.1.0/.agents/plugins/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "agroute",
+  "plugins": [
+    {
+      "name": "agroute",
+      "source": {"source": "local", "path": "./"},
+      "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
+      "category": "Productivity"
+    }
+  ]
+}

agroute-0.1.0/.antigravity-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "agroute",
+  "displayName": "agroute",
+  "version": "0.1.0",
+  "description": "Route delegated tasks across Codex, Claude Code, and Antigravity within live usage limits using howhard.",
+  "author": {"name": "agroute contributors"},
+  "repository": "https://github.com/xu-hao/agroute"
+}

agroute-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,12 @@
+{
+  "name": "agroute",
+  "description": "The agroute skill for usage-limit-aware local agent routing with howhard.",
+  "owner": {"name": "agroute contributors"},
+  "plugins": [
+    {
+      "name": "agroute",
+      "source": "./",
+      "description": "Usage-limit-aware local agent routing across Codex, Claude Code, and Antigravity with howhard."
+    }
+  ]
+}

agroute-0.1.0/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "agroute",
+  "version": "0.1.0",
+  "description": "Route delegated tasks across Codex, Claude Code, and Antigravity within live usage limits using howhard.",
+  "author": {"name": "agroute contributors"},
+  "repository": "https://github.com/xu-hao/agroute"
+}

agroute-0.1.0/.readthedocs.yaml

@@ -0,0 +1,13 @@
+version: 2
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

agroute-0.1.0/AGENTS.md

@@ -0,0 +1,39 @@
+# agroute contributor instructions
+
+Keep this file limited to repository-wide guardrails. Follow the canonical contracts and
+procedures listed in [docs/index.md](docs/index.md). These guardrails adopt AGCoord's
+contributor workflow for this repository.
+
+- Track every code, test, documentation, or packaging change with a descriptive issue.
+  Pair every issue number with a sentence explaining the work it tracks. Do not file an
+  issue solely for machine-local installation, deployment, configuration, service
+  lifecycle, or other operator state; create one only when that work also requires a
+  repository change or the user explicitly requests an issue.
+- Develop and validate only in an issue-specific Git worktree branched from `main`.
+  Preserve unrelated work and do not develop in the primary checkout.
+- Verify behavior at public boundaries. Start bug fixes with a failing behavioral test;
+  accompany runtime changes with focused tests, affected canonical documentation, and a
+  `CHANGELOG.md` entry when the change is user-facing.
+- A documentation-only change needs no tests or AGCoord gate. It qualifies only when every
+  changed path is `README.md`, `CHANGELOG.md`, `AGENTS.md`, Markdown below `docs/`, or a
+  `.png` or `.svg` image below `docs/assets/` whose provenance is recorded in
+  `docs/assets/README.md`. Verify the exact pull-request file list and diff, then merge it
+  through the forge; the issue, worktree, branch, pull-request, and no-direct-target-push
+  rules still apply.
+- Tests own and stop every process, repository, and temporary state they create.
+  Never inspect or clean another agent's state.
+- Keep the package independent of a parent application or sibling checkout.
+  Put project-specific assumptions in optional configuration; the ordinary workflow
+  must work with packaged defaults and explicit CLI/API inputs.
+- For every other change after bootstrap, route checks and publication through the local
+  coordinator, declare every scarce resource, and never submit coordinated work from an
+  admitted job. Gate and publish through one `agc land` request; never bypass or separate
+  its verdict from publication.
+- Never upload an agroute distribution to PyPI unless the user explicitly requests it.
+  Permission to implement, test, commit, push, merge, tag, or create a GitHub release
+  does not authorize an upload.
+- End changed work with the four-part [session handoff](docs/session_handoff_format.md);
+  answer read-only questions directly without an empty handoff shell.
+- Follow the [contributor workflow](docs/contributing.md) for commands, bootstrap,
+  recovery, and cleanup. The [routing and storage contracts](docs/reference.md) and
+  [release guide](docs/releasing.md) define the corresponding component contracts.

agroute-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 — 2026-11-08
+
+- Build `agroute` (`agroute` CLI, Python `Router` API, and native plugin manifests for
+  Codex, Claude Code, and Antigravity) to route delegated tasks across local coding agents
+  within live usage limits.
+- Track per-agent (`codex`, `claude`, `agy`) quota windows (`session_5h`, `weekly_7d`, and
+  model-tier limits) and rate-limit cooldowns from native command and event-stream outputs
+  (`agroute usage show|set|ingest|probe|clear`) with automatic reset-window expiration.
+- Emit `howhard` 2.1+-compatible candidate lists (`agroute candidates`) and named
+  `[inventories]` (`agroute inventory`) with provider-qualified `<agent>/<model>` identities,
+  separating `native_candidates` (when `target == host`) from `cli_candidates` (when
+  `target != host`).
+- Resolve `howhard` decision receipts (`agroute plan`) into deterministic
+  `agroute-execution-plan-v1` payloads (`invoke_subagent`, `Agent`, or `spawn_agent` when
+  `target == host`; `codex exec`, `claude -p`, or `agy -p` when `target != host`), with
+  configurable `host_affinity_epsilon` and explicit `howhard observe` feedback guidance.

agroute-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agroute contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agroute-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include AGENTS.md CHANGELOG.md LICENSE
+include .readthedocs.yaml
+include plugin.json
+include .agents/plugins/marketplace.json
+include .claude-plugin/plugin.json .claude-plugin/marketplace.json
+include .antigravity-plugin/plugin.json
+recursive-include docs *.md *.py *.txt
+recursive-exclude docs/_build *
+recursive-include scripts *
+recursive-include skills *.md
+recursive-include tests *.py

agroute-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: agroute
+Version: 0.1.0
+Summary: Configurable local agent router across Codex, Claude Code, and Antigravity with native usage-limit filtering and howhard integration.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/xu-hao/agroute
+Project-URL: Repository, https://github.com/xu-hao/agroute
+Project-URL: Issues, https://github.com/xu-hao/agroute/issues
+Project-URL: Changelog, https://github.com/xu-hao/agroute/blob/main/CHANGELOG.md
+Keywords: coding-agents,claude-code,codex,antigravity,agent-router,howhard,rate-limits
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: build>=1.2; extra == "test"
+Requires-Dist: twine>=5; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=8; extra == "docs"
+Requires-Dist: myst-parser>=4; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Dynamic: license-file
+
+# agroute
+
+*Route delegated agent tasks across local coding agents within live usage limits.*
+
+`agroute` is a configurable, **plan-only** local task router for coding agents (`codex`,
+`claude`, and `agy`). Given a host agent and native quota/rate-limit state, it filters
+available `(agent, model, effort)` candidate routes, emits a [`howhard` 2.1+](https://github.com/xu-hao/howhard)
+candidate inventory with provider-qualified model identities (`<agent>/<model>`), and
+resolves a `howhard` decision into a deterministic execution plan:
+
+- **Native host delegation** (`target_agent == host_agent`): emits a structured native
+  subagent tool directive for the current host (`invoke_subagent` in Antigravity,
+  `Agent` in Claude Code, or `spawn_agent` in Codex).
+- **Cross-agent CLI execution** (`target_agent != host_agent`): emits a non-interactive
+  CLI execution plan (`codex exec --json`, `claude -p --verbose --output-format stream-json`,
+  or `agy -p --output-format stream-json`) with exact model, effort, and output-capture
+  adapter metadata.
+
+`agroute` never spawns worker processes itself. Model/effort selection, outcome observation,
+portable execution accounting, and writable semantic memory remain in `howhard`.
+
+## Quickstart
+
+You need Python 3.11+, a POSIX shell, Git, [`howhard` 2.1+](https://pypi.org/project/howhard/2.1.0/),
+and a current Codex, Claude Code, or Antigravity client with native plugin support.
+
+Install `agroute` and `howhard` in your project environment:
+
+```sh
+python3 -m venv .venv-agroute
+. .venv-agroute/bin/activate
+python -m pip install "agroute==0.1.0" "howhard>=2.1.0"
+agroute --version
+```
+
+Expect `agroute 0.1.0`. Keep the environment active and start your coding agent from the
+same shell so it can find `agroute` and `howhard`.
+
+Install the native plugin for your host:
+
+```sh
+# Codex
+codex plugin marketplace add xu-hao/agroute
+codex plugin add agroute@agroute
+```
+
+```sh
+# Claude Code
+claude plugin marketplace add xu-hao/agroute
+claude plugin install agroute@agroute
+```
+
+```sh
+# Antigravity
+agy plugin install https://github.com/xu-hao/agroute
+agy plugin list
+```
+
+Invoke the skill explicitly with `$agroute` or `/skills` in Codex, `/agroute:agroute` in
+Claude Code, or `/agroute` in Antigravity.
+
+## Core workflow
+
+1. **Inspect or update native quota state**:
+
+   ```sh
+   agroute usage show --json
+   agroute usage ingest --agent codex --file /tmp/codex-status.jsonl --json
+   agroute usage set --agent claude --session-used-pct 92 --session-reset-at 2026-11-08T21:00:00Z --json
+   ```
+
+2. **Emit filtered `howhard` candidates for the current host**:
+
+   ```sh
+   agroute candidates --host agy --output /tmp/task-candidates.json --json
+   ```
+
+3. **Select a cell with `howhard`** (calling-agent `context`/`retrieve`/`decide` or `pick`)
+   and **resolve the decision into an execution plan**:
+
+   ```sh
+   agroute plan --host agy --decision /tmp/task-decision.json --prompt-file /tmp/task.txt --json
+   ```
+
+4. **Execute the returned plan** (native tool call when `target_agent == host_agent`, or
+   CLI command when `target_agent != host_agent`) and **record the outcome in `howhard`**:
+
+   ```sh
+   howhard observe DECISION_ID clean --id EXECUTION_ID --json
+   ```
+
+See the [quickstart](docs/quickstart.md), [documentation index](docs/index.md),
+[routing and storage contracts](docs/reference.md), [configuration guide](docs/configuration.md),
+[skill guide](docs/skills.md), and [changelog](CHANGELOG.md). Contributors use
+[AGCoord and isolated worktrees](docs/contributing.md).

agroute-0.1.0/README.md

@@ -0,0 +1,95 @@
+# agroute
+
+*Route delegated agent tasks across local coding agents within live usage limits.*
+
+`agroute` is a configurable, **plan-only** local task router for coding agents (`codex`,
+`claude`, and `agy`). Given a host agent and native quota/rate-limit state, it filters
+available `(agent, model, effort)` candidate routes, emits a [`howhard` 2.1+](https://github.com/xu-hao/howhard)
+candidate inventory with provider-qualified model identities (`<agent>/<model>`), and
+resolves a `howhard` decision into a deterministic execution plan:
+
+- **Native host delegation** (`target_agent == host_agent`): emits a structured native
+  subagent tool directive for the current host (`invoke_subagent` in Antigravity,
+  `Agent` in Claude Code, or `spawn_agent` in Codex).
+- **Cross-agent CLI execution** (`target_agent != host_agent`): emits a non-interactive
+  CLI execution plan (`codex exec --json`, `claude -p --verbose --output-format stream-json`,
+  or `agy -p --output-format stream-json`) with exact model, effort, and output-capture
+  adapter metadata.
+
+`agroute` never spawns worker processes itself. Model/effort selection, outcome observation,
+portable execution accounting, and writable semantic memory remain in `howhard`.
+
+## Quickstart
+
+You need Python 3.11+, a POSIX shell, Git, [`howhard` 2.1+](https://pypi.org/project/howhard/2.1.0/),
+and a current Codex, Claude Code, or Antigravity client with native plugin support.
+
+Install `agroute` and `howhard` in your project environment:
+
+```sh
+python3 -m venv .venv-agroute
+. .venv-agroute/bin/activate
+python -m pip install "agroute==0.1.0" "howhard>=2.1.0"
+agroute --version
+```
+
+Expect `agroute 0.1.0`. Keep the environment active and start your coding agent from the
+same shell so it can find `agroute` and `howhard`.
+
+Install the native plugin for your host:
+
+```sh
+# Codex
+codex plugin marketplace add xu-hao/agroute
+codex plugin add agroute@agroute
+```
+
+```sh
+# Claude Code
+claude plugin marketplace add xu-hao/agroute
+claude plugin install agroute@agroute
+```
+
+```sh
+# Antigravity
+agy plugin install https://github.com/xu-hao/agroute
+agy plugin list
+```
+
+Invoke the skill explicitly with `$agroute` or `/skills` in Codex, `/agroute:agroute` in
+Claude Code, or `/agroute` in Antigravity.
+
+## Core workflow
+
+1. **Inspect or update native quota state**:
+
+   ```sh
+   agroute usage show --json
+   agroute usage ingest --agent codex --file /tmp/codex-status.jsonl --json
+   agroute usage set --agent claude --session-used-pct 92 --session-reset-at 2026-11-08T21:00:00Z --json
+   ```
+
+2. **Emit filtered `howhard` candidates for the current host**:
+
+   ```sh
+   agroute candidates --host agy --output /tmp/task-candidates.json --json
+   ```
+
+3. **Select a cell with `howhard`** (calling-agent `context`/`retrieve`/`decide` or `pick`)
+   and **resolve the decision into an execution plan**:
+
+   ```sh
+   agroute plan --host agy --decision /tmp/task-decision.json --prompt-file /tmp/task.txt --json
+   ```
+
+4. **Execute the returned plan** (native tool call when `target_agent == host_agent`, or
+   CLI command when `target_agent != host_agent`) and **record the outcome in `howhard`**:
+
+   ```sh
+   howhard observe DECISION_ID clean --id EXECUTION_ID --json
+   ```
+
+See the [quickstart](docs/quickstart.md), [documentation index](docs/index.md),
+[routing and storage contracts](docs/reference.md), [configuration guide](docs/configuration.md),
+[skill guide](docs/skills.md), and [changelog](CHANGELOG.md). Contributors use
+[AGCoord and isolated worktrees](docs/contributing.md).

agroute-0.1.0/docs/changelog.md

@@ -0,0 +1,2 @@
+```{include} ../CHANGELOG.md
+```

agroute-0.1.0/docs/conf.py

@@ -0,0 +1,10 @@
+from importlib.metadata import version as distribution_version
+
+project = "agroute"
+release = distribution_version("agroute")
+version = release
+extensions = ["myst_parser"]
+source_suffix = {".md": "markdown"}
+master_doc = "index"
+html_theme = "furo"
+exclude_patterns = ["_build"]

agroute-0.1.0/docs/configuration.md

@@ -0,0 +1,100 @@
+# Configuration
+
+`agroute` layers three configuration sources in order:
+
+1. Packaged defaults (`agroute/data/default_config.toml`).
+2. Optional user configuration at `${XDG_CONFIG_HOME:-~/.config}/agroute/config.toml`
+   (or `AGROUTE_USER_CONFIG`; disable with `--no-user-config`).
+3. Project `agroute.toml` in the current directory, or `--config PATH`.
+
+Unknown keys, out-of-range percentages, negative `host_affinity_epsilon`, bare models containing
+`/` or `:`, and `model_default` effort strings are refused before any state is modified.
+
+## Example `agroute.toml`
+
+```toml
+[routing]
+default_host = "agy"
+host_affinity_epsilon = 0.0
+namespace_separator = "/"
+
+[agents.agy]
+enabled = true
+max_session_used_pct = 90.0
+max_weekly_used_pct = 95.0
+max_tier_used_pct = 95.0
+host_reserve_pct = 5.0
+usage_probe_cmd = []
+
+[[agents.agy.native_candidates]]
+model = "pro"
+effort = "standard"
+tier = "pro"
+
+[[agents.agy.native_candidates]]
+model = "flash"
+effort = "standard"
+tier = "flash"
+
+[[agents.agy.cli_candidates]]
+model = "gemini-2.5-pro"
+effort = "high"
+tier = "pro"
+
+[agents.codex]
+enabled = true
+max_session_used_pct = 90.0
+max_weekly_used_pct = 95.0
+max_tier_used_pct = 95.0
+host_reserve_pct = 0.0
+usage_probe_cmd = []
+
+[[agents.codex.native_candidates]]
+model = "gpt-5.4"
+effort = "high"
+
+[[agents.codex.cli_candidates]]
+model = "gpt-5.4"
+effort = "high"
+
+[[agents.codex.cli_candidates]]
+model = "gpt-5.4"
+effort = "medium"
+
+[agents.claude]
+enabled = true
+max_session_used_pct = 90.0
+max_weekly_used_pct = 95.0
+max_tier_used_pct = 95.0
+host_reserve_pct = 0.0
+usage_probe_cmd = []
+
+[[agents.claude.native_candidates]]
+model = "claude-sonnet-4-6"
+effort = "high"
+tier = "sonnet"
+
+[[agents.claude.cli_candidates]]
+model = "claude-opus-4-6"
+effort = "high"
+tier = "opus"
+
+[[agents.claude.cli_candidates]]
+model = "claude-sonnet-4-6"
+effort = "high"
+tier = "sonnet"
+```
+
+(howhard-inventories)=
+## Generating `[inventories]` for `howhard.toml`
+
+`howhard` 2.1+ accepts explicitly named `[inventories]` in `howhard.toml` selected via
+`howhard ... --inventory NAME` or Python `inventory="NAME"`. Generate a filtered inventory
+table for the current host with:
+
+```sh
+agroute inventory --host agy --name router
+```
+
+When availability changes dynamically with live usage windows, pass the fresh candidate list
+from `agroute candidates --host HOST --output FILE` to `howhard ... --candidates FILE`.

agroute-0.1.0/docs/contributing.md

@@ -0,0 +1,31 @@
+# Contributor workflow
+
+Track every repository change with a descriptive issue, and report its number with a
+sentence describing the work. Develop and validate in an issue-specific worktree from
+`main`, preserving unrelated changes. Issue #1 specifies the multi-agent router and
+`howhard` integration; issues #2–#7 specify its package skeleton, native quota tracking,
+candidate emission, execution plan resolution, native plugin manifests, and behavioral
+acceptance tests.
+
+```sh
+git worktree add -b issue-N-description ../agroute-issue-N main
+cd ../agroute-issue-N
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[test,docs]'
+agc run --label "agroute tests" --resource cpu=1 -- .venv/bin/python -m pytest
+```
+
+Use the local AGCoord installation for checks and declare resources. Do not submit nested
+coordinator commands from admitted jobs. Tests use synthetic configs and state directories
+in their own temporary directories, exercise public behavior, and own all state they create.
+
+Update the affected canonical documents, list new documents in the index, and record
+user-facing changes in `CHANGELOG.md`. `AGENTS.md` is the canonical instruction source;
+`CLAUDE.md` is its relative symlink.
+
+The complete validation command is `scripts/check`. It runs tests, builds both distributions,
+verifies wheel and sdist contents/versions in a clean environment, and builds Sphinx with
+warnings treated as errors. Gate and publish through a single `agc land` request using that
+command when a change is ready to land. Never push directly to the target branch or bypass
+the coordinator verdict. Documentation-only changes follow the narrower exemption in the
+root guardrails. End changed work with the [session handoff](session_handoff_format.md).

agroute-0.1.0/docs/index.md

@@ -0,0 +1,32 @@
+# agroute documentation
+
+`agroute` routes delegated coding-agent tasks across Codex (`codex`), Claude Code (`claude`),
+and Antigravity (`agy`) within live usage limits, integrating with `howhard` 2.1+ for
+model/effort selection and learning.
+
+```{toctree}
+:maxdepth: 2
+
+quickstart
+reference
+configuration
+skills
+contributing
+releasing
+session_handoff_format
+changelog
+```
+
+- [Quickstart](quickstart.md) — install the Python backend and native plugin, filter candidates,
+  resolve a `howhard` decision, and record feedback.
+- [Routing and storage contracts](reference.md) — candidate qualification, native vs. CLI
+  execution plans, quota window expiry, `host_affinity_epsilon`, and worktree state.
+- [Configuration](configuration.md) — layered `agroute.toml`, `native_candidates` vs.
+  `cli_candidates`, quota limits, and `howhard.toml` `[inventories]` generation.
+- [Native skill installation](skills.md) — Codex, Claude Code, and Antigravity plugin
+  installation and coordinating-agent instructions.
+- [Contributor workflow](contributing.md) — issue-tracked Git worktrees and `agc` gates.
+- [Packaging and release](releasing.md) — version synchronization, wheel verification, and PyPI
+  release checklist.
+- [Session handoff format](session_handoff_format.md) — four-part closing summary contract.
+- [Changelog](changelog.md) — release history.

agroute-0.1.0/docs/quickstart.md

@@ -0,0 +1,82 @@
+# Quickstart
+
+You need Python 3.11+, a POSIX shell, Git, `howhard` 2.1+, and a current Codex, Claude Code,
+or Antigravity client with native plugin support.
+
+## Install the backend
+
+Run these commands from the project where you want to use `agroute`:
+
+```sh
+python3 -m venv .venv-agroute
+. .venv-agroute/bin/activate
+python -m pip install "agroute==0.1.0" "howhard>=2.1.0"
+agroute --version
+```
+
+Expect `agroute 0.1.0`. Keep this environment active and start your coding agent from the
+same shell so it can find `agroute` and `howhard`.
+
+## Install the native plugin
+
+The Python package supplies the backend. The native plugin supplies the `agroute` skill.
+Install the plugin through your agent's own plugin manager.
+
+Codex:
+
+```sh
+codex plugin marketplace add xu-hao/agroute
+codex plugin add agroute@agroute
+```
+
+Claude Code:
+
+```sh
+claude plugin marketplace add xu-hao/agroute
+claude plugin install agroute@agroute
+```
+
+Antigravity:
+
+```sh
+agy plugin install https://github.com/xu-hao/agroute
+agy plugin list
+```
+
+See [native installation and lifecycle](skills.md) for scope and update commands.
+
+## Route a task within live usage limits
+
+1. **Inspect or update native quota state**:
+
+   ```sh
+   agroute usage show --json
+   agroute usage ingest --agent codex --file /tmp/codex-status.jsonl --json
+   ```
+
+2. **Emit filtered `howhard` candidates for the current host**:
+
+   ```sh
+   agroute candidates --host agy --output /tmp/task-candidates.json --json
+   ```
+
+   `--output` writes the 1–32 cell JSON array expected by `howhard` (`<agent>/<model>` and
+   `<effort>`). When `target == host`, `agroute` uses `native_candidates` supported by the
+   host's native subagent tool; when `target != host`, `agroute` uses `cli_candidates`
+   supported by the target's non-interactive CLI.
+
+3. **Select a cell with `howhard` and resolve the execution plan**:
+
+   ```sh
+   howhard context task --text-file /tmp/task.txt --candidates /tmp/task-candidates.json --llm off --json
+   # After independent baseline forecast, optional retrieval, and decide:
+   agroute plan --host agy --decision /tmp/task-decision.json --prompt-file /tmp/task.txt --json
+   ```
+
+4. **Execute and record feedback**:
+
+   - If `execution_mode == "native"`, invoke the host's native delegation tool
+     (`invoke_subagent`, `Agent`, or `spawn_agent`) with `invocation.parameters`.
+   - If `execution_mode == "cli"`, execute `invocation.argv` and capture the output stream.
+   - Follow `feedback` in the returned plan to record the outcome via `howhard observe`,
+     attach measured usage via `howhard usage collect` / `attach`, and update `howhard` memory.