# Continue Configuration Files: The Complete Guide to `config.yaml`, `config.json`, and Custom Agents

> Master continuedev/continue configuration with config.yaml, config.json, and custom agents. Learn to customize your coding assistant for optimal productivity.

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

---

**Continue (continuedev/continue) uses [`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml) as its primary user-facing configuration file, falling back to legacy [`config.json`](https://github.com/continuedev/continue/blob/main/config.json) when needed, alongside project-local overrides and custom agent definitions stored in `~/.continue/`.**

Understanding the configuration file hierarchy in the Continue open-source AI coding assistant is essential for customizing models, tools, and UI behavior. The repository stores all user-facing settings in a predictable location within the home directory, with validation schemas defined in the source code to ensure correctness.

## The Primary Configuration File ([`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml))

**[`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml)** is the modern, preferred format for configuring Continue. Located at `~/.continue/config.yaml`, this file defines model providers, model roles, tool overrides, and UI preferences.

When present, Continue loads this file in place of the older [`config.json`](https://github.com/continuedev/continue/blob/main/config.json) format. The specification and loading logic live in the `@continuedev/config-yaml` package, specifically documented in [`packages/config-yaml/src/README.md`](https://github.com/continuedev/continue/blob/main/packages/config-yaml/src/README.md).

### Key Configuration Sections

The YAML structure supports nested definitions for models, tools, and interface settings:

```yaml
models:
  - model: "gpt-4"
    provider: "openai"
    role: "chat"
  - model: "codellama:7b"
    provider: "ollama"
    role: "autocomplete"

tools:
  - name: "websearch"
    enabled: true

ui:
  theme: "dark"
  continueAfterToolRejection: true

```

### Validation and Schema Generation

The `@continuedev/config-yaml` package handles parsing through the `loadConfigYaml` function defined in [`packages/config-yaml/src/validation.ts`](https://github.com/continuedev/continue/blob/main/packages/config-yaml/src/validation.ts). The loading process recursively "unrolls" package references, validates against a generated JSON schema, and merges secret variables into the final in-memory structure.

The schema itself is generated automatically by [`packages/config-yaml/src/scripts/generateJsonSchema.ts`](https://github.com/continuedev/continue/blob/main/packages/config-yaml/src/scripts/generateJsonSchema.ts) and output to [`packages/config-yaml/schema/config-yaml-schema.json`](https://github.com/continuedev/continue/blob/main/packages/config-yaml/schema/config-yaml-schema.json).

## Legacy Configuration ([`config.json`](https://github.com/continuedev/continue/blob/main/config.json))

**[`config.json`](https://github.com/continuedev/continue/blob/main/config.json)** at `~/.continue/config.json` serves as the deprecated legacy format. Continue reads this file only when no [`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml) exists, displaying a migration prompt in the UI to encourage upgrading.

The JSON schema for validation resides in [`extensions/vscode/config_schema.json`](https://github.com/continuedev/continue/blob/main/extensions/vscode/config_schema.json), which VS Code registers to provide autocomplete and validation features. However, new features—such as advanced model roles and tool overrides—are implemented in [`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml) first and may not be available in the JSON format.

### Migration Path to YAML

The VS Code extension includes a CodeLens provider at [`extensions/vscode/src/lang-server/codeLens/providers/ConfigJsonConverterCodeLensProvider.ts`](https://github.com/continuedev/continue/blob/main/extensions/vscode/src/lang-server/codeLens/providers/ConfigJsonConverterCodeLensProvider.ts) that offers one-click conversion from [`config.json`](https://github.com/continuedev/continue/blob/main/config.json) to [`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml). This ensures users can migrate existing configurations without manual rewriting.

## Project-Level and Meta Configuration Files

Continue supports workspace-specific overrides and auxiliary configuration files within project directories.

### Custom Agent Definitions (`.continue/agents/`)

Users can create **custom agents**—reusable assistants combining prompts and tool configurations—by placing Markdown files in `~/.continue/agents/`. Each file defines an agent that can be invoked via CLI commands.

According to the skill documentation referenced in [`skills/cn-check/SKILL.md`](https://github.com/continuedev/continue/blob/main/skills/cn-check/SKILL.md), these files follow a structured format:

```markdown

# Security Review Agent

You are a security auditor.  
Check the code for injection, XSS, and credential leaks.

## Steps

1. Scan all changed files.
2. Summarize any findings.
3. Suggest mitigations.

```

### Ignore Patterns (`.continueignore`)

The `.continue/.continueignore` file functions similarly to `.gitignore`, telling the Continue indexer which files to exclude from processing. This file is read by the sync subsystem implemented in [`sync/src/sync/mod.rs`](https://github.com/continuedev/continue/blob/main/sync/src/sync/mod.rs) to optimize indexing performance.

### Project-Local Overrides

A [`.continue/config.json`](https://github.com/continuedev/continue/blob/main/.continue/config.json) file in the workspace root provides project-specific configuration overrides. This allows teams to share standard settings via version control while maintaining user-specific preferences in the home directory.

## Loading Configuration Programmatically

The `@continuedev/config-yaml` package exports `loadConfigYaml` as the single entry point used by the GUI, CLI, and language server. The following example demonstrates how to load and inspect the configuration:

```ts
import { loadConfigYaml, ConfigResult } from "@continuedev/config-yaml";

// Loads the user's config.yaml (or falls back to config.json)
async function getConfig(): Promise<ConfigResult> {
  const { config, errors } = await loadConfigYaml();
  if (errors.length) {
    console.warn("Configuration errors:", errors);
  }
  return config;
}

// Example: list all chat models
(async () => {
  const cfg = await getConfig();
  const chatModels = cfg.models.filter(m => m.role === "chat");
  console.log("Chat models:", chatModels.map(m => m.model));
})();

```

This function returns a `ConfigResult` containing the validated configuration object and any validation errors encountered during parsing.

## Summary

- **`~/.continue/config.yaml`** is the primary configuration file for modern Continue installations, supporting all latest features including model roles and tool overrides.
- **`~/.continue/config.json`** provides backward compatibility but receives new features only after YAML implementation.
- **`~/.continue/agents/*.md`** files define custom agents using Markdown formatting for reusable prompt templates.
- **`.continue/.continueignore`** controls indexer behavior at the project level, excluding files from processing.
- **Validation schemas** are generated automatically from TypeScript types and located in [`extensions/vscode/config_schema.json`](https://github.com/continuedev/continue/blob/main/extensions/vscode/config_schema.json) and [`packages/config-yaml/schema/config-yaml-schema.json`](https://github.com/continuedev/continue/blob/main/packages/config-yaml/schema/config-yaml-schema.json).
- The **`loadConfigYaml`** function in `@continuedev/config-yaml` serves as the unified configuration loading interface across all Continue components.

## Frequently Asked Questions

### What is the difference between config.yaml and config.json in Continue?

**[`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml)** is the modern, actively developed format that receives all new features first, including advanced model roles and tool configurations. **[`config.json`](https://github.com/continuedev/continue/blob/main/config.json)** is the legacy format maintained for backward compatibility; when both exist, [`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml) takes precedence. The VS Code extension provides automated migration tools to convert JSON configurations to YAML.

### Where does Continue store user configuration files?

Continue stores global user configuration in **`~/.continue/config.yaml`** (preferred) or **`~/.continue/config.json`** (legacy). Project-specific overrides reside in **[`.continue/config.json`](https://github.com/continuedev/continue/blob/main/.continue/config.json)** within the workspace root. Custom agents live in **`~/.continue/agents/`**, and indexer ignore patterns use **`.continue/.continueignore`** at the project level.

### How do I create custom agents in Continue?

Create a Markdown file in **`~/.continue/agents/`** with a descriptive name (e.g., [`security.md`](https://github.com/continuedev/continue/blob/main/security.md)). The file should contain a header defining the agent's purpose, followed by instructions and steps. These agents can then be invoked through the Continue CLI using commands like `cn check --agent security` according to the skill documentation format.

### How does Continue validate configuration files?

Continue validates [`config.yaml`](https://github.com/continuedev/continue/blob/main/config.yaml) against a JSON schema generated from TypeScript types in the `@continuedev/config-yaml` package. The schema is regenerated automatically via [`packages/config-yaml/src/scripts/generateJsonSchema.ts`](https://github.com/continuedev/continue/blob/main/packages/config-yaml/src/scripts/generateJsonSchema.ts) whenever types change. For [`config.json`](https://github.com/continuedev/continue/blob/main/config.json), validation uses the static schema defined in [`extensions/vscode/config_schema.json`](https://github.com/continuedev/continue/blob/main/extensions/vscode/config_schema.json), which also powers VS Code's IntelliSense and autocomplete features.