Context management and cost saving

A long agentic run can spend tokens without doing work. clai bounds the run in four places, and each bound is a flag or a config key that you can see and change.

Token stop-loss with a handover

stoploss.max-tokens in textConfig.json, or -mt (-max-tokens) for one run, sets a token budget. When a step crosses the budget, clai finishes that step’s tool batch and then adds a handover message. The handover starts a fresh wrap-up phase: the model is told to finish the work with what it has.

The wrap-up phase has its own tool allowance, stoploss.max-tool-calls-after-handover. Once that allowance is spent, further tool calls are refused. A refused call never reaches its executor: the model reads the refusal text as the tool result, so it stops asking and writes up the answer.

0 means unlimited for both keys. A run with no budget is possible; it is not the default advice.

Tool-call budgets

max-tool-calls in textConfig.json, or -mtc (-max-tool-calls) for one run, caps the number of tool calls before the handover. The controller counts a whole batch before it runs any of it, so a refusal cannot leave half a batch executed.

Tool filtering

Every tool schema costs tokens on every turn. -t (-tools) takes '*' for all tools, or a comma-separated list of tool names and globs:

clai -t="rg,file_tree,mcp_git_*" q "Show what changed in internal/cli"

A profile’s tools field does the same for a saved workflow, so a profile that reviews Go code carries only the tools that review Go code. See Profiles and setup.

Lookback reads what it needs

-lb (-lookback) lets the model see that recent conversations exist and search them. It reads a descriptor first, then one conversation, then one message. A large conversation is not loaded until the model asks for it. Without -lb, the run carries no conversation history and every turn costs only the current prompt.

Where to look next

• Configuration names stoploss and the rest of textConfig.json.
• MCP and tools shows tool filtering against MCP servers.
• Errors and troubleshooting lists the errors a rate limit or a context overflow produces.