Setup

Reckon is a native executable and needs Claude Code or Codex to open an agent. Building from source requires Rust, using the pinned rust-toolchain.toml. Python is used only by compatibility tests. The checkout holds Reckon's code only. Orgs, credentials, knowledge and saved work live under ~/.reckon (or $RECKON_HOME).

macOS and LinuxCopy Anchor Link

git clone https://github.com/piyush-gambhir/reckon.git
cd reckon
bash scripts/setup.sh
export PATH="$HOME/.reckon/bin:$PATH"     # add this to your shell profile

setup.sh installs missing tools with Homebrew on macOS and apt or dnf on Debian, Ubuntu, Fedora and RHEL-family systems. Downloaded binaries such as rpk and kubectl are checksum-verified. It then creates ~/.reckon (mode 0700), builds Reckon with cargo build --locked --release, and links ~/.reckon/bin/reckon to target/release/reckon in the checkout. Other Linux distributions get manual-install guidance.

For Reckon alone, run cargo install --locked --path .. Provider definitions, workspace guides, templates and built-in recipes are embedded in the executable; running the installed binary does not require the checkout or a language runtime.

Once you have created an org, reckon doctor reports the Reckon version, whether ~/.reckon is private, your orgs, connections without credentials or without their CLI, and the default context.

WindowsCopy Anchor Link

Use WSL2 and the same script inside it:

wsl --install

Native PowerShell (scripts\setup.ps1, scripts\reckon.ps1) is experimental. reckon open needs symlink rights there (Developer Mode).

Where data livesCopy Anchor Link

~/.reckon/
  bin/reckon                  native executable, or link to the source build
  context                     default org/env for the next launch (reckon use)
  links.json                  folders linked to an org/env and preferred connections (reckon link)
  orgs/<org>/
    org.json                  environments and connections, no secrets
    secrets/<connection>.env  credentials, 0600, never shown to the agent
    config/<connection>/      the CLI's own config and saved logins
    runtime/<connection>/     private HOME, cache and temp for that CLI
    workspace/                the agent's folder for this org
      RECKON.md               generated: environments and connections
      CLAUDE.md, AGENTS.md    the org's agent guide; add your own notes
      knowledge/              company and per-environment facts
      sessions/               saved work with evidence
      incidents/              promoted RCAs

Next, create an org and connect its tools: see Orgs & connections or the Quick start.

Migrate an older checkoutCopy Anchor Link

Older versions kept one business inside the checkout: .env.<env> files, .config/<env>/, infra-knowledge/, sessions/ and incidents/. reckon migrate copies that layout into a new org. It changes and deletes nothing in the old checkout.

reckon migrate --org acme --rename production=prod --rename staging=dev --share cubeapm --dry-run
reckon migrate --org acme --rename production=prod --rename staging=dev --share cubeapm

• --rename OLD=NEW renames an environment. The new defaults are prod, uat and dev.
• --share TOOL makes one connection for every environment, for example CubeAPM when one server holds them all. It needs identical settings and saved CLI config in every environment, and fails otherwise. A tool that is identical everywhere is shared automatically; any other tool becomes one connection per environment, such as jenkins-prod and jenkins-dev.
• --from PATH reads another checkout (default: this one). --name sets the org's display name.
• Settings that use shell expansion ($(...), ${...}) are skipped and listed by name. Copy those by hand into the new secrets files.

A shared CubeAPM connection still needs its environment labels:

reckon connect cubeapm --org acme --label prod=PROD --label dev=DEV
reckon use acme/prod
reckon verify

Once you have checked the new org, delete the old files from the checkout.

Pinned CLI releasesCopy Anchor Link

Setup installs the ten CLIs maintained alongside Reckon from their GitHub release archives at the versions pinned in scripts/cli-releases.csv, after checking each archive against the release's checksums.txt. Release builds matter: a source build of gsc has no built-in OAuth client. A copy already on your PATH is kept when it is current and replaced in place when it is older than the pin, so rerunning setup upgrades them. reckon doctor lists any that are behind. Where no archive fits your platform, setup builds from source with go install.

The other tools (aws, gh, kubectl, psql, mysql, mongosh, clickhouse, redis-cli, kcat, rpk, jq) come from your package manager or vendor releases.