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

Continue (continuedev/continue) uses config.yaml as its primary user-facing configuration file, falling back to legacy 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)

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 format. The specification and loading logic live in the @continuedev/config-yaml package, specifically documented in packages/config-yaml/src/README.md.

Key Configuration Sections

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

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. 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 and output to packages/config-yaml/schema/config-yaml-schema.json.

Legacy Configuration (config.json)

config.json at ~/.continue/config.json serves as the deprecated legacy format. Continue reads this file only when no 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, 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 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 that offers one-click conversion from config.json to 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, these files follow a structured format:

# 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 to optimize indexing performance.

Project-Local Overrides

A .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:

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 and 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 is the modern, actively developed format that receives all new features first, including advanced model roles and tool configurations. config.json is the legacy format maintained for backward compatibility; when both exist, 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 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). 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 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 whenever types change. For config.json, validation uses the static schema defined in extensions/vscode/config_schema.json, which also powers VS Code's IntelliSense and autocomplete features.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}