# julie-elkins/k8s-triage-agent architecture

> Architecture diagram of the GitHub repository julie-elkins/k8s-triage-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/julie-elkins/k8s-triage-agent
- Repository: https://github.com/julie-elkins/k8s-triage-agent

## Overview

k8s-triage-agent is a read-only Kubernetes triage agent that preserves distinctions between clean results and checks that were refused, unavailable, or inconclusive. The human workflow starts a run, lists pods before targeting one, gathers pod description, logs, and namespace metrics, then diagnoses and reports what could not be checked before pausing for approval. It also exposes the four read-only tools over MCP stdio. The excerpts show the API, contract, and orchestration seams; some graph-stage transitions and unsampled capabilities are documented but not directly visible in the excerpts.

Main entry points: [`src/k8s_triage/server.py`](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/server.py) (MCP server), [`src/k8s_triage/tools.py`](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/tools.py) (Read-only tools), [`src/k8s_triage/cli.py`](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/cli.py) (CLI runner), [`src/k8s_triage/graph.py`](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py) (Evidence collection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI runner<br/>[cli.py]"]
  node_mcp_server["MCP server<br/>[server.py]"]
end

subgraph group_orchestration["Triage workflow"]
  node_intake["Run intake<br/>[graph.py]"]
  node_targeting["Pod targeting<br/>[graph.py]"]
  node_collection["Evidence collection<br/>[graph.py]"]
  node_diagnosis["Diagnosis and report<br/>[graph.py]"]
  node_approval["Approval gate<br/>[graph.py]"]
end

subgraph group_access["Cluster access"]
  node_cluster["Kubernetes client<br/>[cluster.py]"]
  node_kubernetes["Kubernetes API"]
  node_rbac["RBAC boundary"]
end

subgraph group_protocol["Tool interfaces"]
  node_toolbelt["Local toolbelt<br/>[toolbelt.py]"]
  node_mcp_toolbelt["MCP toolbelt<br/>[mcp_toolbelt.py]"]
  node_tools["Read-only tools<br/>[tools.py]"]
end

subgraph group_state["Contracts and state"]
  node_contracts["Outcome contracts<br/>[contracts.py]"]
  node_checkpointing["Checkpointing<br/>[checkpointing.py]"]
  node_sqlite[("SQLite checkpoints")]
end

node_operator(("Operator"))
node_mcp_client(("MCP client"))

node_operator -->|"starts run"| node_cli
node_cli -->|"invokes graph"| node_intake
node_intake -.->|"routes valid input"| node_targeting
node_targeting -.->|"dispatches checks"| node_collection
node_collection -->|"calls tools"| node_toolbelt
node_toolbelt -->|"delegates"| node_tools
node_tools -->|"reads cluster"| node_cluster
node_cluster -->|"calls API"| node_kubernetes
node_rbac -->|"limits access"| node_kubernetes
node_collection -.->|"provides outcomes"| node_diagnosis
node_diagnosis -.->|"presents findings"| node_approval
node_cli -->|"opens saver"| node_checkpointing
node_checkpointing -->|"serializes types"| node_contracts
node_checkpointing -->|"writes state"| node_sqlite
node_mcp_client -->|"calls tools"| node_mcp_server
node_mcp_server -->|"calls handlers"| node_tools
node_mcp_server -->|"provides client"| node_cluster
node_mcp_toolbelt -->|"uses stdio"| node_mcp_server
node_tools -->|"returns outcomes"| node_contracts

click node_cli "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/cli.py"
click node_mcp_server "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/server.py"
click node_intake "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py"
click node_targeting "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py"
click node_collection "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py"
click node_diagnosis "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py"
click node_approval "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py"
click node_toolbelt "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/toolbelt.py"
click node_mcp_toolbelt "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/mcp_toolbelt.py"
click node_tools "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/tools.py"
click node_contracts "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/contracts.py"
click node_checkpointing "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/checkpointing.py"
click node_cluster "https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/cluster.py"
click node_rbac "https://github.com/julie-elkins/k8s-triage-agent/tree/main/deploy"

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_mcp_server,node_mcp_client toneBlue
class node_intake,node_targeting,node_collection,node_diagnosis,node_approval toneAmber
class node_cluster,node_kubernetes,node_rbac toneMint
class node_toolbelt,node_mcp_toolbelt,node_tools toneRose
class node_contracts,node_checkpointing,node_sqlite,node_operator toneIndigo
```

## Components

### Entry points

- [CLI runner](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/cli.py): `src/k8s_triage/cli.py`
- [MCP server](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/server.py): `src/k8s_triage/server.py`

### Triage workflow

- [Run intake](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py): `src/k8s_triage/graph.py`
- [Pod targeting](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py): `src/k8s_triage/graph.py`
- [Evidence collection](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py): `src/k8s_triage/graph.py`
- [Diagnosis and report](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py): `src/k8s_triage/graph.py`
- [Approval gate](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/graph.py): `src/k8s_triage/graph.py`

### Cluster access

- [Kubernetes client](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/cluster.py): `src/k8s_triage/cluster.py`
- **Kubernetes API**
- [RBAC boundary](https://github.com/julie-elkins/k8s-triage-agent/tree/main/deploy): `deploy`

### Tool interfaces

- [Local toolbelt](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/toolbelt.py): `src/k8s_triage/toolbelt.py`
- [MCP toolbelt](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/mcp_toolbelt.py): `src/k8s_triage/mcp_toolbelt.py`
- [Read-only tools](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/tools.py): `src/k8s_triage/tools.py`

### Contracts and state

- [Outcome contracts](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/contracts.py): `src/k8s_triage/contracts.py`
- [Checkpointing](https://github.com/julie-elkins/k8s-triage-agent/blob/main/src/k8s_triage/checkpointing.py): `src/k8s_triage/checkpointing.py`
- **SQLite checkpoints**

### Other components

- **Operator**
- **MCP client**

## Connections

- Operator → CLI runner: starts run (evidence: `src/k8s_triage/cli.py`)
- CLI runner → Run intake: invokes graph (evidence: `src/k8s_triage/cli.py`)
- Run intake → Pod targeting: routes valid input (evidence: `src/k8s_triage/graph.py`)
- Pod targeting → Evidence collection: dispatches checks (evidence: `src/k8s_triage/graph.py`)
- Evidence collection → Local toolbelt: calls tools (evidence: `src/k8s_triage/graph.py`)
- Local toolbelt → Read-only tools: delegates (evidence: `src/k8s_triage/toolbelt.py`)
- Read-only tools → Kubernetes client: reads cluster (evidence: `src/k8s_triage/tools.py`)
- Kubernetes client → Kubernetes API: calls API (evidence: `README.md`)
- RBAC boundary → Kubernetes API: limits access (evidence: `README.md`)
- Evidence collection → Diagnosis and report: provides outcomes (evidence: `src/k8s_triage/graph.py`)
- Diagnosis and report → Approval gate: presents findings (evidence: `src/k8s_triage/graph.py`)
- CLI runner → Checkpointing: opens saver (evidence: `src/k8s_triage/cli.py`)
- Checkpointing → Outcome contracts: serializes types (evidence: `src/k8s_triage/checkpointing.py`)
- Checkpointing → SQLite checkpoints: writes state (evidence: `src/k8s_triage/checkpointing.py`)
- MCP client → MCP server: calls tools (evidence: `README.md`)
- MCP server → Read-only tools: calls handlers (evidence: `src/k8s_triage/server.py`)
- MCP server → Kubernetes client: provides client (evidence: `src/k8s_triage/server.py`)
- MCP toolbelt → MCP server: uses stdio (evidence: `src/k8s_triage/mcp_toolbelt.py`)
- Read-only tools → Outcome contracts: returns outcomes (evidence: `src/k8s_triage/tools.py`)
