Context and compaction

Everything the agent knows in a turn — your instructions, the files it read, the tool output, the conversation so far — occupies one budget. When that budget fills, something has to give. Snaga handles it automatically; these are the controls for when you want to steer.

See how full it is

> /context     # the budget, and when compaction will trigger
> /tokens      # token usage for this conversation

Worth a glance when replies start feeling like the agent has forgotten something you said earlier.

Make room

> /compact

Compaction summarises the older part of the conversation and keeps the recent part verbatim. It happens on its own when the budget demands it; /compact does it now, on purpose.

The summary is intent-preserving: it keeps your original request, your most recent instructions and corrections, and a short tail of recent decisions. This matters more than it sounds. An earlier design summarised the first few messages into a hundred characters each, which meant a big collapse threw away the goal — and a resumed agent, no longer knowing what it was for, would start patching symptoms. If you have ever watched an agent drift from the task over a long session, that is the failure mode this exists to prevent.

One-off instructions carrying a time-to-live are dropped once they expire, so "use this format for the next answer" does not linger for the rest of the session.

Feed it the right things

You can point at what should be in context rather than hoping it gets read:

@codebase indexes your project locally with TF-IDF and retrieves the snippets closest to your query. It is the one to reach for when you know the behaviour but not the filename.

Two things that make context disappear faster than expected

Large tool output. Reading a big file or running a command with a lot of output spends budget in one move. When compaction later rewrites such a result into a short stub, the full body is persisted rather than lost, and the agent can pull it back with read_tool_result instead of re-running the command — but the cheapest fix is asking for the part you want in the first place.

Long-lived sessions. A session that has run all day has been compacted several times, and each compaction is lossy. If precision matters more than continuity, /clear and restate the task — you lose the thread and keep the memory, since stored facts and SNAGA.md survive it. See Memory.

For very large jobs

--fast skips the capability probe and uses a minimal system prompt, trading onboarding for a faster, smaller start. It is meant for trivial one-shot tasks:

snaga -p --fast "fix the typo in README"

It also skips checkpoint saving and the passive memory pass, so it is the wrong choice for anything you might want to undo.