# crazytoto/quota-boss architecture

> Architecture diagram of the GitHub repository crazytoto/quota-boss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crazytoto/quota-boss
- Repository: https://github.com/crazytoto/quota-boss

## Overview

Quota Boss is a multi-model orchestration harness for Claude Code and Codex. The main workflow is: a coding-agent session receives quota and routing context, classifies and delegates subtasks, runs work through provider CLIs, then verifies outcomes that inform later routing. Setup and provider management, session/context aids, code-graph lookup, and diagnostics/savings are separate product capabilities. The sampled files show routing, persistence, hooks, and integrations; several worker and CLI details are documented in the README rather than inspected directly.

Main entry points: [`scripts/route.js`](https://github.com/crazytoto/quota-boss/blob/main/scripts/route.js) (Model router), [`scripts/lib.js`](https://github.com/crazytoto/quota-boss/blob/main/scripts/lib.js) (Config and state), [`scripts/hook-session.js`](https://github.com/crazytoto/quota-boss/blob/main/scripts/hook-session.js) (Session hooks), [`agents`](https://github.com/crazytoto/quota-boss/tree/main/agents) (Worker agents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Session orchestration"]
  node_session_hooks["Session hooks<br/>[hook-session.js]"]
  node_prompt_hook["Prompt hook<br/>[hook-prompt.js]"]
  node_host_rules["Host rules<br/>[hosts.js]"]
  node_worker_agents["Worker agents"]
  node_worker_runner["CLI workers<br/>[cli-run.js]"]
  node_codex_runner["Codex runner<br/>[codex-run.js]"]
end

subgraph group_routing["Model routing"]
  node_result_feedback["Result feedback<br/>[self-test.js]"]
  node_session_routing["Session routing<br/>[session-routing.js]"]
  node_router["Model router<br/>[route.js]"]
  node_model_config["Model registry<br/>[models.json]"]
end

subgraph group_providers["Provider management"]
  node_provider_config["Provider registry<br/>[providers.json]"]
  node_provider_setup["Setup wizard<br/>[setup-wizard.js]"]
  node_provider_tools["CLI management<br/>[tools.js]"]
  node_custom_provider["Custom APIs<br/>[add-api.js]"]
end

subgraph group_state["State and context"]
  node_shared_state[("Config and state<br/>[lib.js]")]
  node_context_handoff["Context handoff<br/>[context.js]"]
  node_latency_learning[("Latency history<br/>[latency.js]")]
end

subgraph group_insight["Project insight"]
  node_code_graph["Code graph lookup<br/>[graph.js]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.js]"]
  node_savings["Usage savings<br/>[savings.js]"]
end

node_user(("Developer"))
node_coding_host["Claude Code / Codex"]
node_provider_clis["Provider CLIs"]

node_user -->|"starts work"| node_coding_host
node_coding_host -->|"starts session"| node_session_hooks
node_coding_host -->|"submits prompt"| node_prompt_hook
node_session_hooks -->|"builds routing table"| node_session_routing
node_session_hooks -->|"loads context"| node_context_handoff
node_session_hooks -->|"queries graph"| node_code_graph
node_prompt_hook -->|"reads route"| node_session_routing
node_prompt_hook -->|"checks context"| node_context_handoff
node_coding_host -->|"follows rules"| node_host_rules
node_host_rules -->|"loads workers"| node_worker_agents
node_coding_host -->|"delegates tasks"| node_worker_agents
node_worker_agents -->|"invokes CLI work"| node_worker_runner
node_worker_agents -->|"delegates Codex work"| node_codex_runner
node_worker_runner -->|"runs provider CLI"| node_provider_clis
node_codex_runner -->|"runs Codex CLI"| node_provider_clis
node_session_routing -->|"requests route"| node_router
node_router -.->|"scores models"| node_model_config
node_router -.->|"filters providers"| node_provider_config
node_router -->|"uses timings"| node_latency_learning
node_router -->|"checks eligibility"| node_result_feedback
node_session_routing -->|"reads quota state"| node_shared_state
node_result_feedback -->|"tests provider"| node_provider_clis
node_provider_setup -->|"manages CLIs"| node_provider_tools
node_provider_setup -->|"adds APIs"| node_custom_provider
node_custom_provider -->|"writes provider"| node_provider_config
node_provider_setup -.->|"configures providers"| node_provider_config
node_context_handoff -->|"reads project state"| node_shared_state
node_latency_learning -->|"persists run data"| node_shared_state
node_diagnostics -->|"checks routing"| node_router
node_diagnostics -->|"checks configuration"| node_shared_state
node_savings -->|"reads usage data"| node_shared_state
node_code_graph -->|"runs Graphify"| node_provider_clis

click node_session_hooks "https://github.com/crazytoto/quota-boss/blob/main/scripts/hook-session.js"
click node_prompt_hook "https://github.com/crazytoto/quota-boss/blob/main/scripts/hook-prompt.js"
click node_host_rules "https://github.com/crazytoto/quota-boss/blob/main/scripts/hosts.js"
click node_worker_agents "https://github.com/crazytoto/quota-boss/tree/main/agents"
click node_worker_runner "https://github.com/crazytoto/quota-boss/blob/main/scripts/cli-run.js"
click node_codex_runner "https://github.com/crazytoto/quota-boss/blob/main/scripts/codex-run.js"
click node_result_feedback "https://github.com/crazytoto/quota-boss/blob/main/scripts/self-test.js"
click node_session_routing "https://github.com/crazytoto/quota-boss/blob/main/scripts/session-routing.js"
click node_router "https://github.com/crazytoto/quota-boss/blob/main/scripts/route.js"
click node_model_config "https://github.com/crazytoto/quota-boss/blob/main/config/models.json"
click node_provider_config "https://github.com/crazytoto/quota-boss/blob/main/config/providers.json"
click node_provider_setup "https://github.com/crazytoto/quota-boss/blob/main/scripts/setup-wizard.js"
click node_provider_tools "https://github.com/crazytoto/quota-boss/blob/main/scripts/tools.js"
click node_custom_provider "https://github.com/crazytoto/quota-boss/blob/main/scripts/add-api.js"
click node_shared_state "https://github.com/crazytoto/quota-boss/blob/main/scripts/lib.js"
click node_context_handoff "https://github.com/crazytoto/quota-boss/blob/main/scripts/context.js"
click node_latency_learning "https://github.com/crazytoto/quota-boss/blob/main/scripts/latency.js"
click node_code_graph "https://github.com/crazytoto/quota-boss/blob/main/scripts/graph.js"
click node_diagnostics "https://github.com/crazytoto/quota-boss/blob/main/scripts/diagnostics.js"
click node_savings "https://github.com/crazytoto/quota-boss/blob/main/scripts/savings.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_session_hooks,node_prompt_hook,node_host_rules,node_worker_agents,node_worker_runner,node_codex_runner toneBlue
class node_result_feedback,node_session_routing,node_router,node_model_config toneAmber
class node_provider_config,node_provider_setup,node_provider_tools,node_custom_provider toneMint
class node_shared_state,node_context_handoff,node_latency_learning toneRose
class node_code_graph,node_diagnostics,node_savings,node_user,node_coding_host,node_provider_clis toneIndigo
```

## Components

### Session orchestration

- [Session hooks](https://github.com/crazytoto/quota-boss/blob/main/scripts/hook-session.js): `scripts/hook-session.js`
- [Prompt hook](https://github.com/crazytoto/quota-boss/blob/main/scripts/hook-prompt.js): `scripts/hook-prompt.js`
- [Host rules](https://github.com/crazytoto/quota-boss/blob/main/scripts/hosts.js): `scripts/hosts.js`
- [Worker agents](https://github.com/crazytoto/quota-boss/tree/main/agents): `agents`
- [CLI workers](https://github.com/crazytoto/quota-boss/blob/main/scripts/cli-run.js): `scripts/cli-run.js`
- [Codex runner](https://github.com/crazytoto/quota-boss/blob/main/scripts/codex-run.js): `scripts/codex-run.js`

### Model routing

- [Result feedback](https://github.com/crazytoto/quota-boss/blob/main/scripts/self-test.js): `scripts/self-test.js`
- [Session routing](https://github.com/crazytoto/quota-boss/blob/main/scripts/session-routing.js): `scripts/session-routing.js`
- [Model router](https://github.com/crazytoto/quota-boss/blob/main/scripts/route.js): `scripts/route.js`
- [Model registry](https://github.com/crazytoto/quota-boss/blob/main/config/models.json): `config/models.json`

### Provider management

- [Provider registry](https://github.com/crazytoto/quota-boss/blob/main/config/providers.json): `config/providers.json`
- [Setup wizard](https://github.com/crazytoto/quota-boss/blob/main/scripts/setup-wizard.js): `scripts/setup-wizard.js`
- [CLI management](https://github.com/crazytoto/quota-boss/blob/main/scripts/tools.js): `scripts/tools.js`
- [Custom APIs](https://github.com/crazytoto/quota-boss/blob/main/scripts/add-api.js): `scripts/add-api.js`

### State and context

- [Config and state](https://github.com/crazytoto/quota-boss/blob/main/scripts/lib.js): `scripts/lib.js`
- [Context handoff](https://github.com/crazytoto/quota-boss/blob/main/scripts/context.js): `scripts/context.js`
- [Latency history](https://github.com/crazytoto/quota-boss/blob/main/scripts/latency.js): `scripts/latency.js`

### Project insight

- [Code graph lookup](https://github.com/crazytoto/quota-boss/blob/main/scripts/graph.js): `scripts/graph.js`
- [Diagnostics](https://github.com/crazytoto/quota-boss/blob/main/scripts/diagnostics.js): `scripts/diagnostics.js`
- [Usage savings](https://github.com/crazytoto/quota-boss/blob/main/scripts/savings.js): `scripts/savings.js`

### Other components

- **Developer**
- **Claude Code / Codex**
- **Provider CLIs**

## Connections

- Developer → Claude Code / Codex: starts work (evidence: `README.md`)
- Claude Code / Codex → Session hooks: starts session (evidence: `README.md`)
- Claude Code / Codex → Prompt hook: submits prompt (evidence: `README.md`)
- Session hooks → Session routing: builds routing table (evidence: `scripts/hook-session.js`)
- Session hooks → Context handoff: loads context (evidence: `scripts/hook-session.js`)
- Session hooks → Code graph lookup: queries graph (evidence: `scripts/hook-session.js`)
- Prompt hook → Session routing: reads route (evidence: `scripts/hook-prompt.js`)
- Prompt hook → Context handoff: checks context (evidence: `scripts/hook-prompt.js`)
- Claude Code / Codex → Host rules: follows rules (evidence: `README.md`)
- Host rules → Worker agents: loads workers (evidence: `scripts/hosts.js`)
- Claude Code / Codex → Worker agents: delegates tasks (evidence: `README.md`)
- Worker agents → CLI workers: invokes CLI work (evidence: `README.md`)
- Worker agents → Codex runner: delegates Codex work (evidence: `README.md`)
- CLI workers → Provider CLIs: runs provider CLI (evidence: `README.md`)
- Codex runner → Provider CLIs: runs Codex CLI (evidence: `README.md`)
- Session routing → Model router: requests route (evidence: `scripts/session-routing.js`)
- Model router → Model registry: scores models
- Model router → Provider registry: filters providers
- Model router → Latency history: uses timings (evidence: `scripts/route.js`)
- Model router → Result feedback: checks eligibility (evidence: `scripts/route.js`)
- Session routing → Config and state: reads quota state (evidence: `scripts/session-routing.js`)
- Result feedback → Provider CLIs: tests provider (evidence: `scripts/self-test.js`)
- Setup wizard → CLI management: manages CLIs (evidence: `scripts/setup-wizard.js`)
- Setup wizard → Custom APIs: adds APIs (evidence: `scripts/setup-wizard.js`)
- Custom APIs → Provider registry: writes provider (evidence: `scripts/add-api.js`)
- Setup wizard → Provider registry: configures providers
- Context handoff → Config and state: reads project state (evidence: `scripts/context.js`)
- Latency history → Config and state: persists run data (evidence: `scripts/latency.js`)
- Diagnostics → Model router: checks routing (evidence: `scripts/diagnostics.js`)
- Diagnostics → Config and state: checks configuration (evidence: `scripts/diagnostics.js`)
- Usage savings → Config and state: reads usage data (evidence: `scripts/savings.js`)
- Code graph lookup → Provider CLIs: runs Graphify (evidence: `scripts/graph.js`)
