kubeintellect
AGENTS.md39 starsChanged 2 months agoMITView on GitHub
Instructions for coding agents (Claude Code, Codex, Cursor, Copilot, Aider, …) working in this repository. Humans should read CONTRIBUTING.md — it is the authority; this file is the machine-oriented summary of it. Format: <https://agents.md/> KubeIntellect is an LLM-orchestrated multi-agent framework for Kubernetes operations. It answers questions about a live cluster by querying kubectl, Prometheus (PromQL), and Loki (LogQL), and it can act on the cluster — but only behind a human-in-the-loop approval gate with role-based access control. This is an…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repositoryOne other file it gives its agents.
- llms.txtllms.txt
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
13 rules. About 0 are common, 9 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 39
Do not "fix" duplication *between* version directories.
- Very specific: line 44
Start with v4/docs/architecture.md for the system topology and v4/docs/configuration.md for feature flags.
- Very specific: line 62
All paths in this table are relative to v4/.
- Very specific: line 161
If you create a file, do not mark it executable unless it is a script with a shebang.
- Distinctive: line 178
Do not report work as complete without running these and reading the output.
- Distinctive: line 209
Do not bump the pin. The remaining families must land as separate per-rule PRs, tracked in #75 ("replaces the prematurely-closed
- Very specific: line 225
Delete one of those comments and UP045 fires again.
- Distinctive: line 262
Never bypass the HITL approval gate: Every mutating cluster operation (scale, delete, restart, apply) stops for explicit human approval.
- Distinctive: line 308
Every behavioral change needs a test that fails before your change and passes after.
- Distinctive: line 309
Verify that directly — write the test, run it against the unpatched code, see it fail.
- Distinctive: line 310
Ask of each new test: *what would have to break for this to fail?* If the answer is "nothing", the test is asserting a constant against …
- Distinctive: line 320
Keep changes scoped to the issue.
- Distinctive: line 321
If a capability can be a new *tool* on an existing agent, don't make it a new *agent*.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Instructions for coding agents (Claude Code, Codex, Cursor, Copilot, Aider, …) working in
this repository. Humans should read CONTRIBUTING.md — it is the
authority; this file is the machine-oriented summary of it.
Format: https://agents.md/
What this project is
KubeIntellect is an LLM-orchestrated multi-agent framework for Kubernetes operations. It
answers questions about a live cluster by querying kubectl, Prometheus (PromQL), and Loki
(LogQL), and it can act on the cluster — but only behind a human-in-the-loop approval gate
with role-based access control.
This is an incident-response tool for production clusters. Output that looks like a real diagnosis but isn't is the single worst failure mode. See "Safety invariants" below — those are not style preferences.
Repository layout
The repo holds four generations of the product. Only v4/ accepts behavioral changes.
| Path | Role | Changes allowed |
v4/ | Current platform — a uv monorepo | ✅ Yes, this is where work happens |
v3/, v2/ | Baseline / experimental lineage | 🔸 Bug fixes and docs only |
v1/ | Published, cited by the paper | ❄️ Frozen — docs/typos only |
root (Makefile, deploy/, scripts/) | Shared infra: one Kind cluster, one observability stack | 🔸 Only if the issue asks |
v4/ contains three distributions:
v4/packages/kubeintellect-server/— the FastAPI server and the agent graph (app/)v4/packages/kube-q/— thekqterminal clientv4/packages/ki-protocol/— the shared SSE wire protocol
Do not "fix" duplication between version directories. They are deliberately independent snapshots of a design lineage, and the older ones are cited by a peer-reviewed paper.
Working map of v4/
Start with v4/docs/architecture.md for the system topology and
v4/docs/configuration.md for feature flags. The main code paths
are:
| Concern | Source of truth |
| Process startup and background services | packages/kubeintellect-server/app/main.py |
| Settings, environment validation, feature flags | packages/kubeintellect-server/app/core/config.py |
| Authenticated API surface | packages/kubeintellect-server/app/api/v1/router.py and packages/kubeintellect-server/app/api/v1/endpoints/ |
| Default V2 LangGraph and session runner | packages/kubeintellect-server/app/agent/workflow.py |
| Optional explicit-node Cortex graph | packages/kubeintellect-server/app/cortex/graph.py |
| Cluster, Prometheus, Loki, and Helm tools | packages/kubeintellect-server/app/tools/ |
| Sensorium, detectors, and autonomous investigations | packages/kubeintellect-server/app/sensorium/, packages/kubeintellect-server/app/detectors/, packages/kubeintellect-server/app/autonomy/ |
| Memory and persistence | packages/kubeintellect-server/app/memory/, packages/kubeintellect-server/app/db/, and packages/kubeintellect-server/app/db/schema.sql |
| Server-to-client event schema | packages/ki-protocol/ki_protocol/ |
| Terminal client | packages/kube-q/kube_q/ |
| Browser demo | packages/kube-q/web/ |
All paths in this table are relative to v4/. CORTEX_V4_ENABLED selects the Cortex graph at
graph initialization; the V2 graph remains the default. Do not implement the same behavior
in both graphs unless the issue explicitly requires parity.
The SSE protocol has two deliberately separate views: ki_protocol/wire.py defines what the
server emits, and ki_protocol/events.py defines what clients parse. Any wire-format change
must update both, plus the server and kube-q parity tests. The server and kube-q test trees are
also separate Python packages named tests; run them as separate pytest invocations.
Setup
Requires Python 3.12 and uv.
cd v4
uv sync # creates .venv and installs the whole workspaceRequired validation
The root .github/workflows/ci.yml is the executable source of
truth. From the repo root, make setup installs the workspace and runs all nine
locally-runnable gates in order, but use the standalone commands below when validating a
change so the lint scope cannot lag behind CI. Individually, from v4/:
# 1. Lint — `ruff check` only. NOT `ruff format`.
uv run ruff check packages/kubeintellect-server/app/ packages/ki-protocol/ packages/kube-q/ tests/ scripts/
# 2. Types — the workspace is at ZERO errors; keep it there.
uv run mypy packages/kubeintellect-server/app packages/ki-protocol packages/kube-q/kube_q
# 3. Server suite (5985 tests)
uv run python -m pytest tests/ -q
# 4. kq CLI suite (757 tests)
cd packages/kube-q && uv run python -m pytest tests/ -q
# 5. Doc claims — every documented count is recollected from the code and compared.
uv run python scripts/check_doc_claims.py # --fix rewrites the numbers in placePlus four repo-root gates, which need no virtualenv. Gates 5, 8 and 9 run inside existing CI
jobs (Lint (ruff) for the first, Syntax warnings for the other two) rather than jobs
of their own — branch protection matches required checks by name, so a new job name is a check
main does not require and every open PR would sit unmergeable until the settings caught up:
# 6. File modes — a tracked file is executable if and only if it has a shebang.
make check-modes # or: ./scripts/check-file-modes.sh
make fix-modes # corrects any violation in place
# 7. Syntax — every tracked .py outside v1-v3 compiles with no SyntaxWarning.
make check-syntax # or: ./scripts/check-syntax-warnings.py
# 8. Encoding — every text-mode read/write names an encoding (#136/#156).
make check-encoding # or: ./scripts/check-text-encoding.py
# 9. Roster — .all-contributorsrc and the README table name the same people (#167).
make check-roster # or: ./scripts/check-contributor-roster.pyci.yml produces 15 named checks and main requires 9. Which is which — and why each
unrequired one is unrequired — is recorded in
.github/required-checks.yml; make check-required compares
that record against the live branch protection (needs an authenticated gh, so it is not a CI
job). Adding a job to ci.yml without deciding its status fails that check rather than
inheriting silence. Note what the unrequired list contains: Container image (build + serve)
is not required, so a PR that breaks the published image can merge green.
CI additionally checks the lockfile and clean-wheel installation, builds and probes the container, and runs the browser demo's lint/build. When a change reaches those surfaces, run the corresponding focused checks locally:
# From v4/ — lockfile and all three distributions
uv lock --check
uv build --package ki-protocol -o dist
uv build --package kube-q -o dist
uv build --package kubeintellect -o dist
# From v4/packages/kube-q/web/ — Node 24 in CI
npm ci --no-audit --no-fund
npm run lint
npm run build
# From v4/ — documentation consistency and site build
uv run python scripts/check_doc_claims.py
uv run mkdocs buildPython 3.14 test jobs are visible but non-blocking candidate coverage. Python 3.12 and 3.13, the install smoke test, web build, and container build-and-serve job are blocking coverage.
Both report what they examined, not what exists: the mode gate reads one git index
(--git-dir DIR points it at another) and the syntax gate compiles the tracked *.py it
can read. Either one finding nothing to check now fails — a sparse or partial checkout
used to produce a confident pass over zero files.
If you create a file, do not mark it executable unless it is a script with a shebang. This
gate exists because ruff's EXE002 cannot run here (see the pin below), so nothing else
catches a stray +x.
The syntax gate exists for the same structural reason: the pinned ruff does not report an
invalid escape sequence in the linted scope, mypy never compiles source, and pytest only
emits the warning on a cold .pyc cache — so a green suite was not evidence. That is how #63
reached an outside contributor, and that escape was also silently corrupting the jsonpath
examples in the coordinator prompt. Never silence one of these; fix the string.
The suites run on two interpreters
CI runs both suites on Python 3.12 and 3.13 (Tests (…) and Tests (… · py3.13)). 3.13 is
not optional coverage — v4/Dockerfile's runtime stage is python:3.13-slim, so it is the
interpreter the shipped container actually executes. If a change passes on one and fails on the
other, that difference is the bug.
Do not report work as complete without running these and reading the output.
The test counts above are gated. v4/scripts/check_doc_claims.py collects both suites and
fails if either number here disagrees, so a PR that adds tests must update this file. That
number drifted to 990-vs-1031 before the gate existed, and a wrong count is worse than none —
an agent uses it to decide whether its own run was complete.
mypy is clean — if it reports something, it is from your change
The workspace type-checks with zero errors across 196 source files, and Types (mypy) is
a CI job. Do not add # type: ignore to silence a real error.
Two annotations are load-bearing and mypy cannot verify them — see "Safety invariants" #6.
Known pre-existing debt — do not try to fix it in an unrelated PR
ruff format --checkis not a CI gate and would reformat 130 files.make lintinv4/does run it, somake lintfails on a clean checkout. Use theruff checkcommand above to predict CI, notmake lint.ruffis pinned<0.16on purpose. Re-measure rather than quoting a number — it drifts with the code, and every number in this bullet has already been wrong once. As measured with ruff 0.16.3 on 2026-09-09, over the exact lint scope in theruff checkcommand above (app/,ki-protocol/,kube-q/,tests/,scripts/): 556 findings, 233 of them auto-fixable. Largest families:I001168 (auto-fixable),BLE001165,PLW151061,RUF10021,ISC00419. Narrowed to just the three packages, it is 251.(The historical series, kept because the drift is the point: 438 → 342 after the
EXE002family was cleared (#70) → 317 on 2026-08-18 over the three packages → 251 for the same scope today. The 2026-08-18 figure was measured over a narrower scope than the one it was filed under, which is how "317" and "556" can both be honest.)Do not bump the pin. The remaining families must land as separate per-rule PRs, tracked in #75 ("replaces the prematurely-closed #64"). Comment there before starting — do not open a new issue. Note the consequence of the pin:
ruffhere is blind toEXE002/EXE001, which is why the separatemake check-modesgate above exists.⚠️
UP045is a safety trap — and it now reports zero, which is the thing to understand before you touch it. It is at zero because it is suppressed, not because the hazard is gone. Three sites carry an inline# noqa: UP045:app/agent/nodes/coordinator.py:736 coordinator(...) app/agent/nodes/coordinator.py:831 _direct_answer(...) tests/test_injected_config_invariant.py:112 the negative-control canaryDelete one of those comments and
UP045fires again;ruff check --fixthen rewritesOptional[X]→X | Noneand the autofix is marked safe, so it applies without--unsafe-fixes. Verified on 2026-09-09 by removing the twocoordinator.pycomments and re-running: 2 findings, both auto-fixed toRunnableConfig | None. Never runruff --fixover this family, and never "clean up" one of those three# noqacomments.Two corrections to what this section used to say, both verified rather than reasoned:
- It said the family "needs a hand-audited PR". That PR already happened — the sites are
suppressed and
Optional[is down to 8 occurrences inapp/. There is no backlog of 91 here to clear, and a contributor sent to clear it would find nothing to do. It listed
app/agent/nodes/coordinator.pyamong the files where widening the annotation disables RBAC. It does not, and the distinction matters. LangGraph injects a node's config by parameter name, so all three spellings receive it — measured directly:Optional[RunnableConfig] -> user_role='admin' OK RunnableConfig | None -> user_role='admin' OK RunnableConfig (bare) -> user_role='admin' OKThe RBAC/HITL hazard in invariant #6 is specific to tools, where
langchain_corematchestype_ is RunnableConfigby identity. Those sites areapp/tools/kubectl_tool.pyand the four ACI read verbs inapp/tools/aci/read_verbs.py, they are all currently bare and correct, andtests/test_injected_config_invariant.pygates them (8 passed). Thecoordinator.pysuppressions are worth keeping anyway — they stop a batch--fixfrom sweeping the file — but do not go looking for an RBAC bug there, because there isn't one.
- It said the family "needs a hand-audited PR". That PR already happened — the sites are
suppressed and
Safety invariants — never weaken these
A change that violates any of these will be rejected regardless of test results.
- Never fabricate an answer. Any command that emits a diagnosis, report, postmortem, or
summary must fail loudly when its data source is absent. It must never return a plausible
hardcoded or synthesized result. This has happened before (PR #58): a command returned a
literal
status: okwith an invented high-severity finding on a machine with no cluster, and its tests passed because they asserted the hardcoded dict against itself. - Never bypass the HITL approval gate. Every mutating cluster operation (scale, delete, restart, apply) stops for explicit human approval. No flag, config, or "convenience" path may skip it.
- Never weaken RBAC. The
admin/operator/readonlyrole checks are load-bearing. - Never widen the kubectl safety guard.
shell=Falseand the command allowlist stay. - Never log or echo secrets. DSNs and tokens pass through the existing redaction helpers.
Never "fix" an injected
RunnableConfigannotation. On tools that receive the run config, the annotation must stay exactly:config: Annotated[RunnableConfig, InjectedToolArg] = None, # type: ignore[assignment]langchain_corematches this parameter by identity (type_ is RunnableConfig). Widening it toRunnableConfig | None— which is what a type checker, a linter, or an agent "cleaning up implicit Optional" will suggest — stops the run config being injected at all. The tool then silently receivesconfig=Noneand losesuser_role(RBAC) andhitl_bypass(the HITL gate). Behaviourally verified byv4/tests/test_kubectl_tool.py::TestAlwaysConfirm; see issue #54 for the full analysis.The annotation itself is now gated by
v4/tests/test_injected_config_invariant.py, which scans everyconfig: Annotated[…, InjectedToolArg]parameter inapp/and fails if any is not bareRunnableConfig, plus two canary tests proving against the installedlangchain_corethat the bare form is injected and the widened form is not.That gate was added after finding the widened form live in
app/tools/aci/read_verbs.py(all four ACI read verbs). It was harmless there — those verbs never readuser_role, so no RBAC decision was affected — but it is the exact shape of the failure this invariant exists to prevent, and it survived because a tool that never usesconfigpasses every behavioural test while silently receivingNone. A behavioural test cannot catch that; only asserting the annotation can.One read-tool failure must not abort a parallel batch. The default coordinator and specialist ReAct loops must pass tools through
app.agent.tool_execution.fault_isolated_tool_node. Ordinary invocation errors become per-call errorToolMessages that include the failed command and reason.The boundary re-raises
GraphBubbleUp, notGraphInterrupt. That base class is LangGraph's marker for every control-flow signal —GraphInterrupt(the HITL approval gate),ParentCommand(a tool routing the parent graph) andGraphDrained— and narrowing it to one named subclass converts the other two into ordinary tool errors, silently losing the routing while every existing test still passes. Both the command and the failure reason go throughredact_secretsbefore they reach the model.
Testing expectations
- Every behavioral change needs a test that fails before your change and passes after. Verify that directly — write the test, run it against the unpatched code, see it fail.
- Ask of each new test: what would have to break for this to fail? If the answer is "nothing", the test is asserting a constant against itself and is worthless.
- For a new user-facing command, run it by hand against a deliberately absent resource (a made-up session id, no cluster configured) and confirm the output is a refusal with a non-zero exit code, not a plausible-looking artifact. CI cannot catch this class.
Conventions
- Match the style of the file you are editing; don't reformat surrounding code.
- Comment density and naming should look like the neighbours'.
- Keep changes scoped to the issue. Drive-by refactors make review harder and get sent back.
- If a capability can be a new tool on an existing agent, don't make it a new agent.
Pull requests
- Branch from
main. One logical change per PR. - Fill in the PR template, including which gate commands you ran and their output.
- Disclose substantial AI assistance in the PR description. This is not held against you — it tells reviewers where to look, exactly like "I copied this pattern from the Kubernetes docs" would. What matters is that you understand every line well enough to explain it in review and that you ran the tests yourself.
- First-time contributors: CI does not run on your PR until a maintainer approves the workflow run. If your PR looks stalled with no checks, that is why — it is not your fault and you do not need to do anything.
Do not touch
.claude/,design/,evaluation/,papers/,v5/— not part of the public contribution surface.- Anything under
_archives/. - The
v1/–v3/trees, beyond documentation typos.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

