Help / Purple Codens

Purple Codens setup

AI development orchestration. Hand off a task and Purple will dispatch Claude Code on Fargate / VPS workers, run tests, and open a PR. Handles long-running and parallel tasks reliably.

Overview

Purple's unit of work is the workflow run. Each run goes from task spec → implementation → tests → PR creation in a single flow, with fix_verify loops and heartbeat jobs running automatically.

Fargate executor: 1 task = 1 ECS Fargate task, isolated (default).
VPS executor: dedicated VPS pool for long-running or GPU-bound tasks (Enterprise add-on).
Workflow shape: feature → develop → main is the default 3-stage flow; base_branch is configurable.

Prerequisites

A Codens account and organization (see Getting Started).
codens-mcp installed and logged in (see MCP setup).
Admin / write access on the target GitHub repository.
Codens GitHub App installed (from https://github.com/apps/codens; you'll be prompted during project creation if it's missing).

Step 1. Create a project & link a repo

Use the dashboard (app.purple.codens.ai) → "New Project", or drive everything from MCP:

Via MCP (recommended)

// Analyze the local repo, create the project, link the repo,
// and import instruction files in one call
await tools.purple_project({
  action: "init_project",
  repo_full_name: "Corevice/your-repo",
  name: "Your Repo",
  base_branch: "develop"
});

// List existing projects
await tools.purple_project({ action: "list_projects" });

init_project performs three things: (1) create the Purple project, (2) link the GitHub repo, and (3) import CLAUDE.md and .claude/rules/ from the repo as instruction files.

Step 2. Sync instruction files (CLAUDE.md / rules)

Importing CLAUDE.md and .claude/rules/*.md means Claude Code inside the workflow run follows the same guidelines as your local agents.

// List imported instructions
await tools.purple_instruction({ action: "list", project_id });

// Diff against latest repo state and sync
await tools.purple_instruction({ action: "sync", project_id });

Strengthen your verify_commands. Don't stop at pytest; combine it with test -f / grep -q so the fix_verify loop has structural signal to work with.

Step 3. Kick off your first workflow run

// Submit a task
const run = await tools.purple_workflow({
  action: "create_workflow",
  project_id: "...",
  name: "Add rate limiting to login API",
  spec: {
    repository: "Corevice/your-repo",
    base_branch: "develop",
    description: "Apply 10 req/min per IP using Redis-backed limiter. Add tests."
  }
});

// Poll progress (status: pending → running → succeeded / failed)
await tools.purple_workflow({ action: "get_run_status", run_id: run.run_id });

// Stream events via SSE
await tools.purple_sse({ action: "subscribe_run_events", run_id: run.run_id });

On success you'll get a PR URL. On failure, purple_log can fetch detailed logs (S3 presigned URL, 1-hour validity).

Operational notes

Inject messages: while a long-running heartbeat job is going, you can interject with purple_workflow({ action: "inject_message" }).
Cancellation: purple_workflow({ action: "cancel_run" }). Do not put meta/parent tickets into "Ready for Agent" — cancellation cascades.
verify_commands: always materialize the venv (e.g. uv venv .venv && uv pip install ...). Anything under .gitignore (such as venv/ or node_modules/) won't exist in the worktree.
Independent repos: under codens-main, each Codens product is its own git repo. Commit / push from within the product directory.

For end-to-end scenarios, see Use case A — Purple workflow.

Next steps

Purple use case

Canonical scenario with agent dialog

Red → Purple chain

Bug to auto-fix PR

Green → Purple chain

PRD / Plan all the way to a PR