# dreamrunnermoshi/gru_minion architecture

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

- Interactive diagram: https://gitdiagram.com/dreamrunnermoshi/gru_minion
- Repository: https://github.com/dreamrunnermoshi/gru_minion

## Overview

Gru & Minion is a two-tier agent harness for benchmark tasks: a frontier-model planner can reason, independently run checks, finish, or delegate bounded work to a cheaper model. The session wires the models and shared test environment; benchmark-specific adapters define task setup, submission and scoring. Results include per-role usage, cost, cache and localization analysis, with a separate Claude Code plugin path. The README documents benchmark and plugin capabilities not present in the supplied tree, and excerpts do not expose every runtime call; those links are omitted or marked unverified rather than inferred.

Main entry points: [`orchestrator/session.py`](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/session.py) (Session wiring), [`orchestrator/gru/model.py`](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/model.py) (Gru model), [`orchestrator/gru/environment.py`](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/environment.py) (Action environment), [`orchestrator/minion/model.py`](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/minion/model.py) (Minion model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and session"]
  node_cli["Session CLI<br/>[run_session.py]"]
  node_session["Session wiring<br/>[session.py]"]
  node_config["Config loading<br/>[configs.py]"]
end

subgraph group_planning["Gru planning"]
  node_gru_model["Gru model<br/>[model.py]"]
  node_action_schema["Action parsing<br/>[toolcall.py]"]
  node_gru_env["Action environment<br/>[environment.py]"]
  node_gru_prompts["Gru prompts<br/>[prompts.py]"]
end

subgraph group_execution["Minion execution"]
  node_minion_runner["Delegation runner<br/>[runner.py]"]
  node_minion_model["Minion model<br/>[model.py]"]
end

subgraph group_evaluation["Benchmarks and analysis"]
  node_benchmark["Benchmark adapters"]
  node_cost_context["Cost context<br/>[cost_context.py]"]
  node_usage_metrics["Token and cache metrics<br/>[token_usage.py]"]
  node_real_cost["Real cost accounting<br/>[real_cost.py]"]
  node_coverage["Localization coverage<br/>[coverage.py]"]
  node_run_analysis["Run analysis<br/>[analyze_run.py]"]
end

subgraph group_integration["Plugin integration"]
  node_plugin_skill["Gru Minion skill"]
  node_delegate_cli["Delegate CLI<br/>[delegate.py]"]
end

node_user(("Task operator"))
node_plugin_user(("Claude Code user"))
node_model_provider(("Model provider"))

node_user -->|"starts run"| node_cli
node_cli -->|"builds session"| node_session
node_session -->|"loads configs"| node_config
node_session -->|"constructs"| node_gru_model
node_session -->|"constructs"| node_minion_runner
node_session -->|"constructs"| node_gru_env
node_session -->|"uses benchmark"| node_benchmark
node_gru_model -->|"parses actions"| node_action_schema
node_gru_env -->|"runs delegation"| node_minion_runner
node_gru_env -.->|"submits result"| node_benchmark
node_session -.->|"provides context"| node_cost_context
node_session -->|"extracts usage"| node_usage_metrics
node_gru_model -->|"prices response"| node_real_cost
node_minion_model -->|"prices response"| node_real_cost
node_minion_runner -->|"builds model"| node_minion_model
node_plugin_user -->|"invokes skill"| node_plugin_skill
node_plugin_skill -.->|"drives delegate"| node_delegate_cli
node_user -->|"runs delegate"| node_delegate_cli
node_gru_model -.->|"requests completions"| node_model_provider
node_minion_model -.->|"requests completions"| node_model_provider
node_benchmark -.->|"scores localization"| node_coverage
node_run_analysis -->|"uses coverage"| node_coverage

click node_cli "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/run_session.py"
click node_session "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/session.py"
click node_config "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/configs.py"
click node_gru_model "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/model.py"
click node_action_schema "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/toolcall.py"
click node_gru_env "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/environment.py"
click node_gru_prompts "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/prompts.py"
click node_minion_runner "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/minion/runner.py"
click node_minion_model "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/minion/model.py"
click node_benchmark "https://github.com/dreamrunnermoshi/gru_minion/tree/main/orchestrator/benchmarks"
click node_cost_context "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/metrics/cost_context.py"
click node_usage_metrics "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/metrics/token_usage.py"
click node_real_cost "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/metrics/real_cost.py"
click node_coverage "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/metrics/coverage.py"
click node_run_analysis "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/analyze_run.py"
click node_plugin_skill "https://github.com/dreamrunnermoshi/gru_minion/tree/main/plugins/gru-minion/skills/gru-minion"
click node_delegate_cli "https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/delegate.py"

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_cli,node_session,node_config,node_plugin_user toneBlue
class node_gru_model,node_action_schema,node_gru_env,node_gru_prompts toneAmber
class node_minion_runner,node_minion_model toneMint
class node_benchmark,node_cost_context,node_usage_metrics,node_real_cost,node_coverage,node_run_analysis,node_user toneRose
class node_plugin_skill,node_delegate_cli,node_model_provider toneIndigo
```

## Components

### Entry and session

- [Session CLI](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/run_session.py): `orchestrator/run_session.py`
- [Session wiring](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/session.py): `orchestrator/session.py`
- [Config loading](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/configs.py): `orchestrator/configs.py`

### Gru planning

- [Gru model](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/model.py): `orchestrator/gru/model.py`
- [Action parsing](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/toolcall.py): `orchestrator/gru/toolcall.py`
- [Action environment](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/environment.py): `orchestrator/gru/environment.py`
- [Gru prompts](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/gru/prompts.py): `orchestrator/gru/prompts.py`

### Minion execution

- [Delegation runner](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/minion/runner.py): `orchestrator/minion/runner.py`
- [Minion model](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/minion/model.py): `orchestrator/minion/model.py`

### Benchmarks and analysis

- [Benchmark adapters](https://github.com/dreamrunnermoshi/gru_minion/tree/main/orchestrator/benchmarks): `orchestrator/benchmarks`
- [Cost context](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/metrics/cost_context.py): `orchestrator/metrics/cost_context.py`
- [Token and cache metrics](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/metrics/token_usage.py): `orchestrator/metrics/token_usage.py`
- [Real cost accounting](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/metrics/real_cost.py): `orchestrator/metrics/real_cost.py`
- [Localization coverage](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/metrics/coverage.py): `orchestrator/metrics/coverage.py`
- [Run analysis](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/analyze_run.py): `orchestrator/analyze_run.py`

### Plugin integration

- [Gru Minion skill](https://github.com/dreamrunnermoshi/gru_minion/tree/main/plugins/gru-minion/skills/gru-minion): `plugins/gru-minion/skills/gru-minion`
- [Delegate CLI](https://github.com/dreamrunnermoshi/gru_minion/blob/main/orchestrator/delegate.py): `orchestrator/delegate.py`

### Other components

- **Task operator**
- **Claude Code user**
- **Model provider**

## Connections

- Task operator → Session CLI: starts run (evidence: `README.md`)
- Session CLI → Session wiring: builds session (evidence: `orchestrator/run_session.py`)
- Session wiring → Config loading: loads configs (evidence: `orchestrator/session.py`)
- Session wiring → Gru model: constructs (evidence: `orchestrator/session.py`)
- Session wiring → Delegation runner: constructs (evidence: `orchestrator/session.py`)
- Session wiring → Action environment: constructs (evidence: `orchestrator/session.py`)
- Session wiring → Benchmark adapters: uses benchmark (evidence: `orchestrator/session.py`)
- Gru model → Action parsing: parses actions (evidence: `orchestrator/gru/model.py`)
- Action environment → Delegation runner: runs delegation (evidence: `orchestrator/gru/environment.py`)
- Action environment → Benchmark adapters: submits result
- Session wiring → Cost context: provides context (evidence: `orchestrator/session.py`)
- Session wiring → Token and cache metrics: extracts usage (evidence: `orchestrator/session.py`)
- Gru model → Real cost accounting: prices response (evidence: `orchestrator/gru/model.py`)
- Minion model → Real cost accounting: prices response (evidence: `orchestrator/minion/model.py`)
- Delegation runner → Minion model: builds model (evidence: `orchestrator/minion/runner.py`)
- Claude Code user → Gru Minion skill: invokes skill (evidence: `README.md`)
- Gru Minion skill → Delegate CLI: drives delegate
- Task operator → Delegate CLI: runs delegate (evidence: `README.md`)
- Gru model → Model provider: requests completions
- Minion model → Model provider: requests completions
- Benchmark adapters → Localization coverage: scores localization
- Run analysis → Localization coverage: uses coverage (evidence: `orchestrator/analyze_run.py`)