PDD uses a layered configuration system. Settings are resolved in this order, with earlier sources winning:
- CLI options (highest priority)
.pddrc context matched to the current path- Environment variables
- Built-in defaults (lowest priority)
The .pddrc file
.pddrc is a YAML file in your project root that defines named contexts. Each context applies to files under specific paths and sets default values for output locations, model parameters, and coverage targets.
version: "1.0"
contexts:
backend:
paths: ["backend/**", "functions/**", "api/**"]
defaults:
generate_output_path: "backend/src/"
test_output_path: "backend/tests/"
example_output_path: "backend/examples/"
default_language: "python"
target_coverage: 95.0
strength: 0.818
temperature: 0.0
budget: 10.0
max_attempts: 3
frontend:
paths: ["frontend/**", "web/**", "ui/**"]
defaults:
generate_output_path: "frontend/src/"
test_output_path: "frontend/__tests__/"
example_output_path: "frontend/examples/"
default_language: "typescript"
target_coverage: 85.0
strength: 0.818
default:
defaults:
generate_output_path: "./"
test_output_path: "tests/"
example_output_path: "examples/"
default_language: "python"
target_coverage: 10.0
strength: 0.818
temperature: 0.0
budget: 10.0
max_attempts: 3
Context defaults reference
Each context’s defaults block can include any of the following keys:
| Key | Type | Description |
|---|
generate_output_path | string | Directory where generated code files are saved |
test_output_path | string | Directory where generated test files are saved |
example_output_path | string | Directory where generated example files are saved |
default_language | string | Language used when not detected from the prompt filename |
target_coverage | float | Target code coverage percentage (default: 90.0) |
strength | float | Model strength from 0.0 (cheapest) to 1.0 (most powerful) |
temperature | float | Model temperature (default: 0.0) |
budget | float | Maximum USD cost for the operation (default: varies by command) |
max_attempts | int | Maximum fix iterations in any iterative loop (default: 3) |
prompts_dir | string | Directory to scan for prompt files |
Context detection
When you run a PDD command, the CLI automatically selects the matching context by comparing the current working directory path against each context’s paths list. The first matching context wins.
Path matching uses glob patterns:
contexts:
commands:
paths: ["pdd/commands/**", "**/pdd/commands/**", "prompts/commands/**"]
default context is used.
Overriding context selection
Use --context to explicitly select a context, bypassing automatic detection:
pdd --context backend --force sync calculator
--list-contexts to see all available contexts in the nearest .pddrc:
pdd --list-contexts
# backend
# frontend
# default
--list-contexts reads .pddrc and exits immediately — no commands run and no auto-update checks occur.
If you pass --context with a name that doesn’t exist in .pddrc, the CLI exits with a usage error before running any subcommand.
Full .pddrc example
This is the .pddrc used by the PDD CLI codebase itself, showing multiple contexts for different parts of the project:
version: "1.0"
contexts:
regression:
paths: ["*/staging/sync_regression_*", "**/staging/sync_regression_*"]
defaults:
generate_output_path: "pdd/"
test_output_path: "tests/"
example_output_path: "examples/"
default_language: "python"
target_coverage: 10.0
strength: 0.818
temperature: 0.0
budget: 10.0
max_attempts: 3
context:
paths: ["context/**"]
defaults:
generate_output_path: "context/"
test_output_path: "tests/context/"
example_output_path: "context/"
default_language: "python"
target_coverage: 85.0
strength: 0.818
backend:
paths: ["backend/**", "functions/**", "api/**"]
defaults:
generate_output_path: "backend/src/"
test_output_path: "backend/tests/"
example_output_path: "backend/examples/"
default_language: "python"
target_coverage: 95.0
strength: 0.818
frontend:
paths: ["frontend/**", "web/**", "ui/**"]
defaults:
generate_output_path: "frontend/src/"
test_output_path: "frontend/__tests__/"
example_output_path: "frontend/examples/"
default_language: "typescript"
target_coverage: 85.0
strength: 0.818
commands:
paths: ["pdd/commands/**", "**/pdd/commands/**", "prompts/commands/**"]
defaults:
generate_output_path: "pdd/commands/"
test_output_path: "tests/commands/"
example_output_path: "context/commands/"
prompts_dir: "prompts/commands"
default_language: "python"
target_coverage: 90.0
strength: 0.818
temperature: 0.0
budget: 10.0
max_attempts: 3
pdd_cli:
paths: ["pdd/**", "*.py", "prompts/**", "tests/**"]
defaults:
generate_output_path: "pdd"
test_output_path: "tests"
example_output_path: "context"
prompts_dir: "prompts"
default_language: "python"
target_coverage: 80.0
strength: 1
temperature: 0.0
budget: 10.0
max_attempts: 3
default:
defaults:
generate_output_path: "./"
test_output_path: "tests/"
example_output_path: "examples/"
default_language: "python"
target_coverage: 10.0
strength: 0.818
temperature: 0.0
budget: 10.0
max_attempts: 3
Order matters. Place more specific contexts (like regression) before general ones (like pdd_cli) so that the first match is the most specific one.
Environment variables
Environment variables provide project-wide defaults that sit between .pddrc and built-in defaults in the precedence chain.
| Variable | Description |
|---|
PDD_AUTO_UPDATE | Set to false to disable automatic CLI updates. Useful in CI/CD pipelines. |
PDD_OUTPUT_COST_PATH | Default path for the cost tracking CSV file. Overridden by --output-cost. |
PDD_GENERATE_OUTPUT_PATH | Default directory for generated code files. Overridden by --output. |
PDD_QUIET | Set to any value to suppress non-error output globally. |
PDD_STRENGTH_DEFAULT | Default model strength (0.0–1.0). Overridden by --strength. |
PDD_NO_GITHUB_STATE | Set to 1 to disable GitHub issue comment-based state persistence. |
PDD_USER_STORIES_DIR | Directory containing story__*.md files (default: user_stories/). |
PDD_PROMPTS_DIR | Directory containing .prompt files (default: prompts/). |
export PDD_AUTO_UPDATE=false
.bashrc, .zshrc, or your CI environment configuration for persistence.
Configuration precedence summary
CLI option (--strength 0.9)
└── .pddrc context defaults (strength: 0.818)
└── Environment variable (PDD_STRENGTH_DEFAULT=0.5)
└── Built-in default (0.5)