Fork and branch
Work on a branch named for what it does. Keep one concern per branch, so review can stay on one topic.
$ git clone https://github.com/<you>/TotallyHot-ArcRouter.git
$ git switch -c fix/token-accounting-rounding
Contribute
Send the fix you needed anyway.
Arc Router is open source under AGPL-3.0. The code, the design documents, the architecture decision records, and the backlog are all in one repository, in the open. Issues, patches, and corrections are welcome.
01 The workflow
Nothing unusual.
Fork, branch, build, test, open a pull request.
Build and test
Every project in the solution has a test project beside it. Run the suite before you open the pull request.
$ cd src
$ dotnet build TotallyHotArcRouter.slnx
$ dotnet test TotallyHotArcRouter.slnx
Describe the change
Say what was wrong and how you know the new behaviour is right. If the change touches
routing, the graders, cost accounting, or the benchmark sync, say what you observed
before and after. A design document in docs/ that no longer matches your
change should move with it.
Open the pull request
Against main. Expect questions about edge cases, particularly anywhere
provider credentials, proxy behaviour, or the sandbox boundary are involved.
02 Where the work is
Find the part that matches what you want to change.
- src/TotallyHotArcRouter
- The router itself: classification, the voter ensemble, backend selection, proxy and MCP surfaces, cost accounting.
- src/TotallyHotArcRouter.Quality
- The verifier and the graders — parsing, static analysis, and the score that gets joined before it is written.
- src/TotallyHotArcRouter.Gui*
- The desktop application and its admin, charts, console, and telemetry modules.
- src/TotallyHotArcRouter.Sandbox
- The isolation boundary for work the router executes on your behalf.
- src/Protos
- Service contracts, relevant if you are working on transport.
- docs/router, docs/gui
- Design documents, plans, and backlogs. Corrections here count as contributions.
- docs/adr
- Architecture decision records. A change that reverses a recorded decision should add a record, not edit the old one.
03 Good first contributions
If you want to help but don’t have a specific itch.
Work the backlog
The router backlog and tracked todos are kept in the repository, in the open, with real items on them.
Router backlog →Reproduce an issue
A confirmed reproduction on a second machine is often worth more than a guess at the fix.
Open issues →Fix the documentation
Documentation that has drifted from the code is a bug. Correcting it needs no build environment.
Browse the docs →04 Terms
What your patch lands under.
AGPL-3.0, plus an exception
Contributions are licensed under the GNU Affero General Public License v3.0, with the additional permission for linking against Microsoft platform components (WebView2 and the Windows App SDK). In short: use, modify, and redistribute freely, but if you distribute the software or run a modified version as a network service, make your corresponding source available under the same terms.
Read the exception →Dependencies stay permissive
Every dependency the project redistributes is MIT, Apache-2.0, or BSD-3-Clause, so nothing pulls extra copyleft into the tree. If your change adds a dependency, check its license first and add it to the third-party notices.
Third-party notices →05 Start reading
Clone it and have a look.
The whole thing is readable in an afternoon. The handbook is the way in, and how-it-learns.md is the single best explanation of what the router is actually doing.