Core Concepts

This page explains how Glove works under the hood. If you haven't built your first app yet, start with Getting Started — it takes 15 minutes and you'll come back here with useful context.

The Agent Loop

Every Glove app is driven by a loop. Here is what happens each time a user sends a message:

1. The user's message is added to the conversation history
2. The AI reads the full conversation and the list of available tools
3. The AI either responds with text (ending the loop) or requests one or more tool calls
4. Glove executes the requested tools and adds the results to the conversation
5. Go back to step 2

The key insight: the AI decides which tools to call and in what order. You don't write if/else logic or state machines. You define capabilities, and the AI uses them to fulfill user requests.

This loop is implemented by the Agent class. On the client side, the useGlove hook manages this loop automatically.

Tools

A tool is a capability your app exposes to the AI. Each tool has four parts:

• name — a unique identifier (like "get_weather")
• description — a plain-English explanation of what it does. The AI reads this to decide when to use the tool.
• inputSchema — a Zod schema that defines what input the tool expects. Glove validates inputs at runtime before your code runs.
• do — the function that runs when the AI calls the tool. It receives the validated input and returns a result that gets sent back to the AI.

Tools can be pure functions (compute something, fetch data, call an API) or interactive — they can push UI to the display stack to show the user results or ask for input.

See ToolConfig for the full type definition.

The Display Stack

The display stack is what makes Glove an app framework, not just a chatbot. When a tool runs, it can push a React component onto a stack that your app renders. This is how tools show UI to the user — product grids, forms, confirmation dialogs, data cards, anything.

The do function receives a display parameter with two methods:

• pushAndForget — push a component and keep the tool running. Use this for showing results: data cards, product grids, status updates. The tool returns normally.
• pushAndWait — push a component and pause the tool until the user responds. Use this for collecting input: forms, confirmations, preference pickers. The tool resumes when the user submits.

Think of it like this: pushAndForget is like printing a receipt — here is your result. pushAndWait is like handing someone a clipboard — fill this out and give it back.

On the React side, the useGlove hook exposes slots (the current stack) and renderSlot() (renders a slot using the tool's render function). See ToolDisplay for the full API.

Colocated Renderers

When you define a tool in glove-react, you can include a render function alongside the do function. This means the tool's logic and its UI live together in the same object — no separate component files, no string-based lookups.

When you call display.pushAndWait({ input }) from a tool that has a render function, Glove automatically uses the tool's name to match the slot to the renderer. The useGlove hook builds the renderer map and provides renderSlot() to your component.

Adapters

Glove uses four pluggable interfaces (called adapters) to stay flexible. Each adapter can be swapped without changing your application code:

• ModelAdapter — the AI provider. Anthropic, OpenAI, local models, or mocks for testing. Anything that takes messages and returns responses.
• StoreAdapter — the persistence layer. Where messages, tokens, and turn counts are stored. In-memory, SQLite, Postgres, or a remote API.
• DisplayManagerAdapter — the UI state layer. Manages the display stack. Framework-agnostic — works with React, Vue, Svelte, or a terminal UI.
• SubscriberAdapter — the event observer. Receives events like text_delta, tool_use, and tool_use_result. Use it for logging, analytics, or real-time streaming.

For example, switching from OpenAI to Anthropic only requires changing the ModelAdapter — your tools, UI, and application logic stay the same.

Context Compaction

AI models have a limited context window — the maximum amount of conversation they can read at once. Long conversations eventually hit this limit.

Glove handles this automatically: when the conversation gets too long, it summarizes everything so far and starts a fresh context with the summary. This is called compaction. Task state is preserved across compaction boundaries, so sessions can run indefinitely without losing track of what they were doing.

You can configure compaction behavior with CompactionConfig.