# sctx — token-optimized command output

`sctx` runs a developer command and re-renders its output token-minimally.
It exists because command output is the largest uncontrolled cost in an agent
session: a test run, a `git log`, a `kubectl get` can each spend thousands
of tokens restating things you do not need.

## What it guarantees

Read these once — they are why you can act on compressed output instead of
re-running the command verbatim to check.

- **The exit code is exact.** Never inferred from the text.
- **Error signal is never compressed away.** A failing command keeps its
  diagnostics; compression targets repetition and noise, not failure.
- **Every elision is marked** — `…+N` (N more lines) or `×N` (repeated N
  times). If you see no marker, nothing was dropped.
- **Any parse failure degrades to raw output.** Tiers fall back
  aggressive → relaxed → verbatim. Output is never suppressed, so an unexpected
  format costs you nothing.

## You do not need to type it

A PreToolUse hook rewrites covered commands automatically. **Write commands
naturally** — including inside pipelines and `&&` sequences. Do not prefix
`sctx` yourself on a covered command: it is not double-wrapped, but the
token is wasted and the command reads as though it needed help.

Covered today: `go`, `git`, `grep`/`rg`, `ls`/`find`/`tree`,
`cat`/`head`/`tail`, `diff`, `ps`, `du`, `make`,
`golangci-lint`, `gh`, `docker`, `kubectl`, `pytest`,
`ruff`, `mypy`, `pip`, `npm`/`pnpm`/`yarn`, `brew`,
`mongosh`, `ssh` (delegates to the remote command's formatter),
`rsync`, `jq`/`curl`. `sctx doctor` prints the effective list.

**Where the hook declines, and why it matters to you.** It leaves a command
alone when wrapping could change what you conclude:

- a downstream `grep`/`sed`/`awk`/`wc`/`jq` — filtering already-compressed
  output would make something look ABSENT that is merely elided;
- file redirects (`> out.txt`), command substitution (`$(…)`), subshells.

`2>&1` is fine, and so are pure pagers (`| head`, `| tail`).

## When to type it yourself

**When you are about to run something NOT in the list above and its output will
be long.** `sctx <cmd>` still helps: JSON stdout is compacted automatically
and repeated lines are collapsed, whatever the program.

`sctx -- <cmd>` forces verbatim passthrough when you genuinely need every
byte.

## Reporting

`sctx gain` shows tokens saved (`--project`, `--since 7d`,
`--format json`). `sctx gain --failures` lists commands that saved
nothing — the fastest way to find an output shape worth compressing.