Skip to main content

​
Overview

The agent loop is the core orchestrator in Rusty. It manages the conversation between the user, the LLM, and the tools.

​
Loop Flow

1

User message

The user’s input is added to the message history.
2

Auto-compaction check

If the conversation exceeds approximately 80,000 tokens or 40 messages, older messages are summarized (keeping the last 10 messages) via an LLM call to reduce context window usage.
3

Send to LLM

The full message history, system prompt, and tool definitions are sent to the LLM provider via SSE streaming.
4

Stream response

The response is streamed back event by event: text deltas, thinking deltas, and tool call deltas are accumulated as they arrive.
5

Process tool calls

If the response contains tool calls, each tool is executed in order. Results are appended to the message history as tool result messages.
6

Loop or complete

If tool calls were present, the loop returns to step 2 with the new messages. If no tool calls were present, the response text is returned as the final answer.

​
Cancellation

The agent loop can be cancelled at any time via Ctrl+C in TUI mode. Cancellation sets an atomic flag that the loop checks between steps. When cancelled:
  • The current LLM stream is terminated
  • Partial text is discarded
  • The session state is preserved (no messages are lost)

​
Turn Limits

The --max-turns flag limits the number of agent loop iterations. Each iteration where tool calls are executed counts as one turn. This prevents runaway loops where the agent keeps calling tools indefinitely. 
rusty --max-turns 10 --prompt "Analyse this codebase"

​
System Prompt

The system prompt is assembled from several sources:
  • Tool descriptions: Names, descriptions, and input schemas for all available tools
  • Permission mode: Current permission mode and allowed tools
  • Platform info: Operating system, architecture, working directory
  • Git status: Current branch, recent commits, working tree status
  • Sandbox notice: Reminder that file operations are restricted to the working directory
  • Context files: Contents of AGENTS.md, CLAUDE.md, or RUSTY.md files found in the project
  • Current date: For time-sensitive operations
  • Plan-with-tasks instructions: Optional instructions for structured task tracking

​
Streaming

All LLM communication is streaming-first. The provider yields a stream of events:
EventDescription
TextDeltaA chunk of response text
ThinkingDeltaA chunk of reasoning/thinking content
ToolCallDeltaA chunk of a tool call (name or arguments)
UsageToken usage information
DoneStream completed
ErrorAn error occurred
Events are consumed one by one by the agent loop and forwarded to the UI via callbacks.

​
Callbacks

The agent accepts optional callbacks for real-time UI updates:
CallbackPurpose
TextCallbackCalled with each text delta
ThinkingCallbackCalled with each thinking delta
ToolCallbackCalled when a tool call starts or completes
PermissionCallbackCalled when a tool requires permission
These callbacks are what drive the TUI streaming display and the permission prompt overlay.

​
Sub-Agents

Sub-agents are spawned as independent Tokio tasks with their own agent loop instance. They run with BypassPermissions and have access to all tools except the agent tool (to prevent recursive spawning). The parent agent receives the sub-agent’s final response as a single text block.