totally

README

Totally

totally is a local CLI for understanding agent sessions: what you worked on, how much it used and cost, and where the underlying transcript lives.

Status: This README defines the intended public CLI. The current implementation is being brought into line with it.

Commands

Command	Purpose
totally	Alias for totally sessions
totally sessions	Find and browse sessions
totally show <session-id>	Explain one session
totally stats	Aggregate and compare usage and estimated cost
totally prices	Show model pricing assumptions and rates
totally files	Inspect raw transcript discovery and storage

Common filters

These filters apply wherever they are meaningful:

--cwd PATH                      Limit to a working directory
--since TIME, --after TIME      Records at or after TIME
--until TIME, --before TIME     Records at or before TIME
--model MODEL                   Limit to a model
--provider PROVIDER             Limit to a provider
--archived                      Include archived sessions
--limit N                       Limit listed rows
--format table|json             Select output format (default: table)

--after is an alias for --since; --before is an alias for --until. Time values accept relative durations (7d), dates (2026-07-01), RFC3339 timestamps, and today, yesterday, or now.

Data sources

--agent AGENT                   Read a supported agent session format
--home PATH                     Agent data directory; may be repeated
--config PATH                   Configuration file path

By default, totally discovers supported local agent homes. Use --home to inspect a specific home or combine several homes in one report.

Find sessions

sessions answers “which session was that?” Its table includes the session ID, working directory, first prompt/task descriptor, start time, model, token use, estimated cost, and duration.

totally sessions
totally sessions --cwd . --since 7d
totally sessions --prompt "command set"
totally sessions --model gpt-5 --sort cost --limit 10
totally sessions --full

Session-specific options:

--prompt TEXT                   Match the first prompt/task descriptor
--sort started|updated|cost|tokens|duration
--latest                        Select the most recently updated session
--full                          Do not truncate display values in table output

Show a session

show answers “what happened, and what did it cost?” An unambiguous session ID prefix is accepted.

totally show 019f44e4
totally show --latest
totally show --latest --cwd . --provider openai --model gpt-5
totally show 019f44e4 --full

--cwd, --provider, and --model narrow --latest to the most recently updated matching session. They can be combined and require --latest.

The report includes session metadata, working directory, first prompt/task descriptor, transcript location, model/provider use, prompts, turns, messages, tool calls, duration, token breakdown, and estimated cost.

Table output shows a shortened prompt preview by default. Use --full to show the complete prompt and other untruncated display values. JSON output always contains the complete prompt.

Compare usage and cost

stats reports session count, prompts, tokens, estimated cost, and duration. Use --by to compare one dimension at a time.

totally stats --since 7d
totally stats --cwd . --since 30d
totally stats --since 30d --by cwd
totally stats --since 30d --by model
totally stats --cwd . --by day --by model

--by cwd|model|provider|day|week|month|session  (may be repeated for composite groups)
--pretty                        Terminal-oriented table output

The currently available session selectors are --cwd, --provider, and --model (along with the global --since, --until, --archived, --home, and --format flags). --by cwd groups by session working directory. Repeat --by to group by a combination, such as --by day --by model. For --by model, tokens and cost are attributed from per-request usage segments. Session-level measures (sessions, prompts, duration, and activity) are assigned to the model with the most attributed tokens (with first-seen breaking ties), so group totals remain additive.

Pricing

totally prices
totally prices --model gpt-5
totally prices --provider openai --model gpt-5
totally prices --format json
totally prices verify
totally prices verify --provider openai --model gpt-5

Pricing output shows the configured rates per million tokens for input, cached input, and output, plus the source and effective date/version. Costs are estimates based on this local price table, not vendor invoice reconciliation.

totally prices verify validates configured pricing overrides and prints field-level diagnostics for malformed keys, unknown fields, invalid monetary values, scales, and effective dates. Use --provider and/or --model to validate only matching overrides. It does not scan session files.

Built-in prices can be overridden for a date range in the Totally TOML configuration. Override keys use provider/model, and monetary values are decimal strings. Surrounding bundled history is retained:

[prices."openai/gpt-5"]
input_per_million_usd = "1.25"
cached_input_per_million_usd = "0.125"
output_per_million_usd = "10.00"
effective_from = "2025-08-07"
source = "user"

Conditional overrides can use long_context_threshold together with long_context_input_scale, long_context_cached_input_scale, long_context_output_scale, and long_context_cache_write_scale.

Organizations that used a model before its first public pricing date can opt into applying that model's earliest known rate to those earlier sessions:

[pricing]
early_access = true

Without this setting, sessions before the first known price remain unpriced.

Set replace = true to replace a model's entire bundled pricing history.

Session costs use the Standard/default API-equivalent basis. Usage tagged with a non-default service tier is left unpriced rather than estimated from Standard rates. Cached input is excluded from regular input before applying its lower rate, and reasoning tokens are not charged separately because they are included in output tokens. If usage cannot be attributed to a priced model, show reports the estimate as unavailable or partial rather than treating it as zero. JSON includes the structured cost object and retains cost_usd as a compatibility field.

Codex can emit last_token_usage events containing only total_tokens while recomputing or compacting context. These are local context-size estimates, not billable token usage, so Totally excludes them from token totals and cost.

The bundled catalog also records conditional long-context multipliers. They are applied per request when a model charges more above its input-token threshold. GPT-5.6 cache writes carry an additional surcharge, but Codex transcripts do not currently distinguish cache-write tokens. Totally bounds the possible amount, uses its midpoint as the estimate, and marks it partial; terminal output shows the half-range as ±, and JSON includes the explicit bounds.

Raw files

totally files
totally files --archived
totally files verify
totally files verify ~/.codex/sessions/.../rollout-*.jsonl
totally files verify --format json

files is a diagnostic command for transcript discovery, compression, paths, and storage. Use sessions for normal work.

totally files verify parses raw transcripts and reports malformed files plus impossible token counters, including negative values, cached input larger than input, and a full input/output breakdown whose total does not match. With no paths it verifies discovered files; provide one or more .jsonl or .jsonl.zst paths to verify those files directly. It exits non-zero when it finds an issue. Codex context-size estimates reported as total-only last_token_usage remain valid telemetry, but are ignored for token totals and cost.

Automation

Terminal tables are the default. Use JSON for scripts and integrations:

totally stats --cwd . --since 30d --format json
totally sessions --since 7d --format json

Build and release

Run the full test suite and build a versioned archive locally:

make test
make build

Versioned Git tags publish GitHub Releases automatically. Create and push a tag after merging the release commit:

git tag -a v0.4.2 -m "v0.4.2"
git push origin v0.4.2

Each release includes archives for Linux and macOS on amd64 and arm64, plus checksums.txt. Download the archive for the current Go platform with:

VERSION=v0.4.2
curl -fLO "https://github.com/rybkr/totally/releases/download/${VERSION}/totally-${VERSION}-$(go env GOOS)-$(go env GOARCH).tar.gz"
tar -xzf "totally-${VERSION}-$(go env GOOS)-$(go env GOARCH).tar.gz"