Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/CODEOWNERS
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
# Default: all PRs require review from the maintainer
* @zbigniewsobiecki
* @mongrel-intelligence
6 changes: 3 additions & 3 deletions .github/workflows/deploy-dev.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ on:

env:
REGISTRY: ghcr.io
ROUTER_IMAGE: ghcr.io/zbigniewsobiecki/cascade-router
WORKER_IMAGE: ghcr.io/zbigniewsobiecki/cascade-worker
DASHBOARD_IMAGE: ghcr.io/zbigniewsobiecki/cascade-dashboard
ROUTER_IMAGE: ghcr.io/mongrel-intelligence/cascade-router
WORKER_IMAGE: ghcr.io/mongrel-intelligence/cascade-worker
DASHBOARD_IMAGE: ghcr.io/mongrel-intelligence/cascade-dashboard

jobs:
build-and-deploy:
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/deploy.yml
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ on:

env:
REGISTRY: ghcr.io
ROUTER_IMAGE: ghcr.io/zbigniewsobiecki/cascade-router
WORKER_IMAGE: ghcr.io/zbigniewsobiecki/cascade-worker
DASHBOARD_IMAGE: ghcr.io/zbigniewsobiecki/cascade-dashboard
ROUTER_IMAGE: ghcr.io/mongrel-intelligence/cascade-router
WORKER_IMAGE: ghcr.io/mongrel-intelligence/cascade-worker
DASHBOARD_IMAGE: ghcr.io/mongrel-intelligence/cascade-dashboard

jobs:
build-and-deploy:
Expand Down
8 changes: 4 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing to CASCADE
# Contributing to Cascade

Thank you for your interest in contributing to CASCADE! This guide will help you get started.
Thank you for your interest in contributing to Cascade! This guide will help you get started.

## Prerequisites

Expand Down Expand Up @@ -127,11 +127,11 @@ See [CLAUDE.md](./CLAUDE.md) for a detailed architecture overview. Key directori

## The `.cascade/` Directory

When CASCADE works on a repository, it looks for a `.cascade/` directory at the root of that repo. This directory lets you customize agent behavior — setup scripts, post-edit hooks, test runners, and environment variables.
When Cascade works on a repository, it looks for a `.cascade/` directory at the root of that repo. This directory lets you customize agent behavior — setup scripts, post-edit hooks, test runners, and environment variables.

See **[`.cascade/` Directory Guide](./docs/cascade-directory.md)** for the full reference.

## Getting Help

- Open an [issue](https://github.com/zbigniewsobiecki/cascade/issues) for bugs or feature requests
- Open an [issue](https://github.com/mongrel-intelligence/cascade/issues) for bugs or feature requests
- Check existing issues and discussions before creating new ones
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,19 @@
# CASCADE
# Cascade

> **CASCADE turns PM cards into pull requests using AI agents.**
> **Cascade orchestrates AI agents (Claude Code, Codex, opencode, LLMist) across your workflows in GitHub, Trello, and Jira.**

CASCADE is an open-source automation platform that bridges your project management tool (Trello or JIRA) with your GitHub repository. Move a card to the right list — or add a label — and CASCADE picks it up, runs an AI agent, and delivers a pull request.
Cascade is an open-source platform that automates the full software development lifecycle. Connect your PM tool and GitHub repository, and Cascade drives work items from plan to merge:

```
PM Card → WebhookRouterRedis/BullMQWorkerAgentPR
PM Card → SplitPlanImplementPRReviewIterate → Merge
```

---

## 🚀 Quick Start

```bash
git clone https://github.com/zbigniewsobiecki/cascade.git
git clone https://github.com/mongrel-intelligence/cascade.git
cd cascade
cp .env.docker.example .env # Edit if needed
bash setup.sh # Build, migrate, and start all services
Expand Down Expand Up @@ -42,7 +42,7 @@ For the full setup walkthrough — projects, credentials, webhooks, and triggers

## 🏗️ Architecture

CASCADE runs as three independent services:
Cascade runs as three independent services:

| Service | Entry Point | Role |
|---------|-------------|------|
Expand Down Expand Up @@ -127,7 +127,7 @@ All project-level credentials (GitHub tokens, PM keys, LLM API keys) are stored

## 🔑 Key Concepts

**Dual-persona GitHub model** — CASCADE uses two separate GitHub bot accounts per project (implementer and reviewer) to prevent feedback loops. The implementer writes code and creates PRs; the reviewer reviews and approves them.
**Dual-persona GitHub model** — Cascade uses two separate GitHub bot accounts per project (implementer and reviewer) to prevent feedback loops. The implementer writes code and creates PRs; the reviewer reviews and approves them.

**Trigger system** — Events from Trello, JIRA, and GitHub webhooks are matched against registered `TriggerHandler` instances. Triggers are configured per-project in the database.

Expand All @@ -146,7 +146,7 @@ For deeper documentation on all of these topics, see [CLAUDE.md](./CLAUDE.md).
1. Fork the repository and create a feature branch from `dev`
2. Make your changes with tests (`npm test`)
3. Ensure lint and typecheck pass (`npm run lint && npm run typecheck`)
4. Open a pull request — CASCADE will review its own PRs if configured to do so
4. Open a pull request — Cascade will review its own PRs if configured to do so

Please follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages. See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.

Expand Down
4 changes: 2 additions & 2 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

**Please do not report security vulnerabilities through public GitHub issues.**

Instead, use [GitHub Security Advisories](https://github.com/zbigniewsobiecki/cascade/security/advisories/new) to report vulnerabilities privately. You should receive a response within 72 hours.
Instead, use [GitHub Security Advisories](https://github.com/mongrel-intelligence/cascade/security/advisories/new) to report vulnerabilities privately. You should receive a response within 72 hours.

Please include:
- Description of the vulnerability
Expand All @@ -20,7 +20,7 @@ Please include:

## Security Design

CASCADE incorporates several security measures:
Cascade incorporates several security measures:

- **Credential encryption at rest**: AES-256-GCM encryption for all stored credentials when `CREDENTIAL_MASTER_KEY` is configured. See [CLAUDE.md](./CLAUDE.md#credential-encryption-at-rest) for details.
- **Dual-persona model**: Separate GitHub bot accounts for implementation and review prevent self-approval and feedback loops.
Expand Down
36 changes: 18 additions & 18 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,22 @@
# Getting Started with CASCADE
# Getting Started with Cascade

This guide walks you through setting up CASCADE using Docker Compose — from zero to a working instance that turns PM cards into pull requests.
This guide walks you through setting up Cascade using Docker Compose — from zero to a working instance that turns PM cards into pull requests.

---

## Prerequisites

- **Docker** and **Docker Compose** (v2+)
- ~6 GB disk space (the worker image includes Claude Code CLI and other agent tools)
- A GitHub repository you want CASCADE to work on
- A GitHub repository you want Cascade to work on
- At least one LLM API key (OpenRouter, Anthropic, or OpenAI) or a Claude Max subscription

---

## 1. Installation

```bash
git clone https://github.com/zbigniewsobiecki/cascade.git
git clone https://github.com/mongrel-intelligence/cascade.git
cd cascade
cp .env.docker.example .env
```
Expand Down Expand Up @@ -104,15 +104,15 @@ node bin/cascade.js projects create \

## 6. Add Credentials

CASCADE needs credentials to interact with GitHub, your PM tool, and LLM providers. All credentials are stored encrypted in the database, scoped to your project.
Cascade needs credentials to interact with GitHub, your PM tool, and LLM providers. All credentials are stored encrypted in the database, scoped to your project.

Via the dashboard: **Projects** > select project > **Credentials** to manage project credentials.

Or via CLI:

### GitHub bot tokens

CASCADE uses two separate GitHub accounts to prevent feedback loops:
Cascade uses two separate GitHub accounts to prevent feedback loops:

- **Implementer** — writes code, creates PRs
- **Reviewer** — reviews PRs, approves or requests changes
Expand Down Expand Up @@ -199,19 +199,19 @@ node bin/cascade.js projects credentials-set my-project \
--name "Codex Subscription Auth"
```

When using subscription auth, CASCADE automatically writes `~/.codex/auth.json` in the worker before each run and captures any token refreshes the Codex CLI performs back into the database — so the credential stays current across ephemeral worker environments.
When using subscription auth, Cascade automatically writes `~/.codex/auth.json` in the worker before each run and captures any token refreshes the Codex CLI performs back into the database — so the credential stays current across ephemeral worker environments.

You can also manage all of this through the dashboard UI: **Projects** > select project > **Credentials**.

---

## 7. Choose Agent Engine

CASCADE supports multiple agent engines. The default is **LLMist** — change it if you want to use a different engine.
Cascade supports multiple agent engines. The default is **LLMist** — change it if you want to use a different engine.

| Engine | Description |
|--------|-------------|
| `llmist` | LLMist SDK with CASCADE gadgets (default) |
| `llmist` | LLMist SDK with Cascade gadgets (default) |
| `claude-code` | Anthropic Claude Code SDK |
| `codex` | OpenAI Codex CLI |
| `opencode` | OpenCode headless agent |
Expand Down Expand Up @@ -251,12 +251,12 @@ node bin/cascade.js projects integration-set my-project \
--config '{"boardId":"BOARD_ID","lists":{"todo":"LIST_ID","inProgress":"LIST_ID","inReview":"LIST_ID"},"labels":{"readyToProcess":"LABEL_ID","processing":"LABEL_ID","processed":"LABEL_ID","error":"LABEL_ID"}}'
```

### JIRA
### Jira

```bash
# Store JIRA credentials (project-scoped)
node bin/cascade.js projects credentials-set my-project --key JIRA_EMAIL --value you@company.com --name "JIRA Email"
node bin/cascade.js projects credentials-set my-project --key JIRA_API_TOKEN --value ... --name "JIRA API Token"
# Store Jira credentials (project-scoped)
node bin/cascade.js projects credentials-set my-project --key JIRA_EMAIL --value you@company.com --name "Jira Email"
node bin/cascade.js projects credentials-set my-project --key JIRA_API_TOKEN --value ... --name "Jira API Token"

# Configure the integration
node bin/cascade.js projects integration-set my-project \
Expand All @@ -268,9 +268,9 @@ node bin/cascade.js projects integration-set my-project \

## 9. Set Up Webhooks

CASCADE needs to receive webhooks from GitHub (and optionally your PM tool) to trigger agents.
Cascade needs to receive webhooks from GitHub (and optionally your PM tool) to trigger agents.

Your CASCADE instance must be reachable from the internet. For local development, use a tunnel like [ngrok](https://ngrok.com/) or [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).
Your Cascade instance must be reachable from the internet. For local development, use a tunnel like [ngrok](https://ngrok.com/) or [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/).

Configure via the dashboard: **Projects** > select project > **Settings** > **Webhooks** tab.

Expand Down Expand Up @@ -302,7 +302,7 @@ Or via CLI:
node bin/cascade.js projects trigger-set my-project \
--agent implementation --event pm:status-changed --enable

# Enable review after CI passes (for CASCADE's own PRs)
# Enable review after CI passes (for Cascade's own PRs)
node bin/cascade.js projects trigger-set my-project \
--agent review --event scm:check-suite-success --enable \
--params '{"authorMode":"own"}'
Expand All @@ -319,7 +319,7 @@ node bin/cascade.js projects trigger-discover --agent implementation

## 11. Test It

1. Create a card in your PM tool (Trello/JIRA) with a clear description of what code change you want
1. Create a card in your PM tool (Trello/Jira) with a clear description of what code change you want
2. Move it to the status that triggers the implementation agent (or add the "Ready to Process" label)
3. Watch the dashboard — a new run should appear within seconds
4. The agent clones your repo, writes code, and opens a pull request
Expand All @@ -332,7 +332,7 @@ Check the dashboard for real-time logs, LLM call traces, and debug information.

### HTTPS with a Reverse Proxy

For production, put CASCADE behind a reverse proxy (nginx, Caddy, Traefik) that terminates TLS:
For production, put Cascade behind a reverse proxy (nginx, Caddy, Traefik) that terminates TLS:

```bash
# .env
Expand Down
2 changes: 1 addition & 1 deletion src/router/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ export async function loadProjectConfig(): Promise<{
export const routerConfig: RouterConfig = {
redisUrl: process.env.REDIS_URL || 'redis://localhost:6379',
maxWorkers: Number(process.env.MAX_WORKERS) || 3,
workerImage: process.env.WORKER_IMAGE || 'ghcr.io/zbigniewsobiecki/cascade-worker:latest',
workerImage: process.env.WORKER_IMAGE || 'ghcr.io/mongrel-intelligence/cascade-worker:latest',
workerMemoryMb: Number(process.env.WORKER_MEMORY_MB) || 4096,
workerTimeoutMs: Number(process.env.WORKER_TIMEOUT_MS) || 30 * 60 * 1000, // 30 minutes
dockerNetwork: process.env.DOCKER_NETWORK || 'services_default',
Expand Down
2 changes: 1 addition & 1 deletion tests/docker/worker-setup-test/run-test.sh
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"

# Use the latest available worker image
WORKER_IMAGE="${WORKER_IMAGE:-ghcr.io/zbigniewsobiecki/cascade-worker:923f7c6215608865ac55e4d89f83663f055ab87a}"
WORKER_IMAGE="${WORKER_IMAGE:-ghcr.io/mongrel-intelligence/cascade-worker:923f7c6215608865ac55e4d89f83663f055ab87a}"

echo "=== Worker Setup Test ==="
echo "Project root : $PROJECT_ROOT"
Expand Down
2 changes: 1 addition & 1 deletion tests/unit/repo-hygiene.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ describe('open-source readiness', () => {

it('uses placeholder repo names', () => {
for (const project of config.projects) {
expect(project.repo).not.toMatch(/zbigniewsobiecki/);
expect(project.repo).not.toMatch(/mongrel-intelligence/);
}
});
});
Expand Down
Loading