Getting started

This guide takes you from zero to a working pull request in about ten minutes.

Prerequisites

Python 3.11 or later
A git repo you’re comfortable letting Cascade work on (start with a fork or scratch repo, not production)
One of:
- An Anthropic, OpenAI, or Google Gemini API key
- A local Claude Code installation (no API key needed)
- A local Ollama install (no API key needed)
A GitHub, GitLab, Bitbucket, or Azure DevOps account with a personal access token

Install

Install the base package
Terminal window
```
pip install cascade-agent
```
Or install with all optional providers (OpenAI, Google, Claude Code, GitLab, Jira):
Terminal window
```
pip install "cascade-agent[all]"
```
Scaffold a project

In a git repo where you want Cascade to work:
Terminal window
```
cascade init
```
This creates cascade.yaml and a team-memory/ directory with starter files. Edit those files to teach Cascade about your team’s conventions, decisions, glossary, and prior work. The more accurate this is, the better Cascade’s output.
Configure your LLM provider
Terminal window
cascade configure llm anthropic --key sk-ant-xxx --set-default
Terminal window
cascade configure llm openai --key sk-xxx --set-default
Terminal window
cascade configure llm google --key gemini-xxx --set-default
Terminal window
cascade configure llm claude_code --set-default
Uses your existing Claude Code installation. No API key required.
Terminal window
cascade configure llm ollama --model llama3 --set-default
Make sure Ollama is running locally first.

Configure your VCS

cascade configure vcs github --token ghp-xxx

cascade configure vcs gitlab --token glpat-xxx
# For self-hosted:
cascade configure vcs gitlab --token glpat-xxx --base-url https://gitlab.acme.io

cascade configure vcs bitbucket --token your-app-password

cascade configure vcs azure_devops --token your-pat --organization myorg

Verify config
Terminal window
```
cascade configure show
```
Secrets are masked, so it’s safe to copy-paste the output if you want help debugging.

Your first run

The fastest end-to-end test: a one-line prompt.

cascade prompt "Add a /health endpoint that returns {'status': 'ok'}"

Cascade will:

Treat your prompt as an approved story.
Plan the change (which files, what intent).
Generate the code and the tests.
Run the tests.
Open a PR for your review.

You’ll see something like:

==> [story-prompt-20260925-103045] Add a /health endpoint...
  branch:  cascade/story-prompt-20260925-103045/add-a-health-endpoint
  commit:  e4f8a2b1...
  install: ok
  tests:   passed (42 passed in 0.18s)
  PR:      #47  https://github.com/myorg/myrepo/pull/47

Open the PR, review the changes, and merge if it looks good.

Getting started

Prerequisites

Install

Your first run

From here