Help / Use cases
Four representative scenarios, illustrated as agent conversations and the actual tool calls behind them.
Carve out an implementation task in your local repo. Purple Codens runs Claude Code on Fargate / VPS workers and opens a PR. Multiple tasks can run in parallel.
User: "Add rate limiting to the auth-codens login API and open a PR."
Agent: 1. Look up existing projects (organization_id is auto-resolved from credentials)
→ purple_project({ action: "list_projects" })
2. Create the workflow run and start it
→ purple_workflow({
action: "create_workflow",
project_id: "...",
name: "Add rate limiting to login API",
spec: {
repository: "Corevice/auth-codens",
base_branch: "develop",
description: "Apply 10 req/min per IP using Redis-backed limiter. Add tests."
}
})
3. Poll progress (status: pending → running → succeeded / failed)
→ purple_workflow({ action: "get_run_status", run_id: "..." })
4. Share the PR URL on completionErrors caught by Sentry (or filed manually) get analyzed by Red. The fix plan is submitted to Purple for a PR. Red can ship simple fixes on its own, but multi-file or structural fixes are stronger through the Purple chain.
User: "Fix the auth-codens error."
Agent: 1. Create the bug report (auto_analyze=true kicks off analysis too)
→ red_bug_report({
action: "create",
project_id: "...",
title: "Login endpoint returns 500 on empty password",
description: "...",
severity: "high",
auto_analyze: true
})
2. After analysis, generate the bug fix plan
→ red_bug_fix_plan({
action: "generate",
bug_id: "..."
})
3. Submit it to Purple to PR
→ red_bug_fix_plan({
action: "submit_to_purple",
plan_id: "..."
})
→ PR URL: https://github.com/Corevice/.../pull/512Generate Playwright E2E tests from a natural-language requirement, run them in Blue, and inspect the results. Failures can be chained into Red for an auto-fix.
User: "Add an E2E test for green-codens' checkout flow."
Agent: 1. Generate the test
→ blue_e2e_test({
action: "generate",
project_id: "...",
requirement: "Verify that a user can complete a checkout flow with an annual plan.",
language: "playwright"
})
2. Run it
→ blue_e2e_test({ action: "run", e2e_test_id: "..." })
3. Fetch the results
→ blue_e2e_test({ action: "get_results", e2e_test_id: "..." })
// → { run_status, passed, failed, video_url, trace_url, ... }Green structures a vague request as Consultation → PRD → Plan and submits it to Purple for implementation. Notion link / unlink is supported.
User: "Add an annual plan option to the billing screen. Handle requirements through to implementation."
Agent: 1. Start a Consultation
→ green_consultation({
action: "create_with_message",
project_id: "...",
title: "Annual plan selector UI",
content: "Add an annual plan option to the billing screen..."
})
2. Convert the Consultation to a PRD (pick a template)
→ green_consultation({
action: "convert_to_prd",
consultation_id: "...",
template_id: "..."
})
3. Generate a Plan from the PRD and submit it to Purple
→ green_plan({ action: "generate_from_prd", prd_id: "..." })
→ green_plan({ action: "submit_to_purple", plan_id: "..." })
4. Share the PR URL on completion