Context Awareness

Rule

The agent must always know what the user is currently viewing. The UI writes navigation state on every route change. The agent reads it before acting.

Why

Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees. Context awareness is what makes the agent feel like a collaborator rather than a disconnected chatbot.

The Core Patterns

1. Navigation State (navigation key)

The UI writes a navigation key to application-state on every route change. This tells the agent the semantic screen state: view, open IDs, active tab, and focused object.

UI side — useNavigationState, an app-owned hook (not a framework import) that every template ships at app/hooks/use-navigation-state.ts. It is a thin wrapper around the framework primitive useAgentRouteState, handling both directions: writing navigation on route change and consuming the agent's navigate command.