Cedar OS

Cedar-OS is an open-source framework designed for building AI-native React applications. It aims to move applications beyond simple side-chatbots by providing deep integration between AI agents and the application itself.

Key capabilities include:

• Agentic State Access: Allowing agents to read and write to the application's local state.
• Streaming & Tool Calls: Real-time rendering of message streaming and agent tool execution.
• Diff & History Management: Tracking AI-driven changes, managing history, and implementing user approval workflows.
• Context-Aware Mentions: A system for providing specific context to chat via mentions.
• Spells: Specialized agent interactions and workflows.
• Voice Integration: Support for voice-powered agent interactions.
• Flexible UI: A library of pre-built, customizable components (Shadcn style) including Floating, SidePanel, Caption, or Embedded chat interfaces.

Cedar-OS is an open-source React framework designed for building AI-native applications. It provides the building blocks for sophisticated AI interactions, including:

Core AI Capabilities

• Diff & History: Track and display state changes made by the AI, allowing users to approve or reject changes.
• Voice Integration: Enables voice-powered agent interactions.
• Mentions: A system for controlling agent context via user state.
• Spells: Methods to interact with the agent outside of the standard chat interface.

UI and Integration Building Blocks

• State Access: Allows agents to read and write to your application state.
• Chat Components: Pre-built UI components including Floating, SidePanel, Caption, and Embedded chat layouts.
• Streaming & Tool Calls: Support for real-time message streaming and rendering agent tool execution.
• Agent Connection Modules: Modules to connect your application to various AI backends.
• Component Library: A library of pre-built UI components optimized for AI-native interfaces.

Cedar OS automatically handles several response types via default processors. When an agent returns a response, the corresponding processor executes logic to update the application state or UI.

Available Default Types:

• "message": Adds text messages to the chat. Requires content: string and optional role: 'user' | 'assistant' | 'bot'.
• "setState": Executes state actions via setters. Requires stateKey: string, setterKey: string, and optional args: unknown.
• "progress_update": Manages progress message lifecycles (creating or updating existing messages). Requires text: string and state: 'in_progress' | 'complete' | 'error'.
• "frontendTool": Executes registered frontend tools. Requires toolName: string and optional args: unknown.
• "humanInTheLoop": Suspends workflow execution to request user input or approval. Requires status: 'suspended', runId: string, and various lifecycle properties.

The Spell Architecture is a gesture-based interaction system designed for high performance and robust event handling. It relies on four primary pillars to manage user interactions (spells) efficiently:

1. SpellActivationManager: A centralized singleton manager that handles all incoming events and orchestrates the activation logic.
2. SpellSlice: A Zustand-based state slice that ensures all spell-related state (active, triggered, etc.) is synchronized across the application.
3. useSpell Hook: The primary React interface used by components to interact with the spell system.
4. Activation Modes: Flexible logic for how a spell is triggered, supporting different user interaction patterns like toggling, holding, or immediate triggering.

This architecture uses a singleton pattern and ref-based callbacks to ensure that gesture processing remains performant and does not cause unnecessary React re-renders.

When your agent backend returns responses, they follow the LLMResponse interface. Cedar uses the object field to find structured responses for processing. The content field is always added to the chat by default as a simple text message.

An LLMResponse can contain:

• content: Text content from the LLM.
• usage: Token usage information (promptTokens, completionTokens, totalTokens).
• metadata: Additional metadata as a Record<string, unknown>.
• object: A single StructuredResponseType or an array of them. This is where Cedar looks for structured data to process via the response processing system.

interface LLMResponse {
	content: string; // Text content from the LLM
	usage?: {
		promptTokens: number;
		completionTokens: number;
		totalTokens: number;
	};
	metadata?: Record<string, unknown>; // Additional metadata
	// The object field contains structured output when using JSON Schema or Zod
	object?: StructuredResponseType | StructuredResponseType[];
}