Config

You can configure codeflow using a JSON config file.

---

Format

codeflow supports both JSON and JSONC (JSON with Comments) formats.

codeflow.jsonc

{
  "$schema": "https://codeflow.ai/config.json",
  // Theme configuration
  "theme": "codeflow",
  "model": "anthropic/claude-sonnet-4-20250514",
  "autoupdate": true,
}

With JSONC, you can use comments in your configuration files:

---

Locations

You can place your config in a couple of different locations and they have a different order of precedence.

---

Global

Place your global codeflow config in ~/.config/codeflow/codeflow.json. You’ll want to use the global config for things like themes, providers, or keybinds.

---

Per project

You can also add a codeflow.json in your project. It takes precedence over the global config. This is useful for configuring providers or modes specific to your project.

Tip

Place project specific config in the root of your project.

When codeflow starts up, it looks for a config file in the current directory or traverse up to the nearest Git directory.

This is also safe to be checked into Git and uses the same schema as the global one.

---

Custom path

You can also specify a custom config file path using the codeflow_CONFIG environment variable. This takes precedence over the global and project configs.

export codeflow_CONFIG=/path/to/my/custom-config.json
codeflow run "Hello world"

---

Schema

The config file has a schema that’s defined in codeflow.ai/config.json.

Your editor should be able to validate and autocomplete based on the schema.

---

Models

You can configure the providers and models you want to use in your codeflow config through the provider, model and small_model options.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-20250514",
  "small_model": "anthropic/claude-3-5-haiku-20241022"
}

The small_model option configures a separate model for lightweight tasks like title generation. By default, codeflow tries to use a cheaper model if one is available from your provider, otherwise it falls back to your main model.

You can also configure local models. Learn more.

---

Themes

You can configure the theme you want to use in your codeflow config through the theme option.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "theme": ""
}

Learn more here.

---

Agents

You can configure specialized agents for specific tasks through the agent option.

codeflow.jsonc

{
  "$schema": "https://codeflow.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        // Disable file modification tools for review-only agent
        "write": false,
        "edit": false,
      },
    },
  },
}

You can also define agents using markdown files in ~/.config/codeflow/agent/ or .codeflow/agent/. Learn more here.

---

Sharing

You can configure the share feature through the share option.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "share": "manual"
}

This takes:

• "manual" - Allow manual sharing via commands (default)
• "auto" - Automatically share new conversations
• "disabled" - Disable sharing entirely

By default, sharing is set to manual mode where you need to explicitly share conversations using the /share command.

---

Commands

You can configure custom commands for repetitive tasks through the command option.

codeflow.jsonc

{
  "$schema": "https://codeflow.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-3-5-sonnet-20241022"
    },
    "component": {
      "template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
      "description": "Create a new component"
    }
  }
}

You can also define commands using markdown files in ~/.config/codeflow/command/ or .codeflow/command/. Learn more here.

---

Keybinds

You can customize your keybinds through the keybinds option.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "keybinds": {}
}

Learn more here.

---

Autoupdate

codeflow will automatically download any new updates when it starts up. You can disable this with the autoupdate option.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "autoupdate": false
}

---

Formatters

You can configure code formatters through the formatter option.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": {
        "NODE_ENV": "development"
      },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

Learn more about formatters here.

---

Permissions

You can configure permissions to control what AI agents can do in your codebase through the permission option.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

This allows you to configure explicit approval requirements for sensitive operations:

• edit - Controls whether file editing operations require user approval ("ask" or "allow")
• bash - Controls whether bash commands require user approval (can be "ask"/"allow" or a pattern map)

Learn more about permissions here.

---

MCP servers

You can configure MCP servers you want to use through the mcp option.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "mcp": {}
}

Learn more here.

---

Instructions

You can configure the instructions for the model you’re using through the instructions option.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

This takes an array of paths and glob patterns to instruction files. Learn more about rules here.

---

Disabled providers

You can disable providers that are loaded automatically through the disabled_providers option. This is useful when you want to prevent certain providers from being loaded even if their credentials are available.

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

The disabled_providers option accepts an array of provider IDs. When a provider is disabled:

• It won’t be loaded even if environment variables are set.
• It won’t be loaded even if API keys are configured through codeflow auth login.
• The provider’s models won’t appear in the model selection list.

---

Variables

You can use variable substitution in your config files to reference environment variables and file contents.

---

Env vars

Use {env:VARIABLE_NAME} to substitute environment variables:

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "model": "{env:codeflow_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

If the environment variable is not set, it will be replaced with an empty string.

---

Files

Use {file:path/to/file} to substitute the contents of a file:

codeflow.json

{
  "$schema": "https://codeflow.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

File paths can be:

• Relative to the config file directory
• Or absolute paths starting with / or ~

These are useful for:

• Keeping sensitive data like API keys in separate files.
• Including large instruction files without cluttering your config.
• Sharing common configuration snippets across multiple config files.