# How Continuedev/Continue Loads Configuration Settings: The Cascade Architecture

> Discover how Continuedev/Continue loads configuration settings using its cascade architecture. Learn about CLI flags, local YAML, remote defaults, and hot reloading for efficient profile management.

- Repository: [Continue/continue](https://github.com/continuedev/continue)
- Tags: internals
- Published: 2026-06-18

---

**Continuedev/Continue loads configuration settings through a layered cascade system that checks CLI flags, local YAML files, and remote defaults before caching the result in ConfigHandler for hot reloading across all profiles.**

The open-source AI coding assistant Continuedev/Continue manages complex configuration states across CLI, VS Code, and core services. Understanding how it loads configuration settings reveals a sophisticated architecture designed for extensibility and real-time updates. This article examines the exact mechanism behind configuration initialization, from source detection to cached `ContinueConfig` objects.

## The Three-Layer Configuration Cascade

The configuration system isolates three distinct concerns during runtime initialization. First, it determines the configuration source through a strict precedence hierarchy implemented in [`extensions/cli/src/configLoader.ts`](https://github.com/continuedev/continue/blob/main/extensions/cli/src/configLoader.ts). Second, it unrolls and parses the configuration into strongly-typed objects. Third, it maintains a cached state with automatic refresh capabilities managed by [`core/config/ConfigHandler.ts`](https://github.com/continuedev/continue/blob/main/core/config/ConfigHandler.ts).

### Determining the Configuration Source

The `loadConfiguration` function implements the following priority order via `determineConfigSource`:

1.  **CLI Flag** (`--config`): A direct file path or assistant slug passed via command line
2.  **Saved URI**: A previously authenticated configuration URI stored in auth settings (`saved-uri`)
3.  **Local config.yaml**: The file located at `~/.continue/config.yaml` (resolved via `env.continueHome`) (`local-config-yaml`)
4.  **Remote Default**: The fallback package `continuedev/default-cli-config` from the Continue platform (`remote-default-config`)

The function checks these options sequentially, returning the first available match.

### Unrolling and Parsing Configuration

Once the source is identified, `loadFromSource` dispatches to specialized loaders in [`configLoader.ts`](https://github.com/continuedev/continue/blob/main/configLoader.ts):

-   `loadFromCliFlag`: Handles local YAML files or assistant slugs
-   `loadFromSavedUri`: Resolves `file://` or `slug://` URIs into paths or slugs
-   `loadLocalConfigYaml`: Reads the user's home directory configuration
-   `loadDefaultConfig`: Fetches the remote default package
-   `loadAssistantSlug`: Retrieves named assistants from the platform (or unrolls locally if offline)
-   `unrollPackageIdentifiersAsConfigYaml`: Processes "inject blocks" for model plugins and extensions

All paths converge on `unrollAssistantWithConfig`, which uses the **config-yaml** library to parse YAML, resolve imports, and inject additional blocks. Errors are wrapped in `ConfigResult` objects, allowing the system to continue operating even if individual blocks fail.

## Caching and Hot Reload with ConfigHandler

The `ConfigHandler` class in [`core/config/ConfigHandler.ts`](https://github.com/continuedev/continue/blob/main/core/config/ConfigHandler.ts) serves as the single source of truth for runtime configuration. It manages a `ProfileLifecycleManager` for each profile (global, workspace, or custom), implementing a robust caching and refresh mechanism.

### Profile Lifecycle Management

The `ProfileLifecycleManager` ([`core/config/ProfileLifecycleManager.ts`](https://github.com/continuedev/continue/blob/main/core/config/ProfileLifecycleManager.ts)) handles asynchronous loading for individual profiles. During initialization, it:

-   Merges additional context providers registered by extensions via `additionalContextProviders`
-   Produces a `ConfigResult` containing the finalized `ContinueConfig`
-   Caches the result in `savedConfigResult`

### Real-Time Configuration Updates

`ConfigHandler` enables hot reloading through several mechanisms:

-   **Event Listening**: Monitors IDE events such as workspace changes or settings updates
-   **Cascade Reload**: Invokes `cascadeInit` or `reloadConfig` to rebuild the cache without process restarts
-   **Profile Switching**: Calling `setSelectedProfileId` triggers a full cascade reload, ensuring downstream services like MCP and DocsIndexer receive updated configurations
-   **Serialization**: Exposes `getSerializedConfig()` and `finalToBrowserConfig()` for UI components to receive properly formatted configuration objects

The `loadConfig()` method returns cached results unless a forced reload is requested, optimizing performance while maintaining consistency.

## Practical Implementation Examples

The following snippets demonstrate how different parts of the codebase interact with the configuration system.

### VS Code Extension Access

```typescript
// From extensions/vscode/src/extension/VsCodeExtension.ts
const { config } = await this.configHandler.loadConfig();
// config is a fully typed ContinueConfig instance

```

### CLI Entry Point

```typescript
// From extensions/cli/src/configLoader.ts
import { loadConfiguration } from "./configLoader.js";

const { config } = await loadConfiguration(
  authConfig,
  cliConfigPath,
  apiClient,
  injectBlocks,
  isHeadless,
);

```

### Core Service Integration

```typescript
// Accessing config during chat message streaming
const { config } = await this.core?.configHandler.loadConfig();
// Determines LLM model, tools, and context providers

```

## Summary

-   **Source Precedence**: Continuedev/Continue checks CLI flags, saved URIs, local [`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml), and remote defaults in that order via `determineConfigSource` in [`extensions/cli/src/configLoader.ts`](https://github.com/continuedev/continue/blob/main/extensions/cli/src/configLoader.ts).
-   **Extensible Loading**: The `unrollAssistantWithConfig` function parses YAML and injects blocks, supporting model plugins and custom context providers through `registerCustomContextProvider`.
-   **Centralized Caching**: `ConfigHandler` maintains per-profile caches via `ProfileLifecycleManager`, ensuring all components receive identical `ContinueConfig` instances.
-   **Hot Reload**: File changes in `~/.continue/` or profile switches trigger automatic cascade reloads via `reloadConfig` without restarting the process.

## Frequently Asked Questions

### What is the priority order for configuration sources in continuedev/continue?

The system follows a strict hierarchy implemented in `determineConfigSource`: first checking for a `--config` CLI flag, then a saved URI from authentication settings, followed by the local `~/.continue/config.yaml` file (located via `env.continueHome`), and finally falling back to the remote default configuration package `continuedev/default-cli-config`.

### How does Continue handle configuration changes while running?

The `ConfigHandler` class implements hot reloading by listening to IDE and filesystem events. When changes are detected, it invokes `reloadConfig` or `cascadeInit` to rebuild the configuration cache, allowing services like the DocsIndexer and MCP integrations to update without requiring a full restart.

### Can custom context providers be added to the configuration dynamically?

Yes. Extensions can register custom context providers at runtime using `registerCustomContextProvider`. The `ProfileLifecycleManager` automatically merges these providers into the loaded configuration during the unrolling process, extending the base [`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml) capabilities.

### Where does Continue store its default configuration when no local file exists?

When no local configuration is found, Continue fetches the default configuration from the Continue platform using the `loadDefaultConfig` function in [`configLoader.ts`](https://github.com/continuedev/continue/blob/main/configLoader.ts), which retrieves the package `continuedev/default-cli-config` and unrolls it into a valid `ContinueConfig` object.