Introduction

reckon is an agent workspace for talking to your infrastructure — investigating incidents, sweeping for problems, and understanding behaviour over time. It wires together fourteen read-only observability, CI/CD, queue, Kubernetes, and database CLIs inside one isolated, per-environment credential setup.

It is not a single CLI or installable binary. Clone the workspace, run its idempotent setup script, add production credentials, and launch Claude Code, Codex CLI, OpenCode, or another runtime that follows AGENTS.md. The agent can then correlate signals across systems in one session instead of investigating each tool in isolation.

Three modes

Not every question is an incident. reckon routes work by what is known:

• investigate — a specific bad thing in a specific window: an alert fired, a metric dropped, errors spiked, a deploy is suspected. Produces an RCA under incidents/<YYYY-MM-DD>-<slug>/.
• monitor — nothing known to be broken; sweeping. Health checks, pre- and post-deploy verification, drift hunting. Produces a health report, and escalates into investigate when it finds something real.
• analyze — no fault at all: capacity headroom, cost drivers, slow-query and endpoint profiling, growth. Produces a ranked analysis.

Environments

One clone targets production, staging, and UAT, selected by RECKON_ENV. Each environment gets its own credentials (.env.<env>) and its own CLI config directory (.config/<env>/), so no two ever share credential state. An unrecognised value fails closed — no credentials load at all, rather than silently falling back to a real environment.

./scripts/reckon use staging     # persists across shells
./scripts/reckon status          # what is active, and how it resolved

The read-only posture is identical everywhere; the split governs which infrastructure you touch, never how safe the access is.

The control surface

scripts/reckon makes the workspace's own state legible, so neither you nor the agent has to guess what is connected:

./scripts/reckon status      # active environment + integration matrix
./scripts/reckon doctor      # diagnose setup problems
./scripts/reckon preflight   # compact digest an agent reads before its first query
./scripts/reckon verify      # live connection checks (the only one that hits your infra)

The toolbelt

• Observability: Grafana for alerts, dashboards, datasources, and annotations; CubeAPM for distributed traces, PromQL metrics, and LogsQL logs; AWS for CloudWatch and infrastructure signals; and optional es for Elasticsearch/ELK log stores.
• CI/CD and change context: Jenkins for jobs, builds, pipelines, and logs; GitHub CLI for pull requests, Actions runs, releases, and issues.
• Queues and infrastructure: kcat and rpk for Kafka metadata, messages, and consumer lag; kubectl for Kubernetes state and events; redis-cli for cache diagnostics.
• Databases: mongosh, psql, and mysql for narrowly scoped, approval-gated production reads after observability has identified a suspect.

How an investigation works

The workspace guides an agent through a broad-to-narrow cascade: assess alerts and failures, inspect traces and logs, check metrics, correlate deployments, map dependencies, then consult queues, infrastructure, caches, or databases only where the evidence points. Findings and raw evidence are persisted under incidents/<YYYY-MM-DD>-<slug>/.

Every RCA carries a root_cause_category from a controlled vocabulary, a calibrated confidence score, and an explicit split between claims backed by tool evidence and claims still unproven — so the incident corpus becomes searchable across incidents instead of a pile of prose.