open-agent-router 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (161) hide show
  1. open_agent_router-0.1.0/.gitattributes +1 -0
  2. open_agent_router-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +43 -0
  3. open_agent_router-0.1.0/.github/ISSUE_TEMPLATE/config.yml +1 -0
  4. open_agent_router-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml +24 -0
  5. open_agent_router-0.1.0/.github/workflows/ci.yml +42 -0
  6. open_agent_router-0.1.0/.github/workflows/release.yml +63 -0
  7. open_agent_router-0.1.0/.gitignore +29 -0
  8. open_agent_router-0.1.0/AGENTS.md +31 -0
  9. open_agent_router-0.1.0/CHANGELOG.md +22 -0
  10. open_agent_router-0.1.0/CLAUDE.md +5 -0
  11. open_agent_router-0.1.0/CONTRIBUTING.md +57 -0
  12. open_agent_router-0.1.0/LICENSE +21 -0
  13. open_agent_router-0.1.0/PKG-INFO +286 -0
  14. open_agent_router-0.1.0/README.md +255 -0
  15. open_agent_router-0.1.0/ROADMAP.md +36 -0
  16. open_agent_router-0.1.0/SECURITY.md +99 -0
  17. open_agent_router-0.1.0/docs/CLASSIFIER.md +198 -0
  18. open_agent_router-0.1.0/docs/DESIGN.md +295 -0
  19. open_agent_router-0.1.0/docs/INSTALL.md +401 -0
  20. open_agent_router-0.1.0/docs/MCP.md +160 -0
  21. open_agent_router-0.1.0/docs/TROUBLESHOOTING.md +106 -0
  22. open_agent_router-0.1.0/docs/assets/architecture-dark.svg +1546 -0
  23. open_agent_router-0.1.0/docs/assets/architecture-light.svg +1546 -0
  24. open_agent_router-0.1.0/docs/assets/banner-dark.svg +26 -0
  25. open_agent_router-0.1.0/docs/assets/banner-light.svg +26 -0
  26. open_agent_router-0.1.0/docs/assets/cycle.svg +173 -0
  27. open_agent_router-0.1.0/docs/assets/dashboard.png +0 -0
  28. open_agent_router-0.1.0/docs/assets/demo.svg +133 -0
  29. open_agent_router-0.1.0/docs/examples/claude-and-kimi.toml +108 -0
  30. open_agent_router-0.1.0/docs/examples/kimi-and-opencode.toml +111 -0
  31. open_agent_router-0.1.0/docs/examples/opencode-and-cline.toml +76 -0
  32. open_agent_router-0.1.0/docs/examples/single-subscription-with-classifier.toml +84 -0
  33. open_agent_router-0.1.0/integrations/claude-code/agent-router-delegate/SKILL.md +65 -0
  34. open_agent_router-0.1.0/integrations/cline/agent-router-delegate/SKILL.md +65 -0
  35. open_agent_router-0.1.0/integrations/kimi-code/agent-router-delegate/SKILL.md +65 -0
  36. open_agent_router-0.1.0/integrations/opencode/agent-router-delegate/SKILL.md +65 -0
  37. open_agent_router-0.1.0/pyproject.toml +94 -0
  38. open_agent_router-0.1.0/src/agent_router/__init__.py +6 -0
  39. open_agent_router-0.1.0/src/agent_router/adapters/__init__.py +19 -0
  40. open_agent_router-0.1.0/src/agent_router/adapters/base.py +175 -0
  41. open_agent_router-0.1.0/src/agent_router/adapters/claude.py +79 -0
  42. open_agent_router-0.1.0/src/agent_router/adapters/cline.py +120 -0
  43. open_agent_router-0.1.0/src/agent_router/adapters/kimi.py +70 -0
  44. open_agent_router-0.1.0/src/agent_router/adapters/opencode.py +88 -0
  45. open_agent_router-0.1.0/src/agent_router/api.py +666 -0
  46. open_agent_router-0.1.0/src/agent_router/auth.py +175 -0
  47. open_agent_router-0.1.0/src/agent_router/classifier.py +790 -0
  48. open_agent_router-0.1.0/src/agent_router/cli.py +1521 -0
  49. open_agent_router-0.1.0/src/agent_router/client.py +163 -0
  50. open_agent_router-0.1.0/src/agent_router/clock.py +70 -0
  51. open_agent_router-0.1.0/src/agent_router/collectors/__init__.py +1 -0
  52. open_agent_router-0.1.0/src/agent_router/collectors/claude_statusline.py +64 -0
  53. open_agent_router-0.1.0/src/agent_router/collectors/opencode_stats.py +136 -0
  54. open_agent_router-0.1.0/src/agent_router/config.example.toml +202 -0
  55. open_agent_router-0.1.0/src/agent_router/config.py +1289 -0
  56. open_agent_router-0.1.0/src/agent_router/dispatcher.py +1266 -0
  57. open_agent_router-0.1.0/src/agent_router/events.py +247 -0
  58. open_agent_router-0.1.0/src/agent_router/export.py +480 -0
  59. open_agent_router-0.1.0/src/agent_router/jobs.py +295 -0
  60. open_agent_router-0.1.0/src/agent_router/jobstore.py +941 -0
  61. open_agent_router-0.1.0/src/agent_router/ledger.py +181 -0
  62. open_agent_router-0.1.0/src/agent_router/lifecycle.py +70 -0
  63. open_agent_router-0.1.0/src/agent_router/mcp_server.py +157 -0
  64. open_agent_router-0.1.0/src/agent_router/pacing.py +117 -0
  65. open_agent_router-0.1.0/src/agent_router/periods.py +122 -0
  66. open_agent_router-0.1.0/src/agent_router/plugins.py +22 -0
  67. open_agent_router-0.1.0/src/agent_router/policy.py +217 -0
  68. open_agent_router-0.1.0/src/agent_router/prices.py +51 -0
  69. open_agent_router-0.1.0/src/agent_router/registry.py +163 -0
  70. open_agent_router-0.1.0/src/agent_router/runner.py +513 -0
  71. open_agent_router-0.1.0/src/agent_router/service.py +427 -0
  72. open_agent_router-0.1.0/src/agent_router/settings_store.py +91 -0
  73. open_agent_router-0.1.0/src/agent_router/sinks.py +113 -0
  74. open_agent_router-0.1.0/src/agent_router/spend.py +80 -0
  75. open_agent_router-0.1.0/src/agent_router/static/app.css +74 -0
  76. open_agent_router-0.1.0/src/agent_router/static/app.js +74 -0
  77. open_agent_router-0.1.0/src/agent_router/statusline.py +125 -0
  78. open_agent_router-0.1.0/src/agent_router/store.py +351 -0
  79. open_agent_router-0.1.0/src/agent_router/templates/_advice.html +49 -0
  80. open_agent_router-0.1.0/src/agent_router/templates/_job.html +134 -0
  81. open_agent_router-0.1.0/src/agent_router/templates/_jobs.html +43 -0
  82. open_agent_router-0.1.0/src/agent_router/templates/_limits.html +39 -0
  83. open_agent_router-0.1.0/src/agent_router/templates/base.html +29 -0
  84. open_agent_router-0.1.0/src/agent_router/templates/calibrate.html +39 -0
  85. open_agent_router-0.1.0/src/agent_router/templates/index.html +15 -0
  86. open_agent_router-0.1.0/src/agent_router/templates/job.html +4 -0
  87. open_agent_router-0.1.0/src/agent_router/templates/jobs.html +4 -0
  88. open_agent_router-0.1.0/src/agent_router/templates/login.html +9 -0
  89. open_agent_router-0.1.0/src/agent_router/templates/message.html +5 -0
  90. open_agent_router-0.1.0/src/agent_router/web.py +444 -0
  91. open_agent_router-0.1.0/src/agent_router/worktree.py +346 -0
  92. open_agent_router-0.1.0/tests/conftest.py +79 -0
  93. open_agent_router-0.1.0/tests/fixtures/claude_error.json +14 -0
  94. open_agent_router-0.1.0/tests/fixtures/claude_ok.json +16 -0
  95. open_agent_router-0.1.0/tests/fixtures/claude_statusline.json +12 -0
  96. open_agent_router-0.1.0/tests/fixtures/cline_error.jsonl +5 -0
  97. open_agent_router-0.1.0/tests/fixtures/cline_limit.txt +5 -0
  98. open_agent_router-0.1.0/tests/fixtures/cline_ok.jsonl +24 -0
  99. open_agent_router-0.1.0/tests/fixtures/kimi_multi.jsonl +7 -0
  100. open_agent_router-0.1.0/tests/fixtures/kimi_ok.jsonl +5 -0
  101. open_agent_router-0.1.0/tests/fixtures/limit_claude.txt +1 -0
  102. open_agent_router-0.1.0/tests/fixtures/limit_kimi.txt +2 -0
  103. open_agent_router-0.1.0/tests/fixtures/limit_opencode.txt +1 -0
  104. open_agent_router-0.1.0/tests/fixtures/opencode_error.jsonl +1 -0
  105. open_agent_router-0.1.0/tests/fixtures/opencode_multi_step.jsonl +7 -0
  106. open_agent_router-0.1.0/tests/fixtures/opencode_ok.jsonl +3 -0
  107. open_agent_router-0.1.0/tests/fixtures/opencode_stats.json +53 -0
  108. open_agent_router-0.1.0/tests/helpers.py +204 -0
  109. open_agent_router-0.1.0/tests/stubs/fake_harness.py +89 -0
  110. open_agent_router-0.1.0/tests/stubs/fake_kimi.py +43 -0
  111. open_agent_router-0.1.0/tests/test_adapter_cline.py +211 -0
  112. open_agent_router-0.1.0/tests/test_adapters.py +359 -0
  113. open_agent_router-0.1.0/tests/test_api_jobs.py +1328 -0
  114. open_agent_router-0.1.0/tests/test_api_limits.py +457 -0
  115. open_agent_router-0.1.0/tests/test_api_snapshot.py +356 -0
  116. open_agent_router-0.1.0/tests/test_auth.py +194 -0
  117. open_agent_router-0.1.0/tests/test_ci.py +33 -0
  118. open_agent_router-0.1.0/tests/test_classifier.py +175 -0
  119. open_agent_router-0.1.0/tests/test_classifier_votes.py +2060 -0
  120. open_agent_router-0.1.0/tests/test_cli_basics.py +763 -0
  121. open_agent_router-0.1.0/tests/test_cli_doctor.py +473 -0
  122. open_agent_router-0.1.0/tests/test_cli_errors.py +119 -0
  123. open_agent_router-0.1.0/tests/test_cli_help.py +61 -0
  124. open_agent_router-0.1.0/tests/test_cli_init.py +622 -0
  125. open_agent_router-0.1.0/tests/test_cli_jobs.py +936 -0
  126. open_agent_router-0.1.0/tests/test_client_wait.py +145 -0
  127. open_agent_router-0.1.0/tests/test_clock.py +49 -0
  128. open_agent_router-0.1.0/tests/test_config.py +646 -0
  129. open_agent_router-0.1.0/tests/test_config_routing.py +303 -0
  130. open_agent_router-0.1.0/tests/test_dispatcher.py +3385 -0
  131. open_agent_router-0.1.0/tests/test_events.py +560 -0
  132. open_agent_router-0.1.0/tests/test_examples.py +174 -0
  133. open_agent_router-0.1.0/tests/test_export.py +519 -0
  134. open_agent_router-0.1.0/tests/test_hygiene.py +171 -0
  135. open_agent_router-0.1.0/tests/test_integrations.py +64 -0
  136. open_agent_router-0.1.0/tests/test_jobs.py +322 -0
  137. open_agent_router-0.1.0/tests/test_jobstore.py +963 -0
  138. open_agent_router-0.1.0/tests/test_ledger.py +362 -0
  139. open_agent_router-0.1.0/tests/test_lifecycle.py +104 -0
  140. open_agent_router-0.1.0/tests/test_mcp.py +362 -0
  141. open_agent_router-0.1.0/tests/test_model_weight.py +560 -0
  142. open_agent_router-0.1.0/tests/test_newcomer_path.py +186 -0
  143. open_agent_router-0.1.0/tests/test_opencode_stats.py +325 -0
  144. open_agent_router-0.1.0/tests/test_pacing.py +182 -0
  145. open_agent_router-0.1.0/tests/test_periods.py +169 -0
  146. open_agent_router-0.1.0/tests/test_periods_properties.py +152 -0
  147. open_agent_router-0.1.0/tests/test_plugins.py +61 -0
  148. open_agent_router-0.1.0/tests/test_policy.py +408 -0
  149. open_agent_router-0.1.0/tests/test_policy_groups.py +360 -0
  150. open_agent_router-0.1.0/tests/test_policy_scenarios.py +207 -0
  151. open_agent_router-0.1.0/tests/test_readme.py +264 -0
  152. open_agent_router-0.1.0/tests/test_registry.py +234 -0
  153. open_agent_router-0.1.0/tests/test_runner.py +959 -0
  154. open_agent_router-0.1.0/tests/test_sinks.py +463 -0
  155. open_agent_router-0.1.0/tests/test_spend.py +577 -0
  156. open_agent_router-0.1.0/tests/test_statusline.py +440 -0
  157. open_agent_router-0.1.0/tests/test_store.py +285 -0
  158. open_agent_router-0.1.0/tests/test_web_dashboard.py +625 -0
  159. open_agent_router-0.1.0/tests/test_web_jobs.py +643 -0
  160. open_agent_router-0.1.0/tests/test_worktree.py +677 -0
  161. open_agent_router-0.1.0/uv.lock +1077 -0
@@ -0,0 +1 @@
1
+ * text=auto eol=lf
@@ -0,0 +1,43 @@
1
+ name: Bug report
2
+ description: Something does not work as described
3
+ labels: [bug]
4
+ body:
5
+ - type: markdown
6
+ attributes:
7
+ value: |
8
+ Security problems go to *Security → Report a vulnerability*, not here.
9
+ Remove tokens, prompts with private code and personal paths from logs before posting.
10
+ - type: input
11
+ id: version
12
+ attributes:
13
+ label: Version
14
+ description: "`uv tool list` shows it, or the commit hash"
15
+ validations:
16
+ required: true
17
+ - type: input
18
+ id: environment
19
+ attributes:
20
+ label: Environment
21
+ description: Windows version, Python version, harnesses involved (OpenCode, Kimi Code, Cline, Claude Code)
22
+ validations:
23
+ required: true
24
+ - type: textarea
25
+ id: steps
26
+ attributes:
27
+ label: What you did
28
+ description: Commands and the relevant part of `config.toml`
29
+ validations:
30
+ required: true
31
+ - type: textarea
32
+ id: actual
33
+ attributes:
34
+ label: What happened
35
+ description: Output, error code, `agent-router result <id>` if a job is involved
36
+ validations:
37
+ required: true
38
+ - type: textarea
39
+ id: expected
40
+ attributes:
41
+ label: What you expected
42
+ validations:
43
+ required: true
@@ -0,0 +1 @@
1
+ blank_issues_enabled: false
@@ -0,0 +1,24 @@
1
+ name: Feature request
2
+ description: A new harness, a routing idea or another improvement
3
+ labels: [enhancement]
4
+ body:
5
+ - type: markdown
6
+ attributes:
7
+ value: Check [ROADMAP.md](https://github.com/kdenischenko/open-agent-router/blob/main/ROADMAP.md) first — it may already be planned.
8
+ - type: textarea
9
+ id: problem
10
+ attributes:
11
+ label: Problem
12
+ description: What you are trying to do and what gets in the way
13
+ validations:
14
+ required: true
15
+ - type: textarea
16
+ id: proposal
17
+ attributes:
18
+ label: Proposal
19
+ description: How it could work; config or CLI sketch welcome
20
+ - type: textarea
21
+ id: alternatives
22
+ attributes:
23
+ label: Alternatives
24
+ description: What you use or do now instead
@@ -0,0 +1,42 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [main]
6
+ pull_request:
7
+ branches: [main]
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ test:
14
+ strategy:
15
+ fail-fast: false
16
+ matrix:
17
+ os: [windows-latest, ubuntu-latest, macos-latest]
18
+ runs-on: ${{ matrix.os }}
19
+ continue-on-error: ${{ matrix.os != 'windows-latest' }}
20
+ timeout-minutes: 30
21
+ steps:
22
+ - uses: actions/checkout@v4
23
+
24
+ - uses: astral-sh/setup-uv@v6
25
+ with:
26
+ version: "0.11.7"
27
+ python-version: "3.12"
28
+
29
+ - name: Install
30
+ run: uv sync --locked
31
+
32
+ - name: Lint
33
+ run: uv run ruff check
34
+
35
+ - name: Format
36
+ run: uv run ruff format --check
37
+
38
+ - name: Test
39
+ run: uv run pytest -q
40
+
41
+ - name: Build
42
+ run: uv build
@@ -0,0 +1,63 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+
7
+ jobs:
8
+ release:
9
+ runs-on: windows-latest
10
+ timeout-minutes: 30
11
+ environment: pypi
12
+ permissions:
13
+ contents: read
14
+ id-token: write
15
+ steps:
16
+ - uses: actions/checkout@v4
17
+
18
+ - uses: astral-sh/setup-uv@v6
19
+ with:
20
+ version: "0.11.7"
21
+ python-version: "3.12"
22
+
23
+ - name: Install
24
+ run: uv sync --locked
25
+
26
+ - name: Lint
27
+ run: uv run ruff check
28
+
29
+ - name: Format
30
+ run: uv run ruff format --check
31
+
32
+ - name: Test
33
+ run: uv run pytest -q
34
+
35
+ - name: Check tag version
36
+ shell: pwsh
37
+ run: |
38
+ $tagVersion = "${{ github.ref_name }}".Substring(1)
39
+ $projectVersion = (Select-String -Path pyproject.toml -Pattern '^version = "([^"]+)"$').Matches.Groups[1].Value
40
+ if ($tagVersion -ne $projectVersion) {
41
+ Write-Error "tag version $tagVersion does not match pyproject.toml version $projectVersion"
42
+ exit 1
43
+ }
44
+
45
+ - name: Build
46
+ run: uv build
47
+
48
+ - name: Smoke test the wheel
49
+ shell: pwsh
50
+ working-directory: ${{ runner.temp }}
51
+ run: |
52
+ $wheel = (Get-ChildItem "$env:GITHUB_WORKSPACE/dist/*.whl").FullName
53
+ $env:AGENT_ROUTER_HOME = Join-Path $env:RUNNER_TEMP "agent-router-home"
54
+ $run = @("run", "--isolated", "--no-project", "--python", "3.12", "--with", $wheel)
55
+ uv @run agent-router --help
56
+ if ($LASTEXITCODE) { exit $LASTEXITCODE }
57
+ uv @run agent-router init
58
+ if ($LASTEXITCODE) { exit $LASTEXITCODE }
59
+ uv @run python -c "import agent_router, pathlib; from agent_router.config import home_dir, load_config; load_config(home_dir() / 'config.toml'); root = pathlib.Path(agent_router.__file__).parent; assert any((root / 'static').iterdir()) and any((root / 'templates').iterdir())"
60
+ if ($LASTEXITCODE) { exit $LASTEXITCODE }
61
+
62
+ - name: Publish
63
+ run: uv publish --trusted-publishing always
@@ -0,0 +1,29 @@
1
+ .env
2
+ .env.*
3
+ data/
4
+ __pycache__/
5
+ .venv/
6
+ .pytest_cache/
7
+ .ruff_cache/
8
+ *.egg-info/
9
+ dist/
10
+ build/
11
+ *.sqlite*
12
+ *.db
13
+ *.token
14
+ .claude/
15
+ .idea/
16
+ .vscode/
17
+ *.py[codz]
18
+ *$py.class
19
+ .coverage
20
+ .coverage.*
21
+ htmlcov/
22
+ .tox/
23
+ .nox/
24
+ .mypy_cache/
25
+ .envrc
26
+ venv/
27
+ env/
28
+ .pypirc
29
+ .scratch/
@@ -0,0 +1,31 @@
1
+ # agent-router — rules for coding agents
2
+
3
+ ## What goes into the repository
4
+
5
+ Commit only code, tests and user-facing documentation (`README.md`, `docs/`, `integrations/`).
6
+ Working notes, plans, drafts and generated reports are not part of the repository.
7
+
8
+ Never commit personal data (e-mail addresses, private remotes, subscription details), tokens or
9
+ `.env` files.
10
+
11
+ ## Gates before every commit
12
+
13
+ ```
14
+ uv run ruff check
15
+ uv run ruff format --check
16
+ uv run pytest -q
17
+ ```
18
+
19
+ ## How to change code
20
+
21
+ Follow the guidelines in [`CONTRIBUTING.md`](CONTRIBUTING.md). The ones agents miss most often:
22
+
23
+ - A bug fix starts with a test that fails for the stated reason.
24
+ - Error codes, event names, status values and JSON fields of the API are never renamed.
25
+ - Messages are in English, start lowercase and have no trailing period.
26
+ - Comments explain what and why, never the history of the change.
27
+ - A change in behavior updates `README.md`, `docs/INSTALL.md` or `docs/DESIGN.md` in the same
28
+ commit if they describe it.
29
+ - Tests never touch the real clock or the real gateway home directory.
30
+
31
+ The project is tested on Windows; keep paths and process handling working there.
@@ -0,0 +1,22 @@
1
+ # Changelog
2
+
3
+ All notable changes are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [0.1.0] - 2026-11-21
8
+
9
+ Alpha for Windows.
10
+
11
+ - Job gateway: `agent-router run` sends a coding job to one of your AI coding subscriptions
12
+ (OpenCode, Kimi Code, Cline, Claude Code) and returns the result.
13
+ - Routing by tier, priority and remaining limits, with pacing across usage windows.
14
+ - Usage tracking across limit windows, with manual calibration.
15
+ - Optional tier classification with local or cloud models.
16
+ - Web dashboard, Claude Code status line and JSONL/CSV export.
17
+ - Delegation skills for Claude Code, OpenCode, Kimi Code and Cline.
18
+ - MCP server for orchestrator agents to submit and track jobs.
19
+ - Guided setup with `agent-router init`, ready-made configs and calibration guidance.
20
+ - Installable from PyPI as `open-agent-router`; the command is `agent-router`.
21
+ - Experimental Linux and macOS support; Windows-only autostart.
22
+ - Troubleshooting guide for common gateway, harness, limit and approval failures.
@@ -0,0 +1,5 @@
1
+ # Claude Code
2
+
3
+ Project rules are in AGENTS.md:
4
+
5
+ @AGENTS.md
@@ -0,0 +1,57 @@
1
+ # Contributing
2
+
3
+ Thanks for your interest. agent-router is a small project maintained by one person, so please
4
+ open an issue before a large change — it saves both of us time.
5
+
6
+ ## Setup
7
+
8
+ Windows, Python 3.12 and [uv](https://docs.astral.sh/uv/):
9
+
10
+ ```
11
+ git clone https://github.com/kdenischenko/open-agent-router.git
12
+ cd open-agent-router
13
+ uv sync
14
+ ```
15
+
16
+ ## Gates
17
+
18
+ Every commit must pass:
19
+
20
+ ```
21
+ uv run ruff check
22
+ uv run ruff format --check
23
+ uv run pytest -q
24
+ ```
25
+
26
+ CI runs the same commands on Windows, Linux and macOS. Windows is required; Linux and
27
+ macOS are experimental and allowed to fail.
28
+
29
+ ## Guidelines
30
+
31
+ - **Tests first** for bug fixes: a test that fails for the stated reason, then the fix.
32
+ - **No new** `noqa`, `skip` or `xfail` without a reason in the pull request.
33
+ - **Tests do not depend on the real clock or the real gateway home directory**: use the clock
34
+ fixtures and `AGENT_ROUTER_HOME` in a temporary directory.
35
+ - **Stable interfaces.** Error codes, event names, status values and JSON fields of the API are
36
+ never renamed; new ones may be added.
37
+ - **Messages** are in English, start with a lowercase letter and have no trailing period:
38
+ `unknown route: x`.
39
+ - **Docs follow behavior.** A change in behavior updates `README.md`, `docs/INSTALL.md` or
40
+ `docs/DESIGN.md` in the same pull request if they describe it.
41
+ - **Comments explain what and why**, not the history of the change.
42
+ - **Nothing personal or secret** in the repository: no e-mail addresses, tokens, `.env` files, real
43
+ paths with user names. `tests/test_hygiene.py` checks the obvious cases.
44
+
45
+ ## Commits
46
+
47
+ [Conventional Commits](https://www.conventionalcommits.org/) style: `fix(cli): ...`,
48
+ `feat(config): ...`, `docs: ...`, `test: ...`, `chore: ...`. One logical change per commit.
49
+
50
+ ## Coding agents
51
+
52
+ Agents working in this repository follow [`AGENTS.md`](AGENTS.md). The same rules apply to their
53
+ pull requests as to human ones.
54
+
55
+ ## Security
56
+
57
+ Please do not report vulnerabilities in public issues — see [`SECURITY.md`](SECURITY.md).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 kdenischenko
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,286 @@
1
+ Metadata-Version: 2.5
2
+ Name: open-agent-router
3
+ Version: 0.1.0
4
+ Summary: Local gateway that routes coding-agent jobs between AI subscriptions by remaining quota
5
+ Project-URL: Homepage, https://github.com/kdenischenko/open-agent-router
6
+ Project-URL: Issues, https://github.com/kdenischenko/open-agent-router/issues
7
+ Project-URL: Changelog, https://github.com/kdenischenko/open-agent-router/blob/main/CHANGELOG.md
8
+ Author: kdenischenko
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: ai,claude-code,cline,coding-agent,gateway,kimi,llm,mcp,opencode,orchestration,quota,router
12
+ Classifier: Development Status :: 3 - Alpha
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Classifier: Operating System :: POSIX :: Linux
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Software Development
21
+ Requires-Python: >=3.12
22
+ Requires-Dist: fastapi<0.163,>=0.162.5
23
+ Requires-Dist: httpx>=0.28.1
24
+ Requires-Dist: jinja2>=3.1.6
25
+ Requires-Dist: mcp<3,>=2.3
26
+ Requires-Dist: platformdirs>=4.14.5
27
+ Requires-Dist: python-multipart>=0.0.33
28
+ Requires-Dist: typer<0.30,>=0.29.1
29
+ Requires-Dist: uvicorn>=0.54.0
30
+ Description-Content-Type: text/markdown
31
+
32
+ <picture>
33
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/banner-dark.svg">
34
+ <img src="https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/banner-light.svg" alt="open-agent-router: route coding jobs across your AI subscriptions">
35
+ </picture>
36
+
37
+ # open-agent-router
38
+
39
+ [![CI](https://github.com/kdenischenko/open-agent-router/actions/workflows/ci.yml/badge.svg)](https://github.com/kdenischenko/open-agent-router/actions/workflows/ci.yml)
40
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kdenischenko/open-agent-router/blob/main/LICENSE)
41
+ [![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org)
42
+ [![Windows | Linux | macOS (experimental)](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS%20(experimental)-blue.svg)](https://github.com/kdenischenko/open-agent-router#platforms)
43
+ [![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](https://github.com/kdenischenko/open-agent-router/blob/main/ROADMAP.md)
44
+
45
+ This is an early alpha (v0.1.0); interfaces and configuration may change.
46
+
47
+ ## Why
48
+
49
+ You pay for several AI coding subscriptions, but each one has its own limits and pace.
50
+ You do not want a job to fail mid-run because a limit ran out, and you do not want to
51
+ spend a strong model on a task a cheap one handles fine. open-agent-router is a local
52
+ gateway that keeps your subscriptions busy without surprises:
53
+
54
+ - **Subscriptions do not sit idle.** The gateway tracks usage in every limit window and
55
+ prefers the pool that is furthest behind its expected pace.
56
+ - **Limits do not surprise you.** A pool that reports a limit is blocked until its reset;
57
+ on a usage limit and on an executor error the job moves to another route. A writing
58
+ attempt that already changed files ends `partial` and is not retried.
59
+ - **Jobs go where they are cheap enough.** Each job gets a tier — `cheap`, `standard` or
60
+ `strong` — and the gateway picks a route for that tier by priority and by how far each
61
+ subscription is behind its pace. An optional classifier — a local model or a cloud one —
62
+ can assign the tier for you.
63
+
64
+ It is for you if you have two or more subscriptions to agentic coding CLIs (such as Claude Code,
65
+ Kimi Code, OpenCode or Cline) and an orchestrator agent that delegates jobs to others.
66
+
67
+ ![Terminal: agent-router advice ranks routes by how far each pool is behind its pace, agent-router status shows usage of every pool window](https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/demo.svg)
68
+
69
+ ## How is this different from LiteLLM or OpenRouter?
70
+
71
+ LiteLLM and OpenRouter route API requests using API keys, with usage billed per token.
72
+ open-agent-router hands whole jobs to the subscriptions you already pay for through their
73
+ official CLIs. It keeps track of every limit window and its pace, and never sees provider
74
+ keys.
75
+
76
+ ## Quick start
77
+
78
+ You need Python 3.12, [uv](https://docs.astral.sh/uv/), git, and at least one harness CLI
79
+ (Kimi Code, OpenCode, Cline or Claude Code), installed and signed in.
80
+
81
+ ```bash
82
+ uv tool install open-agent-router
83
+ agent-router init --allowed-root <directory>
84
+ agent-router serve
85
+ ```
86
+
87
+ To run the latest `main` instead, install with `uv tool install git+https://github.com/kdenischenko/open-agent-router`. If
88
+ `agent-router` is not found after the install, run `uv tool update-shell` and open a new
89
+ terminal. `serve` keeps running in its terminal; stop it with Ctrl+C.
90
+
91
+ With the gateway running, `agent-router advice --tier standard` shows which routes can take a
92
+ job. The `opencode-go` limits in the template are placeholders; replace them with your plan
93
+ limits.
94
+
95
+ The `open-agent-router` package installs the `agent-router` command. `init` creates the
96
+ gateway home directory with `config.toml` and two tokens, adds `<directory>` to
97
+ `tasks.allowed_roots` (repeat `init --allowed-root` to allow more directories, also on an
98
+ existing config, then restart a running `serve`) and prints the next steps. Routes are enabled
99
+ for the harnesses `init` finds, except Claude Code and Cline: set `enabled = true` on the
100
+ `claude-cli/sonnet` or `cline/glm-5.3` route in `config.toml` to let jobs use them. Jobs run before you calibrate the pools; record
101
+ your real usage later with `agent-router calibrate`. Ready-made configs for typical setups are
102
+ in [`docs/examples/`](https://github.com/kdenischenko/open-agent-router/tree/main/docs/examples). Then submit a job from another terminal:
103
+
104
+ ```bash
105
+ agent-router run --no-wait --cwd <directory> --mode read "Describe the structure of this repository"
106
+ agent-router approve <job-id>
107
+ agent-router wait <job-id>
108
+ ```
109
+
110
+ `wait` exits 4 while the job is still running; run it again, or use `--timeout` to wait longer.
111
+ A job that needs approval returns at once with
112
+ `job awaits approval: agent-router approve <id> before <time>, then agent-router wait <id>`.
113
+
114
+ ![Terminal: a job is submitted with run --no-wait, a human approves it, wait prints the result, rate records the rating and status shows the pool usage](https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/cycle.svg)
115
+
116
+ Every route in the `init` template has `confirm = true`, so a job waits until you approve it
117
+ with `approve` or in the dashboard. Set `confirm = false` on a route to let its jobs start
118
+ right away. Without a decision the approval expires after `tasks.approval_timeout_s`
119
+ (default 600 s): the job ends as `declined` with error `approval_expired` and does not move
120
+ to another route.
121
+
122
+ The full guide — harness sign-in, limit calibration, Windows autostart, the web dashboard
123
+ and the delegation skills for orchestrators — is in [docs/INSTALL.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/INSTALL.md).
124
+
125
+ ## Use from your agent
126
+
127
+ An orchestrator agent can work through the gateway in two ways.
128
+
129
+ The first is the MCP server. Register it with your orchestrator, for example with
130
+ `claude mcp add agent-router -- agent-router mcp`: it exposes job operations as MCP
131
+ tools, and it needs the running gateway. Setup for every supported harness is in
132
+ [docs/MCP.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/MCP.md).
133
+
134
+ The second way is a delegation skill: ready-made delegation instructions for
135
+ orchestrators live in [`integrations/`](https://github.com/kdenischenko/open-agent-router/tree/main/integrations): clone or download the
136
+ repository and copy the `agent-router-delegate` folder of your harness into its skills directory.
137
+
138
+ ## How it works
139
+
140
+ <picture>
141
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/architecture-dark.svg">
142
+ <img src="https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/architecture-light.svg" alt="Architecture: an orchestrator calls the agent-router CLI, the gateway HTTP API checks the token and passes the job to the dispatcher; the dispatcher asks the tier classifier (local or cloud models), checks the job directory and human approval, the route policy picks a pool from the ledger and pacing data in SQLite, and the runner starts the harness CLI through its adapter">
143
+ </picture>
144
+
145
+ You submit a job: a prompt, a directory, a mode and optional hints. The gateway estimates
146
+ the tier, checks the remaining limits and pace of every pool, picks a route, queues the
147
+ job and — for routes with `confirm = true` — waits until you approve it. It then runs the
148
+ harness CLI as a child process, records the spend and returns the result. See
149
+ [docs/DESIGN.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/DESIGN.md) for the full architecture.
150
+
151
+ ## Tier classifier
152
+
153
+ A job submitted without `--tier` can get its tier from a classifier model. It can be local —
154
+ a decision or chat model in [Ollama](https://ollama.com), or any OpenAI-compatible server
155
+ such as LM Studio — or a cloud provider over HTTPS with a key from an environment variable.
156
+ Several models can vote side by side: in `shadow` mode they only record votes, and
157
+ `agent-router classifier report` compares them with the tiers you confirm before you let one
158
+ of them decide. Configuration examples, what the classifier receives and measured results are
159
+ in [docs/CLASSIFIER.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/CLASSIFIER.md).
160
+
161
+ ## Dashboard
162
+
163
+ ![Web dashboard with pool limits, advice and jobs](https://raw.githubusercontent.com/kdenischenko/open-agent-router/main/docs/assets/dashboard.png)
164
+
165
+ The gateway also serves a dashboard at `http://127.0.0.1:<port>/` (the port is
166
+ `server.port`, default 8787). Log in with the admin token: paste the contents of the
167
+ `admin.token` file whose path `init` prints. The job page refreshes itself, shows the
168
+ error, and lets you rate a finished job.
169
+
170
+ ## Harnesses
171
+
172
+ The gateway runs each harness CLI with the sign-in you already made in it; it never sees
173
+ provider keys.
174
+
175
+ | Harness | CLI command | Usage source | Status |
176
+ |---|---|---|---|
177
+ | Kimi Code | `kimi` | journal | tested live on Windows |
178
+ | OpenCode | `opencode` | counter (`opencode stats`) | tested live on Windows |
179
+ | Cline | `cline` or `cline-cli` | journal | tested live on Windows |
180
+ | Claude Code | `claude` | journal | not tested live: covered by tests with recorded output only |
181
+
182
+ ## Platforms
183
+
184
+ Windows is supported and tested in CI and live. Linux and macOS are experimental:
185
+ the test suite runs on them in CI, but the gateway has not been run live there,
186
+ and autostart is Windows-only. Help wanted — see
187
+ [ROADMAP](https://github.com/kdenischenko/open-agent-router/blob/main/ROADMAP.md).
188
+
189
+ ## Commands
190
+
191
+ All commands are `agent-router <command>`. Run `agent-router <command> --help` for every
192
+ option.
193
+
194
+ | Command | What it does |
195
+ |---|---|
196
+ | `init` | Create the gateway home, `config.toml`, tokens; `--allowed-root DIR` allows job dirs |
197
+ | `serve` | Run the gateway on `127.0.0.1` (`--port` overrides `server.port`) |
198
+ | `mcp` | Run an MCP server over stdio for orchestrator agents |
199
+ | `status` | Show pool usage, expected pace and window resets in local time |
200
+ | `advice` | Show matching routes for a tier (and `--mode read` or `write`) and why the others are excluded |
201
+ | `calibrate POOL WINDOW PERCENT` | Record the usage your subscription shows; `--resets-at` or `--resets-in 10d` sets the reset of a fixed window, a rolling window takes none (admin token) |
202
+ | `unblock POOL` | Remove a pool block set after a limit hit (admin token) |
203
+ | `run [TEXT]` | Submit a job and wait up to 100 s; `--no-wait` prints the job id, `-` reads the prompt from stdin |
204
+ | `wait JOB_ID` | Wait for a job and print its result; retries for up to 10 s while the gateway restarts |
205
+ | `result JOB_ID` | Print the status and result of a job without waiting |
206
+ | `rate JOB_ID good\|bad\|partial` | Rate a finished job; the last rating wins, a `--note` is stored as hash and length only |
207
+ | `jobs` | List jobs with status, route, tier and creation time, optionally by `--status` |
208
+ | `cancel JOB_ID` | Cancel a queued or running job |
209
+ | `approve JOB_ID` / `deny JOB_ID` | Approve or deny a job that awaits confirmation (admin token) |
210
+ | `doctor` | Check config, store, harnesses and gateway; `--live` runs one read job per harness on routes without `confirm` |
211
+ | `export --since DATE` | Export jobs, attempts, ratings, classifier votes and usage as JSON Lines or CSV; texts are replaced by hash and length |
212
+ | `classifier report` | Show classifier votes, errors and accuracy against ratings; `--json` adds the tier matrix and latency |
213
+ | `classifier eval --models ID,...` | Replay past prompts through offline classifier models |
214
+
215
+ `doctor --statusline-snippet` prints the settings for the Claude Code status line, which reports
216
+ Claude usage to the gateway; see [docs/INSTALL.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/INSTALL.md).
217
+
218
+ ## Exit codes
219
+
220
+ Commands that call the gateway exit `5` when the gateway is unavailable or rejects the
221
+ token, `6` when the request is denied with HTTP 4xx (including a full queue), and `1` on
222
+ other errors. For `run`, `wait` and `result`, once the job state is known: `0` —
223
+ `completed`, `2` — `partial`, `3` — `failed`, `declined` or `cancelled`, `4` — the job is
224
+ not finished yet. `run --no-wait` exits `0` after a successful submit. Local errors
225
+ (configuration, store, reading the prompt, a malformed `--resets-at`) exit `1`; `doctor --live`
226
+ exits `1` unless every probe completes.
227
+
228
+ Common failures and their fixes are in [docs/TROUBLESHOOTING.md](https://github.com/kdenischenko/open-agent-router/blob/main/docs/TROUBLESHOOTING.md).
229
+
230
+ ## Environment variables
231
+
232
+ - `AGENT_ROUTER_HOME` — directory with `config.toml`, tokens and stores; defaults to the
233
+ per-user `agent-router` configuration directory.
234
+ - `AGENT_ROUTER_URL` — gateway address for client commands and the Claude Code status line;
235
+ defaults to `http://127.0.0.1:<server.port>`.
236
+
237
+ ## Adding a subscription or harness
238
+
239
+ 1. **Pool.** Add a `[[pools]]` section with `[[pools.windows]]` for your plan:
240
+ `unit = "percent"` for subscriptions that show a percentage, or `unit = "usd"` with
241
+ `limit_usd` for subscriptions billed in dollars. Optional: `priority`, `weight` (a
242
+ nudge in percentage points of lag) and `price_file` — a TOML table
243
+ `"<model>" = [input, output]` (USD per 1M tokens) used when the harness does not
244
+ report a cost.
245
+ 2. **Harness.** For a new CLI, write an adapter module like
246
+ `src/agent_router/adapters/opencode.py` exposing `HARNESS = HarnessSpec(...)` (name,
247
+ adapter, executable names, spend source `counter`/`journal`), register an entry point
248
+ in the `agent_router.harnesses` group in `pyproject.toml`, then `uv sync`. Adapter
249
+ tests use redacted output samples in `tests/fixtures/` and never run the real CLI. If
250
+ the executable is not in PATH, set `[backends.<name>] executable`.
251
+ 3. **Routes.** Add `[[routes]]` with `pool`, `backend`, `model`, `tiers`, `quality`,
252
+ `modes`; start a new route with `enabled = false`.
253
+ 4. **Models.** To share one model across pools, give its routes a common `model_key` and
254
+ order the pools in `[models."<model_key>"] prefer = [...]`.
255
+ 5. **Verify.** `agent-router doctor` shows the harness, its version and enabled routes;
256
+ `agent-router doctor --live` runs one short job per harness (needs a non-empty
257
+ `allowed_roots`); `agent-router status` shows pool usage.
258
+
259
+ ## Security
260
+
261
+ agent-router is a local tool for a single user and **not a sandbox**: in `--mode write`
262
+ the harness starts with auto-approved tools and can change any file your user can touch.
263
+ The threat model and how to report a vulnerability are in
264
+ [SECURITY.md](https://github.com/kdenischenko/open-agent-router/blob/main/SECURITY.md).
265
+
266
+ A `read_mode_files_changed` violation on a read-mode job means the working tree changed
267
+ while the job ran. If someone else wrote to the same repository in parallel, the
268
+ violation is attributed to the job even though the executor changed nothing.
269
+
270
+ ## Subscriptions
271
+
272
+ Use only official ways to access the providers and follow their terms. You are
273
+ responsible for complying with them. The project is not affiliated with the providers
274
+ and does not bypass their restrictions.
275
+
276
+ ## Contributing and roadmap
277
+
278
+ Contributions are welcome: open an issue before a large change, follow
279
+ [CONTRIBUTING.md](https://github.com/kdenischenko/open-agent-router/blob/main/CONTRIBUTING.md), and keep the gates green
280
+ (`uv run ruff check`, `uv run ruff format --check`, `uv run pytest -q`). Plans — Linux
281
+ and macOS support, an OpenAI-compatible proxy, data retention — are in
282
+ [ROADMAP.md](https://github.com/kdenischenko/open-agent-router/blob/main/ROADMAP.md).
283
+
284
+ ## License
285
+
286
+ [MIT](https://github.com/kdenischenko/open-agent-router/blob/main/LICENSE).