Compression settings

nid compresses large, repetitive text it hands to agents (board history, task details, messages, review diffs, CI logs, handoff summaries) so less of each agent's context and usage window goes to noise. Every compressed block names an id; the agent calls expand("<id>") for the full text. This page covers how to turn the features on and off and where the savings show up; compression describes the engine.

The compression setting#

One key, compression, at three levels. The most specific level wins per key:

1. built-in defaults
2. compression: in ~/.nid/config.yaml (or $NID_HOME/config.yaml)
3. the group: compression: in nid.yaml, nid group set, nid compression, /compression in the terminal app, or the dashboard's Compression panel
4. one session: compression: on a session in nid.yaml, or nid spawn --compression on|off

compression: false is shorthand for { enabled: false }, compression: true for { enabled: true }.

memory and learnAfterDone are group features: they are read from the group and ~/.nid/config.yaml, and a session's value for them is ignored.

# nid.yaml
groups:
  app:
    goal: Ship the importer
    compression:
      diffs: false        # reviewers see full diffs
      minTokens: 500
    sessions:
      - agent: claude
        name: lead
      - agent: codex
        compression: false  # this session's nid traffic is not compressed

# ~/.nid/config.yaml
compression:
  terse: true
  ttlHours: 48

An invalid compression: in ~/.nid/config.yaml does not stop the daemon: nid uses the defaults and reports the problem in nid doctor, nid compression and /compression.

Changing it#

• Terminal app: /compression shows the settings and savings; /compression off, /compression diffs off, /compression minTokens 500, /compression reset (drop the group's override) change this team's setting.
• CLI: nid compression [group] shows the same report (--json for the raw RPC result); nid compression <group> off or nid compression <group> board off changes it. nid group set <group> compression=false and nid group set <group> 'compression={"diffs":false}' also work (they replace the whole value).
• Dashboard: the Compression panel on a group page has a switch per key.

Terse output#

terse: true saves output tokens: agents write shorter status updates, summaries and messages. nid appends this section to the end of the system prompt it gives every agent:

## Keep output short
This group asks for terse output to save tokens:
- No preamble or recap. Status updates and replies: at most 3 short lines.
- Do not restate tool output, file contents or diffs you just read; cite paths and line numbers instead.
- task_update summaries and board notes: what changed and how it was verified, at most 5 lines.
- Messages to teammates: one point per message, no pleasantries.
- Never shorten code, commands, error text or identifiers, and never skip verification to save words.

The system prompt is built when an agent process starts and does not change while it runs, so the prompt cache stays valid. Turning terse on or off therefore applies to new agents and to running ones when they next start (resume, restart or rotation), not mid-conversation. Because the section is appended at the end, the rest of the prompt stays byte-identical. Agents that take the prompt as part of their first message (ACP and PTY custom agents) get it there.

Where the savings show up#

Savings are counted per session and per source (board, messages, diffs, ci, handoff, ...) as tokens before and after compression, and kept in the nid database so they survive daemon restarts.

When an agent calls expand(id), it gets the original back and pays its tokens after all. nid counts those calls separately (source expand: number of calls and tokens returned) and every place below shows net savings: tokens saved by compression minus tokens returned by expand. Net savings can be negative when agents expand most of what they receive; that is a sign a source compresses too aggressively for the work and is worth turning off. Labels add , N expands when there were any, and the dashboard badge turns yellow when the net is negative. Legacy originals outside the tokenizer work limits use an expansion estimate of ceil(UTF-16 code units / 4); those net figures can over- or under-count. Expansion still returns every original byte unchanged.

• nid ls: a SAVED column per session (net, 12.3k 41%; yellow when negative; off when disabled).
• nid status: a SAVED column per group and in the total, proxy when the proxy is on.
• nid doctor: a compression line with the global setting, proxy state, tokenizer, the size of the originals store and tokens saved so far.
• /compression and nid compression: settings with where each value came from, savings per agent and per source, and agents whose proxy routing or proxy terse block still differs from the settings until they restart.
• Dashboard: a badge per group (overview and group page), a saved line per session in the sessions table and on the session page, and the Compression panel.

Proxy savings (source proxy) are shown on their own row, labelled "per request, mostly cached tokens": the proxy compresses the newest tool result in each request, and every later request in the conversation re-sends that history, which the provider mostly serves from its prompt cache. They are real per-request savings, but most of them are cache-read tokens, which cost far less than uncached input, so do not add them to the other sources as if they were.

Programs can read the report with the compression.stats RPC; see the daemon API reference in packages/nid/docs/api.md.