# How Roo Code Cloud Integration Syncs Settings Across Sessions

> Learn how Roo Code cloud integration syncs settings across sessions. Discover how VS Code globalState and hourly polling ensure seamless configuration updates.

- Repository: [Roo Code/Roo-Code](https://github.com/RooCodeInc/Roo-Code)
- Tags: how-to-guide
- Published: 2026-04-26

---

**Roo Code synchronizes your configuration across devices by caching cloud settings in VS Code's `globalState` and refreshing them hourly via a dedicated polling service while the user is authenticated.**

Roo Code's cloud integration ensures that your model selections, skill lists, and UI preferences persist seamlessly between VS Code sessions and across different machines. By leveraging a combination of local caching and remote synchronization, the extension provides instant access to your settings even when offline, while keeping them current through periodic background updates.

## Core Architecture

The synchronization system relies on three primary components that work together to maintain state consistency between the cloud API and the local VS Code environment.

### CloudSettingsService

The `CloudSettingsService` class, defined in [`packages/cloud/src/CloudSettingsService.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/packages/cloud/src/CloudSettingsService.ts), serves as the central authority for retrieving and caching extension settings. It manages the connection to the Roo Code SaaS API and maintains local copies of your configuration.

Key responsibilities include:
- **Local caching**: Stores settings in VS Code's `globalState` using the keys `organization-settings` and `user-settings` (constants defined on lines 25-26)
- **Periodic refresh**: Configures a `RefreshTimer` in the constructor (lines 68-75) that polls the server every 3,600,000ms (one hour) while authenticated
- **Event emission**: Fires a `settings-updated` event when new data arrives, signaling other components to refresh

On initialization, the service immediately calls `loadCachedSettings` (line 79) to restore the last-known configuration from memory, ensuring zero-latency startup.

### CloudService

Located in [`packages/cloud/src/CloudService.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/packages/cloud/src/CloudService.ts), this class acts as the bridge between the settings service and the rest of the extension. It subscribes to update events and manages the lifecycle of cloud synchronization based on authentication state.

The service registers a `settingsListener` on line 108 that forwards `settings-updated` events to the `ExtensionStateContext`. It also handles cleanup during logout by stopping the refresh timer and clearing cached data (lines 86-97 and 355).

### ExtensionStateContext

The `ExtensionStateContext` in [`webview-ui/src/context/ExtensionStateContext.tsx`](https://github.com/RooCodeInc/Roo-Code/blob/main/webview-ui/src/context/ExtensionStateContext.tsx) provides the single source of truth for UI components. It maintains the in-memory state including `cloudIsAuthenticated` (line 34) and the merged settings object (line 488).

When `CloudService` pushes updates, the context updates its `contextValue`, causing all consuming components—such as those using [`useCloudUpsell.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/useCloudUpsell.ts) (line 16)—to re-render with fresh data.

## Step-by-Step Synchronization Flow

Understanding the exact sequence of operations helps clarify how Roo Code maintains consistency across sessions:

1. **Extension startup**: [`src/extension.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/src/extension.ts) instantiates `CloudService` and registers the global `settings-updated` handler (line 267)

2. **Cache hydration**: `CloudSettingsService` reads the Memento keys `organization-settings` and `user-settings` into `this.settings` and `this.userSettings`, making configuration instantly available before any network request

3. **Authentication verification**: If `authService.getState() === "active-session"`, the service starts the `RefreshTimer` (lines 88-90)

4. **Remote fetch**: The timer triggers `fetchSettings()`, which performs a GET request to `https://app.roocode.com/api/extension-settings` (line 115)

5. **Validation and storage**: The response undergoes Zod validation against `organizationSettingsSchema` and `userSettingsDataSchema` (lines 35-45). Valid data updates the cache via `context.globalState.update()` (lines 389-390)

6. **Event propagation**: `this.emit("settings-updated", {})` fires (line 153), triggering `CloudService` to update `ExtensionStateContext`

7. **UI refresh**: Components using `useExtensionState()` automatically receive the new values, including the Settings view and cloud upsell hooks

## Code Implementation Details

The following excerpts demonstrate the critical synchronization mechanisms in the Roo Code codebase.

### Fetching and Caching Remote Settings

When the `RefreshTimer` triggers or manual refresh occurs, `CloudSettingsService` executes this flow to retrieve and persist configuration:

```typescript
// packages/cloud/src/CloudSettingsService.ts (excerpt)
private async fetchSettings(): Promise<boolean> {
  const response = await fetch(`${getRooCodeApiUrl()}/api/extension-settings`);
  const json = await response.json();

  // Validate the shape – Zod guarantees we have a known schema
  const parsed = parseExtensionSettingsResponse(json);
  if (!parsed.success) {
    this.log("[cloud-settings] Invalid extension settings format:", parsed.error);
    return false;
  }

  // Store in VS Code's global state (Memento)
  await this.context.globalState.update(ORGANIZATION_SETTINGS_CACHE_KEY, parsed.data.organization);
  await this.context.globalState.update(USER_SETTINGS_CACHE_KEY, parsed.data.user);

  // Notify the rest of the extension
  this.emit("settings-updated", {} as Record<string, never>);
  return true;
}

```

### Bridging Events to Extension State

The `CloudService` constructor wires the settings service to the extension's event system:

```typescript
// packages/cloud/src/CloudService.ts (excerpt)
constructor(context: ExtensionContext, authService: AuthService, ...) {
  ...
  this.settingsListener = (data) => {
    // Forward the event to the extension host
    this.emit("settings-updated", data);
  };

  // Wire the listener once the SettingsService is ready
  this.settingsService.on("settings-updated", this.settingsListener);
}

```

### Consuming Synced State in UI Components

React components access synchronized settings through the context provider:

```tsx
// webview-ui/src/components/settings/SettingsView.tsx (excerpt)
const { cloudIsAuthenticated, sharingEnabled, ...cachedState } = useExtensionState();

useEffect(() => {
  // Whenever the cloud pushes a new settings payload,
  // `cachedState` is refreshed and the UI reflects the changes.
}, [cachedState]);

```

## Session Management and Cleanup

Roo Code handles session transitions gracefully to prevent stale data or unnecessary network requests:

- **Logout**: The `auth-state-changed` handler (lines 86-97) stops the `RefreshTimer` and invokes `removeSettings()`, which clears both `organization-settings` and `user-settings` from `globalState` (lines 83-84)
- **New device login**: When authenticating on a fresh machine, the startup flow reads empty cached values initially, then the timer fetches the latest cloud settings and populates the local cache

## Summary

- **CloudSettingsService** manages the API connection and local caching in VS Code's `globalState`, refreshing every hour while authenticated
- **CloudService** bridges the settings service to the extension state and handles authentication lifecycle events
- **ExtensionStateContext** provides reactive state to UI components, ensuring automatic re-renders when cloud settings change
- The system stores configuration using Memento keys `organization-settings` and `user-settings`, surviving extension reloads and IDE restarts
- Zod schemas validate all incoming data to maintain type safety across the distributed system

## Frequently Asked Questions

### How often does Roo Code sync settings with the cloud?

Roo Code polls the cloud API every 3,600,000 milliseconds (one hour) while the user maintains an active authenticated session. This interval is configured in the `CloudSettingsService` constructor using the `RefreshTimer` utility, which only runs when `authService.getState()` returns `"active-session"`.

### Where are cloud settings cached locally?

Settings persist in VS Code's `ExtensionContext.globalState` (a Memento storage) using the keys `organization-settings` and `user-settings` defined in [`packages/cloud/src/CloudSettingsService.ts`](https://github.com/RooCodeInc/Roo-Code/blob/main/packages/cloud/src/CloudSettingsService.ts). This storage survives extension reloads and IDE restarts, allowing instant access to your configuration even when offline.

### What happens to my settings when I log out?

Upon logout, the `CloudService` triggers cleanup that stops the `RefreshTimer` and calls `removeSettings()`, which deletes both cached entries from `globalState`. This ensures no sensitive configuration remains on the local machine after authentication ends.

### Can I use Roo Code on multiple devices simultaneously?

Yes. Because settings store in the Roo Code SaaS backend and cache locally on each device, you can authenticate on multiple machines. Each instance polls independently, so changes made on one device appear on others within the next hourly sync cycle, or immediately upon restarting the extension.