reckon 发布智能体运维工作区，接入 14 个只读 CLI 排查线上故障

An agent workspace for talking to your infrastructure — investigating incidents, running RCAs, and understanding production behavior with a read-only ops toolbelt.

📖 Docs site: see web/ (Next.js + Fumadocs, static-exported to Cloudflare Workers Assets). Run cd web && pnpm install && pnpm dev for local preview.

Overview

reckon is an agent workspace for talking to your infrastructure — investigating incidents, running RCAs, and understanding production behavior. It wires together fourteen read-only observability, CI/CD, and infrastructure CLIs, including clickhouse client for analytics and event data and optional es for ES/ELK logs, under one isolated credential environment so a coding agent can correlate signals across systems in one session. It runs under Claude Code (subscription or API key), Codex CLI (ChatGPT subscription or API key), or any agent runtime that reads AGENTS.md — see Agent runtimes.

Reckon also provides saved investigations: service mappings, bounded evidence collection, findings and hypotheses, reports, history, and resume. Optional Jira and Nginx Proxy Manager integrations add ticket and routing context. Requires Python 3.9+; no Python packages to install.

Try the complete offline walkthrough:

./scripts/reckon demo

It creates synthetic evidence and prints a report and resume command without contacting infrastructure. See the investigation guide for mapping a real service, starting debug, collecting evidence, and producing an RCA. The coding agent supplies the reasoning; Reckon preserves the work.

Development status and next steps: product plan and readiness/isolation review.

One clone supports production, staging, and UAT, but exactly one is active at a time. Reckon never chooses production implicitly: select an environment explicitly, and never switch during one investigation.

Quick start

./scripts/reckon use production # explicit first-time selection
./scripts/reckon status      # what environment is active, what's locally configured
./scripts/reckon doctor      # diagnose setup problems
./scripts/reckon preflight   # the digest a coding agent reads first
./scripts/reckon use staging # switch environment (persists in .reckon-env)
./scripts/reckon verify      # live connection checks — the only one that hits your infra

direnv is optional. scripts/agent.sh activates the selected environment itself. For direct CLI use, direnv can auto-load .envrc; ./scripts/reckon doctor detects when the current shell is inactive. To activate a shell without direnv:

eval "$(./scripts/reckon env)"

Editions

reckon comes in two editions that share one brain and differ in who runs the investigation. This repo is the first one.

The methodology (skills/reckon/), the facts (infra-knowledge/), and the incident corpus (incidents/) are the shared core — both editions consume them verbatim. Everything that assumes a shell, direnv, or a human at the keyboard is workspace-specific.

→ EDITIONS.md — the full split, what belongs to the shared core, and the four seam rules that keep the hosted edition attachable later.

Tools available to the agent:

Platform support

Setup

The setup scripts are idempotent — every install function checks whether the binary is already on PATH and skips it if so. Re-run any time you add a new tool to the workspace; only the missing ones get installed.

macOS

git clone https://github.com/piyush-gambhir/reckon.git
cd reckon
bash scripts/setup.sh

Requires Homebrew. scripts/setup.sh installs missing tools via brew, installs the custom Go-based CLIs via pinned go install versions, seeds .env.production and the per-environment infra-knowledge/ directories, and wires the repo-local skill. Select an environment before running direnv allow.

Linux (Debian/Ubuntu or Fedora/RHEL family)

git clone https://github.com/piyush-gambhir/reckon.git
cd reckon
bash scripts/setup.sh

The same scripts/setup.sh auto-detects the distro via /etc/os-release and dispatches to apt or dnf. It verifies checksums for pinned rpk and the current stable kubectl download and uses signed package repositories where available; when a trusted repository is unavailable it fails closed with manual verification guidance. Other distros print a "manual install required" message.

Hooking direnv into your shell (one-time): add eval "$(direnv hook bash)" to ~/.bashrc (or the zsh equivalent to ~/.zshrc). Without this, .envrc won't auto-load when you cd into the repo.

Windows

Recommended: use WSL2. Native Windows is missing reliable ports of direnv, kcat, and rpk — and those are central to the workspace. With WSL2 you get the full Linux experience with no compromises.

# One-time WSL setup (PowerShell as Administrator):
wsl --install
# Reboot, then inside WSL:
git clone https://github.com/piyush-gambhir/reckon.git
cd reckon
bash scripts/setup.sh

Native PowerShell (partial support): if WSL isn't an option, scripts/setup.ps1 installs 10 of the 14 integrations natively — 6 via winget (aws, gh, mongosh, psql, mysql, kubectl) and 4 via go install (grafana, jenkins, cubeapm, es). kcat, rpk, redis-cli, and ClickHouse need WSL2 or manual installation. scripts/reckon.ps1, scripts/activate.ps1, and scripts/agent.ps1 provide the native control, activation, and launcher surfaces.

git clone https://github.com/piyush-gambhir/reckon.git
cd reckon
.\scripts\setup.ps1
.\scripts\reckon.ps1 use production
notepad .env.production           # fill in real credentials
. .\scripts\activate.ps1          # NOTE the leading dot+space
.\scripts\reckon.ps1 status

To auto-activate the selected .env.<env> in every PowerShell session inside this folder, add to your $PROFILE:

if ($PWD.Path -like '*\reckon*') { . .\scripts\activate.ps1 }

Manual install (any platform)

If the script doesn't fit (unsupported distro, locked-down corporate machine, etc.), install each tool yourself using whichever package manager you have. Tool-by-tool install commands are documented in scripts/setup.sh (one install_<tool> function per tool — read those for the canonical install path on each platform).

After tool installation, finish workspace setup manually:

cp -n .env.example .env.production                     # then edit with real credentials
bash scripts/setup.sh                                  # seeds infra-knowledge/ per environment
./scripts/reckon use production
direnv allow                                           # optional — see Quick start

Verify every connection (one safe read per tool):

grafana user current -o json
jenkins status -o json
cubeapm metrics label-values service -o json   # canonical service inventory (not `traces services`)
aws sts get-caller-identity --output json
gh auth status
kcat -L -b "$KAFKA_BOOTSTRAP_SERVERS" -X security.protocol=$KAFKA_SECURITY_PROTOCOL \
     -X sasl.mechanism=$KAFKA_SASL_MECHANISM -X sasl.username=$KAFKA_SASL_USERNAME \
     -X sasl.password=$KAFKA_SASL_PASSWORD | head -20
rpk cluster info                               # RPK_BROKERS / RPK_SASL_* derived from KAFKA_* by .envrc
kubectl get ns                                 # needs KUBECONFIG seeded: aws eks update-kubeconfig --name <cluster>
redis-cli -u "$REDIS_URL" PING
mongosh "$MONGODB_URI" --eval 'db.runCommand({ping:1})'
psql -c "SELECT current_user, current_database(), pg_is_in_recovery();"
mysql --defaults-extra-file="$XDG_CONFIG_HOME/mysql/my.cnf" -e "SELECT CURRENT_USER(), DATABASE(), @@transaction_read_only;"
es cluster health -o json                      # optional — only if ES_URL is set
clickhouse client --host "$CLICKHOUSE_HOST" --port "$CLICKHOUSE_PORT" --user "$CLICKHOUSE_USER" --password "$CLICKHOUSE_PASSWORD" --secure --readonly=1 --query "SELECT 1"

DB safety check: The Postgres command should report pg_is_in_recovery = t (you're on a replica) and SHOW default_transaction_read_only should be on; the MySQL command should report @@transaction_read_only = 1. If Postgres isn't read-only, .envrc didn't reload — run direnv allow. If MySQL isn't read-only, you almost certainly ran a bare mysql instead of mysql --defaults-extra-file="$XDG_CONFIG_HOME/mysql/my.cnf" — the mysql client has no read-only env var, so the option file is the only thing that applies it.

How credentials are isolated

.envrc resolves RECKON_ENV, sets XDG_CONFIG_HOME to .config/<env>/ inside this directory, and loads .env.common → .env.<env> → .env.<env>.local when present. That gives you two repo-local authentication modes:

• Preferred: store credentials in .env.<env> and let direnv export them automatically whenever you enter this repo (or eval "$(./scripts/reckon env)" without direnv).
• Fallback: run grafana login, jenkins login, cubeapm login, aws configure, or gh auth login inside this directory to save per-repo CLI profiles under .config/<env>/.

grafana, jenkins, cubeapm, and gh honour XDG_CONFIG_HOME natively, so their saved state lands inside .config/<env>/ automatically. aws does not — .envrc therefore also exports AWS_CONFIG_FILE and AWS_SHARED_CREDENTIALS_FILE to .config/<env>/aws/, so aws configure writes here instead of ~/.aws/.

Either way, credentials stay isolated from your global ~/.config/ and ~/.aws/ profiles. You can have different credentials per clone of this repo.

Config files land at:

• .config/<env>/grafana-cli/config.yaml
• .config/<env>/jenkins-cli/config.yaml
• .config/<env>/cubeapm-cli/config.yaml
• .config/<env>/aws/{config,credentials}
• .config/<env>/gh/{config.yml,hosts.yml}

Kafka and database tools (kcat, rpk, mongosh, psql, mysql, and clickhouse client) don't have a saved-profile mode here — they read credentials directly from .env.<env>.

Kafka access — read this once

kcat and rpk have no read-only mode, so Kafka safety is two layers, like the databases:

1. Broker-level (the real guard) — the SASL principal in .env.<env> should carry only Describe/Read ACLs (MSK IAM: kafka-cluster:Connect, Describe*, ReadData; no WriteData/Create*/Delete*/Alter*). Provision it like the read-only DB role.
2. Usage-level — only read commands are documented and should be allowlisted (kcat -L/-C/-Q, rpk cluster info, topic list/describe/consume, group list/describe). One trap that looks like a read but isn't: consuming with a group id (kcat -G, rpk topic consume -g) joins the production consumer group, triggering a rebalance and committing offsets. Always consume group-less.

Database access — read this once

The DB clients (mongosh, psql, mysql) can in principle modify production data. The workspace defends against this in three layers, but only layer 1 actually denies writes across every access path — the other two harden the CLI clients and are defence-in-depth, not substitutes:

1. Role-level (the real guard) — every DB user named in .env.<env> MUST be a true read-only role at the database. This is your responsibility to provision; the CLI cannot enforce it, and a read-write role can still write through a non-libpq driver (e.g. a python3 script using psycopg2/pymysql), so this layer is mandatory.
2. Session-level (CLI clients only) — .envrc sets PGOPTIONS=-c default_transaction_read_only=on, which psql honours as the session default (a session can still opt back in with BEGIN READ WRITE). For MySQL there is no read-only env var, so .envrc writes $XDG_CONFIG_HOME/mysql/my.cnf with init-command=SET SESSION TRANSACTION READ ONLY — apply it by invoking mysql --defaults-extra-file="$XDG_CONFIG_HOME/mysql/my.cnf". MongoDB's MONGODB_URI carries ?readPreference=secondary, which is read routing, not a write block.
3. Agent-level (per-clone convention) — the Claude Code allowlist in .claude/settings.local.json should deliberately not pre-approve psql, mysql, or mongosh, so every query prompts you for permission. Friction = safety. Because .claude/ is gitignored, this is a convention each clone must uphold — keep the allowlist tight and never add a broad Bash(python3 -c ...) wildcard, which would let an agent reach a DB driver around the prompt.

Usage with Claude Code

Open this directory in Claude Code (claude) and describe the incident. The agent will follow the RCA workflow in CLAUDE.md to correlate alerts, traces, metrics, logs, and deployment history across all three tools.

Example prompts:

• "The checkout service latency spiked at 14:30 UTC. What happened?"
• "Which Jenkins build broke the payments pipeline and when did it start?"
• "Find all error traces from the auth service in the last hour."

Agent runtimes

The workspace is runtime-agnostic. CLAUDE.md guides Claude Code; AGENTS.md carries the same contract for Codex CLI, OpenCode, and friends. Launch with:

scripts/agent.sh             # auto-detects: claude → codex → opencode
scripts/agent.sh claude      # Claude Code — Pro/Max subscription login, or ANTHROPIC_API_KEY in .env.<env>
scripts/agent.sh codex       # Codex CLI — ChatGPT subscription login, or OPENAI_API_KEY in .env.<env>

The launcher activates the selected environment itself, so it does not depend on direnv state. Subscription logins need no keys; API-key billing reads ANTHROPIC_API_KEY / OPENAI_API_KEY from .env.<env> (see .env.example). Keep approval prompts ON in any runtime — the per-query DB approval is a load-bearing safety layer here, not friction to optimize away.

RCA Workflow (summary)

1. Assess — check Grafana alerts, Jenkins failures, CubeAPM service health
2. Investigate errors — search error traces and logs, view trace waterfalls
3. Check metrics — error rate, latency percentiles, service uptime
4. Check deployments — Jenkins build history, Grafana deploy annotations
5. Map dependencies — service dependency graph, datasource health
6. Correlate — match deployment timestamps with error spikes across tools

See CLAUDE.md for the full agent workflow and exact commands.