cascade.yaml reference

cascade.yaml lives at the root of your repo and configures Cascade’s behavior for that project. Created automatically by cascade init.

Full example

version: 1

agent:
  provider: anthropic         # anthropic | openai | google | claude_code | ollama
  model: claude-opus-4-7
  max_iterations: 1           # 0-5; how many PR-comment iteration rounds (future use)
  temperature: 0.2            # 0.0-2.0; lower is more deterministic

memory:
  path: team-memory           # relative to repo root
  max_chars_per_call: 20000   # cap on team-memory chars per LLM call

paths:
  allowed:                    # globs Cascade IS allowed to write
    - "src/**"
    - "tests/**"
    - "docs/**"
  disallowed:                 # globs Cascade is NEVER allowed to write (deny wins)
    - ".github/**"
    - "migrations/**"
    - "cascade.yaml"
    - "team-memory/**"
    - "infrastructure/**"
    - "secrets/**"

language: null                # null = auto-detect; or python/typescript/go/rust/java/ruby/csharp/javascript
test_command: null            # null = use language profile's default; or e.g. "pytest -xvs"

default_base_branch: main     # branch new PRs target by default

Fields

version

Config schema version. Currently always 1. Cascade refuses to load configs with an unknown version, so we can evolve the schema safely.

agent

LLM behavior for this project.

Field	Type	Default	Description
provider	string	anthropic	Which LLM provider to use. One of: anthropic, openai, google, claude_code, ollama.
model	string	claude-opus-4-7	Model identifier. Provider-specific.
max_iterations	int	1	How many review-comment iteration rounds the agent will run on a PR before giving up. (Reserved for future PR-comment-loop feature; currently fixed at 1.)
temperature	float	0.2	Sampling temperature. Lower is more deterministic. 0.0 for maximum reproducibility.

memory

Team memory layer settings. See team memory for what to put in the files.

Field	Type	Default	Description
path	string	team-memory	Directory containing the memory files. Relative to repo root.
max_chars_per_call	int	20000	Truncates politely if memory exceeds this. Per-file proportional truncation, not just last-N-chars.

paths

What Cascade is allowed to modify. This is your blast-radius limit.

Field	Type	Default	Description
allowed	list of globs	["src/**", "tests/**", "docs/**"]	Cascade may write to paths matching any glob.
disallowed	list of globs	See below	Cascade NEVER writes to paths matching any glob. Deny wins over allow.

Default disallowed:

• .github/** (CI workflows)
• migrations/** (database migrations)
• cascade.yaml (Cascade’s own config)
• team-memory/** (Cascade’s grounding layer)

Recommended additions for any production repo:

• infrastructure/** or terraform/**
• secrets/** or .env*
• package-lock.json, yarn.lock, Pipfile.lock (lockfiles; let your package manager generate them)

language

Optional explicit language override. If null (or omitted), Cascade auto-detects from marker files in the repo root.

Supported values: python, typescript, javascript, go, rust, java, ruby, csharp.

See languages for detection priority and per-language behavior.

test_command

Optional override for the language profile’s default test command. Useful if your project uses a non-standard test runner or specific args.

Examples:

test_command: pytest -xvs --cov

test_command: npm run test:unit

test_command: go test -race -timeout 30s ./...

test_command: cargo test --workspace --all-features

If null, Cascade uses the language profile’s default (e.g., pytest for Python, go test ./... for Go).

default_base_branch

Optional. The branch Cascade-generated PRs target by default. Override per-call with --base-branch.

default_base_branch: develop

Defaults to main if omitted.

Precedence

For each setting, Cascade resolves the value in this order (highest wins):

1. CLI flag on the command (e.g., --language go, --base-branch develop)
2. Project-level cascade.yaml (the file in your repo)
3. User-level ~/.config/cascade/config.yaml (credentials and global defaults)
4. Environment variables (ANTHROPIC_API_KEY, etc.)
5. Hardcoded defaults

Where to put what

Setting	Belongs in	Why
API keys, tokens	~/.config/cascade/config.yaml (via cascade configure)	Per-user; never in a repo (would leak via git)
Default LLM provider	~/.config/cascade/config.yaml	Per-user preference
Language override for this repo	cascade.yaml	Per-repo fact
Path allowlists for this repo	cascade.yaml	Per-repo policy
Test command for this repo	cascade.yaml	Per-repo fact
Per-call overrides	CLI flags	One-off changes

A note on globs

paths.allowed and paths.disallowed use standard glob syntax:

• * matches any sequence of characters except /
• ** matches any sequence of characters including / (recursive)
• ? matches any single character
• [abc] matches any character in the set

Examples:

Glob	Matches
src/**	Everything under src/, recursively
tests/*.py	Python files directly in tests/, not in subdirs
docs/**/*.md	Markdown files anywhere under docs/
.env*	.env, .env.local, .env.production, etc.
*.lock	Any lockfile in the repo root

Validation

Cascade validates cascade.yaml on every command start. Errors point at the field that is wrong:

error: cascade.yaml is invalid
  field:       agent.temperature
  problem:     value 3.0 is above maximum of 2.0
  suggestion:  use a temperature between 0.0 and 2.0; lower means more deterministic

Run cascade doctor to validate the config without running any other command.

Migrating between versions

We will bump version: when the schema changes incompatibly. Cascade refuses to load configs with an unknown version rather than guessing.

If we ever release version: 2, Cascade will also ship a cascade migrate command that updates your file in place. Until then, this is the only schema.

What is next

• CLI reference for the commands that read this file
• Team memory for what to put in the directory memory.path points at
• Languages for the detection rules and per-language test commands