Getting started

This guide walks you from zero to a merged pull request in about ten minutes. By the end, you will have run the full pipeline end-to-end on a real repo.

Before you start

You need four things:

Python 3.11+

Run python3 --version to check. Most modern Linux distros and the macOS Homebrew Python are fine.

A git repo to work in

Use a fork or a scratch repo for the first run. Do not point Cascade at production code on day one.

An LLM (any one of these)

Anthropic, OpenAI, or Google Gemini API key. Or a local Claude Code or Ollama install (no key needed).

A VCS account

GitHub, GitLab, Bitbucket, or Azure DevOps. With a personal access token that can open PRs.

Note

Cascade never sends your code to anyone except the LLM provider you explicitly configure. If your employer prohibits SaaS LLMs, run with local Claude Code or local Ollama, and your code stays on your machine.

Install

1. Install the base package

   pip install cascade-agent

   Cascade is in alpha (0.1.0a1); pip installs it automatically since no stable version exists yet. With non-default providers (OpenAI, Google, Claude Code, GitLab, Jira, and the Studio web UI):

   pip install "cascade-agent[all]"

   With meeting transcription (adds Whisper and roughly 2 GB of ML dependencies, only needed for cascade ingest):

   pip install "cascade-agent[all,ingest]"

2. Run the health check

   Before doing anything else, confirm the install works:

   cascade doctor

   You should see roughly eleven checks, most marked OK. Anything marked FAIL is something you need to fix before the next step. Anything marked WARN is fine to ignore for now.

3. Scaffold a project

   cd into a git repo where you want Cascade to work, then:

   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 gets. See Team memory for what belongs in each file.

4. Configure your LLM provider

   Anthropic

   cascade configure llm anthropic --key sk-ant-xxx --set-default

   Get a key at console.anthropic.com. Cascade defaults to claude-opus-4-7 which is the best model for code generation as of this writing.

   OpenAI

   cascade configure llm openai --key sk-xxx --set-default

   Get a key at platform.openai.com. GPT-4o or o1 are good picks for code work.

   Google Gemini

   cascade configure llm google --key gemini-xxx --set-default

   Get a key at aistudio.google.com. Gemini 1.5 Pro is the default model.

   Claude Code (no key)

   cascade configure llm claude_code --set-default

   Uses your existing Claude Code installation. No API key required. Calls are billed against your Claude Code subscription. See Run without any API key for details.

   Ollama (local)

   cascade configure llm ollama --model llama3.3 --set-default

   Make sure Ollama is running locally first (ollama serve in another terminal). Pull the model with ollama pull llama3.3. You want at least a 70B-class model for usable code quality.

5. Configure your VCS

   GitHub

   cascade configure vcs github --token ghp-xxx

   Create a token at github.com/settings/tokens with repo scope.

   GitLab

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

   Create a token at GitLab → Preferences → Access Tokens, scopes: api, write_repository.

   Bitbucket

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

   Use a Bitbucket App Password with Pull requests: write and Repositories: write. Create one at Bitbucket → Personal Settings → App passwords.

   Azure DevOps

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

   Create a PAT at Azure DevOps → User Settings → Personal Access Tokens with Code: Read & write scope.

6. Verify everything is wired up

   cascade configure show

   Output looks like this (secrets are masked, so it is safe to paste into a chat if you need help debugging):

   Config file: /home/you/.config/cascade/config.yaml
   Defaults:
     llm_provider:   anthropic
     vcs_provider:   github
     issue_provider: (none)
   
   LLM providers:
     anthropic: key=sk-ant-***...x9k2 model=claude-opus-4-7 base_url=(default)
   
   VCS providers:
     github: token=ghp_***...e7b9 base_url=(default) org=(n/a)

Try it without touching your repo

Before pointing Cascade at a real repo, run the built-in toy story end-to-end in a disposable temp directory:

cascade try

This:

1. Creates a throwaway Python project in /tmp/cascade-try-xxxxx/
2. Asks the LLM to add a tiny hello() function and a test
3. Runs the test
4. Reports the cost and result
5. Cleans up the temp directory (pass --keep-workspace to inspect what was generated)

The whole thing takes thirty seconds and costs a few cents. If it passes, your install is healthy. If it fails, the error message tells you exactly what is wrong, often with a suggested fix.

Your first real run

The fastest end-to-end test on a real repo is a one-line prompt. In a git repo you have configured Cascade in:

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

Watch the pipeline run, with live progress for each stage:

==> [story-prompt-20260925-103045] Add a /health endpoint...
  ✓ plan: 2 file(s) to change
  ✓ code: 2 file(s) generated
  ✓ branch: cascade/add-a-health-endpoint
  ✓ apply: 2 file(s) written
  ✓ install: ok
  ✓ test: passed (42 passed in 0.18s)
  ✓ commit: e4f8a2b1
  ✓ push: cascade/add-a-health-endpoint
  ✓ pr: #47
  branch:  cascade/add-a-health-endpoint
  commit:  e4f8a2b1
  install: ok
  tests:   passed (42 passed in 0.18s)
  PR:      #47  https://github.com/myorg/myrepo/pull/47
  cost:    $0.08 (4,820 in / 1,330 out tokens)

Open the PR, review the changes, and merge if it looks good. The same flow works for medium-sized features. For larger work, prefer the meeting-recording or ticket-based on-ramps so you can review proposed stories before code gets written.

When things go wrong

Cascade’s errors are designed to tell you what failed AND what to try next. The most common first-run issues:

What you see	What it means	What to do
No GitHub token in environment	The token never made it to Cascade.	Re-run cascade configure vcs github --token ghp-xxx and cascade configure show to confirm.
LLM call failed: 401 Unauthorized	The API key is wrong, expired, or has no credit.	Check the key in the provider’s console. For Anthropic, also verify there is a balance on the account.
pytest: command not found	The repo’s test runner is not installed.	Activate the project’s venv, run pip install -e .[dev], then re-run cascade prompt.
Working tree is not clean	You have uncommitted changes.	Cascade refuses to work on a dirty tree to avoid losing your work. Commit or stash, then retry.
error: pathspec 'main' did not match	Your default branch is not main.	Pass --base-branch master (or whatever your branch is called).

For anything else, run cascade doctor for a fresh health check, or open an issue at github.com/Thinknext-Software-Solutions/Cascade/issues with the full output.

Where to go next

You have a working install. Here is how to get the most out of it:

Process a real meeting recording

Drop in an mp3 from a sprint planning or standup. Cascade transcribes, extracts stories, walks you through review, then builds the approved ones. See from a meeting.

Build from a tracker ticket

Point Cascade at a Jira, Linear, GitHub, GitLab, or Azure Boards ticket. See from a ticket.

Run without any API key

Use your existing Claude Code or local Ollama install. No new key, no new bill. See no API key.

Set up team memory properly

The difference between generic AI output and code that fits your codebase is what you put in team-memory/. See team memory.

Understand the pipeline

Every stage Cascade runs, in order, with what each one reads and writes. See the pipeline.

Security model

What Cascade sees, what it never sees, and how to keep it that way at scale. See security.