Skip to content

Global Configuration

Global configuration settings apply across all Prodigy projects and workflows. These settings are stored in your user home directory and can be overridden by project-specific configuration or environment variables.

Configuration Structure

The global configuration is defined by the GlobalConfig struct, which contains system-wide settings for Prodigy's behavior, external tool integration, and operational parameters.

// Source: src/config/mod.rs:45-59
/// Global configuration settings for Prodigy
///
/// These settings apply across all projects and workflows. Can be overridden
/// by project-specific configuration. Stored in the user's home
/// directory under ~/.prodigy/config.yml.
pub struct GlobalConfig {
    pub prodigy_home: PathBuf,
    pub default_editor: Option<String>,
    pub log_level: Option<String>,
    pub claude_api_key: Option<String>,
    pub max_concurrent_specs: Option<u32>,
    pub auto_commit: Option<bool>,
    pub plugins: Option<PluginConfig>,
}

Configuration Fields

Field Type Description Default
prodigy_home PathBuf Directory for Prodigy data, sessions, and state ~/.prodigy
default_editor Option<String> Default text editor for editing files None (uses $EDITOR)
log_level Option<String> Logging verbosity level "info"
claude_api_key Option<String> Claude API key for authentication None
max_concurrent_specs Option<u32> Maximum number of concurrent spec executions 1
auto_commit Option<bool> Automatically commit changes after successful commands true
plugins Option<PluginConfig> Plugin system configuration None

File Locations

Global Configuration

The global configuration file is stored in the Prodigy data directory:

~/.prodigy/config.yml

The global directory location is determined by platform-specific conventions:

// Source: src/config/mod.rs:26-31
pub fn get_global_prodigy_dir() -> Result<PathBuf> {
    ProjectDirs::from("com", "prodigy", "prodigy")
        .map(|dirs| dirs.data_dir().to_path_buf())
        .ok_or_else(|| anyhow!("Could not determine home directory"))
}

Platform-specific paths:

~/.local/share/prodigy/

~/Library/Application Support/com.prodigy.prodigy/

C:\Users\<username>\AppData\Roaming\prodigy\prodigy\

Project Configuration

Project-specific configuration files are stored within the project directory:

<project-root>/.prodigy/config.yml

Configuration Precedence

Prodigy uses a hierarchical configuration system where settings can be overridden at multiple levels. The precedence order from highest to lowest is:

graph TD
    Env[Environment Variables<br/>PRODIGY_*] --> Project[Project Config<br/>.prodigy/config.yml]
    Project --> Global[Global Config<br/>~/.prodigy/config.yml]
    Global --> Defaults[Default Values<br/>Hardcoded]

    Env -.->|Highest Priority| Resolution[Final Value]
    Project -.->|Override Global| Resolution
    Global -.->|Override Defaults| Resolution
    Defaults -.->|Lowest Priority| Resolution

    style Env fill:#e8f5e9
    style Project fill:#e1f5ff
    style Global fill:#fff3e0
    style Defaults fill:#f5f5f5
    style Resolution fill:#e8eaf6

Figure: Configuration precedence hierarchy showing how values are resolved from highest to lowest priority.

Precedence Order

Configuration values are resolved in this order: Environment Variables → Project Config → Global Config → Defaults. The first defined value wins.

Precedence Examples

Claude API Key Resolution:

// Source: src/config/mod.rs:133-138
pub fn get_claude_api_key(&self) -> Option<&str> {
    self.project
        .as_ref()
        .and_then(|p| p.claude_api_key.as_deref())
        .or(self.global.claude_api_key.as_deref())
}
  1. PRODIGY_CLAUDE_API_KEY environment variable (highest priority)
  2. claude_api_key in project .prodigy/config.yml
  3. claude_api_key in global ~/.prodigy/config.yml
  4. None (no API key configured)

Auto-Commit Behavior:

// Source: src/config/mod.rs:140-146
pub fn get_auto_commit(&self) -> bool {
    self.project
        .as_ref()
        .and_then(|p| p.auto_commit)
        .or(self.global.auto_commit)
        .unwrap_or(true)
}
  1. PRODIGY_AUTO_COMMIT environment variable
  2. auto_commit in project config
  3. auto_commit in global config
  4. true (default)

Environment Variables

Environment variables provide the highest-priority configuration mechanism, useful for CI/CD environments, temporary overrides, and secrets management.

When to Use Environment Variables

Use environment variables for:

  • CI/CD pipelines - Keep secrets out of version control
  • Temporary overrides - Test different settings without modifying config files
  • Multi-environment deployments - Same workflow, different configs per environment
  • Sensitive credentials - API keys and tokens that shouldn't be stored in files

Supported Environment Variables

// Source: src/config/mod.rs:111-131
pub fn merge_env_vars(&mut self) {
    if let Ok(api_key) = std::env::var("PRODIGY_CLAUDE_API_KEY") {
        self.global.claude_api_key = Some(api_key);
    }

    if let Ok(log_level) = std::env::var("PRODIGY_LOG_LEVEL") {
        self.global.log_level = Some(log_level);
    }

    if let Ok(editor) = std::env::var("PRODIGY_EDITOR") {
        self.global.default_editor = Some(editor);
    } else if let Ok(editor) = std::env::var("EDITOR") {
        self.global.default_editor = Some(editor);
    }

    if let Ok(auto_commit) = std::env::var("PRODIGY_AUTO_COMMIT") {
        if let Ok(value) = auto_commit.parse::<bool>() {
            self.global.auto_commit = Some(value);
        }
    }
}
Variable Purpose Example
PRODIGY_CLAUDE_API_KEY Override Claude API key sk-ant-api03-...
PRODIGY_LOG_LEVEL Set logging verbosity debug, info, warn, error
PRODIGY_EDITOR Override default editor vim, code, nano
EDITOR System default editor (fallback) vim, emacs
PRODIGY_AUTO_COMMIT Enable/disable auto-commit true, false

Environment Variable Usage

# Temporary API key override for a single command
PRODIGY_CLAUDE_API_KEY=sk-ant-api03-xxx prodigy run workflow.yml

# Enable debug logging for troubleshooting
PRODIGY_LOG_LEVEL=debug prodigy run workflow.yml

# Disable auto-commit for manual control
PRODIGY_AUTO_COMMIT=false prodigy run workflow.yml

Claude Settings

Claude integration is configured through the claude_api_key field, which can be set at multiple levels.

API Key Configuration

Global Configuration:

# ~/.prodigy/config.yml
claude_api_key: sk-ant-api03-xxxxxxxxxxxxx
log_level: info

Project Configuration Override:

# .prodigy/config.yml
name: my-project
claude_api_key: sk-ant-api03-project-specific-key

Environment Variable (Recommended for CI/CD):

export PRODIGY_CLAUDE_API_KEY=sk-ant-api03-xxxxxxxxxxxxx

API Key Security

Never commit API keys to version control. Use environment variables or secure secret management systems for production environments.

Best Practices for API Key Management

API Key Storage Strategy

Choose the right storage level for your use case:

  1. Development: Use global config file (~/.prodigy/config.yml) - convenient for local work
  2. CI/CD: Use environment variables (PRODIGY_CLAUDE_API_KEY) - keeps secrets out of code
  3. Multi-tenant: Use project-specific config for different API keys per project
  4. Production/Sensitive: Use secret management tools (Vault, AWS Secrets Manager, GitHub Secrets)

Configuration Loading

Prodigy uses a multi-stage configuration loading process with clear precedence rules.

Loading Hierarchy

// Source: src/config/loader.rs:31-55
pub async fn load_with_explicit_path(
    &self,
    project_path: &Path,
    explicit_path: Option<&Path>,
) -> Result<()> {
    match explicit_path {
        Some(path) => {
            // Load from explicit path, error if not found
            self.load_from_path(path).await?;
        }
        None => {
            // Check for .prodigy/workflow.yml
            let default_path = project_path.join(".prodigy").join("workflow.yml");
            if default_path.exists() {
                self.load_from_path(&default_path).await?;
            }
            // Otherwise use defaults (already set in new())
        }
    }
    Ok(())
}

Load Order:

Configuration Load Sequence

Prodigy loads configuration in this sequence:

  1. Explicit Path: If -f or --file flag provided, load that exact file (error if not found)
  2. Project Default: Check for .prodigy/workflow.yml in project directory
  3. Global Defaults: Use default GlobalConfig values if no project config exists

Configuration Format

Prodigy configuration files must use YAML format with the .yml extension.

YAML Only

Configuration files MUST use .yml extension. Files with .toml or other extensions will be rejected with a validation error.

// Source: src/config/loader.rs:65-69
let extension = path.extension().and_then(|ext| ext.to_str()).unwrap_or("");

validate_config_format(extension)
    .with_context(|| format!("Invalid configuration file: {}", path.display()))?;

TOML Deprecated

Earlier versions of Prodigy supported TOML format (.toml), but this has been deprecated in favor of YAML for consistency with workflow definitions.

Internal Representation

While all Prodigy configuration files must be written in YAML format, some internal data structures (like ProjectConfig.variables) use toml::Table for historical reasons and backward compatibility. This is an implementation detail - users should always write configuration in YAML format with the .yml extension.

Default Values

When no configuration is explicitly provided, Prodigy uses these default values:

// Source: src/config/mod.rs:88-99
impl Default for GlobalConfig {
    fn default() -> Self {
        Self {
            prodigy_home: get_global_prodigy_dir().unwrap_or_else(|_| PathBuf::from("~/.prodigy")),
            default_editor: None,
            log_level: Some("info".to_string()),
            claude_api_key: None,
            max_concurrent_specs: Some(1),
            auto_commit: Some(true),
            plugins: None,
        }
    }
}
Setting Default Value Reason
prodigy_home Platform-specific (see above) Standard user data directory
default_editor None Uses $EDITOR or $PRODIGY_EDITOR
log_level "info" Balance between visibility and noise
claude_api_key None Must be explicitly configured
max_concurrent_specs 1 Sequential execution for safety
auto_commit true Automatic change tracking
plugins None Plugins disabled by default

Plugin Configuration

The plugin system allows extending Prodigy with custom commands and workflows.

Plugin Structure

// Source: src/config/mod.rs:81-86
pub struct PluginConfig {
    pub enabled: bool,
    pub directory: PathBuf,
    pub auto_load: Vec<String>,
}

Enabling Plugins

# ~/.prodigy/config.yml
plugins:
  enabled: true
  directory: ~/.prodigy/plugins
  auto_load:
    - git-helpers
    - code-review
    - custom-validators

Fields:

  • enabled: Master switch for plugin system
  • directory: Location where plugins are stored
  • auto_load: List of plugins to load automatically on startup

Complete Configuration Examples

Minimal Global Configuration

# ~/.prodigy/config.yml
# Minimal configuration with only API key
claude_api_key: sk-ant-api03-xxxxxxxxxxxxx

Full Global Configuration

# ~/.prodigy/config.yml
# Complete configuration with all options
prodigy_home: ~/.prodigy                        # (1)!
default_editor: code                            # (2)!
log_level: info                                 # (3)!
claude_api_key: sk-ant-api03-xxxxxxxxxxxxx      # (4)!
max_concurrent_specs: 1                         # (5)!
auto_commit: true                               # (6)!

plugins:
  enabled: true                                 # (7)!
  directory: ~/.prodigy/plugins                 # (8)!
  auto_load:                                    # (9)!
    - git-helpers
    - code-review
  1. Directory for sessions, state, events, and DLQ data
  2. Editor for prodigy edit commands (falls back to $EDITOR)
  3. Logging verbosity: debug, info, warn, error
  4. Claude API key for authentication (keep secret!)
  5. Maximum concurrent MapReduce agents (start low, increase carefully)
  6. Automatically commit changes after successful commands
  7. Enable/disable the plugin system
  8. Where plugin scripts are stored
  9. Plugins to load automatically on startup

Project Configuration Override

# <project>/.prodigy/config.yml
# Project-specific overrides
name: my-project                                        # (1)!
description: Example project with custom settings       # (2)!
version: 1.0.0

# Override global API key for this project
claude_api_key: sk-ant-api03-project-specific-key      # (3)!

# Override auto-commit for manual control
auto_commit: false                                      # (4)!

# Project-specific variables
variables:                                              # (5)!
  deploy_env: staging
  api_url: https://staging.api.example.com
  1. Project identifier used in state and event tracking
  2. Human-readable description for documentation
  3. Project-specific API key (overrides global config)
  4. Disable auto-commit for this project (manual git commit control)
  5. Variables available in workflows as ${variable_name}

Environment Variable Workflow

#!/bin/bash
# CI/CD workflow using environment variables

# Set configuration via environment
export PRODIGY_CLAUDE_API_KEY=${CLAUDE_API_KEY_SECRET}
export PRODIGY_LOG_LEVEL=debug
export PRODIGY_AUTO_COMMIT=true

# Run workflow with environment-based config
prodigy run .prodigy/workflow.yml