Overview

Every tool runs through Reckon:

reckon run <connection-or-tool> -- <the CLI's own arguments>
reckon run jenkins -- build list deploy-api --limit 20 -o json
reckon run jenkins-uat -- whoami -o json

• Naming the tool (jenkins) picks the one connection for the active environment. Naming a connection from another environment is refused.
• Put the command before its flags: get pods -n x, not -n x get pods.
• Ask for JSON (-o json, --json, --output json) whenever the output will be parsed.
• --stdin passes standard input through, for example a Query DSL body for es ... -f -.
• --session <id> (with an optional --label) saves the output as evidence in a session.

Reckon flags go before --; everything after it belongs to the tool. The workflow pages below show the CLI arguments that matter for each area.

The reckon commandCopy Anchor Link

Commands you run yourself:

Commands the agent runs (you can too):

Most commands accept --org, --env and --json. Run reckon <command> --help for every flag.

Incident orderCopy Anchor Link

For operations work, the agent narrows from broad to specific:

1. Run reckon preflight and read knowledge/_shared/ and knowledge/<env>/ for service names, label conventions, quirks and known issues.
2. Assess Grafana alerts, failed Jenkins jobs and the CubeAPM service list.
3. Narrow with traces, logs, metrics, deployment history and dependencies.
4. Use AWS, GitHub, Kubernetes, Elasticsearch, Nginx Proxy Manager, Kafka, Redis or a database only where the earlier signals point.
5. Correlate timestamps, save evidence in a session, and promote it to an RCA.

Checking a sessionCopy Anchor Link

reckon check <session> exits 1 when a saved session should not be trusted as is: broken evidence integrity, a finding without successful evidence, evidence from another org or environment, or a session closed as done without a finding. It also warns about partial evidence, hypotheses without a next check and knowledge that changed since the session started.

Reusing recent readsCopy Anchor Link

reckon run <tool> --cache 15m -- <args> returns an identical successful read from the last 15 minutes instead of calling the tool again, and says when it was observed. The cache is per org, environment and connection, stored without secrets in ~/.reckon/orgs/<org>/cache/. Evidence saved from a cached read keeps its original observation time.

RoutinesCopy Anchor Link

A routine runs a workflow on a schedule with headless Claude Code (claude -p), pinned to one org and environment like reckon open: it reads through reckon run, saves a session, may prepare writes and never applies them. It runs in dontAsk permission mode with no MCP servers, so only the workspace's allow rules can run, whatever your default mode is. Codex is not offered for routines: its sandboxes have no deny list, and unattended it could read secrets files.

reckon routine add weekly-growth --org acme --env prod --workflow growth-review \
  --param site=sc-domain:acme.com --at "mon 08:30"
reckon routine install weekly-growth --org acme   # writes the launchd job (macOS) or prints a crontab line
reckon routine run weekly-growth --org acme       # what the scheduler runs; try it once by hand
reckon routine list --org acme

--at takes daily HH:MM, weekdays HH:MM or a day such as mon HH:MM, in local time. A routine in a production environment needs --production. A run still going makes the next one skip; launchd runs a missed job once after the Mac wakes. Each run's output is kept in ~/.reckon/orgs/<org>/routines/<name>/, and the activity log records its result. Routines spend model usage without anyone watching, so start with one a week. install writes the schedule but does not load it; it prints the launchctl command for you to run.

Watches and the inboxCopy Anchor Link

A watch is a saved read polled for new items: a new Stripe dispute, a new Sentry issue, a failed Jenkins build. New items land in the org's inbox, and the brief lists them.

reckon watch add disputes --org acme --env prod --production --connection stripe --items data --key id --title reason \
  -- disputes list --limit 20
reckon watch run --org acme        # by hand, or from cron: */30 * * * * ~/.reckon/bin/reckon watch run --org acme
reckon inbox                       # new items in this environment, last 7 days

The read must pass the same checks as reckon run when the watch is added and each time it runs. --items is the dotted path to the list in the JSON output and --key the field that identifies an item. The first run records what already exists, so only later items reach the inbox; changing or re-adding a watch starts again from a baseline. Production watches need --production, and tools that ask before every run (databases) cannot be watched. Watches are for the operator; an agent can read its own environment's inbox.

GoalsCopy Anchor Link

Put an org's targets in knowledge/_shared/goals.json (or knowledge/<env>/goals.json), each bound to a read and the number to take from its JSON output:

{"goals": [
  {"id": "clicks", "title": "Organic clicks (28 days)", "provider": "gsc",
   "command": ["performance"], "match": ["sc-domain:acme.com", "28d"],
   "path": "current.clicks", "target": 5000},
  {"id": "p95", "title": "Checkout p95 ms", "provider": "cubeapm",
   "command": ["metrics", "query"], "path": "data.0.value", "target": 800, "direction": "down"}
]}

reckon brief shows each goal's value from the newest saved read of that command in the environment (with its date and evidence id), whether it is on track, or the read to run when there is none. match lists arguments the read must include (here the site and the period), so a one-day read of another site never counts. Check path against the tool's real output; a weekly routine keeps the readings fresh. A goals file that does not parse shows as one invalid row, not an error.

Agent spendCopy Anchor Link

reckon spend                  # tokens used in this org's workspace, last 30 days
reckon spend --all-orgs --days 7

Each org has its own workspace folder, and Claude Code and Codex record the folder each session ran in, so Reckon totals input, output and cache tokens per org and model from their session files (~/.claude/projects, ~/.codex/sessions). Only usage counters are read, never content. Prices change, so dollar estimates appear only for models you list in ~/.reckon/prices.json, in USD per million tokens:

{"claude-opus-5-5": {"input": 0, "output": 0, "cache_read": 0, "cache_write": 0}}

reckon brief --all-orgs shows each org's token total next to its open work.

reckon spend --org acme --set-budget 20000000 --budget-days 30   # 0 clears it

With a budget set, reckon open and the brief (its "Agent budget" section) warn once the org has used more tokens than that in the window. It warns rather than blocks, and only you can set it (a pinned agent is refused).

Activity logCopy Anchor Link

Every reckon run, every refusal (wrong environment, denied command, spent budget) and every act prepare, apply and reconcile is appended to ~/.reckon/orgs/<org>/activity.jsonl, with or without a session. Entries keep the command words and a hash of the arguments, never their values.

reckon log                    # last 7 days, this environment
reckon log --event refused --all-envs --days 30

Daily briefCopy Anchor Link

reckon brief                 # last 7 days, this org and environment
reckon brief --days 30 --save  # also writes briefs/<date>-<env>.md in the org folder
reckon brief --all-envs      # every environment of this org
reckon brief --all-orgs --save  # every business in one digest, saved to ~/.reckon/briefs/

The brief is built from saved files only: open sessions, recent findings, writes waiting for reckon act apply or with an unknown outcome, refused runs, connections that are not ready, knowledge untouched for 90 days, and when each review series (a workflow recipe and, for growth reviews, a site) last finished. --all-orgs starts with one table row per org and runs only in your own terminal, never in a pinned agent. It contacts no tool, so it is safe to run from cron or launchd, for example 0 8 * * 1-5 RECKON_HOME=~/.reckon ~/.reckon/bin/reckon brief --org acme --env prod --save.